Introduction to OAuth¶

Snowflake supports the OAuth 2.0 protocol for authentication and authorization. OAuth is an open-standard protocol that allows supported clients authorized access to Snowflake without sharing or storing user login credentials. This is known as delegated authorization, because a user authorizes the client to act on their behalf to retrieve their data. Snowflake offers two OAuth pathways: Snowflake OAuth and External OAuth.

Snowflake OAuth uses Snowflake’s built-in OAuth service and supports the following applications:

External OAuth integrates a Customer’s OAuth 2.0 server and supports three authorization server options, custom clients, and two partner applications.

The following table compares Snowflake OAuth and External OAuth.

Category	Snowflake OAuth	External OAuth
Modify client application	Required	Required
Client application browser access	Required	Not required
Programmatic clients	Requires a browser	Best fit
Driver property	`authenticator = oauth`	`authenticator = oauth`
Security integration syntax	`create security integration type = oauth ...`	`create security integration type = external_oauth`
OAuth flow	OAuth 2.0 code grant flow	Any OAuth flow that the client can initiate with the External OAuth server

Snowflake enables OAuth for clients through integrations. An integration is a Snowflake object that provides an interface between Snowflake and third-party services. Administrators configure OAuth using a security integration, a type of integration that enables clients that support OAuth to redirect users to an authorization page and generate access tokens (and optionally, refresh tokens) for access to Snowflake.

In this Topic:

OAuth Concepts¶

Authorization Server¶

This server displays an interface to a user to approve or deny client access to their data. The server issues an access token to the client after successfully authenticating the user and validating an authorization request.

Access Token¶

A string that represents the authorization granted to a client by a user to access their data using a specified role. These tokens expire after a short period; a refresh mechanism can be used to obtain new access tokens.

Refresh Token¶

A string that is used to obtain a new access token when it expires. A refresh token is optionally issued by the authorization server to the client together with an access token. The client can use the refresh token to request another access token, avoiding involving the user again until the refresh token expires. At that point, the OAuth workflow is invoked again.

Resource Server¶

This server protects the resource (i.e. Snowflake) and handles requests to access the resource using access tokens.

Confidential and Public Clients¶

Confidential clients can store the OAuth client_secret. They run in a protected area where end users cannot access them. For example, a secured service deployed on the cloud could be a confidential client; whereas, a client running on a desktop or distributed through an app store could be a public client.

For public clients, the user must authorize client access to Snowflake every time using a specified role. For confidential clients, the user only needs to authorize client access once for a specified role.

Snowflake supports OAuth for both confidential and public clients.

Snowflake OAuth Authorization Flow¶

The OAuth authorization flow is as follows:

In the client, the user attempts to connect to Snowflake using OAuth.

The application sends an authorization request to the Snowflake authorization server, which in turn displays an authorization screen that asks the user to authorize access.
The user submits the Snowflake login name and password, and is in turn presented with a consent screen to allow the client access to Snowflake using a specific role in a user session (e.g. SYSADMIN or CUSTOM_ROLE1).

The user submits consent to use the specific role in a session.

The Snowflake authorization server sends an authorization code back to the client.
The client sends the authorization code back to the Snowflake authorization server to request an access token and, optionally, a refresh token that allows the client to obtain new access tokens.

The Snowflake authorization server accepts the authorization code and provides the client with an access token specific to the user resources in the Snowflake resource server. Based on the settings in the authorization request, the authorization server issues a refresh token to obtain new access tokens tied to the specific resource.
The client sends the access token to the Snowflake resource server.

The resource server recognizes the valid access token and creates a user session with the authorized role. The client now has access to the Snowflake resources limited by the role specified by the access token.

Access tokens have a short life; typically 10 minutes. When the access token expires, the client can send a refresh token to obtain new access tokens. A refresh token is sent to the Snowflake authorization server to request a new access token each time the current access token expires (Steps 3-6). If the integration is configured to prevent sending refresh tokens, the user must repeat the above steps to re-authorize the client.

Configuring OAuth Support¶

Snowflake OAuth Partner Applications¶

To configure support, see Configure Snowflake OAuth for Partner Applications.

To learn about using OAuth without traversing the public Internet, see OAuth and Private Connectivity.

Snowflake OAuth Custom Clients¶

Snowflake supports custom clients configured by your organization. To configure support, see Configure Snowflake OAuth for Custom Clients.

External OAuth Partner Applications¶

To configure External OAuth partner applications, see External OAuth Partner Applications.

External OAuth Custom Clients¶

Snowflake supports External OAuth custom clients configured by your organization. To configure support, see Configure Custom Clients for External OAuth.

Auditing OAuth Logins¶

To query login attempts by Snowflake users, Snowflake provides a login history:

LOGIN_HISTORY , LOGIN_HISTORY_BY_USER (table function)
LOGIN_HISTORY View (view)

When OAuth is used to authenticate (successfully or unsuccessfully), the FIRST_AUTHENTICATION_FACTOR column in the output has the value OAUTH_ACCESS_TOKEN.

Integration DDL¶

To support creating and/or managing integrations and delegated authorizations, Snowflake provides the following set of special DDL commands:

OAuth and Federated Authentication¶

Snowflake supports OAuth with Federated Authentication & SSO (single sign-on) using any identity provider (IdP) supported by Snowflake.

With federated authentication configured, the authorization flow is as follows:

In the client, the user attempts to connect to Snowflake.

The application sends an authorization request to the Snowflake authorization server, which in turn displays an authorization screen that asks the user to authorize access.
The user clicks the option to log in using the IdP and is redirected to the IdP authentication page.
The user submits the IdP login name and password, and is in turn presented with a consent screen to allow the client access to Snowflake using a specific role in a user session (e.g. SYSADMIN or CUSTOM_ROLE1).

The user submits consent to use the specific role in a session.

The Snowflake authorization server sends an authorization code back to the client.
The client sends the authorization code back to the Snowflake authorization server to request an access token and, optionally, a refresh token that allows the client to obtain new access tokens.

The Snowflake authorization server accepts the authorization code and provides the client with an access token specific to the user resources in the Snowflake resource server. Based on the settings in the authorization request, the authorization server issues a refresh token to obtain new access tokens tied to the specific resource.
The client sends the access token to the Snowflake resource server.

The resource server recognizes the valid access token and creates a user session with the authorized role. The client now has access to the Snowflake resources limited by the role specified by the access token.

OAuth and Private Connectivity¶

Snowflake supports External OAuth with Private Connectivity to the Snowflake Service.

Snowflake OAuth and Tableau can be used with private connectivity to Snowflake as follows:

Tableau Desktop

Starting with Tableau 2020.4, Tableau contains an embedded OAuth client that supports connecting to Snowflake with the account URL for Private Connectivity to the Snowflake Service.

After upgrading to Tableau 2020.4, no further configuration is needed; use the corresponding private connectivity URL for either AWS or Azure to connect to Snowflake.

Tableau Server

Starting with Tableau 2020.4, users can optionally configure Tableau Server to use the embedded OAuth Client to connect to Snowflake with the account URL for Private Connectivity to the Snowflake Service.

To use this feature, create a new Custom Client security integration and follow the Tableau instructions.

Tableau Online

Tableau Online does not support the Snowflake account URL for Private Connectivity to the Snowflake Service because Tableau Online requires access to the public Internet.

Please contact Tableau for more information regarding when Tableau Online will support the private connectivity Snowflake account URLs for Private Connectivity to the Snowflake Service.

Important

To determine the account URL to use with Private Connectivity to the Snowflake Service, call the SYSTEM$GET_PRIVATELINK_CONFIG function.

Looker

Currently, combining Snowflake OAuth and Looker requires access to the public Internet. Therefore, you cannot use Snowflake OAuth and Looker with Private Connectivity to the Snowflake Service.

For more information, see:

OAuth and Network Policies¶

You can integrate a dedicated network policy with Snowflake OAuth only. The External OAuth security integration does not support setting a separate network policy, but you can still use a general network policy that applies to the entire Snowflake account.

The Snowflake OAuth security integration has a network_policy parameter so that the Snowflake OAuth integration can authenticate and authorize users without adding these IP addresses for normal user access.

Setting up a network policy specific to the Snowflake OAuth integration allows the Snowflake OAuth network policy to be distinct from other network policies that may apply to the Snowflake account. The Snowflake OAuth network policy does not affect other network policies on the account nor do other account network policies affect the Snowflake OAuth network policy. Therefore, the Snowflake OAuth network policy allows for the authentication and authorization of users as intended.

Important

If a network policy per user or account is set and you are using a service that runs in a different location (e.g. Microsoft Power BI Service), you will not be able to connect to Snowflake.

After creating the Snowflake OAuth security integration, set the OAuth network policy using this command:

alter security integration <oauth_integration> set network_policy = <oauth_network_policy>;

To unset the Snowflake OAuth network policy, use this command:

alter security integration <oauth_integration> unset <oauth_network_policy>;

Where:

<oauth_integration>: Specifies the name of the Snowflake OAuth security integration.
<oauth_network_policy>: Specifies the Snowflake OAuth network policy in Snowflake.

For more information, see Network Policies and ALTER SECURITY INTEGRATION (Snowflake OAuth).

OAuth and Secondary Roles¶

Snowflake supports using secondary roles with External Oauth.

For more information, see Using Secondary Roles with External OAuth.

Note that in-session role switching to secondary roles with Snowflake OAuth is not supported.

OAuth with Clients, Drivers, and Connectors¶

Supported clients, drivers, and connectors can use OAuth to verify user login credentials.

Note the following:

It is necessary to set the authenticator parameter to oauth and the token parameter to the oauth_access_token.
When passing the token value as a URL query parameter, it is necessary to URL-encode the oauth_access_token value.
When passing the token value to a Properties object (e.g. JDBC Driver), no modifications are necessary.

For more information, see the connection parameters for each client, driver, or connector.

OAuth and Client Redirect¶

Snowflake supports using Client Redirect with Snowflake OAuth and External OAuth, including using Client Redirect and OAuth with supported Snowflake Clients.

For more information, see Redirecting Client Connections.

OAuth and Replication¶

Snowflake supports replication and failover/failback with both the Snowflake OAuth and External OAuth security integrations from the source account to the target account.

For details, see Replication of Security Integrations & Network Policies Across Multiple Accounts.

OAuth Error Codes¶

The following are error codes associated with OAuth that can be returned during the authorization flow, the token exchange, or when creating a Snowflake session after completing the OAuth flow:

Error Code	Error	Description
390302	OAUTH_CONSENT_INVALID	Issue generating or validating consent for a given user.
390303	OAUTH_ACCESS_TOKEN_INVALID	Access token provided used when attempting to create a Snowflake session is expired or invalid.
390304	OAUTH_AUTHORIZE_INVALID_RESPONSE_TYPE	Invalid `response_type` was provided as a parameter to the authorization endpoint (it should most likely be `code`).
390305	OAUTH_AUTHORIZE_INVALID_STATE_LENGTH	State parameter provided as a parameter to the authorization endpoint exceeds 2048 characters.
390306	OAUTH_AUTHORIZE_INVALID_CLIENT_ID	Integration associated with a provided client id does not exist.
390307	OAUTH_AUTHORIZE_INVALID_REDIRECT_URI	`redirect_uri` given as a parameter to the authorization endpoint does not match the `redirect_uri` of the integration associated with the provided `client_id` or the `redirect_uri` is not properly formatted.
390308	OAUTH_AUTHORIZE_INVALID_SCOPE	Either the scope requested is not a valid scope, or the scopes requested cannot fully be granted to the user.
390309	OAUTH_USERNAMES_MISMATCH	The user you were trying to authenticate as differs from the user tied to the access token.
390311	OAUTH_AUTHORIZE_INVALID_CODE_CHALLENGE_PARAMS	Either the code challenge or code challenge method is missing, invalid, or not supported.
390318	OAUTH_ACCESS_TOKEN_EXPIRED	OAuth access token expired. {0}
390144	JWT_TOKEN_INVALID	JWT token is invalid.

Additionally, the following errors are taken from the RFC and are returned in the JSON blob generated during an unsuccessful token request or exchange:

Error	Description
invalid_client	There was a failure relating to client authentication, such as the client being unknown, a client secret mismatch, etc.
invalid_grant	The provided authorization grant or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.
unsupported_grant_type	A grant type was provided that Snowflake currently does not support (“refresh_token” and “authorization_code” are the only two supported grant types at the moment).
invalid_request	The request was malformed or could not be processed.