271 lines
6.8 KiB
Markdown
271 lines
6.8 KiB
Markdown
# ungleichotp #
|
||
|
||
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.
|
||
|
||
It basically revamps Kerberos in a simple way into the web area.
|
||
|
||
ungleichotp has been created and is maintained by [ungleich](https://ungleich.ch/).
|
||
|
||
Related documentation:
|
||
|
||
* [Python pyotp](https://pyotp.readthedocs.io/)
|
||
* [RFC6238, TOTP](https://tools.ietf.org/html/rfc6238)
|
||
* [RFC4120, Kerberos](https://tools.ietf.org/html/rfc4120)
|
||
|
||
## Overview
|
||
|
||
This repository contains three components:
|
||
|
||
* ungleichotp-server: the reference implementation of the ungleichotp server
|
||
* ungleichotp-client: a sample implementation of an ungleichotp client
|
||
|
||
|
||
## 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 |
|
||
|
||
|
||
|
||
## Environment / Configuration (unfinished)
|
||
|
||
- POSTGRES_USERNAME
|
||
- SECRET_KEY -- random (?)
|
||
|
||
|
||
## Random notes / stuff (unfinished)
|
||
|
||
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',
|
||
}
|
||
}
|
||
```
|
||
|
||
Custom auth
|
||
|
||
```
|
||
from django.contrib.auth.models import User
|
||
from rest_framework import authentication
|
||
from rest_framework import exceptions
|
||
|
||
class ExampleAuthentication(authentication.BaseAuthentication):
|
||
def authenticate(self, request):
|
||
username = request.META.get('X_USERNAME')
|
||
if not username:
|
||
return None
|
||
|
||
try:
|
||
user = User.objects.get(username=username)
|
||
except User.DoesNotExist:
|
||
raise exceptions.AuthenticationFailed('No such user')
|
||
|
||
return (user, None)
|
||
|
||
```
|
||
|
||
Custom user
|
||
|
||
Don’t forget to point AUTH_USER_MODEL to it. Do this before creating any migrations or running manage.py migrate for the first time.
|
||
|
||
|
||
|
||
|
||
|
||
### To document
|
||
|
||
* Login via username password interactively
|
||
* Login via name/realm/token rest
|
||
|
||
## The library (ungleichotp)
|
||
|
||
## The server (ungleichotp-server)
|
||
|
||
## The sample client (ungleichotp-client)
|
||
|
||
The included client application is a Django application that makes use
|
||
of an ungleichotp-server to authenticate requests.
|
||
|
||
### Usage
|
||
|
||
* Ensure that the ungleichotp-server is running and reachable
|
||
|
||
|
||
## Integrating ungleichotp
|
||
|
||
### In Django
|
||
|
||
|
||
### In other frameworks
|
||
|
||
In general, you will need to implement the following into your app for
|
||
resources that need to have an authenticated user:
|
||
|
||
#### Retrieve name, realm and token from the request
|
||
|
||
This is application specific. In the sample Django rest framework, we
|
||
use JSON to retrieve this values:
|
||
|
||
```
|
||
{
|
||
"name": "info@ungleich.ch",
|
||
"token": "947732",
|
||
"realm": "ungleich-admin",
|
||
"otherdata": "..."
|
||
}
|
||
|
||
```
|
||
#### Send name, realm and token from the request to the ungleichotp-server
|
||
|
||
Post a JSON object to /ungleichotp/verify that contains the following
|
||
elements:
|
||
|
||
Request JSON object:
|
||
|
||
```
|
||
{
|
||
version: "1",
|
||
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.
|
||
|
||
|
||
## TODOs
|
||
|
||
- [x] (server) Serialize / input request
|
||
- [x] (server) Make seed read only
|
||
- [x] (server) Implement registering of new entries
|
||
- [x] (server) OTPSerializer: allow to read seed for admin
|
||
- [x] (server) Implement deleting entry
|
||
- [x] (server) Include verify in ModelSerializer
|
||
- [x] (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
|
||
- [x] (server) Use Custom authentication - needs to have a user!
|
||
- [x] (server) Implement creating new "User" by POST / Model based
|
||
- [n] (server) Remove hard coded JSON in /verify (no - good enough for the moment)
|
||
- [ ] (security) Ensure that only the right realms can verify
|
||
- [ ] (security) Ensure that only the right realms can manage
|
||
- [ ] (server) Add tests for verify
|
||
- [ ] (server) Add tests for authentication
|
||
- [ ] (doc) Add proper documentation
|
||
- [ ] (server) move totp constants into settings
|
||
- [ ] (server) move field lengths into settings
|
||
- [ ] (server, client) Make settings adjustable by environment - k8s/docker compatible
|
||
- [ ] (server, client) Read DB from outside (?) (fallback to sqlite)
|
||
- [ ] (library) Write a "client library" that can use ungleichotp
|
||
- [ ] (library) extract generic parts from server
|
||
- [ ] (library) upload to pypi
|
||
- [ ] (client) Bootstrap Django + DRF (including an object for CRUD)
|
||
- [ ] (client) Add custom authentication / remote auth
|
||
- [ ] (server) Document how admin vs. rest works
|
||
- [ ] (server) Fully rename server from ungleichotp to ungleichotpserver
|
||
|
||
|
||
|
||
## Changelog
|
||
|
||
### 0.6, 2018-11-18
|
||
|
||
* Reuse TokenSerializer for VerifySerializer logic
|
||
|
||
### 0.5, 2018-11-18
|
||
|
||
* Require authentication on all rest endpoints by token
|