This pages describes the implementation details of Reduce usage of authenticator

NOTE: THIS IS A WORK IN PROGRESS

Tokens

The token table will store a number of different types of token.

Tokens are 32 random hex characters created by the random_string function. The token table requires them to be unique for all currently active tokens.

They are described here:

Name	Id	Duration	New/ Existing	Description
Delete Account	D	1 day	Existing	Sent in email to user to confirm access to account email before deleting an account
Change Email	E	1 week	Existing	Used in email sent to the old email address after a user changes their email address. It allows them to revert the change (protection against someone maliciously changing accounts)
Login Intercept	L	2 hour	Existing	Created after login in cases where the user has not yet agreed to the required terms of use. Once the user agrees to the required terms of user, then this token validates that the user has been logged in and can get a full web access token
One-time login	O	1 hour	New	This token will be used in any case where the system needs to allow the user a one-time login token. This will first be used after registering through the client and when a link is provided for the user to finish setting up their account. It would also make sense to use this for ‘forgot password’ emails.
Web session	S	20 minutes	New	This token will be used instead of the authenticator in the “auth” cookie used for website access. It will expire after 20 minutes of non-use (i.e. each time the user access the website, the expire field for the token should be extended by 20 minutes)
Remember me	R	1 month	New	This token will be set in the ‘rememberme’ cookie when the user wishes to remain logged into the website on a specific browser. Each time it is used, it should be deleted and the rememberme cookie update with a new remember me token value.

Database Table Changes

OAUTH_CLIENT

This table stores information about oauth clients that are allowed to interact with the project website. Note: secret is the value from password_hash() using the bcrypt algorithm - the actual key is not stored. It is only available one time when the client is added to this table. Columns:

• client_id: INTEGER primary key not null auto generated
• name: VARCHAR(254) not null
• scopes: VARCHAR(254) not null
• secret: VARCHAR(100) not null

OAUTH_CLIENT_URL

This table stores the list of allowed return urls for the client (only requests made for these urls are allowed). There should be at least one and possibly multiple URL’s allowed for each client. Columns:

• client_id: INTEGER primary key not null pk to OAUTH_CLIENT
• url: varchar(512) primary key not null

OAUTH_TRANSITION

This table stores the transient state of authorizations approved by the user but not yet claimed by the OAUTH_CLIENT. Items on this table should be deleted after 1 hour.

• code: char(32) primary key not null
• user_id: Integer not null fk to user
• client_id: Integer not null fk to OAUTH_CLIENT
• scopes: VARCHAR(254) not null
• challenge_code: varchar(128) not null
• challenge_code_method: varchar(20) not null
• create_timestamp: timestamp not null default current timestamp

OAUTH_AUTHORIZATION

This table stores the list of authorizations granted by users to specific clients and the authorization code used.

• auth_id: primary key not null auto generated
• user_id: Integer not null fk to user
• client_id: Integer not null fk to OAUTH_CLIENT
• scopes: VARCHAR(254) not null
• refresh_token: VARCHAR(32) not null
• create_timestamp: timestamp not null default current timestamp
• expire_timestamp: timestamp not null

OAUTH_ACCESS

This table stores the active access tokens

• auth_id: primary key not null fk to OAUTH_AUTHORIZATION
• token: VARCHAR(32)
• create_timestamp: timestamp not null default current timestamp
• expire_timestamp: timestamp not null

Pages to Support OAuth

Manage client page (admin)

Part of the site admin pages

Manage clients page (user)

This page allows the user to revoke access to any oauth client at any time

Authorize client page

This describes the server side flow. See ​https://www.oauth.com/oauth2-servers/server-side-apps/example-flow/ for additional details about the security aspects of this implementation.

This page is the page that oauth clients will send users to in order to obtain permission to access their account. The oauth client must provide the following parameters in their request to this page:

• client_id
• redirect_url
• state
• scope
• response_type=code
• code_challenge
• code_challenge_method

The redirect URL must be one of the values stored on OAUTH_CLIENT_URL for this particular oauth client.

The user must be logged in before reaching this page. As a result, the page should redirect the user to a login/create account page if they do not have an active web session. Once the user creates an account or logs in, they should be redirected back to this page with all the parameters listed above preserved. The login/create account pages will need to be modified to handle redirection if they don’t already.

The page will display the name of the oauth client, the permissions the client wants and the option for the user to “Grant access” or “Deny access”.

If the user denies access, then the user is returned to the oauth clients website as specified in the URL.

If the user grants access, then an entry is created in OAUTH_AUTHORIZATION for the pair of oauth_client and user, storing the scope authorized, the challenge code and creating an authorization code for the oauth_client. The user is then redirected back to the URL that was provided and includes the following parameters on the URL:

• state
• code

New RPCs to Support OAuth

Token

The token API is when the API called by the oauth client after the user has been redirected back to their website. This API will exchange the code from the in the URL for an access token and a refresh token. The parameters sent in this call are:

• client_id
• client_secret
• code
• code_verifier
• grant_type=authorization_code

The API will verify the client_id and client_secret and then look up the entry on OAUTH_TRANSITION

If valid, the API will respond with an access token and a refresh token. The access token is a short lived token that is provided with API requests to interact with the project's web API’s on behalf of the user. The refresh token is a long lived token that is used to request new access tokens when they expire. The refresh token should be stored with the users account on the client while the access token can be immediately used to make API calls on behalf of the user.