pslockout/authserver

Protospace lockout authorization server

Provides an API to the web client and web server to serve tool data and authenticate users on tools.

Setup

$ sudo apt install python3 python3-pip python3-virtualenv   # for Debian
$ virtualenv -p python3 env
$ . env/bin/activate
(env) $ pip install -r requirements.txt
(env) $ python manage.py migrate --run-syncdb
(env) $ python manage.py createsuperuser --email admin@example.com --username admin
(env) $ python manage.py runserver

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.

API

The API is RESTful and returns hyperlinked json data. URLs require a trailing slash.

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.

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.

Example request:

curl -d username=tanner.collin -d password=supersecret http://tools-auth.protospace.ca/login/

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

Example authenticated request:

curl -H "Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" http://tools-auth.protospace.ca/user/

For anonymous users

GET /tooldata/

Returns all the info about the shop and its tools. Tools are split into categories.

Example response:

{
    "categories": [
        {
            "url": "http://tools-auth.protospace.ca/category/wood-shop/",
            "tools": [
                {
                    "url": "http://tools-auth.protospace.ca/tool/table-saw/",
                    "category": "http://tools-auth.protospace.ca/category/wood-shop/",
                    "name": "Table Saw",
                    "slug": "table-saw",
                    "info": "scary tool",
                    "wiki_id": 123,
                    "photo": "http://tools-auth.protospace.ca/media/DSC00125.jpg",
                    "mac": "2C3AE843A15F"
                },
                {
                    "url": "http://tools-auth.protospace.ca/tool/jointer/",
                    "category": "http://tools-auth.protospace.ca/category/wood-shop/",
                    "name": "Jointer",
                    "slug": "jointer",
                    "info": "goes buzz buzz",
                    "wiki_id": 1,
                    "photo": "http://tools-auth.protospace.ca/media/uq4ldzsp4bu01.jpg",
                    "mac": "2C3AE8439EAD"
                }
            ],
            "name": "Wood Shop",
            "slug": "wood-shop",
            "info": "protospace wood shop",
            "photo": "http://tools-auth.protospace.ca/media/ps-wood-shop.jpg"
        },
        {
            "url": "http://tools-auth.protospace.ca/category/metal-shop/",
            "tools": [
                {
                    "url": "http://tools-auth.protospace.ca/tool/metal-lathe/",
                    "category": "http://tools-auth.protospace.ca/category/metal-shop/",
                    "name": "Metal Lathe",
                    "slug": "metal-lathe",
                    "info": "spins fast",
                    "wiki_id": 42,
                    "photo": "http://tools-auth.protospace.ca/media/lathe.jpeg",
                    "mac": "ABCDEF000003"
                }
            ],
            "name": "Metal Shop",
            "slug": "metal-shop",
            "info": "protospace metal shop",
            "photo": "http://tools-auth.protospace.ca/media/metal-shop02.jpg"
        }
    ]
}

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"

For authenticated users

GET /user/

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",
        "profile": {
            "url": "http://tools-auth.protospace.ca/profile/2/",
            "user": "tanner.collin",
            "card": "00000A4123",
            "authorized_tools": [
                "table-saw",
                "jointer"
            ],
            "lockout_admin": true
        }
    }
]

For lockout admins

Ensure images are square and 1280x1280 px large. Slugs should be lowercase and one word (replace spaces with hyphens).

GET, POST /tool/

Get a list of tools, or post a new tool to the database.

GET, PUT, DELETE /tool/[slug]/

Get a specific tool, modify or delete an existing one.

GET, POST /category/

Get a list of categories, or post a new category to the database.

GET, PUT, DELETE /category/[slug]/

Get a specific category, modify or delete an existing one.

Note: you can only delete a category that has no tools.

GET /profile/

Get a list of all profiles.

GET, PUT /profile/[id]/

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/