Be python friendly, don't use dashes

README.md

@@ -1,10 +1,28 @@
-# ungleich-otp
+# 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) seed and
-creates time based tokens (See python pyotp, RFC4226, RFC6238).
+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 ##
 
@@ -54,84 +72,14 @@ them to verify a token of somebody else.
 | 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
+## Environment / Configuration (unfinished)
 
 - POSTGRES_USERNAME
-- SECRET_KEY -- random
+- SECRET_KEY -- random (?)
 
-## Random notes / stuff
+
+## Random notes / stuff  (unfinished)
 
 django.db.backends.postgresql
 django.contrib.admin
@@ -177,32 +125,6 @@ Don’t forget to point AUTH_USER_MODEL to it. Do this before creating any migra
 
 
 
-## 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
-- [x]
-- [ ] 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
@@ -210,6 +132,133 @@ Don’t forget to point AUTH_USER_MODEL to it. Do this before creating any migra
 * 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

ungleichotp/ungleichotp.py

@@ -0,0 +1,16 @@
+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)

ungleichotpclient/ungleichotpclient/settings.py

@@ -37,6 +37,8 @@ INSTALLED_APPS = [
     'django.contrib.sessions',
     'django.contrib.messages',
     'django.contrib.staticfiles',
+    'rest_framework',
+    'restapp'
 ]
 
 MIDDLEWARE = [

ungleichotpserver/manage.py

@@ -3,7 +3,7 @@ import os
 import sys
 
 if __name__ == '__main__':
-    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'ungleichotp.settings')
+    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'ungleichotpserver.settings')
     try:
         from django.core.management import execute_from_command_line
     except ImportError as exc:

ungleichotpserver/otpauth/serializer.py

@@ -3,6 +3,7 @@ from otpauth.models import OTPSeed
 import pyotp
 import otpauth
 
+# For accessing / modifying the data
 class OTPSerializer(serializers.ModelSerializer):
     class Meta:
         model = OTPSeed
@@ -13,6 +14,7 @@ class OTPSerializer(serializers.ModelSerializer):
         validated_data['seed'] = pyotp.random_base32()
         return OTPSeed.objects.create(**validated_data)
 
+# For parsing authentication
 class TokenSerializer(serializers.Serializer):
     name = serializers.CharField(max_length=128)
     token = serializers.CharField(max_length=128)
@@ -42,6 +44,7 @@ class TokenSerializer(serializers.Serializer):
 
         return (db_instance, token_in)
 
+# For verifying a token
 class VerifySerializer(TokenSerializer):
     verifyname = serializers.CharField(max_length=128)
     verifytoken = serializers.CharField(max_length=128)

ungleichotpserver/otpauth/views.py

@@ -9,7 +9,7 @@ from django.http import JsonResponse
 from otpauth.serializer import VerifySerializer, OTPSerializer
 from otpauth.models import OTPSeed
 
-
+#
 class OTPVerifyViewSet(viewsets.ModelViewSet):
     serializer_class = OTPSerializer
     queryset = OTPSeed.objects.all()

ungleichotpserver/ungleichotpserver/settings.py

@@ -51,7 +51,7 @@ MIDDLEWARE = [
     'django.middleware.clickjacking.XFrameOptionsMiddleware',
 ]
 
-ROOT_URLCONF = 'ungleichotp.urls'
+ROOT_URLCONF = 'ungleichotpserver.urls'
 
 TEMPLATES = [
     {
@@ -69,7 +69,7 @@ TEMPLATES = [
     },
 ]
 
-WSGI_APPLICATION = 'ungleichotp.wsgi.application'
+WSGI_APPLICATION = 'ungleichotpserver.wsgi.application'
 
 
 # Database