# ungleich-otp ungleich-otp is a full blown authentication and authorisation service made for micro services. The basic idea is that every micro service has a (long term) seed and creates time based tokens (TOTP, RFCXXXX). ## Setup instructions ## This is a standard django project and thus can be easily setup using ``` pip install -r requirements.txt ``` To bootstrap the application, you need your very first trusted seed to access the application. You can generate it using ``` to be filled in ``` After that, you can run the application using ``` python manage.py runserver ``` The usual instructions on how to setup an https proxy should be followed. ## Realms ## Access is granting/denied based on realms. There are two reserved realms, all other realms can be used by the users: ### Reserved realms Conceptually the realms "ungleich-admin" and "ungleich-auth" are reserved for higher priviliged applications. Usually there is only 1 entry in ungleich-admin that is used to bootstrap and manage ungleich-otp. All micro services that are trusted to authenticate another micro service should have an entry in the ungleich-auth realm, which allows them to verify a token of somebody else. | Name | Capabilities | |------------------+--------------------------------------------| | ungleich-admin | authenticate, create, delete, list, update | | ungleich-auth | authenticate | | all other realms | NO ACCESS | ## Status ## ## Usage: REST ## - Use an existing token to connect to the service - All REST based messages: JSON ### POST: /verify Request JSON object: ``` { version: "1", appuuid: "your-app-uuid", token: "current time based token", appuuidtoverify: "appuuid that wants to be authenticated", tokentoverify: "current time based token of appuuidtoverify", } ``` Response JSON object: Either ``` { status: "OK", } ``` OR ``` { status: "FAIL", } ``` ### POST /register Register a new seed. Returns an app ID. Request JSON object: ``` { version: "1", appuuid: "your-app-uuid", token: "current time based token", username: "user this app belongs to", appname: "name of your web app" } ``` Response JSON object: ``` { status: "OK", appuuid: "UUID of your app", } ``` OR ``` { status: "FAIL", error: "Reason for failure" } ``` ### POST /app/register Register a new app. Returns an app ID. Request JSON object: ``` { version: "1", appuuid: "your-app-uuid", token: "current time based token", username: "user this app belongs to", appname: "name of your web app" } ``` Response JSON object: ``` { status: "OK", appuuid: "UUID of your app", } ``` OR ``` { status: "FAIL", error: "Reason for failure" } ``` ### GET /app List all registered apps for the current user. Request JSON object: ``` { version: "1", appuuid: "your-app-uuid", token: "current time based token" } ``` Response JSON object: ``` { status: "OK", apps: [ { name: "name of your web app" appuuid: "UUID of your app", }, { name: "name of your second web app" appuuid: "UUID of your second app", } ] } ``` ### GET /app/UUID Get seed for APP to be used as a token Request JSON object: ``` { version: "1", appuuid: "your-app-uuid", token: "current time based token" } ``` Response JSON object: ``` { status: "OK", seed: "seed of your app" } ``` ## Usage: OTP The seeds that you receive can be used for TOTP to authenticate your apps. ## Database The database saves a list of appuuids with their seeds and the user assignments as well as whether the appuuid might use the BUS interface. Fields: - appuuid (a random UUID) - appname (name chosen by the user) - username (who this appuuid belongs to) - seed (a random base32 string) - trusted (boolean, whether app is allowed to use the BUS and the verify method) ## Environment / Configuration - POSTGRES_USERNAME - SECRET_KEY -- random ## Random notes / stuff django.db.backends.postgresql django.contrib.admin ``` DATABASES = { 'default': { 'ENGINE': 'django.db.backends.postgresql', 'NAME': 'mydatabase', 'USER': 'mydatabaseuser', 'PASSWORD': 'mypassword', 'HOST': '127.0.0.1', 'PORT': '5432', } } ```