ungleich-otp/README.md
2018-11-18 13:24:09 +01:00

216 lines
4.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 (See python pyotp, RFC4226, RFC6238).
## 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 |
## Usage: REST ##
- Use an existing token to connect to the service
- All REST based messages: JSON
### POST: /ungleichotp/verify
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."}
```
### GET, POST, ... /ungleichotp/
Standard django rest framework behaviour for updating / listing
objects.
## 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',
}
}
```
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
Dont forget to point AUTH_USER_MODEL to it. Do this before creating any migrations or running manage.py migrate for the first time.
## TODOs
- [x] serialize / input request
- [x] Make seed read only
- [x] Implement registering of new entries
- [x] OTPSerializer: allow to read seed for admin
- [x] Implement deleting entry
- [x] Include verify in ModelSerializer
- [x] Maybe we map name+realm == User (?)
- name == name@realm
- password is used for admin login (?)
- seed
- custom auth method
- [n] try to fake username for django based on name+realm (?)
- [n] maybe overwrite get_username() (?)
- [x] Use Custom authentication - needs to have a user!
- [x] Implement creating new "User"
- by POST / Model based
- [ ] Add tests for verify
- [ ] Add tests for authentication
- [ ] Add proper documentation
- [ ] move totp constants into settings
- [ ] move field lengths into settings
- [ ] make settings adjustable by environment (?)
- [ ] Remove hard coded JSON (?)
### To document
* Login via username password interactively
* Login via name/realm/token rest
## Changelog
### 0.5, 2018-11-18
* Require authentication on all rest endpoints by token