Key Pair Authentication: Troubleshooting

This topic helps you troubleshoot errors that occur when connecting to Snowflake with key pair authentication. It focuses on errors that contain JWT token is invalid.

Find the Error

Before troubleshooting, you need to determine that the issue is resulting in a JWT token is invalid error.

If your Snowflake client is a driver or connector that does not have an interactive interface, use logs to inspect connection errors:

  1. Enable logging for the Snowflake connector or driver. For details, see Generate log files for Snowflake Drivers & Connectors (https://community.snowflake.com/s/article/How-to-generate-log-file-on-Snowflake-connectors) (Snowflake Knowledge Base article).

  2. Check for errors that contain the string JWT token is invalid.

    For example, a client using the Snowflake JDBC driver might get the following error when trying to use key pair authentication:

    yyyy-mm-dd hh:mm:ss.nnn n.s.c.jdbc.SnowflakeSQLException FINE <init>:40 -
Snowflake exception: JWT token is invalid. [0ce9eb56-821d-4ca9-a774-04ae89a0cf5a],
sqlState:08001, vendorCode:390,144, queryId:

Retrieve additional details

Each JWT token is invalid error includes a UUID that appears in brackets immediately after the error (for example, JWT token is invalid. [0ce9eb56-821d-4ca9-a774-04ae89a0cf5a]). You should provide the UUID of the error to a Snowflake administrator so they can obtain more information about the error.

Administrators use the SYSTEM$GET_LOGIN_FAILURE_DETAILS function to obtain additional details about the error. For example, to obtain additional information about the error JWT token is invalid. [0ce9eb56-821d-4ca9-a774-04ae89a0cf5a], a user with the ACCOUNTADIMN role can execute:

SELECT JSON_EXTRACT_PATH_TEXT(SYSTEM$GET_LOGIN_FAILURE_DETAILS('0ce9eb56-821d-4ca9-a774-04ae89a0cf5a'), 'errorCode');
Copy

The JSON_EXTRACT_PATH_TEXT function parses the JSON output of the SYSTEM$GET_LOGIN_FAILURE_DETAILS function to retrieve the error code and error.

List of Errors

The output of the SYSTEM$GET_LOGIN_FAILURE_DETAILS function is one of the following error code/error combinations.

Error Code

Error

Description

390144

JWT_TOKEN_INVALID

There is a general issue with the JWT token. For possible solutions, see Common Errors and Solutions.

394300

JWT_TOKEN_INVALID_USER_IN_ISSUER

The user name specified in the issuer does not exist in the Snowflake account. For possible solutions, see Common Errors and Solutions.

394301

JWT_TOKEN_MISSING_ISSUE_OR_EXPIRATION_TIME

The JWT token does not contain an issue time or an expiration time.

394302

JWT_TOKEN_INVALID_ISSUE_TIME

The JWT token was received by Snowflake more than 60 seconds after the issue time. For possible solutions, see Common Errors and Solutions.

394303

JWT_TOKEN_INVALID_EXPIRATION_TIME

The JWT token is expired.

394304

JWT_TOKEN_INVALID_PUBLIC_KEY_FINGERPRINT_MISMATCH

There is a mismatch between the public key fingerprint specified in the issuer and the one stored for the user in Snowflake. For possible solutions, see Common Errors and Solutions.

394305

JWT_TOKEN_INVALID_ALGORITHM

The JWT token was not signed with the RS256 algorithm.

394306

JWT_TOKEN_INVALID_SIGNATURE

Snowflake could not verify the signature provided by the JWT token. It is possible that the JWT was signed with a private key that is not paired with the provided public key. It is also possible that the JWT signature is corrupt or has been modified.

Common Errors and Solutions

The most common errors associated with key pair authentication are:

Use the following descriptions and solutions to troubleshoot these errors.

JWT_TOKEN_INVALID

Description:

There is a general problem with the JWT token.

Solution #1:

The token itself might be malformed. Double-check that the application accessing Snowflake is generating valid JWT tokens.

Solution #2:

Double-check that the client (driver, connector, or request URL) is using the correct account identifier to connect to the Snowflake account. You should also check that this value matches the account identifier in the iss claim.

Solution #3:

Double-check that the account identifier and user name in the sub claim match the corresponding values in the iss claim.

Solution #4:

Double-check that iss claim specifies SHA256 as the signing algorithm.

JWT_TOKEN_INVALID_PUBLIC_KEY_FINGERPRINT_MISMATCH

Description:

There is a mismatch between the public key fingerprint specified in the issuer and the one stored for the user in Snowflake.

Solution:

Obtain the public key fingerprint of the JWT token, then compare it with the fingerprint associated with the user in Snowflake.

One method of obtaining the fingerprint of the JWT token is to enable DEBUG logging for your driver (https://community.snowflake.com/s/article/How-to-generate-log-file-on-Snowflake-connectors) and attempt to login. Look for the pattern SHA256:<hash>, where <hash> is the public key fingerprint.

To obtain the public key fingerprint associated with the user in Snowflake, execute the DESCRIBE USER command. The public key fingerprint is located in either the RSA_PUBLIC_KEY_FP or the RSA_PUBLIC_KEY_2_FP property. If the user is missing a public key fingerprint, execute the ALTER USER command to set these properties.

JWT_TOKEN_INVALID_USER_IN_ISSUER

Description:

The user name specified in the issuer does not exist in the Snowflake account.

Solution:

The user name configured in the Snowflake client must match the LOGIN_NAME of the Snowflake user, not its NAME. Sometimes these values are different.

Execute the DESCRIBE USER command and verify that the value of the LOGIN_NAME property matches the user name that the Snowflake client is using to connect.

JWT_TOKEN_INVALID_ISSUE_TIME

Description:

The JWT token was received by Snowflake more than 60 seconds after the issue time.

Solution #1:

Check the host where the driver is running to ensure it is synchronized to NTP and doesn’t have clock skew. If the server clock is skewed, Snowflake might determine that the current time is more than 60 seconds after the issue time of the token, when it really isn’t. For example, if the client machine is 30 seconds behind and it took the token 45 seconds to reach Snowflake, then Snowflake determines that it has been 75 seconds since the JWT token was issued, not 45 seconds.

You can check that the clock of the client machine is accurate by comparing it to an NTP server. For example, you can use NIST Internet Time Servers (https://tf.nist.gov/tf-cgi/servers.cgi) to sync the client machine. For help with checking and synchronizing your host’s clock to an NTP server, refer to the administrator guide for your operating system or reach out to a system administrator.

Solution #2:

Use an OS-specific monitoring tool to determine if the error occurs during times of extreme CPU/disk usage.

Solution #3:

Check whether there is excessive network latency that is causing the JWT token to be processed by Snowflake more than 60 seconds after the token’s issue time.

When using a connectivity diagnostic tool to measure network latency, set the destination to account_identifier.snowflakecomputing.cn. For example, if the Snowflake client is using myorg-account1 as the account identifier, set the destination to myorg-account1.snowflakecomputing.cn.

Language: English