Set up Snowflake External OAuth with Okta as your IdP

This guide describes how to use the External OAuth auth method of the Snowflake Integration. It includes instructions for configuring Snowflake as an OAuth Resource and Okta as an External OAuth authorization server to use with Superblocks.

Once configured, you'll be able to connect to Snowflake on behalf of the current Superblocks user and enforce data access using your already defined roles and permissions in Snowflake.

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 Snowflake account with ACCOUNTADMIN permission

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

External OAuth 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. If the API includes a step to query Snowflake, the Superblocks Agent will make a request to your Okta authorization server to exchange the user’s Okta JWT for a new access token intended for Snowflake
4. The Okta authorization server will validate the user’s JWT and grants a new access token with the necessary sub, aud, and scp to access Snowflake
5. The Superblocks Agent connects to Snowflake using this access token
6. Your Snowflake instance validates the JWT and decodes it to authenticate the user to Snowflake
7. Provided the user is authenticated, Superblocks executes their query and returns data to the browser

For more resources on this auth flow, see:

• Snowflake's docs to Configure Okta for External OAuth
• Okta's docs on Authorization Servers
• Superblocks docs on OAuth 2.0 - On-Behalf-Of Token Exchange

Set up instructions

The following instructions show how to configure Okta, Snowflake, and 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.

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

Create the authorization server

1. In the Admin Console, go to Security → API
2. On the Authorization Servers tab
3. Click Add Authorization Server and in the dialog enter the following:
   • Name: Snowflake Authorization Server
   • Description: Issue access tokens for Snowflake
   • Audience: The URL of the Snowflake account you want to connect to. For example https://<your-snowflake-account>.snowflakecomputing.com
4. Click Save

Finding your Snowflake Account URL

If you don't know your Snowflake account URL, log into Snowflake and click on the profile icon, as shown below, to copy the URL.

Add session:role-any scope

1. From the authorization server, select the Scopes tab
2. Click Add scopes
3. In the dialog, enter the following:
   • Name: session:role-any
   • Display phrase: session:role-any
   • Description: Ask Snowflake to let Superblocks assume the user's roles
   • User consent: Implicit
   • Metadata: Include in public metadata
4. Click Save

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

   Use the following values for the policy:

   • Name: Access Snowflake
   • 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 Snowflake
   • AND Scopes requested: Select The following scopes, and select the session:role-any scope
   • AND Refresh token lifetime is: Unlimited (this is recommmended but not required)

Learn more about how to Create an Okta Authorization Servers

Collect Okta information

1. From the authorization server, select the Settings tab
2. Click on the Metadata URI link to open the metadata document
3. In this document, locate the following values:

Metadata Value	Example	Snowflake Reference Value
issuer	https://dev-111111.oktapreview.com/oauth2/auslh9j9vf9ej7NfT0h7	OKTA_ISSUER
jwks_uri	https://dev-111111.oktapreview.com/oauth2/auslh9j9vf9ej7NfT0h7/v1/keys	OKTA_JWS_KEY_ENDPOINT
token_endpoint	https://dev-111111.oktapreview.com/oauth2/auslh9j9vf9ej7NfT0h7/v1/token	OKTA_OAUTH_TOKEN_ENDPOINT

Create Snowflake Security Integration

With the information you've gathered from your Okta Authorization Server, you'll now create a security integration in Snowflake. The security integration ensures that Snowflake can communicate with Okta securely, validates the tokens from Okta, and provides the appropriate Snowflake data access to users based on the user role associated with the OAuth token.

For more information, see Snowflake's docs on CREATE SECURITY INTEGRATION

1. Log in to your Snowflake account
2. Change your current role to ACCOUNTADMIN or to a role with the global CREATE INTEGRATION privilege
3. Run the following SQL command

   create security integration Superblocks_Okta_Security_Integration
       type = external_oauth
       enabled = true
       external_oauth_type = okta
       external_oauth_issuer = '<OKTA_ISSUER>'
       external_oauth_jws_keys_url = '<OKTA_JWS_KEY_ENDPOINT>'
       external_oauth_audience_list = ('<SNOWFLAKE_ACCOUNT_URL>')
       external_oauth_token_user_mapping_claim = 'sub'
       external_oauth_snowflake_user_mapping_attribute = 'login_name';

Update SSO Metadata

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

To do this, we will need to the .well-known/openid-configuration URL of your Snowflake Authorization Server we just created. To location this URL:

1. Go to the Settings tab of your Snowflake 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 us Token Exchange

info

If you want to use the token exchange flow with you backend APIs as well as Snowflake, make sure you've added this server as a trusted server to all other auth server you'll use in Superblocks.

Configure Snowflake 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 Snowflake Integration. To do so:

1. Navigate to the Integrations page and locate your Snowflake integration or create a new one

2. In the Connection method dropdown, select External OAuth

3. Choose Login Identity Provider as the Subject token source

4. Specifying the following configuration values:

   Field	Required	Description
   Account identifier		Snowflake Account Identified
   Token URL		Set to the OKTA_OAUTH_TOKEN_ENDPOINT value
   Client ID		The client_id of the API created earlier
   Client secret		The client_secret of the API created earlier
   Audience		SNOWFLAKE_ACCOUNT_URL
   Scopes		session:role-any

info

You can choose to set a default warehouse, schema, and role for the integration. If none are set, we will assume the defaults set by the user executing the query.

Testing & troubleshooting

Test your Integration

With your Integration updated to use your Okta authorization server, you're ready to start writing queries.

1. In a Application create a new Backend API
2. Add a step that uses your Snowflake Integration
3. Run the SQL comment SELECT CURRENT_USER();
4. Click Run API

If everything is working properly, you should see YOUR Snowflake user name returned.

Common errors

There are several common errors you may see when using token exchange. The table below include error messages, 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.