OAuth 2.0 and authentication flow

06/16/2021

The SeqsLab systems enable the processing of potentially sensitive genomic and biomedical datasets through a client-server model. Access to SeqsLab systems and services requires user authentication and authorization through a trusted identity and access management (IAM) provider, which the SeqsLab platform identity endpoint uses to authenticate authorized users using the industry standard protocol OAuth 2.0 ().

For details on the user sign-in process in SeqsLab for supported IAM providers, see Sign in with Azure Active Directory.

Tokens

OAuth 2.0 uses the bearer tokens represented as JSON Web Tokens (JWTs), an open, industry standard RFC 7519 () method for securely representing claims between two parties. A bearer token is a security token that grants the bearer access to a protected resource. The SeqsLab platform makes extensive use of bearer tokens when accessing the platform systems and when requesting access to computing environments in the users’ own cloud infrastructure.

SeqsLab applies industry security principles when transmitting over a network and when storing bearer tokens for caching use. SeqsLab transmits the bearer token in a secure channel by transport layer security (HTTPS) to prevent man-in-the-middle attacks from using it for unauthorized access to a protected resource. When storing tokens, SeqsLab uses system keyring services such as Freedesktop Secret Service () and macOS Keychain ().

In the context of the users’ cloud infrastructure, the bearer is the SeqsLab system that gets a copy of the token by first authenticating with the users’ IAM provider and using the token to access the protected compute and storage resources. In the context of SeqsLab platform services, the bearer is any client app that obtains a copy of the token to access SeqsLab platform services by first signing users into the SeqsLab platform identity endpoint. The same security principles must be applied when storing or caching bearer tokens in client apps.

There are primarily 4 categories of tokens used in SeqsLab:

• ID tokens - tokens that the SeqsLab system receives from the IAM authorization server, used to sign in a user and get their basic information for access verification.

• Access tokens - tokens that a user’s computing resource server receives from a SeqsLab system, containing permissions that SeqsLab has been granted.

• API tokens - tokens that a SeqsLab system receives from a client app, authorizing the client to access SeqsLab on behalf of a user.

• Refresh tokens - tokens used by a SeqsLab system or client to get new access and API tokens over time.

SeqsLab provides a seamless sign-in user experience, automatically obtaining and exchanging bearer tokens when users access SeqsLab systems and services from SeqsLab client apps, such as the management console and CLI. If you want to implement your program by directly sending and handling HTTP requests or using a third-party open-source library, see SeqsLab API tokens, which provides human-readable instructions on how to get an API token for a specific SeqsLab service endpoint.

Sign in with Azure Active Directory

Important

To use SeqsLab in Microsoft Azure cloud, you must have an active Azure subscription. SeqsLab only supports users with a work or school account in an organizational directory from Microsoft (Azure Active Directory).

If you are unable to sign in, contact your SeqsLab administrator to check if your account is allowed to access the SeqsLab apps that are registered as enterprise applications in your Azure Active Directory.

SeqsLab implements the Microsoft Entra ID () OAuth 2.0 authentication flow and uses the obtained access tokens to access the protected computing resources on behalf of the authorized Azure user account.

Sign-in process in Azure

At a high level, the entire authentication flow for user sign-in is depicted in the following diagram.

SeqsLab uses public work or school email addresses and associates them with users who were added by their SeqsLab administrator. During the sign-in session, the SeqsLab identity auth endpoint caches the username, tenant, and subscription information, and accesses or refreshes the tokens required for better user experience and on-demand task execution. When users sign out of SeqsLab, the user account information are deleted from the system.

Governance

In a user sign-in request, SeqsLab abides by the principle of least privilege and asks for the permissions that SeqsLab systems need to perform the services and functions. Users must approve the permission request before SeqsLab systems can access data and resources, and before SeqsLab can act on the users’ behalf.

SeqsLab requires the following delegated permissions:

• Sign in and read user profile (email address)

• Maintain access to data that users have given it access to

• Access Azure Batch Service

• Access Azure Storage Service

• Access Azure Service Management as organization users

SeqsLab can provide most of the functions when there is a signed-in user present. However, when users need to run scheduled jobs without a signed-in user present (OAuth 2.0 client credentials grant) or to create workspaces (a.k.a. Azure resource groups) using SeqsLab apps, certain application permissions require administrator consent:

• Read applications (read SeqsLab service principal ID once registered in Enterprise Applications)

Administrative users (SeqsLab administrators) must have Application Administrator, User Access Administrator, and Contributor role assignments before they can consent to application permissions, and create and manage workspaces. For more information about permissions and consent, see the Microsoft documentation ().