ungleich-otp/README.md

# 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