API 1.2.0
inexcode
parent
1e7e9f384c
commit
ab395730eb
|
|
@ -4,6 +4,151 @@ At that time, only one access token could be used. It is declared during nixos-i
|
|||
## After 1.2.0
|
||||
New auth system was introduced in 1.2.0. See [[migrations#Create tokens JSON file]] for details on migration to the new system.
|
||||
### Tokens storage
|
||||
Tokens are stored in `/etc/nixos/userdata/tokens.json`, which can be accessed only by root.
|
||||
File follows this schema:
|
||||
```json
|
||||
{
|
||||
"$schema": "http://json-schema.org/schema#",
|
||||
"$id": "https://git.selfprivacy.org/inex/selfprivacy-nixos-config/raw/branch/master/userdata/tokens_schema.json",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"tokens": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"token": {
|
||||
"type": "string"
|
||||
},
|
||||
"name": {
|
||||
"type": "string"
|
||||
},
|
||||
"date": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"token",
|
||||
"name",
|
||||
"date"
|
||||
]
|
||||
}
|
||||
},
|
||||
"recovery_token": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"token": {
|
||||
"type": "string"
|
||||
},
|
||||
"date": {
|
||||
"type": "string"
|
||||
},
|
||||
"expiration": {
|
||||
"type": "string"
|
||||
},
|
||||
"uses_left": {
|
||||
"type": "integer"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"token",
|
||||
"date"
|
||||
]
|
||||
},
|
||||
"new_device": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"token": {
|
||||
"type": "string"
|
||||
},
|
||||
"date": {
|
||||
"type": "string"
|
||||
},
|
||||
"expiration": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"token",
|
||||
"date",
|
||||
"expiration"
|
||||
]
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"tokens"
|
||||
]
|
||||
}
|
||||
```
|
||||
i.e.:
|
||||
```json
|
||||
{
|
||||
"tokens": [
|
||||
{
|
||||
"token": "device token",
|
||||
"name": "device name",
|
||||
"date": "date of creation",
|
||||
}
|
||||
],
|
||||
"recovery_token": {
|
||||
"token": "recovery token",
|
||||
"date": "date of creation",
|
||||
"expiration": "date of expiration",
|
||||
"uses_left": "number of uses left"
|
||||
},
|
||||
"new_device": {
|
||||
"token": "new device auth token",
|
||||
"date": "date of creation",
|
||||
"expiration": "date of expiration",
|
||||
}
|
||||
}
|
||||
```
|
||||
All dates MUST follow the `%Y-%m-%dT%H:%M:%S.%fZ` format.
|
||||
### Token control
|
||||
Refer to the API documentation.
|
||||
You can list the tokens and delete tokens.
|
||||
|
||||
### New device token creation
|
||||
To authorize a new device, existing authorized device must acquire a new device token.
|
||||
|
||||
POST `/auth/new_device` is used without any arguments.
|
||||
|
||||
New device tokens are 16 random bytes encoded to the mnemonic phrase. Token lifetime is 10 minutes or less. There can only be one token for new device auth.
|
||||
|
||||
This token is used by the new device to get a proper access token.
|
||||
|
||||
POST `/auth/new_device/authorize` is used with two arguments:
|
||||
- `token` is the new device token.
|
||||
- If new device token is incorrect, does not exist of expired, 404 error is returned
|
||||
- `device` is the device name.
|
||||
- If the name already taken, random suffix will be added.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
actor A as Authorized device
|
||||
participant Server
|
||||
actor B as New device
|
||||
A->>+Server: /auth/new_device
|
||||
Server-->>A: Mnemonic token
|
||||
Note over A,B: Mnemonic token is used by new device to get access token
|
||||
B->>Server: /auth/new_device/authorize
|
||||
Server-->>-B: Access token
|
||||
```
|
||||
### Recovery token
|
||||
Recovery tokens are 24 random bytes encoded to the mnemonic phrase. Optionally, token lifetime and allowed uses can be limited.
|
||||
|
||||
Only one recovery token can exist at a time. If a new token is generated, the old one is deleted.
|
||||
|
||||
POST `/auth/recovery_token` is used to generate a recovery token. There are two *optional* arguments:
|
||||
- `expiration` is the datetime when token must expire.
|
||||
- MUST follow the `%Y-%m-%dT%H:%M:%S.%fZ` format.
|
||||
- Returns 400 if time format is incorrect
|
||||
- Returns 400 if date is in the past
|
||||
- `uses` is how many times the recovery token can be used
|
||||
- MUST be 1 or more.
|
||||
|
||||
POST `/auth/recovery_token/use` to use the token. Two required arguments:
|
||||
- `token` is the recovery token
|
||||
- If recovery token is incorrect, does not exist of expired, 404 error is returned
|
||||
- `device` is the device name
|
||||
- If the name already taken, random suffix will be added.
|
||||
|
|
@ -1,11 +1,18 @@
|
|||
# Changelog
|
||||
## authorization_tokens branch
|
||||
## 1.2.0
|
||||
- Added authorization tokens module to allow
|
||||
- Having more than one device controlling the server
|
||||
- Refreshing the current token
|
||||
- Obtaining a recovery token
|
||||
### API changes
|
||||
-
|
||||
- `/auth/tokens` added
|
||||
- `/auth/new_device` added
|
||||
- **Public endpoint** `/auth/new_device/authorize` added.
|
||||
- `/auth/recovery_token` added
|
||||
- **Public endpoint** `/auth/recovery_token/use` added.
|
||||
### New migrations
|
||||
- [[migrations#Create tokens JSON file|Migrate to new tokens storage]]
|
||||
|
||||
## 1.1.1
|
||||
Released on 26 Jan 2022
|
||||
|
||||
|
|
|
|||
|
|
@ -40,11 +40,11 @@ Git repository at `/etc/nixos` is using `rolling-testing` branch.
|
|||
## Create tokens JSON file
|
||||
**Migration ID**: `create_tokens_json`
|
||||
|
||||
**Introduced in**: [[changelog#authorization_tokens branch]]
|
||||
**Introduced in**: [[changelog#1 2 0|v1.2.0]]
|
||||
|
||||
### Description
|
||||
Selfprivacy API used a single token in userdata.json for authentication.
|
||||
This migration creates a new tokens.json file with the old token in it.
|
||||
Selfprivacy API used a single token in `userdata.json` for authentication.
|
||||
This migration creates a new `tokens.json` file with the old token in it.
|
||||
|
||||
### Run conditions
|
||||
`/etc/nixos/userdata/tokens.json` does not exist.
|
||||
|
|
|
|||
Loading…
Reference in New Issue