# 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/ ```