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

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.

Optional parameters

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

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

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

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.

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.

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.

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.

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.

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.

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.

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.