Token Authentication

Once a user is authenticated, a token is generated for authorisation and access to a NebularStack environment. A token can have a variable life span; however, the default expiry value is one hour. The recommended expiry value is set to a low value that allows enough time to complete tasks.

In short, NebularStack uses JWT (JSON Web tokens), which is the proposed Internet standard for creating data with optional signature and/or optional encryption whose payload holds JSON that asserts some number of claims. The claims in our case would be role assignments and the current scoped domain and tenant. The tokens are signed using certificates. Any tampering with the token would invalidate it.

Using token authentication, you have un-scoped and scoped tokens. Scoped means the token has been generated for a specific domain or domain and tenant. Based on the roles assigned to the authenticated user for the domain and tenant, those roles are set within the token.

Tokens can be renewed anytime and re-scoped to another domain and tenant. During the re-scope or renewal, a newly updated token is provided. If your token is scoped to a domain and not within a tenant with sufficient roles to perform desired actions on all relevant tenants, you only need to use the X-Tenant-ID header on any requests in that domain to set the tenant-id for the request.

Almost all requests require a X-Auth-Token header to any service endpoint.

{
    "username": "test@example.com",
    "user_domain": "example.com",
    "domain": "example.com",
    "credentials": {
        "password": "secret"
    }
}

{
    "user_id": "c31a8f26-26e2-11ee-8506-af6e8a7f3a67",
    "metadata": {
        "name": "Test User Name",
        "system": false
    },
    "username": "test@example.com",
    "user_domain": "example.com",
    "domain": "example",
    "exp": 1689849985,
    "roles": [
        "Root"
    ],
    "token": "TOKEN_FOR_X-AUTH-TOKEN_HEADER"
}

Scope Token Context

It is necessary to update a token to change context, when working with an unscoped token.

{
    "domain": "{domain}",
    "tenant_id": "{tenant_id}"
}

{
    "user_id": "c31a8f26-26e2-11ee-8506-af6e8a7f3a67",
    "metadata": {
        "name": "Test User Name",
        "system": false
    },
    "username": "test@example.com",
    "user_domain": "example.com",
    "domain": "example",
    "exp": 1689849985,
    "roles": [
        "Root"
    ],
    "token": "TOKEN_FOR_X-AUTH-TOKEN_HEADER"
}

Renew Token

{
    "user_id": "c31a8f26-26e2-11ee-8506-af6e8a7f3a67",
    "metadata": {
        "name": "Test User Name",
        "system": false
    },
    "username": "test@example.com",
    "user_domain": "example.com",
    "domain": "example",
    "exp": 1689849985,
    "roles": [
        "Root"
    ],
    "token": "TOKEN_FOR_X-AUTH-TOKEN_HEADER"
}