156 lines
4.9 KiB
Markdown
156 lines
4.9 KiB
Markdown
# Authorization
|
|
## Before 1.2.0
|
|
At that time, only one access token could be used. It is declared during nixos-infect stage and generated by the mobile app.
|
|
## 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.
|
|
- Name SHOULD only contain `[^a-zA-Z0-9]`. All other symbols will be replaced with `_`
|
|
|
|
```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.
|
|
- Name SHOULD only contain `[^a-zA-Z0-9]`. All other symbols will be replaced with `_` |