| Column | Type | Obtained from | Description |
|---|---|---|---|
| id | UUID | Generated | ID to keep track of the request |
| token_hash | str | Generated | Hash of a secret token stored in a flow cookie |
| session_id | Optional FK | Logged in session | Associated login session |
| client_id | FK | Query string | The OAuth client sending this request |
| response_type | str | Query string | OAuth response type. e.g. Authorization Code, ID token etc. |
| scope | str | Query string | The requested scope. Usually contains openid as a minimum |
| state | str | Query string | Client specific state |
| nonce | str | Query string | Passed through to the ID token |
| redirect_uri | str | Query string | Where to redirect after authenticating |
| acr_values | str | Query string | Requested authentication level |
| code_challenge | str | Query string | PKCE challenge |
| code_challenge_method | str | Query string | PKCE method |
The response is dependent on the response_type field. This is a space separated set with various options:
code: a code to be submitted to the Token endpoint to obtain other information.token: an access token.id_token: an OpenID ID token.
The response_mode is determined implicitly based on the response_type. This can take the following values:
query: the response is returned in the query string.fragment: the response is returned in the URL fragment (stuff after the # symbol).
The query mode is used when only the code is being requested, otherwise the URL fragment is used. Most of the time clients will only be requesting a code.
This is a short lived code that can be submitted to the Authorization endpoint in exchange for ID and access tokens. The code_challenge may also be used at this point using the PKCE standard
The ID token shall be returned if the openid scope was requested. These are the claims we plan to support:
| Claim | Required | Description | Obtained from |
|---|---|---|---|
| iss | REQUIRED | Issuer identtifier. | Portal base URL. |
| sub | REQUIRED | Subject identifier. | User from the session_id. |
| aud | REQUIRED | Audience(s) the ID token is intended for. | client_id. |
| exp | REQUIRED | Token expiration time. | Per-client configuration. |
| iat | REQUIRED | When the token was issued. | Current time when the token is generated. |
| auth_time | OPTIONAL (unless requested through max_age query parameter) | Time when end user authentication occured. | Most recent timestamp in the session's last_xx_auth fields. |
| nonce | OPTIONAL unless present in request | String value to associate client session with ID token and to mitigate replay attacks. | Request nonce. |
| acr | OPTIONAL unless requested by acr_values | Authentication context class (how “strong” the authentication was). | Session authentication level. |
| amr | OPTIONAL | Authentication methods. | Session authentication methods based on last_xx_auth fields. May be filtered based on max_age if present. |
Note that only azp is missing from the OpenID core spec as we don't plan to use any extensions to the spec.
While the Hackspace services might be spread across multiple servers, we will use a single logical API approach for our access tokens. This means that all scopes will be part of a single global namespace. For example email:send might allow sending emails via and email service.
The Access token will be a transparent signed JWT with the following claims:
| Claim | Description | Obtained from |
|---|---|---|
| iss | Issuer of the token | The portal base URL |
| sub | Subject | The user or client subject depending on whether it was a Authorization Code flow, or Client Credentials |
| aud | The global scope namespace | Configuration value e.g. hackspace |
| exp | Expiry | Relatively short configuration value e.g. 1 hour |
| iat | Issued at | Timestamp when the token was created |
| jti | Unique identifier | Randomly generated |
| client_id | Client identifier | The OAuth client that requested the token |
| scope | Granted scopes | Requested scopes filtered by the user's permissions |
The refresh token will be an opaque token with a corresponding table containing the same information as the access token. The table may also contain a reference to the user's session ID so the token can be revoked if the session ends.