Authenticate with OAuth 2.0 authentication

Superblocks supports many OAuth 2.0 flows to use when authenticating Integrations. OAuth 2.0 is most commonly used by REST APIs and GraphQL, but can also be used by some cloud databases.

OAuth 2.0 overview

OAuth 2.0 is an industry standard protocol for user authentication and authorization. Using OAuth 2.0, a remote server, like an API, can grant access to a client securely by issuing a short-lived access token.

Glossary

The OAuth 2.0 spec, and it's usage in Superblocks, comes with some important terms:

• Client: The app that wants to access data
• App type: The type of Superblocks tool trying to access the data (App, Workflow, Scheduled Job)
• Resource server: The API that stores the data the client wants to access
• Resource owner: The owner of the data in the server
• Authorization server: The server that manages access and issues access tokens
• Access token: The token issued by the authorization server in exchange for the grant
• ID token: An optional token that contains information about the end user in the form of claims
• Refresh token: An optional token that is exchanged for a new access token if the access token has expired

OAuth 2.0 flows

OAuth 2.0 flows are often called "multi-legged" authorization flows because they involve multiple requests exchanged between the client, user, and server. For example, a usual OAuth 2.0 Authorization Code flow runs as follows:

1. A client makes a request for the user to authorize access to their data
2. If the user grants access, the client requests an access token by passing the authorization grant to an authorization server
3. If the grant is valid, the authorization server returns an access token, possibly alongside a refresh and/or ID token
4. The client uses the access token in requests to the API server
5. When the token expires, the client uses the refresh token to automatically request a new access token

In Superblocks, OAuth 2.0 flows are performed by exchanging requests between the user's browser, the Superblocks Agent, and resource server. Once an access token is received, it is always sent to the resource server by the Superblocks Agent when steps are executed.

Choosing an OAuth 2.0 flow

The OAuth 2.0 flow you use depends on your use case and flows supported by your API server. Reference API documentation to determine the flows supported by the API you intend to use.

If your API supports multiple flows, use the following table to help decide which flow to use:

App type	Resource owner	Shared token	User prompt	OAuth 2.0 flow
Workflow/Job	Server			Client credentials
Workflow/Job	User			Authorization Code w/ shared token Password Grant (Legacy) w/ shared token On-Behalf-Of Token Exchange w/ static token
Application	Server			Client credentials
Application	User			Authorization Code w/ shared token Password Grant (Legacy) w/ shared token On-Behalf-Of Token Exchange w/ static token
Application	User			On-Behalf-Of Token Exchange w/ IdP token
Application	User			Authorization Code, Implicit, or Password Grant (Legacy)

Using OAuth 2.0

Authorization Code

Authorization Code grants require a user to authenticate with the authorization server before an access token can be issued. After authenticating and granting access, an authorization code is sent back to Superblocks. The Superblocks Agent sends this token to the /token endpoint of the auth server to get an access token.

To use the authorization code flow:

1. In the Integration configuration select OAuth2 - Authorization Code

2. Copy the Callback URL provided and add it to the Allowed Callback URLs of your OAuth client

3. Specify the following configuration values:

   Field	Required	Description
   Authorization URL		The endpoint users will be redirected to to login and authorize access. Note: this value is not required for public APIs and is set by Superblocks
   Token URL		The token endpoint of the authorization server, used to exchange an authorization code for an access token. Note: this value is not required for public APIs and is set by Superblock
   Client ID		The ID issued to your OAuth client during registration.
   Client secret		The secret issued to your OAUth client during registration.
   Audience		The intended recipient of the token, usually in a format like https://api-a.example.com. Check API docs for the format.
   Prompt		Determines if the user is prompted for consent. To skip the prompt and perform silent authentication, set to none
   Scopes		The scopes that you want to request authorization for. These must be separated by spaces.
   Client authentication		If the Client ID and Client secret will be sent to the Token URL in the body or as a basic auth header.
   Send state		When checked, an opaque value will be added to the Authorization URL call and used on redirect to prevent CSRF attacks.

4. If available, select Share access token across all users to use the same access token for all clients. If selected, click the Connect button to initiate the authorization flow.

   warning

   If the shared token option is not selected, integrations with this auth method cannot be used in Workflows or Scheduled Jobs

5. Use the oauth object in Headers or Params to define how the token response is used. For example, to send the access token to subsequent requests in the Authorization header, set:

   

If you're not using the shared token option, this flow will be initiated in the user's browser when an API using this Integration executes. After an access token is retrieved it is cached for future use. If a refresh token is provided, Superblocks will refresh the token when it expires without reprompting the user to authenticate. Learn more about token caching and refresh

Full specification

1. GET Authorization URL

Prompt user to log in and get an authorization code

Request

GET {authorization_url}?
    client_id={client_id}&
    audience={audience}&
    scope={scopes}&
    response_type=code&
    redirect_uri=https%3A%2F%2Fapp.superblocks.com%2Foauth%2Fcallback&
    state=STATE

Expected Response

HTTP/1.1 302 Found
Location: https://app.superblocks.com/oauth/callback?code=AUTHORIZATION_CODE&state=STATE

2. POST Token URL

Exchange authorization code with authorization server for an access token

Request

If Client authentication is set to Send client credentials in body

curl --request POST \
    --url '{token_url}' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencoded 'grant_type=authorization_code' \
    --data-urlencoded 'client_id={client_id}' \
    --data-urlencoded 'client_secret={client_secret}' \
    --data-urlencoded 'code=AUTHORIZATION_CODE' \
    --data-urlencoded 'redirect_uri=https://app.superblocks.com/oauth/callback'

If Client authentication is set to Send as basic auth header

curl --request POST \
    --url '{token_url}' \
    --header 'Accept: application/json' \
    --header 'Authorization: Basic {Base64-encoded client_id and client_secret}' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencoded 'grant_type=authorization_code' \
    --data-urlencoded 'code=AUTHORIZATION_CODE' \
    --data-urlencoded 'redirect_uri=https://app.superblocks.com/oauth/callback'

Expected Response

HTTP/1.1 200 OK
Content-Type: application/json
{
    "token_type": "Bearer",
    "expires_in": 86400,
    "access_token": "eyJz93a...k4laUWw",
    "refresh_token": "GEbRxBN...edjnXbL",
    "id_token": "eyJ0XAi...4faeEoQ"
}

On-Behalf-Of Token Exchange

warning

This flow can only be used by organizations with an OIDC-based Single Sign-On flow configured. If you're not sure how you SSO provider is configured, contact support for assistance.

The On-Behalf-Of Token Exchange is a delegated access flow that lets a client exchange an access token received from an upstream client for a new token by interacting with an authorization server. In the case of Superblocks, this flows lets Superblocks exchange access tokens issued when a user logs in via an IdP, with an authorization server to get an access token to send to downstream servers.

For example, lets say your backend API is secured using tokens issued by Okta. This flow allows you to exchange a user's Superblocks access token with an Okta authorization server to obtain access tokens for your backend API without requiring the user to log in again.

To use the on-behalf-of token exchange flow:

1. In the Integration configuration select OAuth2 - On-Behalf-Of Token Exchange

2. Select a Subject token source

   • Login Identity Provider: Use the JWT issued to Superblocks during user log in as the subject_token
   • Static Token: Provide a static token to use as the subject_token
   warning

   If you choose Login Identity Provider, this integration can't be used in Workflows or Scheduled Jobs since it will require a user's JWT to authenticate

3. Specifying the following configuration values:

   Field	Required	Description
   Token URL		The token endpoint of the authorization server, used to exchange an authorization code for an access token
   Client ID		The ID issued to your OAuth client during registration.
   Client secret		The secret issued to your OAuth client during registration.
   Audience		The intended recipient of the token, usually in a format like https://api-a.example.com. Check API docs for the format.
   Scopes		The scopes that you want to request authorization for. These must be separated by spaces.

4. Use the oauth object in Headers or Params to define how the token response should be sent to the resource server. For example, to send the access token as an Authorization header, set:

   

When an API with this auth type executes, the Superblocks Agent will send a request to the /token endpoint of the authorization server, including in the request a subject_token based on the source selected. After an access token is returned, it is cached to improve future API performance. Once the token expires, Superblocks reinitiates the token exchange for you.

If you use your IdP as the source of the subject token and the IdP token has expired, the user will be prompted to log in again to obtain a new subject token.

Learn more about token caching and refresh

Full specification

POST Token URL

Exchanging user's JWT issued at login or static token for new access token

Request

curl --location --request POST \
  --url '{token_url}' \
  --header 'Accept: application/json' \
  --header 'Authorization: Basic {Base64-encoded client_id and client_secret}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  --data-urlencode 'subject_token_type=urn:ietf:params:oauth:token-type:access_token' \
  --data-urlencode 'subject_token={current user JWT issued at login or static token}' \
  --data-urlencode 'scope={scopes}' \
  --data-urlencode 'audience={audience}'

Expected Response

HTTP/1.1 200 OK
Content-Type: application/json
{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "eyJraWQiOiJR.....ajXZIk3GryDPC8OIhLsQ",
    "scope": "api:access:read api:access:write",
    "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}

Client Credential

Client credential grant types are typically not used to access user data but instead for machine-to-machine communication. When an API executes, Superblocks exchanges OAuth client information with the authorization server to get an access token. That token is then used in the subsequent request.

To use the client credential flow:

1. In the Integration configuration select OAuth2 - Client Credentials Grant

2. Specify the following configuration values:

   Field	Required	Description
   Token URL		The token endpoint of the authorization server, used to exchange an authorization code for an access token. Note: this value is not required for public APIs and is set by Superblocks
   Client ID		The ID issued to your OAuth client during registration.
   Client secret		The secret issued to your OAuth client during registration.
   Audience		The intended recipient of the token, usually in a format like https://api-a.example.com. Check API docs for the format.
   Scopes		The scopes that you want to request authorization for. These must be separated by spaces.

3. Use the oauth object in Headers or Params to define how the token response should be sent to the resource server. For example, to send the access token as an Authorization header, set:

   

After an access token is retrieved it is cached to improve future API performance. Once the token expires, Superblocks reinitiates the token exchange to get a new token. Learn more in token caching and refresh.

Full specification

POST Token URL

Get an access token using the client ID and client secret

Request

curl --request POST \
  --url {token_url} \
  --header 'Accept: application/json' \
  --header 'Authorization: Basic {Base64-encoded client_id and client_secret}' \
  --header 'Cache-Control: no-cache' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencoded 'grant_type=client_credentials' \
  --data-urlencoded 'scope={scopes}' \
  --data-urlencoded 'audience={audience}'

Expected Response

HTTP/1.1 200 OK
Content-Type: application/json
{
    "token_type": "Bearer",
    "expires_in": 86400,
    "access_token": "eyJhbG[...]1LQ",
    "scope": "customScope"
}

Implicit

Implicit flows are primarily intended for browser-based apps that don't support Cross-Origin Resource Sharing (CORS) or lack modern cryptography APIs. In this flow, the client doesn't make a request to a /token endpoint, but instead receives the access token in the redirect from the /authorize endpoint.

warning

This flow is less secure, it's recommended to use Authorization Code if available. Because it is intended for less-trusted clients, it doesn't support refresh tokens.

To use the implicit flow:

1. In the Integration configuration select OAuth2 - Implicit Grant

2. Copy the Callback URL provided and add it to the Allowed Callback URLs of your OAuth client

3. Specify the following configuration values:

   Field	Required	Description
   Authorization URL		The endpoint users will be redirected to to login and authorize access. Note: this value is not required for public APIs and is set by Superblocks
   Client ID		The ID issued to your OAuth client during registration.
   Audience		The intended recipient of the token, usually in a format like https://api-a.example.com. Check API docs for the format.
   Prompt		Determines if user is prompted for consent. To skip the prompt and perform silent authentication, set to none
   Scopes		The scopes that you want to request authorization for. These must be separated by spaces.

4. Use the oauth object in Headers or Params to define how the token response should be sent to the resource server. For example, to send the access token as an Authorization header, set:

   

This flow is initiated in the user's browser when an API using this Integration executes. After an access token is returned, it is saved as an HTTP-Only secure cookie in the user's browser. Once the token expires, Superblocks will reprompt the user to log in. Learn more about token caching.

warning

Since a user must log in, integrations that use this auth method can't be used in Workflows or Scheduled Jobs

Full specification

GET Authorization URL

Request

GET {authorization_url}?
   client_id={client_id}&
   scope={scopes}}&
   audience={audience}&
   response_type=token&
   redirect_uri=https%3A%2F%2Fapp.superblocks.com%2Foauth%2Fcallback&
   state=STATE&
   nonce=NONCE

Expected Response

HTTP/1.1 302 Found
Location: https://app.superblocks.com/oauth/callback#access_token=TOKEN&
    state=STATE&
    token_type=Bearer&
    scope={scopes}&
    expires_in=SECONDS

Password Grant (Legacy)

The Password Grant (Legacy) flow, sometimes referred to as a Resource Owner Password flow, is an OAuth flow intended for highly-trusted apps that can't do redirects. With this flow, either the Integration Configurer or an end-user will provide a username and password. These credentials will be sent to the /token endpoint, which then responds with a short-lived access token.

To use the password grant (legacy) flow:

1. In the Integration configuration select OAuth2 - Password Grant (Legacy)

2. Specify the following configuration values:

   Field	Required	Description
   Token URL		The token endpoint of the authorization server, used to exchange an authorization code for an access token. Note: this value is not required for public APIs and is set by Superblocks
   Client ID		The ID issued to your OAuth client during registration.
   Client secret		The secret issued to your OAuth client during registration.
   Audience		The intended recipient of the token, usually in a format like https://api-a.example.com. Check API docs for the format.

3. If you want to use shared credentials, check Share username/password across all users and provide the shared username & password

   warning

   If the shared credentials option is not selected, integrations with this auth method cannot be used in Workflows or Scheduled Jobs

4. Use the oauth object in Headers or Params to define how the token response should be sent to the resource server. For example, to send the access token as an Authorization header, set:

   

If shared credentials aren't used, users will be prompted for a username/password before APIs can execute.

Once an access token is returned, it is saved as an HTTP-Only secure cookie in the browser. Superblocks will prompt the user to log back in when the token expires. Learn more about token caching.

Full specification

POST Token URL

Request

curl --request POST \
  --url {token_url} \
  --header 'Accept: application/json' \
  --header 'Authorization: Basic {Base64-encoded client_id and client_secret}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencoded 'grant_type=password' \
  --data-urlencoded 'username=USERNAME' \
  --data-urlencoded 'password=PASSWORD' \
  --data-urlencoded 'scope={scopes}' \
  --data-urlencoded 'audience={audience} \

Expected Response

HTTP/1.1 200 OK
Content-Type: application/json
{
    "token_type": "Bearer",
    "expires_in": 86400,
    "access_token": "eyJz93a...k4laUWw",
    "id_token": "eyJhb[...]yosFQ",
    "scope": "customScope"
}

The oauth object

The results of an OAuth 2.0 exchange can be referrenced in your Integration configuration using the oauth object. The oauth object has the following properties.

Property	Datatype	Description	Full Path
token	STRING	The access token returned by the OAuth flow	oauth.token
idToken	STRING	The ID token returned by the OAuth flow if available	oauth.idToken
tokenDecoded	OBJECT	A JSON object of the decoded ID token claims	oauth.tokenDecoded

Token caching and refresh

This section includes specifics on how OAuth 2.0 access tokens are handled. For more information on sessions management see our guide on Credential & Session Management

How tokens are cached

OAuth 2.0 flows result in an access token that is used when making requests to a service. Once an access token is obtained through an OAuth flow, it is cached by Superblocks based on both the OAuth client generating the token (client_id, audience, scopes, etc) and the user for whom the token was issued.

Because tokens are cached based on the OAuth client, you can use the same OAuth client across integrations. If a user already has a cached token for the OAuth client from a different integration, Superblocks will use that cached token, even when executing requests with integrations the user has never used.

Caching reduces the need for repeated authentication requests, improving performance and the user experience of your Superblocks app.

Cache locations

Tokens are either cached in the user's browser or Superblocks Cloud server depending on the nature of the token generated. See the table below to understand where tokens are cached based on the OAuth 2.0 flow.

Tokens are only ever cached in the browser if the OAuth 2.0 flow is a high-trust flow that exposes tokens to the client. These tokens are stored in HTTP-Only Secure cookies that are not accessible to client-side JavaScript.

OAuth 2.0 Flow	Shared Credentials	Cache location
Authorization Code		Server-side
Authorization Code		Server-side
On-Behalf-Of Token Exchange		Server-side
On-Behalf-Of Token Exchange		Server-side
Client Credential		Server-side
Implicit		Client-side
Password Grant (Legacy)		Client-side
Password Grant (Legacy)		Server-side

Refreshing access tokens

During certain OAuth 2.0 flows, the authorization server returns a long-lived refresh token. When refresh token is present, Superblocks will automatically use it to refresh expired access tokens in the background before executing requests. The refreshed access token is then cached for future use.

The following OAuth methods support token refresh flows:

• Authorization Code
• Password Grant (Legacy)