API

Redbrick Administrator Web API

The source code for the API can be found here.

The Redbrick web API serves as an easy interface to carry out administrator tasks (mainly LDAP related), and for use in automation.

This saves time instead of accessing machines, and formulating and executing manual LDAP queries or scripts.

The server code for the API is hosted on Zeus in a docker container called 'api-redbrick', written in Python with FastAPI. This container is then served to the public using traefik, you can view the dashboard here.

Reference

For the most up to date, rich API reference please visit https://api.redbrick.dcu.ie/docs

All requests are validated with Basic Auth for access. See example.

Method	Route	URL Parameters	Body
GET	/users/username	username - Redbrick username	N/A
PUT	/users/username	username - Redbrick username	ldap_key
POST	/users/register	N/A	ldap_value

Examples

GET a user's LDAP data

import requests

url = "https://api.redbrick.dcu.ie/users/USERNAME_HERE"

headers = {
  'Authorization': 'Basic <ENCODED_USERANDPASS_HERE>'
}

response = requests.request("GET", url, headers=headers)

print(response.text)

PUT a user's LDAP data to change their loginShell to /usr/local/shells/zsh

import requests
import json

url = "https://api.redbrick.dcu.ie/users/USERNAME_HERE"
payload = json.dumps({
  "ldap_key": "loginShell",
  "ldap_value": "/usr/local/shells/zsh"
})
headers = {
  'Authorization': 'Basic <ENCODED_USERANDPASS_HERE>',
  'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Important Notes and Caveats

As the FastAPI server for the API is hosted inside of a Docker container, there are limitations to the commands we can execute that affect the "outside" world.

This is especially important with commands that rely on LDAP.

For example inside the ldap-register.sh script used by the /register endpoint.

• Commands like chown which require a user group or user to be passed to them will not work because they cannot access these users/groups in the container.

• This is prevalent in our implementation of the API that creates and modifies users' webtree directory.

How do we fix this?

Instead of relying on using users/group names for the chown command, it is advisable to instead use their unique id's.

# For example, the following commands are equivalent.
chown USERNAME:member /storage/webtree/U/USERNAME

chown 13371337:103 /storage/webtree/U/USERNAME
# Where 13371337 is userid and 103 is the id for the 'member' group.

Note that USERNAME can be used to refer to the user's web directory here since it is the name of the directory and doesn't refer to the user object.

 

---

Last update: 2023-09-27