pslockout/authserver/README.md

232 lines
6.6 KiB
Markdown
Raw Normal View History

2018-09-14 20:26:12 +00:00
# Protospace lockout authorization server
Provides an API to the web client and web server to serve tool data and authenticate users on tools.
## Setup
2018-09-12 06:21:26 +00:00
```
2018-09-18 00:16:39 +00:00
$ sudo apt install python3 python3-pip python3-virtualenv # for Debian
2018-09-12 06:21:26 +00:00
$ virtualenv -p python3 env
$ . env/bin/activate
(env) $ pip install -r requirements.txt
2018-09-14 00:04:02 +00:00
(env) $ python manage.py migrate --run-syncdb
2018-09-12 06:21:26 +00:00
(env) $ python manage.py createsuperuser --email admin@example.com --username admin
(env) $ python manage.py runserver
```
2018-09-14 20:26:12 +00:00
2018-09-18 00:16:39 +00:00
Authenticate a Protospace login using the `curl` command below against **your** server, then navigate to http://127.0.0.1:8000/admin/ and login with the superuser account you just created above.
Once logged in, navigate to "Profiles" and make your Protospace user a lockout admin.
Now you have total control of the system and can make other users lockout admins though the API or web interface.
2018-09-14 20:26:12 +00:00
## API
2018-09-16 03:25:39 +00:00
The API is RESTful and returns hyperlinked json data. **URLs require a trailing slash.**
2018-09-18 00:16:39 +00:00
It's also possible to interact with the API through a web interface at http://tools-auth.protospace.ca from the Protospace LAN. Any Protospace users that have already authenticated through /login/ are able to login.
2018-09-16 03:25:39 +00:00
### Authentication
Authentication is token-based and done against the Protospace member portal. Upon successful login, the auth server will automatically register the user and create them a profile.
#### POST `/login/`
POST data `username` and `password`. Upon successful login, a 200 status and a token will be returned.
2018-09-16 05:32:33 +00:00
Example request:
```
curl -d username=tanner.collin -d password=supersecret http://tools-auth.protospace.ca/login/
```
2018-09-16 03:25:39 +00:00
Example response:
```
{
"token": "9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"
}
```
In subsequent requests, the token key should be included in the `Authorization` HTTP header. The key should be prefixed by the string literal "Token", with whitespace separating the two strings. For example:
```
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b
```
2018-09-14 20:26:12 +00:00
Example authenticated request:
```
curl -H "Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" http://tools-auth.protospace.ca/user/
```
2018-09-14 20:26:12 +00:00
### For anonymous users
2018-09-14 23:39:06 +00:00
#### GET `/tooldata/`
2018-09-14 20:26:12 +00:00
Returns all the info about the shop and its tools. Tools are split into categories.
Example response:
```
{
"categories": [
{
2018-09-18 00:43:54 +00:00
"url": "http://tools-auth.protospace.ca/category/wood-shop/",
2018-09-14 20:26:12 +00:00
"tools": [
{
2018-09-18 00:43:54 +00:00
"url": "http://tools-auth.protospace.ca/tool/table-saw/",
"category": "http://tools-auth.protospace.ca/category/wood-shop/",
2018-09-14 20:26:12 +00:00
"name": "Table Saw",
"slug": "table-saw",
"info": "scary tool",
"wiki_id": 123,
2018-09-18 00:43:54 +00:00
"photo": "http://tools-auth.protospace.ca/media/DSC00125.jpg",
"mac": "2C3AE843A15F"
2018-09-14 20:26:12 +00:00
},
{
2018-09-18 00:43:54 +00:00
"url": "http://tools-auth.protospace.ca/tool/jointer/",
"category": "http://tools-auth.protospace.ca/category/wood-shop/",
2018-09-14 20:26:12 +00:00
"name": "Jointer",
"slug": "jointer",
"info": "goes buzz buzz",
"wiki_id": 1,
2018-09-18 00:43:54 +00:00
"photo": "http://tools-auth.protospace.ca/media/uq4ldzsp4bu01.jpg",
"mac": "2C3AE8439EAD"
2018-09-14 20:26:12 +00:00
}
],
"name": "Wood Shop",
"slug": "wood-shop",
"info": "protospace wood shop",
2018-09-18 00:43:54 +00:00
"photo": "http://tools-auth.protospace.ca/media/ps-wood-shop.jpg"
2018-09-14 20:26:12 +00:00
},
{
2018-09-18 00:43:54 +00:00
"url": "http://tools-auth.protospace.ca/category/metal-shop/",
2018-09-14 20:26:12 +00:00
"tools": [
{
2018-09-18 00:43:54 +00:00
"url": "http://tools-auth.protospace.ca/tool/metal-lathe/",
"category": "http://tools-auth.protospace.ca/category/metal-shop/",
2018-09-14 20:26:12 +00:00
"name": "Metal Lathe",
"slug": "metal-lathe",
"info": "spins fast",
"wiki_id": 42,
2018-09-18 00:43:54 +00:00
"photo": "http://tools-auth.protospace.ca/media/lathe.jpeg",
"mac": "ABCDEF000003"
2018-09-14 20:26:12 +00:00
}
],
"name": "Metal Shop",
"slug": "metal-shop",
"info": "protospace metal shop",
2018-09-18 00:43:54 +00:00
"photo": "http://tools-auth.protospace.ca/media/metal-shop02.jpg"
2018-09-14 20:26:12 +00:00
}
]
}
```
2018-11-11 04:40:09 +00:00
#### GET `/cards/[MAC]/`
Returns all card numbers authorized to use a machine based on MAC address.
Card numbers are on one line separated by a comma.
Example request:
```
curl http://tools-auth.protospace.ca/cards/2C3AE843A15F/
```
Example response:
```
"00000B8567,00000A4123,00000C9999"
```
2018-09-14 20:26:12 +00:00
### For authenticated users
2018-09-14 23:39:06 +00:00
#### GET `/user/`
2018-09-14 20:26:12 +00:00
Returns info about the logged in user, including which tools they are authorized on. Note the top-level array (a quirk of django-rest-framework).
Example response:
```
[
{
"username": "tanner.collin",
2018-09-14 20:26:12 +00:00
"profile": {
"url": "http://tools-auth.protospace.ca/profile/2/",
"user": "tanner.collin",
"card": "00000A4123",
2018-09-14 20:26:12 +00:00
"authorized_tools": [
"table-saw",
"jointer"
],
"lockout_admin": true
}
}
]
```
### For lockout admins
2018-09-14 20:36:57 +00:00
Ensure images are square and 1280x1280 px large. Slugs should be lowercase and one word (replace spaces with hyphens).
2018-09-14 20:26:12 +00:00
2018-09-14 23:39:06 +00:00
#### GET, POST `/tool/`
2018-09-14 20:26:12 +00:00
Get a list of tools, or post a new tool to the database.
2018-09-14 23:39:06 +00:00
#### GET, PUT, DELETE `/tool/[slug]/`
2018-09-14 20:26:12 +00:00
Get a specific tool, modify or delete an existing one.
2018-09-14 23:39:06 +00:00
#### GET, POST `/category/`
2018-09-14 20:26:12 +00:00
Get a list of categories, or post a new category to the database.
2018-09-14 23:39:06 +00:00
#### GET, PUT, DELETE `/category/[slug]/`
2018-09-14 20:26:12 +00:00
Get a specific category, modify or delete an existing one.
Note: you can only delete a category that has no tools.
2018-09-14 23:39:06 +00:00
#### GET `/profile/`
2018-09-14 20:26:12 +00:00
Get a list of all profiles.
2018-09-14 23:39:06 +00:00
#### GET, PUT `/profile/[id]/`
2018-09-14 20:26:12 +00:00
Get a specific profile, or modify an existing one.
Here you can authorize users on tools or make them another lockout admin.
#### PUT `/update-cards/`
Send a dictionary of username=card_number pairs to update any profiles already in the system. Users not already registered will be ignored.
Responds with the number of profiles updated.
Operation is idempotent.
Example PUT data:
```
{
"tanner.collin": "00000A4123",
"matthew.mulrooney": "00000B8567",
"not-a-member": "539830843A"
}
```
Example response:
```
{"updated":2}
```
Example request:
```
curl -X PUT -H "Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" -d tanner.collin=00000A4123 -d matthew.mulrooney=00000B8567 http://tools-auth.protospace.ca/update-cards/
```