Set up OAuth 2.0 On-Behalf-Of Token Exchange with Okta as your IdP

This guide describes how to configure Okta as an authorization server for your REST or GraphQL based backend API.

With this auth method, Superblocks will be able to perform a machine-to-machine token exchange to get an access token for your backend API without losing context who is making the request in your Superblocks app. This lets your API perform auth checks using the user's permissions without forcing your user through a second login flow for your backend API.

Prerequisites

To follow this guide, you'll need:

• An Okta account with the following permissions:
  • API Access Management Administrator
  • Application Administrator
• An existing Superblocks SSO configuration using Okta OIDC
• A REST or GraphQL-based backend API

warning

If your Superblocks SSO currently uses a SAML-based flow, please reach out to our support team for assistance migrating to an OIDC-based log-in flow

Token Exchange flow

note

Note: This flow assumes the user is already logged into Superblocks

When using this flow:

1. Your user will log in to Superblocks using your Okta OIDC app
2. When the user executes an API, a request is sent from the browser to the Superblocks Agent that includes the user's Okta JWT
3. The API includes a step to make a request to your backend API. The Superblocks Agent will make a request to your Okta authorization server to exchange the user’s Okta JWT for a new token intended for your backend API
4. The Okta authorization server validates the user’s JWT and then grants a new access token with scopes that allows Superblocks to make requests to your backend API. The new access token retains the user context so your backend API knows on whose behalf the request is made.
5. The Superblocks Agent makes a request to your backend API and includes the new access token

For more details on this token exchange in Superblocks, see our docs on the OAuth 2.0 - On-Behalf-Of Token Exchange auth method.

Set up instructions

The following instructions show how to configure Okta & Superblocks to perform the token exchange.

Create an API in Okta

To perform the token exchange, you'll need to create an API application that the Superblocks Agent will use to act as an OAuth client for your backend API.

1. Log in to Okta and go to the Admin Console
2. Navigate to Applications → Applications
3. Click Create App Integration
4. Select API Services followed by Next
5. Name the app something like Superblocks Integration and click Save
6. Click Edit in the General Settings section of the General tab
7. Uncheck the checkbox for Require Demonstrating Proof of Possession (DPoP) header in token requests
8. Check the checkbox for Token Exchange and click Save
9. Make a note of the Client ID in the Client Credentials section and the Client Secret in the CLIENT SECRETS section

Create an Authorization Server

During the token exchange, the Superblocks Agent exchanges the user's OpenID access token granted during log in with an Okta Authorization Server configured to issue tokens for our backend API.

Create the authorization server

1. In the Admin Console, go to Security → API

2. On the Authorization Servers tab, click Add Authorization Server

3. Enter a Name, Audience, and Description for the authorization server

   info

   Note: The Audience value specified will be set as the aud claim of the access token sent to your backend API. The Audience property should be set to the URI expected by your API.

Add custom scopes & claims

1. From the authorization server, select the Scopes tab
2. Click Add scopes and add any custom scopes your backend API requires
3. Click on the Claims tab
4. Click Add claim and configure any custom claims you want to include on the access token

Create access policies and rules

1. From the authorization server, select the Access Policies tab and click Add Policy

2. In the Add Policy dialog that appears, enter the following:

   • Name: Access Superblocks
   • Description: Enter a description
   • Assign to: Select The following clients and search for your organization's Superblocks SSO application

3. Click Create Policy

4. Click Add Rule and in the dialog that appears, enter the following:

   • Name: Superblocks App to Agent
   • AND Scopes requested: Select The following scopes and enter openid

5. Click Create rule

6. Repeat steps 1 - 5 to create a policy and a rule that lets the Superblocks Agent talk to your backend API.
   Use the following values for the policy:

   • Name: Access Backend API
   • Assign to: Select The following clients, start typing the name of the API that you created earlier

   Use the following values for the rule:

   • Name: Agent to Backend API
   • AND Scopes requested: Select The following scopes, and select any of the custom scopes you configured previously
   • AND Refresh token lifetime is: Unlimited (this is recommmended but not required)

Learn more about how to Create an Okta Authorization Server

Update SSO Metadata

Superblocks SSO by default uses your Okta Org Authorization Server. To use token exchange, we'll need to update your SSO configuration to use a Custom Authorization Server.

To do this, we will need the .well-known/openid-configuration URL of your Authorization Server.

To locate this URL:

1. Go to the Settings tab of your Authorization Server
2. Copy the Metadata URI shown in the Settings section
3. Replace oauth-authorization-server with openid-configuration
4. Send this link to support@superblocks.com with the Subject Update Okta SSO to use Token Exchange

info

If your backend uses a micro-services architecture that has multiple APIs, or you plan on using token exchange for your backend API as well as services like Snowflake, make sure you've added this server as a trusted server to all other auth servers you'll use in Superblocks.

Update your Integration

Once you've gotten confirmation from Superblocks that we've updated your SSO to use the new Authorization Server, you're ready to configure your Integration. To do so:

1. Navigate to the Integrations page and search for your REST or GraphQL API

2. Select OAuth2 - On-Behalf-Of Token Exchange as the Authentication method

3. Choose Login Identity Provider as the Subject token source

4. Specifying the following configuration values:

   Field	Required	Description
   Token URL		The token_endpoint found in your Authorization Server's {SERVER}/.well-known/oauth-authorization-server metadata file
   Client ID		The client_id of the API created earlier
   Client secret		The client_secret of the API created earlier
   Audience		Your Authorization Server's Audience
   Scopes		Any custom scopes you configured for your authorization server

5. Use the oauth object in Headers or Params to define how the access token returned by the authorization server should be sent to your API

warning

Okta Authorization Servers can only return an access_token, not an id_token. For this reason, oauth.idToken and oauth.tokenDecoded aren't available when using this auth method.

Testing & troubleshooting

Test your Integration

With your Integration updated to use your Okta authorization server to issue access tokens, you're ready to test it in a Backend API.

1. In an Application create a new Backend API
2. Add a step that uses your Integration
3. Configure the step to make a request to your API
4. Click Run API

If everything is working properly, you should see the step respond as it would if you made a cURL request with your own access token to the API.

Troubleshooting

The easiest way to troubleshoot authorization issues is by inspecting the access token that Superblocks is sending to your API. To do this:

1. Make a copy of your Integration
2. Replace the Base URL with a API resting service like webhook.site or Postman Echo
3. Add an Authorization header with the value {{ oauth.token }}
4. Save the Integration
5. Build a Backend API that uses this "echo" integration
6. Run the API and copy the access token from the authorization header
7. Use a tool like JWT to inspect the token

Common errors

See the below guide for known error conditions, why they happen, and how to address them.

Error message	Why it's happening	Resolution
Could not find identity provider token	Your organization either doesn't use SSO or it's configured in a way that doesn't support token exchange	Follow docs to set up Okta SSO or contact support@superblocks.com to update your configuration
Identity provider token expired	Your Okta session has expired so the authorization server won't issue an access token	Refresh your browser, you should be prompted to reauthenticate. If you're not, log out and back in.
Could not find a user JWT	The Superblocks Agent doesn't have a user JWT so can't extract a subject_token to send to Okta. It most likely is occurring because the Integration is being used in a Workflow, Scheduled Job, or public App.	Refactor your code to use the Integration in a Backend API
Token exchange failed	Superblocks couldn't successfully complete the token exchange with the Okta authorization server.	See the additional error details provided by Okta. You may also be able to find additional error information in your Okta system logs.