Changes between Initial Version and Version 1 of Reduce_usage_of_authenticator_implementation


Ignore:
Timestamp:
Nov 8, 2020, 3:00:32 PM (4 years ago)
Author:
Kevin Reed
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Reduce_usage_of_authenticator_implementation

    v1 v1  
     1This pages describes the implementation details of [wiki:Reduce_usage_of_authenticator Reduce usage of authenticator]
     2
     3**NOTE: THIS IS A WORK IN PROGRESS**
     4
     5= Tokens =
     6The token table will store a number of different types of token.
     7
     8Tokens are 32 random hex characters created by the random_string function.  The token table requires them to be unique for all currently active tokens.
     9
     10They are described here:
     11
     12|| Name || Id || Duration || New/ Existing || Description ||
     13|| Delete Account || D || 1 day || Existing || Sent in email to user to confirm access to account email before deleting an account ||
     14|| 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) ||
     15|| 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 ||
     16|| 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. ||
     17|| 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) ||
     18|| 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. ||
     19
     20
     21= Database Table Changes =
     22
     23== OAUTH_CLIENT ==
     24This 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.
     25Columns:
     26* client_id: INTEGER primary key not null auto generated
     27* name: VARCHAR(254) not null
     28* scopes: VARCHAR(254) not null
     29* secret: VARCHAR(100) not null
     30
     31== OAUTH_CLIENT_URL ==
     32This 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.
     33Columns:
     34* client_id: INTEGER primary key not null pk to OAUTH_CLIENT
     35* url: varchar(512) primary key not null
     36
     37== OAUTH_TRANSITION ==
     38This 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.
     39
     40* code: char(32) primary key not null
     41* user_id: Integer not null fk to user
     42* client_id: Integer not null fk to OAUTH_CLIENT
     43* scopes: VARCHAR(254) not null
     44* challenge_code: varchar(128) not null
     45* challenge_code_method: varchar(20) not null
     46* create_timestamp: timestamp not null default current timestamp
     47
     48
     49== OAUTH_AUTHORIZATION ==
     50This table stores the list of authorizations granted by users to specific clients and the authorization code used.
     51
     52* auth_id: primary key not null auto generated
     53* user_id: Integer not null fk to user
     54* client_id: Integer not null fk to OAUTH_CLIENT
     55* scopes: VARCHAR(254) not null
     56* refresh_token: VARCHAR(32) not null
     57* create_timestamp: timestamp not null default current timestamp
     58* expire_timestamp: timestamp not null
     59
     60== OAUTH_ACCESS ==
     61This table stores the active access tokens
     62* auth_id: primary key not null fk to OAUTH_AUTHORIZATION
     63* token: VARCHAR(32)
     64* create_timestamp: timestamp not null default current timestamp
     65* expire_timestamp: timestamp not null
     66
     67= Pages to Support OAuth =
     68== Manage client page (admin) ==
     69Part of the site admin pages
     70
     71== Manage clients page (user) ==
     72This page allows the user to revoke access to any oauth client at any time
     73
     74== Authorize client page ==
     75This 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.
     76
     77This 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:
     78
     79* client_id 
     80* redirect_url
     81* state
     82* scope
     83* response_type=code
     84* code_challenge
     85* code_challenge_method
     86
     87The redirect URL must be one of the values stored on OAUTH_CLIENT_URL for this particular oauth client.
     88
     89The 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.
     90
     91The 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”.
     92
     93If the user denies access, then the user is returned to the oauth clients website as specified in the URL. 
     94
     95If 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:
     96
     97* state
     98* code
     99
     100= New RPCs to Support OAuth =
     101== Token ==
     102The 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:
     103
     104* client_id
     105* client_secret
     106* code
     107* code_verifier
     108* grant_type=authorization_code
     109
     110The API will verify the client_id and client_secret and then look up the entry on OAUTH_TRANSITION
     111
     112If 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.