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).
Use Cases & Benefits¶
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.
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.
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.
Clients can authenticate to Snowflake without browser access, allowing ease of integration with the External OAuth server.
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.
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.
Configure your External OAuth authorization server in your environment and the security integration in Snowflake to establish a trust.
A user attempts to access Snowflake data through their business intelligence application, and the application attempts to verify the user.
On verification, the authorization server sends a JSON Web Token (i.e. OAuth token) to the client application.
The Snowflake driver passes a connection string to Snowflake with the OAuth token.
Snowflake validates the OAuth token.
Snowflake performs a user lookup.
On verification, Snowflake instantiates a session for the user to access data in Snowflake based on their role.
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, use the ALTER ACCOUNT command to set the EXTERNAL_OAUTH_ADD_PRIVILEGED_ROLES_TO_BLOCKED_LIST account parameter to FALSE.
For Okta, PingFederate, and Custom, use the role scope pattern in the following table.
For Azure AD, see Prerequisite 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
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
Maps to a custom Snowflake role. For example, if your custom role is ANALYST, your scope is
Maps to the PUBLIC Snowflake role.
Using Secondary Roles with External OAuth¶
Snowflake supports using secondary roles with External OAuth.
For more information, see:
External OAuth and Client Redirect¶
Snowflake supports using Client Redirect with External OAuth, including using Client Redirect and OAuth with supported Snowflake Clients.
For more information, see Redirecting Client Connections.
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.
If you encounter an error message associated with a failed External OAuth login attempt, and the error message has a UUID, you can ask an administrator that has a MONITOR privilege assigned to their role to use the UUID from the error message to get a more detailed description of the error using the SYSTEM$GET_LOGIN_FAILURE_DETAILS function.