OAuth 2.0 authentication / authorization

​

OAuth 2.0 overview

​

Glossary

• 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

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

​

Choosing an OAuth 2.0 flow

​

Using OAuth 2.0

​

Authorization Code

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.
   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:

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

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

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'

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'

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

1. In the Integration configuration select OAuth2 - On-Behalf-Of Token Exchange
2. Select a Subject token source
   • Login Identity Provider: Use the token issued to Superblocks when users logged in as the subject_token
   • Static Token: Provide a static token to use as the subject_token
   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
   Subject token type	✗	The type of security token provided in the Static token field or by your IdP when logging into Superblocks. Defaults to urn:ietf:params:oauth:token-type:access_token
   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:

curl --location --request POST \
  --url '{token_url}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  --data-urlencode 'client_id={client_id}' \
  --data-urlencode 'client_secret={client_secret}' \
  --data-urlencode 'subject_token_type={subject_token_type or 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}'

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

​

Client Credential

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:

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}'

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

​

Implicit

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:

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

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)

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
   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:

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

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

​

Token caching and refresh

​

How tokens are cached

​

Cache locations

​

Refreshing access tokens

• Authorization Code
• Password Grant (Legacy)