ungleich-otp/README.md

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',
    }
}