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 |
|
|
Security integration syntax |
|
|
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 Authorization Servers 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.
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 tooauth
and thetoken
parameter to theoauth_access_token
.When passing the
token
value as a URL query parameter, it is necessary to URL-encode theoauth_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 |
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 |
|
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. |