Multi-factor authentication (MFA)¶

Prompt user to add a new MFA method¶

If a user loses access to the MFA method that they use as their second factor of authentication (for example, by losing the YubiKey that stores their passkey), an administrator can help the user set up a new MFA method so that they can sign in to Snowflake.

When a user does not have access to their MFA method and needs to set up a new one, the administrator executes an ALTER USER … ENROLL MFA statement. For example, if user joe needs to establish a new MFA method, the administrator can execute the following:

ALTER USER joe ENROLL MFA;

• If the user has a verified email, Snowflake sends an email prompting them to add an MFA authentication method.

• If the user doesn’t have a verified email, Snowflake returns the URL of a page that prompts the user to add an MFA authentication method. Administrators can send this URL to the locked-out user.

Temporarily disable MFA¶

If an administrator needs to temporarily disable MFA for a user, they can execute an ALTER USER … SET MINS_TO_BYPASS_MFA statement. For example, to temporarily disable MFA so that user joe can authenticate with a single-factor password for 30 minutes, execute the following:

ALTER USER joe SET MINS_TO_BYPASS_MFA = 30;

Using MFA token caching to minimize the number of prompts during authentication — optional¶

MFA token caching can help to reduce the number of prompts that must be acknowledged while connecting and authenticating to Snowflake, especially when multiple connection attempts are made within a relatively short time interval.

A cached MFA token is valid for up to four hours.

The cached MFA token is invalid if any of the following conditions are met:

1. The ALLOW_CLIENT_MFA_CACHING parameter is set to FALSE for the account.

2. The method of authentication changes.

3. The authentication credentials change (i.e. username and/or password).

4. The authentication credentials are not valid.

5. The cached token expires or is not cryptographically valid.

6. The account name associated with the cached token changes.

The overall process Snowflake uses to cache MFA tokens is similar to that used to cache connection tokens for browser-based federated single sign-on. The client application stores the MFA token in the keystore of the client-side operating system. Users can delete the cached MFA token from the keystore at any time.

Snowflake supports MFA token caching with the following drivers, connectors, and tools on macOS and Windows. This feature is not supported on Linux.

• Snowflake CLI version 3.0 (or later)

• ODBC driver version 2.23.0 (or later).

• JDBC driver version 3.12.16 (or later).

• Python Connector for Snowflake version 2.3.7 (or later).

Snowflake recommends consulting with internal security and compliance officers prior to enabling MFA token caching.

To enable MFA token caching, complete the following steps:

1. As an account administrator (i.e. a user with the ACCOUNTADMIN system role), set the ALLOW_CLIENT_MFA_CACHING parameter to true for an account using the ALTER ACCOUNT command.

   ALTER ACCOUNT SET ALLOW_CLIENT_MFA_CACHING = TRUE;
   

   Copy

2. In the client connection string, update the authenticator value to authenticator = username_password_mfa.

3. Add the package or libraries needed by the driver or connector:

   • If you are using the Snowflake Connector for Python, install the optional keyring package by running:

     pip install "snowflake-connector-python[secure-local-storage]"
     

     Copy

     You must enter the square brackets ([ and ]) as shown in the command. The square brackets specify the extra part of the package that should be installed.

     Use quotes around the name of the package as shown to prevent the square brackets from being interpreted as a wildcard.

     If you need to install other extras (for example, pandas for using the Python Connector APIs for Pandas), use a comma between the extras:

     pip install "snowflake-connector-python[secure-local-storage,pandas]"
     

     Copy

   • For the Snowflake JDBC Driver, see Add the JNA classes to your classpath.

To disable MFA token caching, unset the ALLOW_CLIENT_MFA_CACHING parameter:

ALTER ACCOUNT UNSET ALLOW_CLIENT_MFA_CACHING;

To find all users who use MFA token caching as the second-factor authentication to log in, you can execute the following SQL statement as an account administrator (a user with the ACCOUNTADMIN role):

SELECT EVENT_TIMESTAMP,
       USER_NAME,
       IS_SUCCESS
  FROM SNOWFLAKE.ACCOUNT_USAGE.LOGIN_HISTORY
  WHERE SECOND_AUTHENTICATION_FACTOR = 'MFA_TOKEN';

Using MFA with SnowSQL¶

MFA can be used for connecting to Snowflake through SnowSQL. By default, the Duo Push authentication mechanism is used when a user is enrolled in MFA.

To use a Duo-generated passcode instead of the push mechanism, the login parameters must include one of the following connection options:

--mfa-passcode <string> OR --mfa-passcode-in-password

For more details, see SnowSQL (CLI client).

Using MFA with JDBC¶

MFA can be used for connecting to Snowflake via the Snowflake JDBC driver. By default, the Duo Push authentication mechanism is used when a user is enrolled in MFA; no changes to the JDBC connection string are required.

To use a Duo-generated passcode instead of the push mechanism, one of the following parameters must be included in the JDBC connection string:

passcode=<passcode_string> OR passcodeInPassword=on

Where:

• passcode_string is a Duo-generated passcode for the user who is connecting. This can be a passcode generated by the Duo Mobile application or an SMS passcode.

• If passcodeInPassword=on, then the password and passcode are concatenated, in the form of <password_string><passcode_string>.

For more details, see JDBC Driver.

Using MFA with Node.js¶

MFA can be used for connecting to Snowflake through the Snowflake Node.js driver. By default, the Duo Push authentication mechanism is used when a user is enrolled in MFA.

To use a Duo-generated passcode instead of the push mechanism, the login parameters must include one of the following connection options. Both examples use a password of abc123 and MFA passcode of 987654 to demonstrate the configuration.

• Set the passcodeInPassword option to true and include the passcode as part of the password string, similar to the following:

  authenticator: 'USERNAME_PASSWORD_MFA',
  password: "abc123987654", // passcode 987654 is part of the password
  passcodeInPassword: true  // because passcodeInPassword is true
  

  Copy

• Set the passcode option to the value of the passcode to specify the password and the passcode separately, similar to the following:

  authenticator: 'USERNAME_PASSWORD_MFA',
  password: "abc123", // password and MFA passcode are input separately
  passcode: "987654"
  

  Copy

  To use this approach, ensure that the passcodeInPassword option is false (the default value). If both passcodeInPassword is set to true and passcode is also configured, the passcodeInPassword setting takes precedence and the driver assumes the password field contains both the password and the MFA passcode when authenticating.

For more details, see Use an MFA passcode.

Using MFA with ODBC¶

MFA can be used for connecting to Snowflake via the Snowflake ODBC driver. By default, the Duo Push authentication mechanism is used when a user is enrolled in MFA; no changes to the ODBC settings are required.

To use a Duo-generated passcode instead of the push mechanism, one of the following parameters must be specified for the driver:

passcode=<passcode_string> OR passcodeInPassword=on

Where:

• passcode_string is a Duo-generated passcode for the user who is connecting. This can be a passcode generated by the Duo Mobile application or an SMS passcode.

• If passcodeInPassword=on, then the password and passcode are concatenated, in the form of <password_string><passcode_string>.

For more details, see ODBC Driver.

Using MFA with Python¶

MFA can be used for connecting to Snowflake via the Snowflake Python Connector. By default, the Duo Push authentication mechanism is used when a user is enrolled in MFA; no changes to the Python API calls are required.

To use a Duo-generated passcode instead of the push mechanism, one of the following parameters must be specified for the driver in the connect() method:

passcode=<passcode_string> OR passcode_in_password=True

Where:

• passcode_string is a Duo-generated passcode for the user who is connecting. This can be a passcode generated by the Duo Mobile application or an SMS passcode.

• If passcode_in_password=True, then the password and passcode are concatenated, in the form of <password_string><passcode_string>.

For more details, see the description of the connect() method in the Functions section of the Python Connector API documentation.