Edit this page | Blame

OAuth2

The new authorisation system is made up of two layers:

This document will concern itself mostly with "Client Authorisation".

Client Authorisation

The authentication/authorisation system will (probably) find use in the entire suite of applications that are under the Genenetwork umbrella.

The relevant applications (as of 27 May 2023) are:

Serves as both the authorisation server and the API server.

Will eventually be the main user-facing UI making requests to GN3 for data and computational requests.

Provides a means to upload new data into the Genenetwork database. It does perform some quality-control on the data before upload. Currently, this application is not available to the general public due to the potential to mess up the data. Once the auth system has been running a while, and the major bugs quashed, this will be integrated into the other system and allow users to upload their own data.

In this case, the GN2 and QC applications would be clients to GN3 (as the auth server), and will have specific scopes of access.

As such, we need to register the clients that can access the authorisation server.

If you try to access the authorisation server, or for that matter, the API server with a client that is not registered, you will receive an error message of the form:

{
    "error": "invalid_client",
    "error_description": "No client found for the given CLIENT_ID and CLIENT_SECRET."
}

Registering a new OAuth2 Client

To enable the clients (such as GN2 and QC mentioned above) to work with the authentication and/or API server (GN3), we need to register them. We do that on GN3, and only an administrative user has that ability.

The administrative user logs on to GN3 on the `/api/oauth2/admin/login` endpoint. Once logged on, they can visit the "Register OAuth2 Client" page on the `/api/oauth2/admin/register-client` endpoint. There they can provide the necessary information, and select from a set of options that apply to the client they are registering.

Once the admin submits the registration information, the system will generate CLIENT_ID and CLIENT_SECRET values and show them. The CLIENT_SECRET value is stored encrypted in the system and there is no way to retrieve it once the user navigates it away from the registration page.

The CLIENT_ID and CLIENT_SECRET values are then added to the client's (e.g. GN2) configurations to enable the client access the servers.

The following sections will document the various options available when registering the clients.

#### Client Scope

The client's scope determines what the client is allowed to do and/or access on both the API and authorisation servers. Some of the scopes work in unison.

  • profile: This is the most basic scope. It allows the client to access basic user information for the authenticated user.
  • group: This allows the client to access the user-group information for the authenticated user.
  • role: This allows the client to access the roles assigned to the authenticated user.
  • resource: This allows the client to access the resources that the authenticated user has access to.
  • user: This allows the client to access user information, but also act on certain data that one with only the "profile" scope cannot.
  • masquerade: This allows a client to access the masquerade feature for users with the authorisation to masquerade as other users. This should be offered sparingly, even when requested by users registering new clients.

The remaining scope choices can mostly be ignored for all publicly-facing OAuth2 clients. The choices have, however, been documented below for completeness.

  • introspect: DANGEROUS: Mostly for troubleshooting and SHOULD NEVER be granted to public-facing clients. It is however useful during development, and possibly for troubleshooting issues with tokens, and as such, is provided as one of the choices.
  • register-client: WONTIMPLEMENT: This is an artifact of development and will be removed. Client registration is handled on the authorisation server, and is a system-admin feature.
  • migrate-data: OBSOLETE: This existed during development flux, but has been superceded by a CLI client run on the backend, and the choice not to retain old user accounts in the first place.

#### Basic Client Informations

  • Client Name: This is the name of the client. It can be anything you want, but it is highly recommended that you give a descriptive name, maybe with the name of the client (e.g. GN2) and the environment (e.g. staging).
  • Redirect URI: This is the URI where the authorisation will redirect to, to provide the authorisation code that the client will then use to acquire the authorisation token.
  • Other redirect URIs: Currently not in use, but these should mostly be fallback URIs in case the main redirect URI fails.

#### Grant Types

There are a number of

We currently only support the

with work to enable the

ongoing.

Down the road, we will also enable the

for better security.

#### Client Owner

Each client has as user that "owns" it. For Genenetwork clients, any system admin can be set up as the owner.

For clients registered by other users, then the owner of the client should be the user that requested to register the client.

For now, we do not support external clients, but this is possible down the road.

User Authentication/Authorisation

A user will make use of (an) authorised client(s) (see 'Client Authorisation' section above) to access the authorisation and API servers.

Once the user has authenticated (provided valid authentication credentials), they will be able to access the resources in the system according to the roles and privileges that they are authorised for.

(made with skribilo)