ungleich-otp/README.md

222 lines
5 KiB
Markdown
Raw Normal View History

2018-10-26 16:31:36 +00:00
# ungleich-otp
ungleich-otp is a full blown authentication and authorisation service
made for micro services.
2018-10-26 17:22:17 +00:00
The basic idea is that every micro service has a (long term) seed and
2018-11-17 10:39:42 +00:00
creates time based tokens (See python pyotp, RFC4226, RFC6238).
2018-10-26 17:22:17 +00:00
## Setup instructions ##
2018-10-26 17:22:17 +00:00
This is a standard django project and thus can be easily setup using
2018-10-26 17:36:34 +00:00
```
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
```
2018-10-26 17:36:34 +00:00
After that, you can run the application using
2018-10-26 17:22:17 +00:00
```
python manage.py runserver
```
2018-10-26 17:22:17 +00:00
The usual instructions on how to setup an https proxy should be followed.
2018-10-26 17:45:36 +00:00
## Realms ##
2018-10-26 17:45:36 +00:00
Access is granting/denied based on realms. There are two reserved
realms, all other realms can be used by the users:
2018-10-26 17:45:36 +00:00
2018-11-17 08:51:06 +00:00
### 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
2018-11-17 18:00:48 +00:00
### POST: /ungleichotp/verify
Request JSON object:
2018-10-26 17:48:15 +00:00
```
{
version: "1",
2018-11-17 10:39:42 +00:00
name: "your-name",
realm: "your-realm",
token: "current time based token",
2018-11-17 10:39:42 +00:00
verifyname: "name that wants to be authenticated",
verifyrealm: "realm that wants to be authenticated",
verifytoken: "token that wants to be authenticated",
2018-10-26 17:48:15 +00:00
}
```
Response JSON object:
2018-10-26 17:48:15 +00:00
2018-11-17 21:53:51 +00:00
Either HTTP 200 with
2018-10-26 17:48:15 +00:00
```
{
status: "OK",
2018-10-26 17:48:15 +00:00
}
```
2018-11-17 21:53:51 +00:00
OR return code 403:
2018-10-26 17:48:15 +00:00
2018-11-17 21:53:51 +00:00
* If token for authenticating is wrong, you get
2018-10-26 17:48:15 +00:00
2018-10-26 17:45:36 +00:00
```
2018-11-17 21:53:51 +00:00
{"detail":"Incorrect authentication credentials."}
2018-10-26 17:48:15 +00:00
```
2018-11-17 21:53:51 +00:00
* If token that is being verified is wrong, you get
2018-10-26 17:48:15 +00:00
```
2018-11-17 21:53:51 +00:00
{"detail":"You do not have permission to perform this action."}
2018-10-26 17:50:56 +00:00
```
2018-10-26 17:31:18 +00:00
2018-11-17 21:53:51 +00:00
### GET, POST, ... /ungleichotp/
2018-10-26 17:50:56 +00:00
2018-11-17 21:53:51 +00:00
Standard django rest framework behaviour for updating / listing
objects.
2018-10-26 17:22:17 +00:00
2018-10-26 17:45:36 +00:00
2018-10-26 17:22:17 +00:00
## Usage: OTP
The seeds that you receive can be used for TOTP to authenticate your
apps.
## Database
2018-10-26 19:48:21 +00:00
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.
2018-10-26 17:22:17 +00:00
Fields:
2018-10-26 19:48:21 +00:00
- appuuid (a random UUID)
2018-10-26 17:22:17 +00:00
- appname (name chosen by the user)
2018-10-26 19:48:21 +00:00
- username (who this appuuid belongs to)
2018-10-26 17:22:17 +00:00
- seed (a random base32 string)
2018-10-26 19:48:21 +00:00
- 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
2018-10-27 10:09:05 +00:00
```
2018-10-26 19:48:21 +00:00
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.postgresql',
'NAME': 'mydatabase',
'USER': 'mydatabaseuser',
'PASSWORD': 'mypassword',
'HOST': '127.0.0.1',
'PORT': '5432',
}
}
2018-10-27 10:09:05 +00:00
```
2018-11-17 17:48:12 +00:00
2018-11-17 18:00:48 +00:00
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)
```
2018-11-17 20:45:53 +00:00
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.
2018-11-17 17:48:12 +00:00
## TODOs
2018-11-17 18:00:48 +00:00
- [x] serialize / input request
2018-11-17 21:15:17 +00:00
- [x] Make seed read only
2018-11-17 21:28:17 +00:00
- [x] Implement registering of new entries
- [x] OTPSerializer: allow to read seed for admin
- [x] Implement deleting entry
2018-11-17 21:53:51 +00:00
- [x] Include verify in ModelSerializer
- [x] Maybe we map name+realm == User (?)
2018-11-17 20:45:53 +00:00
- name == name@realm
- password is used for admin login (?)
2018-11-17 20:45:53 +00:00
- 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"
2018-11-17 20:45:53 +00:00
- by POST / Model based
2018-11-18 12:42:16 +00:00
- [x]
- [ ] Add tests for verify
- [ ] Add tests for authentication
- [ ] Add proper documentation
2018-11-17 21:53:51 +00:00
- [ ] move totp constants into settings
- [ ] move field lengths into settings
- [ ] make settings adjustable by environment (?)
- [ ] Remove hard coded JSON (?)
2018-11-18 12:24:09 +00:00
### To document
* Login via username password interactively
* Login via name/realm/token rest
## Changelog
2018-11-18 12:24:09 +00:00
2018-11-18 12:42:16 +00:00
### 0.6, 2018-11-18
* Reuse TokenSerializer for VerifySerializer logic
2018-11-18 12:24:09 +00:00
### 0.5, 2018-11-18
* Require authentication on all rest endpoints by token