OAuth2 Server

Open authorisation has been used to allow users of Central EnteroBase to access Local EnteroBase instances using their Central EnteroBase login. More information about OAuth2 can be found at: https://www.oauth.com/. In order to maintain consistency throughout the codebase, and between Central and Local EnteroBase, one library has been used for all OAuth-related functionality. This library is called “Authlib”, and its documentation can be found at: https://docs.authlib.org/en/latest/. Because Central EnteroBase is still using Python 2, an older version of the library is used (Authlib v0.12.1), however, this can easily be updated once Central EnteroBase moves to use Python 3. The Local EnteroBase version used is Authlib v0.15.3. Authlib v1.0.0 is currently under development, so it is strongly recommended that both codebases upgrade to it once it is released in production. In Central EnteroBase, all code relating to OAuth2 can be found in the “entero/oauth” directory of the repository.

Building the OAuth2 Server

The Authlib documentation has been the main source of reference for building the OAuth server. The documentation for this is found here: https://docs.authlib.org/en/stable/flask/2/index.html. It may also be useful to look at the official OAuth2 server example found here: https://github.com/authlib/example-oauth2-server. All endpoints that require OAuth can be found in “entero/oauth/views.py”, and all utilities used by OAuth can be found in “entero/oauth/utils.py”. The following grants are used by Central EnteroBase:

  • Authorisation Code Grant: The Authorisation grant is used to provide a user in Local EnteroBase with an access token. “Access tokens are the thing that applications use to make API requests on behalf of a user” - https://www.oauth.com/. Access tokens are given once a user logs in and can be used to access resources on the server related to that specific user.

  • Refresh Token Grant: The Refresh token grant is used in order to generate refresh tokens. Refresh tokens are tokens with a much longer lifespan than access tokens, that can be used in order to obtain a new access token without forcing the user to log in again. A refresh token is also generated when the user logs in, but cannot be used to directly access resources.

  • Client Credentials Grant: The client credentials grant is used in order to allow the Local EnteroBase instance to access resources that are specific to itself. They cannot access any user details, only details that are relevant to the Local EnteroBase instance as a whole. The grant works by authorising the request using the client_id and client_secret generated by Central EnteroBase upon approval (see Administration). The current use of this grant is to show the user the details of the Local EnteroBase instance at the end of the configuration test (see Configuration Test). An idea for how this credential could be used in the future would be for streaming Central EnteroBase news and updates to the Local EnteroBase instance.

Relevant SQLAlchemy Database models

All relevant models can be found in “entero/databases/system/models”.

  • LocalEnterobaseClient: This model is used to keep track of Local EnteroBase clients. It uses the OAuth2ClientMixin object from the Authlib library to ensure that all attributes required by the library exist in the model. Alongside the OAuth2 attributes, this model also contains the information given by the administrator during registration (see: Register Local EnteroBase &:ref:local-enterobase-registration-label).

  • UserGrantAuthorizationCode: This model is used temporarily during the authorisation grant flow and destroyed afterwards. It uses the OAuth2AuthorizationCodeMixin object from the Authlib library to ensure that all attributes required by the library exist in the model.

  • UsersToken: This model is used to store the access and refresh tokens of a user. It uses the OAuth2TokenMixin object from the Authlib library to ensure that all attributes required by the library exist in the model.

  • LocalEnterobaseClientUsersConfirmation: This model is used to store whether or not a user has approved a Local EnteroBase instance to access their details.

OAuth2 endpoints

All OAuth2 endpoints are available in the “entero/oauth/views.py” file of the repository. The endpoints available are as follows:

  • /oauth/authorize: used as part of the authorisation code grant workflow by Authlib. Has an additional check to see if the user has already approved the Local EnteroBase instance to access their credentials, and if not it asks the user to do so.

  • /oauth/token: used as part of the authorisation workflow by Authlib. Used to generate an access and refresh token.

  • /oauth/revoke: used to revoke a token, for example when a user logs out.

  • /oauth/oauth_config: endpoint for displaying relevant oauth endpoints in a similar format to OpenID (https://ldapwiki.com/wiki/Openid-configuration).

  • /oauth/user_info: endpoint for retrieving the basic info about a Central EnteroBase user.

  • /oauth/local_enterobase_client_info: endpoint for retrieving the basic info about a Local EnteroBase instance.

  • /oauth/lastname: endpoint for testing OAuth2 that simply returns the last name of the user.

  • /oauth/upload_strain: endpoint for uploading an assembled strain (not currently fully implemented).

  • /oauth/check_user_authorised_for_database: verifies if a user is able to access a database.

Notes

  • For development purposes, it is important to set the following environmental variable in order to allow non-secure http requests from clients:
    export AUTHLIB_INSECURE_TRANSPORT=true