ungleich-otp/README.md

198 lines
5.7 KiB
Markdown
Raw Normal View History

2018-11-18 13:33:30 +00:00
# ungleichotp #
2018-10-26 16:31:36 +00:00
ungleich-otp is a full blown authentication and authorisation service
made for micro services.
2018-10-26 17:22:17 +00:00
2018-11-18 13:33:30 +00:00
The basic idea is that every micro service has a (long term) triple
constisting of (name, realm, seed) and creates time based tokens.
2018-12-24 19:28:21 +00:00
This basically revamps Kerberos in a simple way into the web area.
2018-11-18 13:33:30 +00:00
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)
2018-12-24 19:46:54 +00:00
## Overview ##
2018-11-18 13:33:30 +00:00
2018-12-24 19:46:54 +00:00
This repository contains...
2018-11-18 13:33:30 +00:00
2018-12-24 19:46:54 +00:00
* ungleichotpserver: the reference implementation of the ungleichotp server
* ungleichotpclient.py: a sample implementation of an ungleichotp client
2018-11-18 13:33:30 +00:00
2018-10-26 17:22:17 +00:00
2018-12-24 19:46:54 +00:00
## Verifying a token using ungleichotpclient.py ##
2018-12-24 19:28:21 +00:00
2018-12-24 19:46:54 +00:00
Assuming you want to verify
(name=ipv6only, realm=ungleich-intern, token=498593) is a
valid triple and you do have credentials to access ungleich-otp
(name=info@ungleich.ch, realm=ungleich-admin, seed=PZKBPTHDGSLZBKIZ),
then the following call will verify the token:
2018-10-26 17:36:34 +00:00
```
2018-12-24 19:46:54 +00:00
UNGLEICHOTPNAME=info@ungleich.ch \
UNGLEICHOTPREALM=ungleich-admin \
UNGLEICHOTPSEED=PZKBPTHDGSLZBKIZ \
UNGLEICHOTPSERVER=http://localhost:8000/ungleichotp/verify/ \
python ungleichotpclient.py -n -r ungleich --token 498593
```
2018-12-24 19:46:54 +00:00
You can also veriy using a seed:
```
2018-12-24 19:46:54 +00:00
UNGLEICHOTPNAME=info@ungleich.ch \
UNGLEICHOTPREALM=ungleich-admin \
UNGLEICHOTPSEED=PZKBPTHDGSLZBKIZ \
UNGLEICHOTPSERVER=http://localhost:8000/ungleichotp/verify/ \
python ungleichotpclient.py -n -r ungleich --seed CEKXVG3235PO2HDW
```
2018-10-26 17:36:34 +00:00
2018-12-24 19:46:54 +00:00
The client requires pyotp.
## Server Setup instructions ##
This is a standard django project and thus can be easily setup using
2018-10-26 17:22:17 +00:00
```
2018-12-24 19:46:54 +00:00
pip install -r requirements.txt
python manage.py createsuperuser
python manage.py runserver
```
2018-10-26 17:22:17 +00:00
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 |
2018-10-26 17:22:17 +00:00
2018-12-24 19:46:54 +00:00
## Verify using http POST ##
2018-11-18 13:33:30 +00:00
2018-12-24 19:46:54 +00:00
Post a JSON object to the server at /ungleichotp/verify/ that
contains the following elements:
2018-11-18 13:33:30 +00:00
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."}
```
2018-12-24 19:46:54 +00:00
## Authorize the request ##
2018-11-18 13:33:30 +00:00
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.
2018-11-18 14:41:47 +00:00
## Limitations ##
* Name, Realm and seed are hard coded to 128 bytes length. This can be
changed, if necessary.
* Only python3 support for ungleichotp
2018-11-17 17:48:12 +00:00
## TODOs
2018-11-18 13:33:30 +00:00
- [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 (?)
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
2018-11-18 13:33:30 +00:00
- [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)
2018-11-18 14:41:47 +00:00
- [x] (server) Fully rename server from ungleichotp to ungleichotpserver
2018-11-18 13:33:30 +00:00
- [ ] (security) Ensure that only the right realms can verify
- [ ] (security) Ensure that only the right realms can manage
2018-11-18 14:41:47 +00:00
- [ ] (doc) Add proper documentation
2018-11-18 13:33:30 +00:00
- [ ] (server) Add tests for verify
- [ ] (server) Add tests for authentication
- [ ] (server) move totp constants into settings
- [ ] (server) move field lengths into settings
2018-11-18 14:41:47 +00:00
- [ ] (server) Document how admin vs. rest works
2018-11-18 13:33:30 +00:00
- [ ] (server, client) Make settings adjustable by environment - k8s/docker compatible
- [ ] (server, client) Read DB from outside (?) (fallback to sqlite)
2018-11-18 14:41:47 +00:00
- [x] (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
2018-11-18 13:33:30 +00:00
- [ ] (library) Write a "client library" that can use ungleichotp
- [ ] (library) extract generic parts from server
- [ ] (library) upload to pypi
2018-11-18 12:24:09 +00:00
## 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