Introduction to OAuth

.

Related Topics

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 a 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 enter their Snowflake username and password each time before authorizing client access to Snowflake using the specified role. For confidential clients, the user only needs to enter their credentials once for the specified role.

Snowflake supports OAuth for both confidential and public clients.

Snowflake OAuth Authorization Flow

The OAuth authorization flow is as follows:

Snowflake OAuth workflow

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

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

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

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

Currently, Snowflake supports OAuth authorization with the following Snowflake partner applications:

Client

Required Client Version

Client Type

Tableau Desktop / Server / Online

2019.1 or higher

Public

Looker

6.20 or higher

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

Currently, Snowflake supports Microsoft Power BI as an External OAuth partner application.

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:

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:

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

  2. The user clicks the option to log in using the IdP and is redirected to the IdP authentication page.

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

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

  5. 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 AWS PrivateLink and Azure Private Link.

Snowflake OAuth and Tableau can be used with either AWS PrivateLink or Azure Private Link 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 AWS PrivateLink and Azure Private Link.

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 either AWS PrivateLink or Azure Private Link.

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 either AWS PrivateLink or Azure Private Link 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 AWS PrivateLink and Azure Private Link.

Important

To determine the account URL to use with either AWS PrivateLink or Azure Private Link, run 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 either AWS PrivateLink or Azure Private Link.

For more information, see:

OAuth and Network Policies

You can use network policies with Snowflake OAuth only. The External OAuth security integration does not support setting a separate network policy.

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