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:

{
    "$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.:

{
    "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 _

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 _