OAuth

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.

OAuth

Capturing the request

Generating the response

The authorization code

The ID token

The access and refresh tokens