| | 1 | This 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 = |
| | 6 | The token table will store a number of different types of token. |
| | 7 | |
| | 8 | 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. |
| | 9 | |
| | 10 | They 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 == |
| | 24 | 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. |
| | 25 | Columns: |
| | 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 == |
| | 32 | 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. |
| | 33 | Columns: |
| | 34 | * client_id: INTEGER primary key not null pk to OAUTH_CLIENT |
| | 35 | * url: varchar(512) primary key not null |
| | 36 | |
| | 37 | == OAUTH_TRANSITION == |
| | 38 | 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. |
| | 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 == |
| | 50 | This 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 == |
| | 61 | This 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) == |
| | 69 | Part of the site admin pages |
| | 70 | |
| | 71 | == Manage clients page (user) == |
| | 72 | This page allows the user to revoke access to any oauth client at any time |
| | 73 | |
| | 74 | == Authorize client page == |
| | 75 | 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. |
| | 76 | |
| | 77 | 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: |
| | 78 | |
| | 79 | * client_id |
| | 80 | * redirect_url |
| | 81 | * state |
| | 82 | * scope |
| | 83 | * response_type=code |
| | 84 | * code_challenge |
| | 85 | * code_challenge_method |
| | 86 | |
| | 87 | The redirect URL must be one of the values stored on OAUTH_CLIENT_URL for this particular oauth client. |
| | 88 | |
| | 89 | 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. |
| | 90 | |
| | 91 | 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”. |
| | 92 | |
| | 93 | If the user denies access, then the user is returned to the oauth clients website as specified in the URL. |
| | 94 | |
| | 95 | 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: |
| | 96 | |
| | 97 | * state |
| | 98 | * code |
| | 99 | |
| | 100 | = New RPCs to Support OAuth = |
| | 101 | == Token == |
| | 102 | 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: |
| | 103 | |
| | 104 | * client_id |
| | 105 | * client_secret |
| | 106 | * code |
| | 107 | * code_verifier |
| | 108 | * grant_type=authorization_code |
| | 109 | |
| | 110 | The API will verify the client_id and client_secret and then look up the entry on OAUTH_TRANSITION |
| | 111 | |
| | 112 | 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. |
