Tokens¶

The Alias authentication server can produce a range of different types of tokens which are used for different purposes.

ID Tokens¶

OpenID Connect ID tokens are JSON Web Tokens that authenticate users. An ID token verifies that the user controls the Alias account represented by the subject (sub claim) of the token - i.e. they have authenticated with Alias. They can be requested using an authorization code grant request that includes the openid scope.

ID tokens are signed with a JSON Web Key. The current JWK Set is available at /.well-known/jwks.json.

Alias uses pairwise subject identifiers to help preserve user privacy. This means that the sub claim is an alias ID, not the actual user ID. A client will always receive the same alias ID in sub for a given user, but different clients will receive different alias IDs.

Supported Claims

Claim	Description
`jti`	The ID for the token.
`iss`	The token issuer. Always `https://projectalias.com`.
`aud`	The ID for the client the token was issued to.
`iat`	When the token was issued.
`exp`	When the token will expire. Tokens are valid for 30 minutes.
`nonce`	The nonce provided by the client in the initial auth request, if any.
`at_hash`	The hash of the access token issued with alongside the ID token, as defined here.
`sub`	The alias ID for the user.
`nickname`	The nickname the user provided. Only included if the auth request included the `nickname` scope, and it was granted.
`auth_time`	When the user last authenticated themselves to Alias. Alias sessions last up to 24 hours.

Date-time claims are in the JWT NumericDate format - i.e. seconds since 1970-01-01T00:00:00Z.

Example JWT Payload

{
  "jti": "DCZ2_7Se3ziXdcdSscAL0w",
  "iss": "https://projectalias.com",
  "aud": "bjOB6HV7cTKtxvfr2k2ucg",
  "iat": 1593519330,
  "exp": 1593521130,
  "nonce": "rgnxaHF9zIHaafVo4_8Pdw",
  "at_hash": "iMuKaVovQSoj4ue0szDidg",
  "sub": "epGEcGfc6LQMmKTqffWW2g",
  "nickname": "Fred",
  "auth_time": 1593518730
}

User Tokens¶

User tokens are OAuth 2.0 Access Tokens that represent scope and channel permissions granted to a client by a user. They can be requested using the authorization code grant. They are used to authenticate requests to user endpoints.

User tokens are valid for 30 minutes. If they are being used from a frontend, a new auth request can be performed to get a new token when required.

If they are being used from a backend, a refresh token can be used to get a new token when required. Alternatively, the client endpoints maybe able to be used instead.

Refresh Tokens¶

OAuth 2.0 Refresh Tokens can be exchanged for a new user token at the token endoint. They are valid for 7 days. As an updated refresh token is returned when one is used, they can maintain access indefinitely without needing the user to log in.

Warning

Refresh tokens provide access to a connection for an extended period, so should always be kept secure. Do not use them from a frontend, or any other unsecured context.

To help mitigate the risk of a refresh token being exposed, they are only issued as part of an authorization code grant if:

The client is confidential,
The offline_access scope was requested and approved,
The user was prompted for consent during the auth request.

This last restriction essentially means a new refresh token is only issued if a new permission is requested - otherwise the existing refresh token can still be used.

If a new refresh token is required for some reason, prompt=consent can be used to force the user to be prompted for consent even if no new permissions are being requested.

Client Tokens¶

Client tokens are OAuth 2.0 Access Tokens that represent permissions to act on the client itself, rather than on a specific user. They can be requested using the client credentials grant. They are used to authenticate requests to client endpoints.

Client tokens are valid for 30 minutes. A new client credentials grant can be performed to get a new token when required.

Warning

Client tokens provide access to all of a client's connections, so should always be kept secure. Do not use them from a frontend, or any other unsecured context.