Integrate your web application

Overview

The Seven Bridges Platform allows you to integrate your custom-built web application as a way to extend the Platform appearance and behavior. This document is intended for the developer of the web application and will describe the procedure for integrating it with the Seven Bridges Platform.

To complete the registration and add members with appropriate permissions you will need to contact our Support team and provide them with the required information as described in sections below.

📘

A license is required to use this feature. Please contact [email protected] for more information.

Register your web application

To register your web application, please contact our Support Team and provide the information listed below.

Required parameters

Parameter

Description

Name

Short name for the web application. For web applications of type ANALYSIS, this name will be shown as a title of the app on the Interactive Analysis page. The maximum number of characters 256.

Type

Choose the type of web application:

  • PORTAL - a web application that replaces the Seven Bridges standard visual interface for a select group of users. This type of web application is accessed directly via its browser URL.

  • ANALYSIS - a web application that is featured on the Interactive Analysis page and is accessible via the user’s project dashboard.

  • AUTOMATION - a web application serving as custom visual interface for setting up and starting automations. The URL of this web application can be registered as URL for select automations, where it replaces the standard RHEO visual interface for running automations of that type.

Owner

The owner of the web application. This can be either a Division or a user (e.g. rosalind_franklin). It is shown in the disclaimer.

Maintainer

Person who maintains the web application. Must have an active Seven Bridges platform account. Can be the same person as the owner. After registration, only the maintainer is given access to application secrets (client_id and client_secret).

Affiliation

The company or the institute the web application owner is affiliated with.

Redirect URL

The URL the Seven Bridges Platform should redirect to after successful user authentication.

Important notes:

The web application can be hosted independently from the rest of the Seven Bridges infrastructure.

The Redirect URL can include the port number as well as the URL query parameters.

Controlled access (yes/no)

Determines if the web application will have access to controlled data. As an extra layer of security, the Platform users with access to controlled data are not allowed to log into web applications that are not licensed to handle controlled data. Currently only web applications controlled and hosted by Seven Bridges can be licensed for controlled data access.

Members

Seven Bridges Platform users with permission to log into this web application.

After you provide this information, the Seven Bridges Support team will generate the following two parameters, which you will use to authenticate your web application with the Seven Bridges Platform.

The application secrets are made available to the developer via personal correspondence. Please do not share those application secrets with anyone.

Parameter

Description

client_id

Your unique identifier for authenticating on the Platform.

client_secret

A secret key which you will use together with the client_id to authenticate on the Platform.

Optional parameters

For all application types, your registration request can also include the following optional parameters.

Parameter

Description

Access token lifetime

Duration of the access token in seconds. The default value is 1800 seconds (30 minutes).

Refresh token lifetime

Duration of the refresh token in seconds. The default value is 86400 seconds (24 hours).

For web applications of type ANALYSIS, your registration request can include one or more of the following optional parameters.

Parameter

Description

Website URL

Specifies the website that is reached when users click on the “Learn more” link on the Interactive Analysis page. This can for example link to the GitHub repository of your web application.

Description

The application description inside the Interactive Analysis page. The maximum number of characters is: 255.

Thumbnail image

The thumbnail image used inside the Interactive Analysis page.

Recommendations:

  • Aspect ratio: 1000x800 pixels
  • File format: JPEG(or an SVG, PNG, JPG)
  • Size: 500KB - 1MB

Here is an example of the parameters as seen on the Interactive Analysis page:

611611

OAuth2 integration (authorization code flow)

The Seven Bridges Platform serves as Authorization and Resource Server under the OAuth2 protocol. To gain access to the Seven Bridges Platform, your web application first uses the Authorization Code Grant Type to obtain an access token. This access token is then used to access the Seven Bridges public API.

915915

The authorization code flow involves the following steps:

  • The web application redirects the user to the Seven Bridges login page.
  • The user logs in and approves the web application request in the authorization prompt (user disclaimer).
  • The user is redirected back to the web application with an authorization code in the query string.
  • The web application exchanges the authorization code for an access token and refresh token.

Step 1: Get the user's permission (user authorization)

To begin the authorization flow the web application constructs a URL like the one below and opens it in a browser:

https://accounts.sbgenomics.com/oauth2/authorization?
response_type=code&
client_id=29352915982374239857&
redirect_uri=https%3A%2F%2Fexample-app.com%2Fcallback&
scope=openid&
state=xcoiv98y2kd22vusuye3kch

Query parameters

The following query parameters are available.

Parameter

Description

response_type=code

This tells the authorization server that the web application is initiating the authorization code flow.

client_id

The public identifier for the web application, obtained when the developer first registered the application.

redirect_uri

This will be used by the authorization server to redirect the user after their request has been approved. This has to match the “Redirect URL” provided during the web application registration request. This protects users from being redirected to an unknown and potentially unsafe location.

scope

One or more space-separated strings indicating which permissions the web application is requesting.

Only openid scope is currently supported (indicates that the application intends to use OIDC to verify the user's identity).

state

The web application generates a random string and includes it in the request. It should then check that the same value is returned after the user authorizes the app. This is used to prevent CSRF attacks.

Step 2: Authorize application request

Upon visiting the URL mentioned above, the Seven Bridges authorization server will show the login form. If the user is not logged into the Seven Bridges Platform the users will be able to log in using their Platform credentials or some of already configured external identity providers.

606606

After logging in successfully the user will be redirected to the disclaimer page and prompted to authorize this application’s request. Currently the Seven Bridges Platform does not allow users to manage their application permissions.

Therefore permission to access the Seven Bridges Platform needs to be granted to an application every time it is opened, not just the first time.

16921692

Step 3: Redirect back to web application

Once the request is approved, the Seven Bridges authorization server will redirect the browser back to the redirect_uri specified by the web application, adding a code, state, and browser ID to the query string.

For example:

https://example-app.com/redirect?
code=g0ZGZmNjVmOWIjNTk2NTk4ZTYyZGI3&
state=xcoiv98y2kd22vusuye3kch&
browser_id=32029c9e-6661-46fd-8d47-8416807cc919

Query parameters

The following parameters are present in the redirect URL.

Parameter

Description

code

An alphanumeric password generated by the Seven Bridges authorization server

state

Random generated string that the web application initially set in the request.

browser_id

Unique browser identification number the request came from.

The state value will be the same value that the web application initially set in the request. The web application checks that the state in the redirect matches the state it originally set. This enables protection against CSRF and other related attacks.

The code is the authorization code generated by the Seven Bridges authorization server. The expiration time of this code is 10 minutes.

Step 4: Exchange the authorization code for an access token

The exchange of the authorization code for the access token is the final step of the flow. The web application uses the authorization code to get an access token. The web application uses the authorization code to get an access token using a POST request as described below.

https://accounts.sbgenomics.com/oauth2/token

Request header

The request should be authorized with the authorization header containing the client_id and the client_secret configuration parameters.

Header key

Header value

Authorization

BASIC base64(client_id:client_secret)

Parameter

Description

client_id

The web application client ID.

client_secret

The web application client secret. This ensures that the request to get the access token is made only from the web application, and not from a potential attacker that may have intercepted the authorization code.

Authorization header example

In our example, the client_id is '4af483498b9442b3b44a6390a20dd229' and the client_secret is 'cN4GWhXFntD9pKCoWz7NL9LMzJGvQKWxTGTg3E16uEznjAipiQ'.

After concatenating these two values and base64 encoding, the authorization header will look like this:

Authorization: BASIC NGFmNDgzNDk4Yjk0NDJiM2I0NGE2MzkwYTIwZGQyMjk6Y040R1doWEZudEQ5cEtDb1d6N05MOUxNekpHdlFLV3hUR1RnM0UxNnVFem5qQWlwaVE=

The token endpoint will verify all the parameters in the request, ensuring the code has not expired and that the client_id and client_secret match. If that is the case the access token will be generated in the response.

Request body

The following fields should be present in the request body.

Parameter

Description

code

The authorization code obtained in the redirect.

grant_type

The grant type for this flow is authorization code and should be set to "AUTHORIZATION_CODE".

Response

{
  “access_token”: “626ec61dcf1348ceacfd952fb65ee0a9”,
  “refresh_token”: “cc0a07c28d264bef930d589053aba00b”,
  “token_type”: “BEARER”,
  “expires_in”: 86400,
  “id_token”: %base64_encoded_JWT%
}

Logout

The web application should use this endpoint to deactivate all issued tokens and sessions on the Seven Bridges Platform.

https://accounts.sbgenomics.com/oauth2/logout

This endpoint should be authorized with the obtained access token.
The Authorization header example:

Authorization: BEARER 626ec61dcf1348ceacfd952fb65ee0a9

API authentication

The Access Token obtained through the OAuth2 flow should be used for the authorization with the Seven Bridges public API.

The Authorization header example:

Authorization: BEARER 626ec61dcf1348ceacfd952fb65ee0a9

R Shiny reference implementation

A reference implementation that implements the above authentication flow as part of an R Shiny app can be found on GitHub.