# External OAuth Overview¶

External OAuth integrates the customer’s OAuth 2.0 server to provide a seamless SSO experience, especially for programmatic client applications connecting to Snowflake. The External OAuth topics describe how to configure External OAuth using OAuth 2.0 to facilitate secure, programmatic access to Snowflake data for the supported authorization servers, custom clients, and supported partner applications.

Snowflake supports three External OAuth servers, a custom integration, and two partner applications.

After configuring your organization’s External OAuth server, which includes any necessary OAuth 2.0 Scopes mapping to Snowflake roles, the user can connect to Snowflake securely and programmatically without having to enter any additional authentication or authorization factors or methods. The user’s access to Snowflake data is dependent on both their role and the role being integrated into the access token for the session. For more information, see Scopes (in this topic).

In this Topic:

## Use Cases & Benefits¶

1. Snowflake delegates the token issuance to a dedicated authorization server to ensure that the OAuth Client and user properly authenticate. The result is centralized management of tokens issued to Snowflake.

2. Customers can integrate their policies for authentication (e.g. multi-factor, subnet, biometric) and authorization (e.g. no approval, manager approval required) into the authorization server. The result is greater security leading to more robust data protection by issuing challenges to the user. If the user doesn’t pass the policy challenge(s), the Snowflake session is not instantiated, and access to Snowflake data does not occur.

3. For programmatic clients that can access Snowflake and users that only initiate their Snowflake sessions through External OAuth, no additional authentication configuration (i.e. set a password) is necessary in Snowflake. The result is that service accounts or users used exclusively for programmatic access will only ever be able to use Snowflake data when going through the External OAuth configured service.

4. Clients can authenticate to Snowflake without browser access, allowing ease of integration with the External OAuth server.

5. Snowflake’s integration with External OAuth servers is cloud-agnostic.

• It does not matter whether the authorization server exists in a cloud provider’s cloud or if the authorization server is on-premises. The result is that customers have many options in terms of configuring the authorization server to interact with Snowflake.

## General Workflow¶

For each of the supported identity providers, the workflow for OAuth relating to External OAuth authorization servers can be summarized as follows. Note that the first step only occurs once and the remaining steps occur with each attempt to access Snowflake data.

1. Configure your External OAuth authorization server in your environment and the security integration in Snowflake to establish a trust.

2. A user attempts to access Snowflake data through their business intelligence application, and the application attempts to verify the user.

3. On verification, the authorization server sends a JSON Web Token (i.e. OAuth token) to the client application.

4. The Snowflake driver passes a connection string to Snowflake with the OAuth token.

5. Snowflake validates the OAuth token.

6. Snowflake performs a user lookup.

7. On verification, Snowflake instantiates a session for the user to access data in Snowflake based on their role.

## Scopes¶

The scope parameter in the authorization server limits the operations and roles permitted by the access token and what the user can access after instantiating a Snowflake session. Note that the ACCOUNTADMIN and SECURITYADMIN roles are blocked by default. If it is necessary to use either or both of these two roles, please contact Snowflake Support.

• For Okta, PingFederate, and Custom, use the role scope pattern in the following table.

• For Azure AD, see Pre-Requisite Step: Determine the OAuth Flow in Azure AD

• If you do not want to manage Snowflake roles in your External OAuth server, pass the static value of SESSION:ROLE-ANY in the scope attribute of the token.

The following table summarizes External OAuth scopes. Note that if you do not define a scope, the connection attempt to Snowflake will fail.

Scope / Role Connection Parameter

Description

session:role-any

Maps to the ANY role in Snowflake. . If the user’s default role in Snowflake is desirable, pass this scope in the External OAuth token. . The external_oauth_any_role_mode security integration parameter must be configured in order to enable ANY role for a given External OAuth Provider. . For configuration details, see the ANY role section in Okta, Azure AD, PingFederate, Custom, or Power BI SSO.

session:role:<custom_role>

Maps to a custom Snowflake role. For example, if your custom role is ANALYST, your scope is session:role:analyst.

session:role:public

Maps to the PUBLIC Snowflake role.

## Troubleshooting¶

• Use the SYSTEM\$VERIFY_EXTERNAL_OAUTH_TOKEN function to determine whether your External OAuth access token is valid or needs to be regenerated.

• See the OAuth Error Codes for a list of error codes associated with OAuth, as well as errors that are returned in the JSON blob, during the authorization flow, token request or exchange, or when creating a Snowflake session after completing the OAuth flow.