ungleich-otp/README.md

211 lines
3.1 KiB
Markdown
Raw Normal View History

2018-10-26 16:31:36 +00:00
# ungleich-otp
2018-10-26 17:22:17 +00:00
The ungleich OTP service that allows you access to the ungleich micro
service infrastructure.
We are using
- nameko for internal communication
- django for the DB + admin interface
2018-10-26 17:36:34 +00:00
## Status
In development, pre production.
2018-10-26 17:22:17 +00:00
## Usage: WEB
- No user interface (UI) supported (?)
-> idea is to keep flow logic in ungleich-dynamicweb
2018-10-26 17:45:36 +00:00
## Usage: BUS
2018-10-26 19:48:21 +00:00
### RPC: verify(appuuid, token, appuuidtoverify, tokentoverify)
2018-10-26 17:45:36 +00:00
Verify whether the requesting app is authenticated. This is only
2018-10-26 19:48:21 +00:00
allowed to be used for trusted appuuids.
2018-10-26 17:45:36 +00:00
2018-10-26 17:48:15 +00:00
Returns a JSON object:
Either
```
{
2018-10-26 20:00:47 +00:00
status: "OK"
2018-10-26 17:48:15 +00:00
}
```
OR
```
{
2018-10-26 20:00:47 +00:00
status: "FAIL"
2018-10-26 17:48:15 +00:00
}
```
2018-10-26 17:50:56 +00:00
## Usage: REST
- Use an existing token to connect to the service
- All REST based messages: JSON
2018-10-26 17:45:36 +00:00
### POST: /verify
Not sure if this one will be publicly available.
2018-10-26 17:48:15 +00:00
Request JSON object:
2018-10-26 17:45:36 +00:00
```
{
version: "1",
2018-10-26 19:48:21 +00:00
appuuid: "your-app-uuid",
2018-10-26 17:45:36 +00:00
token: "current time based token",
2018-10-26 19:48:21 +00:00
appuuidtoverify: "appuuid that wants to be authenticated",
tokentoverify: "current time based token of appuuidtoverify",
2018-10-26 17:45:36 +00:00
}
```
2018-10-26 17:48:15 +00:00
Response JSON object:
Either
```
{
status: "OK",
}
```
OR
```
{
status: "FAIL",
}
```
2018-10-26 17:22:17 +00:00
### POST /app/register
Register a new app. Returns an app ID.
2018-10-26 17:31:18 +00:00
Request JSON object:
{
2018-10-26 17:34:17 +00:00
version: "1",
2018-10-26 19:48:21 +00:00
appuuid: "your-app-uuid",
2018-10-26 17:34:17 +00:00
token: "current time based token",
username: "user this app belongs to",
appname: "name of your web app"
2018-10-26 17:31:18 +00:00
}
Response JSON object:
2018-10-26 17:50:56 +00:00
```
2018-10-26 17:31:18 +00:00
{
2018-10-26 17:50:56 +00:00
status: "OK",
2018-10-26 19:48:21 +00:00
appuuid: "UUID of your app",
2018-10-26 17:31:18 +00:00
}
2018-10-26 17:50:56 +00:00
```
2018-10-26 17:31:18 +00:00
2018-10-26 17:50:56 +00:00
OR
```
{
status: "FAIL",
error: "Reason for failure"
}
```
2018-10-26 17:31:18 +00:00
2018-10-26 17:22:17 +00:00
### GET /app
List all registered apps for the current user.
2018-10-26 17:31:18 +00:00
Request JSON object:
{
2018-10-26 17:34:17 +00:00
version: "1",
2018-10-26 19:48:21 +00:00
appuuid: "your-app-uuid",
2018-10-26 17:31:18 +00:00
token: "current time based token"
}
Response JSON object:
2018-10-26 17:22:17 +00:00
2018-10-26 17:51:33 +00:00
```
2018-10-26 17:50:56 +00:00
{
status: "OK",
apps: [
{
name: "name of your web app"
2018-10-26 19:48:21 +00:00
appuuid: "UUID of your app",
2018-10-26 17:50:56 +00:00
},
{
name: "name of your second web app"
2018-10-26 19:48:21 +00:00
appuuid: "UUID of your second app",
2018-10-26 17:50:56 +00:00
}
]
}
2018-10-26 17:51:33 +00:00
```
2018-10-26 17:31:18 +00:00
### GET /app/UUID
2018-10-26 17:22:17 +00:00
Get seed for APP to be used as a token
2018-10-26 17:31:18 +00:00
Request JSON object:
2018-10-26 17:51:33 +00:00
```
2018-10-26 17:31:18 +00:00
{
2018-10-26 17:34:17 +00:00
version: "1",
2018-10-26 19:48:21 +00:00
appuuid: "your-app-uuid",
2018-10-26 17:31:18 +00:00
token: "current time based token"
}
2018-10-26 17:51:33 +00:00
```
2018-10-26 17:31:18 +00:00
Response JSON object:
2018-10-26 17:51:33 +00:00
```
2018-10-26 17:31:18 +00:00
{
2018-10-26 17:51:33 +00:00
status: "OK",
2018-10-26 17:31:18 +00:00
seed: "seed of your app"
}
2018-10-26 17:51:33 +00:00
```
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
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.postgresql',
'NAME': 'mydatabase',
'USER': 'mydatabaseuser',
'PASSWORD': 'mypassword',
'HOST': '127.0.0.1',
'PORT': '5432',
}
}