MFA（多重身份验证）¶

Multi-factor authentication (MFA) reduces the security risks associated with password authentication. When a password user is enrolled in MFA, they must use a second factor of authentication when signing in to Snowflake. These users enter their password, and then use the second factor. For information about how a user adds an MFA method that they can use as a second factor of authentication, see Configuring a second factor of authentication.

MFA is intended for human users who authenticate with a password. Service users must use another form of authentication. For more information about these user types, see Types of users.

要求用户注册 MFA¶

Currently, strategies for implementing MFA for your organization vary depending on whether or not an account existed when the 2024_08 behavior change bundle was enabled:

• If an account existed before the 2024_08 bundle was enabled, then you must configure your account if you want to require all human users to use MFA. For information about implementing MFA to require all human users to enroll in MFA, see Hardening user or account authentication using MFA.

• If the account was created after the 2024_08 bundle was enabled, then all human users who authenticate with a password must enroll in MFA by default. This MFA requirement does not apply to service users.

  If you want to disable the requirement that all human users enroll in MFA, create a custom authentication policy with MFA_ENROLLMENT=OPTIONAL, and then set the authentication policy on the account. Password users who use Snowsight must still use MFA, but MFA isn’t required for other interfaces. For more information about creating and setting authentication policies, see Authentication policies.

  Be aware that the ability to opt out of mandatory MFA for human users is temporary; see Planning for the deprecation of single-factor password sign-ins.

Requiring MFA for single sign-on authentication¶

By default, Snowflake doesn’t require MFA for users who authenticate with single sign-on (SSO). Snowflake relies on the identity provider (IdP) to enforce MFA or some other strong authentication method. If you want to harden authentication for SSO users, you use an authentication policy to require SSO users to use Snowflake MFA after authenticating with the IdP.

The following authentication policy requires SSO users to enroll and use Snowflake MFA:

CREATE AUTHENTICATION POLICY ACCOUNTADMIN_DOUBLE_MFA
  AUTHENTICATION_METHODS = ('PASSWORD', 'SAML')
  SECURITY_INTEGRATIONS = ('<SAML SECURITY INTEGRATIONS>')
  MFA_ENROLLMENT = 'REQUIRED'
  MFA_POLICY=(ENFORCE_MFA_ON_EXTERNAL_AUTHENTICATION='ALL');

限制哪些 MFA 方法可用¶

当用户注册 MFA 时，他们需要使用一种 MFA 方法作为第二重身份验证因素。Snowflake 允许使用以下 MFA 方法：

• 使用可通过多种方式存储和访问的密钥进行身份验证。
• 使用可生成基于时间的一次性密码 (TOTP) 的身份验证器应用程序进行身份验证。
• 使用 Duo 进行身份验证。

As an administrator, you can use an authentication policy to control which MFA methods can be used as a second factor of authentication. For example, the following authentication policy allows users to use a passkey or authenticator app as their second factor of authentication, but not Duo:

CREATE AUTHENTICATION POLICY mfa_policy
  MFA_ENROLLMENT = REQUIRED
  MFA_POLICY = (ALLOWED_METHODS = ('PASSKEY', 'TOTP'));

如果用户之前配置了现已禁止的 MFA 方法，则他们下次登录时，系统会提示他们使用先前存在的方法进行身份验证，然后提示他们配置新的允许方法。

For more information about the MFA_POLICY parameter, see CREATE AUTHENTICATION POLICY.

移除用户的 MFA 方法¶

您可以移除用户先前添加的 MFA 方法，这样他们就不能再将其用作第二重身份验证因素。

1. Execute the SHOW MFA METHODS command and find the value in the name column. For example, if you are removing an MFA method for a user joe, execute the following and copy the name of the MFA method from the output:

   Copy codeExpand code block

   SHOW MFA METHODS FOR USER joe;

   Show lessSee more

   Scroll to top
   Expand code block

   +---------------+-----------------+------------------------+-------------------------------+---------------------------------+---------------------+
   |   name        |      type       |    comment             |     last_used                 |        created_on               |  additional_info    |
   +---------------+-----------------+------------------------+-------------------------------+---------------------------------+---------------------+
   | TOTP-48A7     |    TOTP         | Authenticator App 48A7 | 2025-02-26 11:14:38.000 -0800 |  2025-02-26 11:13:19.000 -0800  | null                |
   +---------------+-----------------+------------------------+-------------------------------+---------------------------------+---------------------+

   Show lessSee more

   Scroll to top

2. Execute an ALTER USER … REMOVE MFA METHOD statement to remove the MFA method:

   Copy codeExpand code block

   ALTER USER joe REMOVE MFA METHOD TOTP-48A7;

   Show lessSee more

   Scroll to top

恢复被锁定的用户

If a password user is locked out of Snowflake because they don’t have access to a second factor of authentication, an administrator can help them recover the ability to sign in by temporarily disabling MFA or by helping the user set up a new MFA method.

提示用户添加新的 MFA 方法¶

如果用户无法访问其用作第二重认证因素的 MFA 方法（例如，丢失用于存储密钥的 YubiKey），管理员可协助用户设置新的 MFA 方法，以恢复 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.

暂时禁用 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;

设置管理员紧急访问权限

Break glass refers to the ability to log in using alternative authentication methods not typically available in the account. Administrators need break glass access to Snowflake if regular authentication methods become unavailable; for example, if an organization’s identity provider has an outage.

Organizations can provide break glass access by creating a dedicated Snowflake user, and then storing the user’s password credential in a key vault. An administrator can generate one or more one-time passcodes (OTPs) that can be stored in the vault with the user’s password. To access Snowflake, an administrator can retrieve the password and OTP from the vault, and then sign in. Using OTPs creates an additional layer of protection and satisfies Snowflake multi-factor authentication requirements.

Generating one-time passcodes¶

To generate one or more OTPs for a user, run an ALTER USER … ADD MFA METHOD OTP command. The optional COUNT keyword determines how many OTPs are generated. For example, to generate 5 OTPs for the user breakglass_user, run the following command:

ALTER USER breakglass_user ADD MFA METHOD OTP COUNT = 5;

After the codes are generated, you can use them as your second factor of authentication when authenticating to Snowflake.

Invalidating one-time passcodes¶

You have the following options if you want to invalidate a one-time passcode (OTP) so it can’t be used to authenticate.

Invalidate all existing OTPs for a user

• Use the ALTER USER … ADD MFA METHOD OTP command to generate new OTPs. Previously generated OTPs are invalidated.

Invalidate a specific OTP for the current user

• Use Snowsight to invalidate an OTP by taking the following steps:
  1. In the left-hand navigation, select your name.
  2. In the user menu, select Settings.
  3. Select Authentication.
  4. In the Multi-factor authentication section, find the OTP, and then select the More icon.
  5. Select Unenroll, and then confirm that you want to delete the OTP.

Invalidate a specific OTP for a different user

• Use the ALTER USER … REMOVE MFA METHOD command to invalidate a specific OTP for a different user. If you want to invalidate an OTP for yourself, use Snowsight. For example, to invalidate the OTP_2 passcode for user joe, run the following command:
  Copy codeExpand code block

  ALTER USER joe REMOVE MFA METHOD OTP_2;

  Show lessSee more

  Scroll to top

Replicating authentication for break glass users¶

You can’t replicate OTPs from a source account to a target account when you replicate the break glass user. This is to prevent a scenario where an OTP could be used twice, once in the source account and again in the target account. You have two options to implement authentication for the break glass user in the target account:

• Sign in to the target account and generate OTPs for the user in that account.
• Replace the use of OTPs with a time-based one-time passcode (TOTP) or passkey, which can be replicated.

使用 MFA 连接到 Snowflake¶

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

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

MFA 令牌缓存有助于减少在连接和验证 Snowflake 时必须确认的提示次数，尤其是在相对较短的时间间隔内进行多次连接尝试时。

缓存的 MFA 令牌的有效期最长为四个小时。

如果满足以下任何条件，缓存的 MFA 令牌将无效：

1. The ALLOW_CLIENT_MFA_CACHING parameter is set to FALSE for the account.
2. 身份验证方法发生变化。
3. 身份验证凭证（即用户名和/或密码）更改。
4. 身份验证凭据无效。
5. 缓存的令牌已过期或加密无效。
6. 与缓存令牌相关的账户名称发生变化。

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 支持在以下驱动程序、连接器和工具中进行 MFA 令牌缓存：

• NET 驱动程序 4.3.0 版本（或更高版本）
• ODBC 驱动程序 2.23.0 版本（或更高版本）
• JDBC 驱动程序 3.12.16 版本（或更高版本）
• Python Connector for Snowflake 2.3.7 版本（或更高版本）。
• Snowflake CLI version 3.0 (or later)

Snowflake 建议在启用 MFA 令牌缓存之前咨询内部安全和合规管理人员。

要启用 MFA 令牌缓存，请完成以下步骤：

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.

   Copy codeExpand code block

   ALTER ACCOUNT SET ALLOW_CLIENT_MFA_CACHING = TRUE;

   Show lessSee more

   Scroll to top

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

3. 添加驱动程序或连接器所需的包或库：

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

     Copy codeExpand code block

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

     Show lessSee more

     Scroll to top

     You must enter the square brackets ([ and ]) as shown in the command. The square brackets specify the extra part of the package (https://www.python.org/dev/peps/pep-0508/#extras) 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:

     Copy codeExpand code block

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

     Show lessSee more

     Scroll to top

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

要禁用 MFA 令牌缓存，请取消设置 ALLOW_CLIENT_MFA_CACHING 参数：

ALTER ACCOUNT UNSET ALLOW_CLIENT_MFA_CACHING;

要查找使用 MFA 令牌缓存作为第二因素身份验证进行登录的所有用户，可以账户管理员（具有 ACCOUNTADMIN 角色的用户）身份执行以下 SQL 语句：

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

Using MFA with Snowflake CLI¶

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

要使用 Duo 生成的密码而不是推送机制，登录参数必须包含以下连接选项之一：

• Use the --mfa-passcode <string> option.
• Set passcode_in_password=true in the config.toml configuration file.

For more details, see Use multi-factor authentication (MFA).

将 MFA 与 SnowSQL 配合使用¶

MFA 可用于通过 SnowSQL 连接到 Snowflake。默认情况下，用户注册 MFA 时会使用 Duo Push 身份验证机制。

要使用 Duo 生成的密码而不是推送机制，登录参数必须包含以下连接选项之一：

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

For more details, see SnowSQL (CLI client).

将 MFA 与 JDBC 配合使用¶

MFA 可用于通过 Snowflake JDBC 驱动程序连接到 Snowflake。默认情况下，当用户注册 MFA 时将使用 Duo Push 身份验证机制；无需更改 JDBC 连接字符串。

要使用 Duo 生成的密码而不是推送机制，必须在 JDBC 连接字符串中包含以下参数之一：

passcode=<passcode_string> OR passcodeInPassword=on

其中：

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

使用 Duo 的 JDBC 连接字符串示例¶

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

Copy codeExpand code block

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

Show lessSee more

Scroll to top

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:

Copy codeExpand code block

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

Show lessSee more

Scroll to top

将 MFA 与 Node.js 配合使用¶

MFA 可用于通过 Snowflake Node.js 驱动程序连接到 Snowflake。默认情况下，用户注册 MFA 时会使用 Duo Push 身份验证机制。

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:

  Copy codeExpand code block

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

  Show lessSee more

  Scroll to top

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

  Copy codeExpand code block

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

  Show lessSee more

  Scroll to top

  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.

将 MFA 与 ODBC 配合使用¶

MFA 可用于通过 Snowflake ODBC 驱动程序连接到 Snowflake。默认情况下，当用户注册 MFA 时将使用 Duo Push 身份验证机制；无需更改 ODBC 设置。

要使用 Duo 生成的代码而不是推送机制，必须为驱动程序指定以下参数之一：

passcode=<passcode_string> OR passcodeInPassword=on

其中：

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

将 MFA 与 Python 配合使用¶

MFA 可用于通过 Snowflake Python Connector 连接到 Snowflake。默认情况下，当用户注册 MFA 时将使用 Duo Push 身份验证机制；无需更改 Python API 调用。

要使用 Duo 生成的密码而不是推送机制，必须在 connect() 方法中为驱动程序指定以下参数之一：

passcode=<passcode_string> OR passcode_in_password=True

其中：

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