Multi-factor authentication (MFA)

Snowflake supports multi-factor authentication (i.e. MFA) to provide increased login security for users connecting to Snowflake. MFA support is provided as an integrated Snowflake feature, powered by the Duo Security service, which is managed completely by Snowflake.

Users do not need to separately sign up with Duo or perform any tasks, other than installing the Duo Mobile application, which is supported on multiple smart phone platforms (iOS, Android, Windows, etc.). See the Duo User Guide for more information about supported platforms/devices and how Duo multi-factor authentication works.

MFA is enabled on a per-user basis; however, at this time, users are not automatically enrolled in MFA. To use MFA, users must enroll themselves.

Attention

At a minimum, Snowflake strongly recommends that all users with the ACCOUNTADMIN role be required to use MFA.

Prerequisite

The Duo application service communicates through TCP port 443.

To ensure consistent behavior, update your firewall settings to include the Duo application service on TCP port 443.

*.duosecurity.com:443
Copy

For more information, see the Duo documentation.

MFA login flow

The following diagram illustrates the overall login flow for a user enrolled in MFA, regardless of the interface used to connect:

MFA login flow

Enrolling a Snowflake user in MFA

Any Snowflake user can self-enroll in MFA through the web interface. For more information, see Manage your user profile by using Snowsight.

Switching phones used for MFA

Instant Restore is a Duo feature that allows a user to backup the Duo app before switching to a new phone. As long as a Snowflake user backs up their old phone first, they can use Instant Restore to enable authentication on the new phone without interrupting MFA for Snowflake.

If a user does not back up the old phone or loses the old phone, the Snowflake account administrator must disable MFA for each username that used the old phone before MFA can be re-enabled on the new phone.

Managing MFA for an account and users

At the account level, MFA requires no management. It is automatically enabled for an account and available for all users to self-enroll. However, the account administrator (i.e. the user granted the ACCOUNTADMIN system role) may find the need to disable MFA for a user, either temporarily or permanently, for example if the user loses their phone or changes their phone number and cannot log in with MFA.

The account administrator can use the following properties for the ALTER USER command to perform these tasks:

  • MINS_TO_BYPASS_MFA

    Specifies the number of minutes to temporarily disable MFA for the user so that they can log in. After the time passes, MFA is enforced and the user cannot log in without the temporary token generated by the Duo Mobile application.

  • DISABLE_MFA

    Disables MFA for the user, effectively canceling their enrollment. It may be necessary to refresh the browser to verify that the user is no longer enrolled in MFA. To use MFA again, the user must re-enroll.

    Note

    DISABLE_MFA is not a column in any Snowflake table or view. After an account administrator executes the ALTER USER command to set DISABLE_MFA to TRUE, the value for the EXT_AUTHN_DUO property is automatically set to FALSE.

    To verify that MFA is disabled for a given user, execute a DESCRIBE USER statement and check the value for the EXT_AUTHN_DUO property.

The account administrator (that is, a user granted the ACCOUNTADMIN system role) can also use Hardening user or account authentication using MFA to enforce users to enroll in MFA.

Connecting to Snowflake with MFA

MFA login is designed primarily for connecting to Snowflake through the web interface, but is also fully-supported by SnowSQL and the Snowflake JDBC, Node.js, and ODBC drivers.

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 and connectors on macOS and Windows. This feature is not supported on Linux.

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

Tip

MFA token caching can be combined with connection caching in federated single sign-on.

To combine these two features, ensure that the ALLOW_ID_TOKEN parameter is set to true in tandem with the ALLOW_CLIENT_MFA_CACHING parameter.

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 Adding 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;
Copy

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';
Copy

Using MFA with Snowsight

To sign in to Snowsight with MFA:

  1. Sign in to Snowsight.

  2. Enter your credentials (user login name and password).

  3. If Duo Push is enabled, you may select a notification method. If Send Me a Push is selected, a push notification is sent to your Duo Mobile application. When you receive the notification, select Approve and you will be logged into Snowflake.

    MFA selection dialog with Send Me a Push, Call Me and Enter a Passcode options.

    As shown on the above, instead of using the push notification, you can also choose to:

    • Select Call Me to receive login instructions from a phone call to the registered mobile device.

    • Select Enter a Passcode to log in by manually entering a passcode provided by the Duo Mobile application.

Using MFA with the Classic Console web interface

To log into the Classic Console with MFA:

  1. Point your browser at the URL for your account. For example: https://myorg-account1.snowflakecomputing.com.

  2. Enter your credentials (user login name and password).

  3. If Duo Push is enabled, a push notification is sent to your Duo Mobile application. When you receive the notification, select Approve and you will be logged into Snowflake.

    MFA selection dialog with Send Me a Push, Call Me and Enter a Passcode options.

    As shown on the above screenshot, instead of using the push notification, you can also choose to:

    • Select Call Me to receive login instructions from a phone call to the registered mobile device.

    • Select Enter a Passcode to log in by manually entering a passcode provided by the Duo Mobile application.

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.

Examples of JDBC connection strings using Duo

JDBC connection string for user demo connecting to the xy12345 account (in the US West region) using a Duo passcode:

jdbc:snowflake://xy12345.snowflakecomputing.com/?user=demo&passcode=123456
Copy

JDBC connection string for user demo connecting to the xy12345 account (in the US West region) using a Duo passcode that is embedded in the password:

jdbc:snowflake://xy12345.snowflakecomputing.com/?user=demo&passcodeInPassword=on
Copy

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.

MFA error codes

The following are error codes associated with MFA that can be returned during the authentication flow.

The errors are displayed with each failed login attempt. Historical data is also available in Snowflake Information Schema and Account Usage:

Error Code

Error

Description

390120

EXT_AUTHN_DENIED

Duo Security authentication is denied.

390121

EXT_AUTHN_PENDING

Duo Security authentication is pending.

390122

EXT_AUTHN_NOT_ENROLLED

User is not enrolled in Duo Security. Contact your local system administrator.

390123

EXT_AUTHN_LOCKED

User is locked from Duo Security. Contact your local system administrator.

390124

EXT_AUTHN_REQUESTED

Duo Security authentication is required.

390125

EXT_AUTHN_SMS_SENT

Duo Security temporary passcode is sent via SMS. Please authenticate using the passcode.

390126

EXT_AUTHN_TIMEOUT

Timed out waiting for your login request approval via Duo Mobile. If your mobile device has no data service, generate a Duo passcode and enter it in the connect string.

390127

EXT_AUTHN_INVALID

Incorrect passcode was specified.

390128

EXT_AUTHN_SUCCEEDED

Duo Security authentication is successful.

390129

EXT_AUTHN_EXCEPTION

Request could not be completed due to a communication problem with the external service provider. Try again later.

390132

EXT_AUTHN_DUO_PUSH_DISABLED

Duo Push is not enabled for your MFA. Provide a passcode as part of the connection string.