Authenticating Snowflake REST APIs with Snowflake¶
This topic describes how to authenticate to the server when using the Snowflake REST APIs.
When you send a request, the request must include authentication information using either of the following:
Using key pair authentication¶
When using key pair authentication, you need to complete the following tasks:
Set up key pair authentication¶
To use key pair authentication, follow these steps:
Set up key pair authentication.
As part of this process, you must:
Generate a public-private key pair. The generated private key should be in a file (e.g. named
rsa_key.p8
).Assign the public key to your Snowflake user. After you assign the key to the user, run the DESCRIBE USER command. In the output, the
RSA_PUBLIC_KEY_FP
property should be set to the fingerprint of the public key assigned to the user.
For instructions on how to generate the key pair and assign a key to a user, see Key-pair authentication and key-pair rotation.
Use SnowSQL to verify that you can use the generated private key to connect to Snowflake:
$ snowsql -a <account_identifier> -u <user> --private-key-path <path>/rsa_key.p8
If you generated an encrypted private key, SnowSQL prompts you for the passphrase that you created when you generated the key.
Generate a JWT token¶
To generate a JWT token in your application code, use the following steps:
Generate the fingerprint (a SHA-256 hash) of the public key for the user. Prefix the fingerprint with
SHA256:
.For example:
SHA256:hash
You can also execute the SQL DESCRIBE USER command to get the value from the RSA_PUBLIC_KEY_FP property.
Generate a JSON Web Token (JWT) with the following fields in the payload:
Field
Description
Example
iss
Issuer of the JWT. Set it to the following value:
account_identifier.user.SHA256:public_key_fingerprint
where:
account_identifier
is your Snowflake account identifier.If you are using the account locator, exclude any region information from the account locator.
user
is your Snowflake user name.SHA256:public_key_fingerprint
is the fingerprint that you generated in the previous step.
Note
The
account_identifier
anduser
values must use all uppercase characters.MYORGANIZATION-MYACCOUNT.MYUSER.SHA256:public_key_fingerprint
sub
Subject for the JWT. Set it to the following value:
account_identifier.user
MYORGANIZATION-MYACCOUNT.MYUSER
iat
Issue time for the JWT in UTC. Set the value to the current time value as either seconds or milliseconds.
1615370644
(seconds) .1615370644000
(milliseconds)exp
Expiration time for the JWT in UTC. You can specify the value as either seconds or milliseconds.
Note
The JWT is valid for at most one hour after the token is issued, even if you specify a longer expiration time.
1615374184
(seconds) .1615374184000
(milliseconds)In each API request that you send, set the following headers:
Authorization: Bearer JWT
where
JWT
is the token that you generated.X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT
Using OAuth¶
To use OAuth, follow these steps:
Set up OAuth for authentication.
See Introduction to OAuth for details on how to set up OAuth and get an OAuth token.
Use SnowSQL to verify that you can use a generated OAuth token to connect to Snowflake:
For Linux and MacOS systems
$ snowsql -a <account_identifier> -u <user> --authenticator=oauth --token=<oauth_token>
For Windows systems
$ snowsql -a <account_identifier> -u <user> --authenticator=oauth --token="<oauth_token>"
In each API request you send, set the following headers:
Authorization: Bearer oauth_token
where
oauth_token
is the generated OAuth token.X-Snowflake-Authorization-Token-Type: OAUTH