The ungleich OTP service
Go to file
PCoder d38b5378b0 More logging 2019-02-11 01:06:21 +01:00
logs Add logs directory 2019-02-10 23:37:15 +01:00
otpauth More logging 2019-02-11 01:06:21 +01:00
ungleichotpserver Load configs from .env and add basic logging config 2019-02-10 23:32:59 +01:00
.env.sample Add values to .env.sample 2019-02-10 23:30:17 +01:00
.gitignore Update .gitignore 2019-02-10 23:31:26 +01:00 Cleanup docs, remove debug print 2019-02-08 20:00:28 +01:00 Restructure -> easier checkout on app server 2018-12-30 18:10:45 +01:00
requirements.txt Add python-decouple requirement 2019-02-10 23:31:48 +01:00 Cleanup 2018-12-24 20:46:54 +01:00


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) triple constisting of (name, realm, seed) and creates time based tokens.

This basically revamps Kerberos in a simple way into the web area.

ungleichotp has been created and is maintained by ungleich.

Related documentation:


This repository the reference implementation of the ungleichotp server.

Using the ungleichotpclient

The client can be used to test the ungleich-otp-server.

All client commands need the parameters --auth-name and --auth-realm. Also either --auth-seed or --auth-token needs to be specified.

python ungleichotpclient create \
    --auth-name admin
    --auth-realm ungleich-admin
    [--auth-seed THESEEDFORADMIN]
    [--auth-token THECURRENTTOKEN]

Creating new users

--name USERNAME --realm REALMOFUSER create

The seed is randomly created.

Listing users


Deleting users

--name USERNAME --realm REALMOFUSER delete

Verifying a token is correct

Verify using:


You can also verify using a seed:

--name USERNAME --realm REALMOFUSER --seed SEEDOFUSER verify

Server Setup instructions

This is a standard django project and thus can be easily setup using

pip install -r requirements.txt
python createsuperuser
python runserver


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                                  |

Verify using http POST

Post a JSON object to the server at /ungleichotp/verify/ that contains the following elements:

Request JSON object:

    name: "your-name",
    realm: "your-realm",
    token: "current time based token",
    verifyname: "name that wants to be authenticated",
    verifyrealm: "realm that wants to be authenticated",
    verifytoken: "token that wants to be authenticated",

Response JSON object:

Either HTTP 200 with

    status: "OK",

OR return code 403:

  • If token for authenticating is wrong, you get
{"detail":"Incorrect authentication credentials."}
  • If token that is being verified is wrong, you get
{"detail":"You do not have permission to perform this action."}

Authorize the request

From the ungleichotp-server, you get a validated information that a name on a realm authenticated successfully. The associated permissions ("authorization") is application specific and needs to be decided by your application.


  • Name, Realm and seed are hard coded to 128 bytes length. This can be changed, if necessary.
  • Only python3 support for ungleichotp


  • (server) Serialize / input request
  • (server) Make seed read only
  • (server) Implement registering of new entries
  • (server) OTPSerializer: allow to read seed for admin
  • (server) Implement deleting entry
  • (server) Include verify in ModelSerializer
  • (server) Map name+realm == User (?)
    • name == name@realm
    • password is used for admin login (?)
    • seed
    • custom auth method
  • [n] (server) Try to fake username for django based on name+realm (?)
    • No need
  • [n] (server) maybe overwrite get_username()
    • No need
  • (server) Use Custom authentication - needs to have a user!
  • (server) Implement creating new "User" by POST / Model based
  • [n] (server) Remove hard coded JSON in /verify (no - good enough for the moment)
  • (server) Fully rename server from ungleichotp to ungleichotpserver
  • (security) Ensure that only the right realms can verify
  • (security) Ensure that only the right realms can manage
  • (doc) Add proper documentation
  • (server) Add tests for verify
  • (server) Add tests for authentication
  • (server) move totp constants into settings
  • (server) move field lengths into settings
  • (server) Document how admin vs. rest works
  • (server, client) Make settings adjustable by environment - k8s/docker compatible
  • (server, client) Read DB from outside (?) (fallback to sqlite)
  • (client) Establish auth using urllib
  • (client) Bootstrap Django + DRF (including an object for CRUD)
  • (client) Add custom authentication / remote auth
  • (client) Show case: any realm vs. specific realm
  • (library) Write a "client library" that can use ungleichotp
  • (library) extract generic parts from server
  • (library) upload to pypi


0.8, 2019-02-08

  • Verify needed to call super()

0.6, 2018-11-18

  • Reuse TokenSerializer for VerifySerializer logic

0.5, 2018-11-18

  • Require authentication on all rest endpoints by token