The ungleich OTP service
Go to file
PCoder 6ba71545a1 Fix psycopg2 bug
Internal Server Error: /admin/login/
Traceback (most recent call last):
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/core/handlers/", line 34, in inner
    response = get_response(request)
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/core/handlers/", line 115, in _get_response
    response = self.process_exception_by_middleware(e, request)
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/core/handlers/", line 113, in _get_response
    response = wrapped_callback(request, *callback_args, **callback_kwargs)
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/views/decorators/", line 44, in _wrapped_view_func
    response = view_func(request, *args, **kwargs)
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/contrib/admin/", line 399, in login
    return LoginView.as_view(**defaults)(request)
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/views/generic/", line 71, in view
    return self.dispatch(request, *args, **kwargs)
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/utils/", line 45, in _wrapper
    return bound_method(*args, **kwargs)
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/views/decorators/", line 76, in sensitive_post_parameters_wrapper
    return view(request, *args, **kwargs)
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/utils/", line 45, in _wrapper
    return bound_method(*args, **kwargs)
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/utils/", line 142, in _wrapped_view
    response = view_func(request, *args, **kwargs)
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/utils/", line 45, in _wrapper
    return bound_method(*args, **kwargs)
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/views/decorators/", line 44, in _wrapped_view_func
    response = view_func(request, *args, **kwargs)
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/contrib/auth/", line 61, in dispatch
    return super().dispatch(request, *args, **kwargs)
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/views/generic/", line 97, in dispatch
    return handler(request, *args, **kwargs)
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/views/generic/", line 141, in post
    if form.is_valid():
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/forms/", line 185, in is_valid
    return self.is_bound and not self.errors
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/forms/", line 180, in errors
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/forms/", line 382, in full_clean
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/forms/", line 409, in _clean_form
    cleaned_data = self.clean()
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/contrib/auth/", line 205, in clean
    self.user_cache = authenticate(self.request, username=username, password=password)
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/contrib/auth/", line 73, in authenticate
    user = backend.authenticate(request, **credentials)
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/contrib/auth/", line 20, in authenticate
    user = UserModel._default_manager.get_by_natural_key(username)
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/contrib/auth/", line 44, in get_by_natural_key
    return self.get(**{self.model.USERNAME_FIELD: username})
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/db/models/", line 82, in manager_method
    return getattr(self.get_queryset(), name)(*args, **kwargs)
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/db/models/", line 402, in get
    num = len(clone)
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/db/models/", line 256, in __len__
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/db/models/", line 1242, in _fetch_all
    self._result_cache = list(self._iterable_class(self))
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/db/models/", line 55, in __iter__
    results = compiler.execute_sql(chunked_fetch=self.chunked_fetch, chunk_size=self.chunk_size)
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/db/models/sql/", line 1175, in execute_sql
    return list(result)
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/db/models/sql/", line 1554, in cursor_iter
    for rows in iter((lambda: cursor.fetchmany(itersize)), sentinel):
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/db/models/sql/", line 1554, in <lambda>
    for rows in iter((lambda: cursor.fetchmany(itersize)), sentinel):
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/db/", line 96, in inner
    return func(*args, **kwargs)
  File "/home/app/pyvenv/lib/python3.9/site-packages/django/db/backends/postgresql/", line 6, in utc_tzinfo_factory
    raise AssertionError("database connection isn't set to UTC")

2021-11-03 19:48:37 +05:30
logs Add logs directory 2019-02-10 23:37:15 +01:00
otpauth Set name, realm and seed for superusers also 2019-09-26 15:26:10 +05:30
ungleichotpserver Add missing parenthesis 2019-09-26 15:45:54 +05:30
.env.sample Set ALLOWED_HOSTS from .env 2019-09-26 15:16:07 +05:30
.gitignore Update .gitignore 2019-02-10 23:31:26 +01:00 Update 2019-06-08 09:36:55 +02:00 Restructure -> easier checkout on app server 2018-12-30 18:10:45 +01:00
requirements.txt Fix psycopg2 bug 2021-11-03 19:48:37 +05:30 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, verify                       |
| all other realms | authenticate                               |

Verify using http POST

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

Request JSON object:

    auth_name: "auth-name",
    auth_realm: "auth-realm",
    auth_token: "current time based token",
    name: "name that wants to be authenticated",
    realm: "realm that wants to be authenticated",
    token: "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