Configure Snowflake OAuth for custom clients¶

Workflow¶

The following high-level steps are required to configure OAuth for custom clients:

1. Register your client with Snowflake. To register your client, create an integration. An integration is a Snowflake object that provides an interface between Snowflake and third-party services, such as a client that supports OAuth.

   The registration process defines a client ID and client secrets.

2. Configure calls to the Snowflake OAuth endpoints to request authorization codes from the Snowflake authorization server and to request and refresh access tokens.

   The optional “scope” parameters in the initial authorization request limit the role permitted by the access token and can additionally be used to configure the refresh token behavior.

Create a Snowflake OAuth integration¶

Create a Snowflake OAuth integration using the CREATE SECURITY INTEGRATION command. Be sure to specify OAUTH_CLIENT = CUSTOM when creating the integration.

CREATE SECURITY INTEGRATION oauth_kp_int
  TYPE = OAUTH
  ENABLED = TRUE
  OAUTH_CLIENT = CUSTOM
  OAUTH_CLIENT_TYPE = 'CONFIDENTIAL'
  OAUTH_REDIRECT_URI = 'https://localhost.com'
  OAUTH_ISSUE_REFRESH_TOKENS = TRUE
  OAUTH_REFRESH_TOKEN_VALIDITY = 86400
  BLOCKED_ROLES_LIST = ('SYSADMIN')
  OAUTH_CLIENT_RSA_PUBLIC_KEY ='
  MIIBI
  ...
  ';

Call the OAuth endpoints¶

OAuth endpoints are the URLs that clients call to request authorization codes and to request and refresh access tokens. These endpoints refer to specific OAuth 2.0 policies that execute when the endpoint is called.

Snowflake provides the following OAuth endpoints:

Authorization:

<snowflake_account_url>/oauth/authorize

Token requests:

<snowflake_account_url>/oauth/token-request

Where <snowflake_account_url> is a valid Snowflake account URL. For example, you might use the endpoints https://myorg-account_xyz.snowflakecomputing.com/oauth/authorize and https://myorg-account_xyz.snowflakecomputing.com/oauth/token-request. For a list of supported formats for the Snowflake account URL, see Connecting with a URL.

To see a list of valid OAuth endpoints for a security integration, execute DESCRIBE INTEGRATION, and then view the values in the OAUTH_ALLOWED_AUTHORIZATION_ENDPOINTS and OAUTH_ALLOWED_TOKEN_ENDPOINTS properties.

<snowflake_account_url>/oauth/authorize

<snowflake_account_url>/oauth/token-request

Content-type: application/x-www-form-urlencoded

{
  "access_token":  "ACCESS_TOKEN",
  "expires_in": 600,
  "refresh_token": "REFRESH_TOKEN",
  "token_type": "Bearer",
  "username": "user1",
}

{
  "data" : null,
  "message" : "This is an invalid client.",
  "code" : null,
  "success" : false,
  "error" : "invalid_client"
}

<snowflake_account_url>/oauth/token

Content-type: application/x-www-form-urlencoded

{
    'grant_type': 'urn:ietf:params:oauth:grant-type:jwt-bearer',
    'scope': 'session:role:TEST_ROLE ab12-orgname-acctname.snowflakecomputing.app',
    'assertion': '<token>'
}

{
    'grant_type': 'urn:ietf:params:oauth:grant-type:jwt-bearer',
    'scope': 'ab12-orgname-acctname.snowflakecomputing.app',
    'assertion': '<token>'
}

Proof key for code exchange¶

Snowflake supports Proof Key for Code Exchange (PKCE) for obtaining access tokens using the authorization_code grant type as described in RFC 7636. PKCE can be used to lessen the possibility of an authorization code interception attack, and is suitable for clients that might not be able to fully keep the client secret secure.

By default, PKCE is optional and is enforced only if the code_challenge and code_challenge_method parameters are both included in the authorization endpoint URL. However, Snowflake highly recommends that your client require PKCE for all authorizations to make the OAuth flow more secure.

The following describes how PKCE for Snowflake works:

1. The client creates a secret called the code verifier and performs a transformation on it to generate the code challenge. The client holds onto the secret.

   Important

   Generate the code verifier from the allowed ASCII characters according to Section 4.1 of RFC 7636.

2. The client directing the user to the Authorization URL appends the following two query parameters:

   code_challenge

   Specifies the code challenge generated in Step 1.

   code_challenge_method

   Specifies the transformations used on the code verifier in Step 1 to generate the code challenge. Currently, Snowflake only supports SHA256, so this value must be set to S256. The transformation algorithm for SHA256 is BASE64URL-ENCODE(SHA256(ASCII(code_verifier))).

3. After the user consents to the requested scopes or Snowflake determines that consent is present for that user, the authorization code is issued.

4. The client receives the authorization code from the Snowflake authorization server, which it then submits along with the code_verifier in the request to the token endpoint.

5. Snowflake transforms the code_verifier value and verifies that the transformed value matches the code_challenge value used when generating authorizations. If these values match, then the authorization server issues the access and refresh tokens.

Using key-pair authentication¶

Snowflake supports using key pair authentication rather than the typical username/password authentication when calling the OAuth token endpoint. This authentication method requires a 2048-bit (minimum) RSA key pair. Generate the PEM (Privacy Enhanced Mail) public-private key pair using OpenSSL. The public key is assigned to the Snowflake user who uses the Snowflake client.

To configure the public/private key pair:

1. From the command line in a terminal window, generate an encrypted private key:

   $ openssl genrsa 2048 | openssl pkcs8 -topk8 -v2 des3 -inform PEM -out rsa_key.p8
   

   Copy

   OpenSSL prompts for a passphrase used to encrypt the private key file. Snowflake recommends using a strong passphrase to protect the private key. Record this passphrase. You must input it when connecting to Snowflake. Note that the passphrase is only used for protecting the private key and is never sent to Snowflake.

   Sample PEM private key

   -----BEGIN ENCRYPTED PRIVATE KEY-----
   MIIE6TAbBgkqhkiG9w0BBQMwDgQILYPyCppzOwECAggABIIEyLiGSpeeGSe3xHP1
   wHLjfCYycUPennlX2bd8yX8xOxGSGfvB+99+PmSlex0FmY9ov1J8H1H9Y3lMWXbL
   ...
   -----END ENCRYPTED PRIVATE KEY-----
   

   Copy

2. From the command line, generate the public key by referencing the private key:

   $ openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub
   

   Copy

   Sample PEM public key

   -----BEGIN PUBLIC KEY-----
   MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAy+Fw2qv4Roud3l6tjPH4
   zxybHjmZ5rhtCz9jppCV8UTWvEXxa88IGRIHbJ/PwKW/mR8LXdfI7l/9vCMXX4mk
   ...
   -----END PUBLIC KEY-----
   

   Copy

3. Copy the public and private key files to a local directory for storage. Record the path to the files.

   Note that the private key is stored using the PKCS#8 (Public Key Cryptography Standards) format and is encrypted using the passphrase you specified in the previous step; however, the file should still be protected from unauthorized access using the file permission mechanism provided by your operating system. It is your responsibility to secure the file when it is not being used.

4. Assign the public key to the integration object using ALTER SECURITY INTEGRATION. For example:

   ALTER SECURITY INTEGRATION myint SET OAUTH_CLIENT_RSA_PUBLIC_KEY='MIIBIjANBgkqh...';
   

   Copy

   Note

   • Only account administrators can execute the ALTER SECURITY INTEGRATION command.

   • Exclude the public key header and footer in the command.

   Verify the public key fingerprint using DESCRIBE INTEGRATION:

   DESC SECURITY INTEGRATION myint;
   
   +----------------------------------+---------------+----------------------------------------------------------------------+------------------+
   | property                         | property_type | property_value                                                       | property_default |
   |----------------------------------+---------------+----------------------------------------------------------------------+------------------|
   ...
   | OAUTH_CLIENT_RSA_PUBLIC_KEY_FP   | String        | SHA256:MRItnbO/123abc/abcdefghijklmn12345678901234=                  |                  |
   | OAUTH_CLIENT_RSA_PUBLIC_KEY_2_FP | String        |                                                                      |                  |
   ...
   +----------------------------------+---------------+----------------------------------------------------------------------+------------------+
   

   Copy

   Note

   The OAUTH_CLIENT_RSA_PUBLIC_KEY_2_FP property is described in Key Rotation (in this topic).

5. Modify and execute the sample code below. The code uses the private key to encode a JWT and then passes that token to the Snowflake authorization server:

   • Update the security parameters:

     • <private_key>: Contents of the decrypted rsa_key.p8 (including BEGIN and END), which you can obtain by executing openssl rsa -in rsa_key.p8 -text.

   • Update the session parameters:

     • <account_locator>: Your account locator code, for example CIB07125. You cannot use the account name (for example, myorg-account_xyz).

   • Update the token-request endpoint in the _make_request() function:

     • <account_name>: This is the account name format of your account’s identifier (for example, myorg-account_xyz).

   • Update the public key fingerprint:

     • <public_key_fp>: Retrieved by executing the DESC SECURITY INTEGRATION command. There can be 2 public keys so ensure you’re referencing the correct key.

   • Update the redirect URI:

     • <redirect_uri>: The redirect URI your integration is configured with. Execute the DESC SECURITY INTEGRATION command to obtain it.

   • Obtain an OAuth authorization code:

     • <oauth_az_code>: Obtained after authenticating with your /authorize endpoint. Note: this code needs to be refreshed periodically.

   • Update the JSON Web Token (JWT) fields:

     post body

     A JSON object with the following standard fields (“claims”):

     Attribute	Data Type	Required	Description
     iss	String	Yes	Specifies the principal that issued the JWT in the format client_id.public_key_fp where client_id is the client ID of the OAuth client integration and public_key_fp is the fingerprint of the public key that is used during verification.
     sub	String	Yes	Subject of the JWT in the format account_locator.client_id where
     account_locator is your Snowflake account locator and client_id is the client ID of the OAuth client integration. Depending on the cloud platform (AWS or Azure) and region where your account is hosted, the full account name might require additional segments. For more information, see the account variable description under Token endpoint.
     iat	Timestamp	No	Time when the token was issued.
     exp	Timestamp	Yes	Time when the token should expire. This period should be relatively short (e.g. a few minutes).

   Sample code

   Note that the private_key value (decrypted) includes the -----BEGIN header and the -----END footer.

   import datetime
   import json
   import urllib
   
   import jwt
   import requests
   
   private_key = """
   <private_key>
   """
   
   public_key_fp = "<public_key_fp>" # SHA256:MR...
   
   
   def _make_request(payload, encoded_jwt_token):
       token_url = "https://<account_name>.snowflakecomputing.com/oauth/token-request"
       headers = {
               u'Authorization': "Bearer %s" % (encoded_jwt_token),
               u'content-type': u'application/x-www-form-urlencoded'
       }
       r = requests.post(
               token_url,
               headers=headers,
               data=urllib.urlencode(payload))
       return r.json()
   
   
   def make_request_for_access_token(oauth_az_code, encoded_jwt_token):
       """ Given an Authorization Code, make a request for an Access Token
       and a Refresh Token."""
       payload = {
           'grant_type': 'authorization_code',
           'code': oauth_az_code,
           'redirect_uri': <redirect_uri>
       }
       return _make_request(payload, encoded_jwt_token)
   
   
   def make_request_for_refresh_token(refresh_token, encoded_jwt_token):
       """ Given a Refresh Token, make a request for another Access Token."""
       payload = {
           'grant_type': 'refresh_token',
           'refresh_token': refresh_token
       }
       return _make_request(payload, encoded_jwt_token)
   
   
   def main():
       account_locator = "<account_locator>"
       client_id = "1234"  # found by running DESC SECURITY INTEGRATION
       issuer = "{}.{}".format(client_id, public_key_fp)
       subject = "{}.{}".format(account_locator, client_id)
       payload = {
           'iss': issuer,
           'sub': subject,
           'iat': datetime.datetime.utcnow(),
           'exp': datetime.datetime.utcnow() + datetime.timedelta(seconds=30)
       }
       encoded_jwt_token = jwt.encode(
               payload,
               private_key,
               algorithm='RS256')
   
       data = make_request_for_access_token(<oauth_az_code>, encoded_jwt_token)
       refresh_token = data['refresh_token']
       data = make_request_for_refresh_token(refresh_token, encoded_jwt_token)
       access_token = data['access_token']
   
   
   if __name__ == '__main__':
       main()
   

   Copy

   After the token is created, submit it in requests to the token endpoint. Requests require the Bearer authorization format as the authorization header instead of the basic authorization format normally used for the client ID and client secret, as follows:

   "Authorization: Bearer JWT_TOKEN"
   

   Copy

Error codes¶

See the 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.

Pre-authorizing user consent for a role¶

Security administrators (i.e. users with the SECURITYADMIN role) or higher can pre-authorize consent for a client to initiate a session for a user using a specified role and integration. This consent is granted using ALTER USER with the ADD DELEGATED AUTHORIZATION keywords. Without this delegated authorization, a user must authorize consent for the role after authentication. This delegated authorization can also be revoked.

For more information, see Managing user consent for OAuth.