API 1.2.0
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
|
## 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.
|
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 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
|
### Token control
|
||||||
|
Refer to the API documentation.
|
||||||
|
You can list the tokens and delete tokens.
|
||||||
|
|
||||||
### New device token creation
|
### 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 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
|
# Changelog
|
||||||
## authorization_tokens branch
|
## 1.2.0
|
||||||
- Added authorization tokens module to allow
|
- Added authorization tokens module to allow
|
||||||
- Having more than one device controlling the server
|
- Having more than one device controlling the server
|
||||||
- Refreshing the current token
|
- Refreshing the current token
|
||||||
- Obtaining a recovery token
|
- Obtaining a recovery token
|
||||||
### API changes
|
### 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
|
## 1.1.1
|
||||||
Released on 26 Jan 2022
|
Released on 26 Jan 2022
|
||||||
|
|
||||||
|
|
|
@ -40,11 +40,11 @@ Git repository at `/etc/nixos` is using `rolling-testing` branch.
|
||||||
## Create tokens JSON file
|
## Create tokens JSON file
|
||||||
**Migration ID**: `create_tokens_json`
|
**Migration ID**: `create_tokens_json`
|
||||||
|
|
||||||
**Introduced in**: [[changelog#authorization_tokens branch]]
|
**Introduced in**: [[changelog#1 2 0|v1.2.0]]
|
||||||
|
|
||||||
### Description
|
### Description
|
||||||
Selfprivacy API used a single token in userdata.json for authentication.
|
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.
|
This migration creates a new `tokens.json` file with the old token in it.
|
||||||
|
|
||||||
### Run conditions
|
### Run conditions
|
||||||
`/etc/nixos/userdata/tokens.json` does not exist.
|
`/etc/nixos/userdata/tokens.json` does not exist.
|
||||||
|
|
Loading…
Reference in New Issue