对连接进行身份验证

要向 Snowflake 进行身份验证，您可以使用以下选项之一：

Additionally, the Snowflake Node.js driver supports the ability to cache SSO and MFA tokens. For more information, see 身份验证令牌缓存.

通过 Web 浏览器使用单点登录 (SSO)

If you have configured Snowflake to use single sign-on (SSO), you can configure your client application to use browser-based SSO for authentication.

在应用程序代码中，执行以下操作：

  1. Set the authenticator option to EXTERNALBROWSER.
  2. To establish a connection, call the connect or connectAsync method.

例如：

// Use a browser to authenticate via SSO.
const connection = snowflake.createConnection({
  ...,
  authenticator: 'EXTERNALBROWSER'
});

// Establish a connection.
connection.connect((err, conn) => {
  if (err) {
    ... // Handle any errors.
  } else {
    // Execute SQL statements.
    const statement = connection.execute({...});
  }
});

For more information about using browser-based SSO for authentication, see Browser-based SSO.

通过 Okta 使用原生 SSO

If you have configured Snowflake to use single sign-on (SSO) through Okta, you can configure your client application to use native SSO authentication through Okta.

在应用程序代码中，执行以下操作：

  1. 设置以下选项：

    • Set the authenticator option to the Okta URL endpoint for your Okta account (e.g. https://<okta_account_name>.okta.com).
    • Set the username and password options to the user name and password for your Identity Provider (IdP).

  2. To establish a connection, call the connect or connectAsync method.

例如：

// Use native SSO authentication through Okta.
const connection = snowflake.createConnection({
  ...,
  username: '<user_name_for_okta>',
  password: '<password_for_okta>',
  authenticator: 'https://myaccount.okta.com'
});

// Establish a connection.
connection.connect((err, conn) => {
  if (err) {
    ... // Handle any errors.
  } else {
    // Execute SQL statements.
    const statement = connection.execute({...});
  }
});

For more information about using native SSO authentication through Okta, see Native SSO — *Okta only*.

使用密钥对身份验证和密钥对轮换

该驱动程序支持密钥对身份验证和密钥轮换。要使用密钥对身份验证和密钥轮换，请按照以下步骤操作：

  1. Configure key pair authentication, as explained in Key-pair authentication and key-pair rotation.
  2. 在应用程序代码中，执行以下操作：
    1. Set the authenticator option to SNOWFLAKE_JWT.
    2. 使用私钥通过以下方式之一进行身份验证：

      • Set the privateKey option to the private key.

      • Set the privateKeyPath option to the path to the private key file.

        If the file is encrypted, you must also set the privateKeyPass option to the passphrase to decrypt the private key.

The following example loads the private key from a file and sets the privateKey option to the private key:

import crypto from 'crypto';
import fs from 'fs';

// Read the private key file from the filesystem.
const privateKeyFile = fs.readFileSync('<path_to_private_key_file>/rsa_key.p8');

// Get the private key from the file as an object.
const privateKeyObject = crypto.createPrivateKey({
  key: privateKeyFile,
  format: 'pem',
  passphrase: 'passphrase'
});

// Extract the private key from the object as a PEM-encoded string.
const privateKey = privateKeyObject.export({
  format: 'pem',
  type: 'pkcs8'
});

// Use the private key for authentication.
const connection = snowflake.createConnection({
  ...
  authenticator: 'SNOWFLAKE_JWT',
  privateKey: privateKey
});

// Establish a connection.
connection.connect((err, conn) => {
  ... // Handle any errors.
});

// Execute SQL statements.
const statement = connection.execute({...});

The following example sets the privateKeyPath option to an encrypted private key file and sets the privateKeyPass option to the passphrase used to decrypt the private key:

// Use an encrypted private key file for authentication.
// Specify the passphrase for decrypting the key.
const connection = snowflake.createConnection({
  ...
  authenticator: 'SNOWFLAKE_JWT',
  privateKeyPath: '<path-to-privatekey>/privatekey.p8',
  privateKeyPass: '<passphrase_to_decrypt_the_private_key>'
});

// Establish a connection.
connection.connect((err, conn) => {
  ... // Handle any errors.
});

// Execute SQL statements.
const statement = connection.execute({...});

使用 OAuth

To connect using OAuth, set the authenticator option to OAUTH and the token option to the OAuth access token. For example:

// Use OAuth for authentication.
const connection = snowflake.createConnection({
  ...
  authenticator: 'OAUTH',
  token: '<your_oauth_token>'
});

// Establish a connection.
connection.connect((err, conn) => {
  ... // Handle any errors.
});

// Execute SQL statements.
const statement = connection.execute({...});

For more information, see Clients, drivers, and connectors.

使用 OAuth 2.0 授权码流程

OAuth 2.0 授权码流程是一种安全的方法，客户端应用程序可以使用该流程，在不泄露用户凭据的情况下代表用户从授权服务器获取访问令牌。

要启用 OAuth 2.0 授权码流程，请执行以下操作：

  1. Set the authenticator connection parameter to oauth_authorization_code.
  2. 设置以下 OAuth 连接参数：
    • oauthClientId: Value of client id provided by the identity provider for Snowflake integration (Snowflake security integration metadata).
    • oauthClientSecret: Value of the client secret provided by the identity provider for Snowflake integration (Snowflake security integration metadata).
    • oauthAuthorizationUrl: Identity provider endpoint supplying the authorization code to the driver. When Snowflake is used as an identity provider, this value is derived from the server or account parameters.
    • oauthTokenRequestUrl: Identity provider endpoint supplying the access tokens to the driver. When Snowflake is used as an identity provider, this value is derived from the server or account parameters.
    • oauthScope: Scope requested in the identity provider authorization request. By default, it is derived from the role. When multiple scopes are required, the value should be a space-separated list of multiple scopes.
    • oauthRedirectUri: URI to use for authorization code redirection (Snowflake security integration metadata). Default: http://127.0.0.1:{randomAvailablePort}.

使用 OAuth 2.0 客户端凭据流程

OAuth 2.0 客户端凭据流程为机器对机器 (M2M) 身份验证提供了一种安全的方式，例如连接后端服务的 Snowflake Connector for Python。与 OAuth 2.0 授权码流程不同，此方法不依赖于任何用户特定的数据。

要启用 OAuth 2.0 客户端凭据流程，请执行以下操作：

  1. Set the authenticator connection parameter to oauth_client_credentials.
  2. 设置以下 OAuth 连接参数：
    • oauthClientId: Value of client id provided by the identity provider for Snowflake integration (Snowflake security integration metadata).
    • oauthClientSecret: Value of the client secret provided by the identity provider for Snowflake integration (Snowflake security integration metadata)
    • oauthTokenRequestUrl: Identity provider endpoint supplying the access tokens to the driver.
    • oauthScope: Scope requested in the identity provider authorization request. By default, it is derived from the role. When multiple scopes are required, the value should be a space-separated list of multiple scopes.

Authenticate with workload identity federation (WIF)

Workload identity federation provides a service-to-service authentication method for Snowflake. This method enables applications, services, or containers to authenticate with Snowflake by leveraging their cloud provider’s native identity system, such as AWS IAM, Microsoft Entra ID, or Google Cloud service accounts. This approach eliminates the need for managing long-lived credentials and simplifies credential acquisition compared to other methods like External OAuth. Snowflake connectors are designed to automatically obtain short-lived credentials from the platform’s identity provider.

To enable the Workload Identity Federation authenticator, do the following:

  1. Set the authenticator connection parameter to WORKLOAD_IDENTITY.
  2. Set the workloadIdentityProvider connection parameter to AWS, AZURE, GCP, or OIDC, based on your platform.
  3. For OpenID Connect (OIDC), specify the token connection parameter.

使用 MFA 密码

Note

此功能需要 Snowflake Node.js 驱动程序版本 1.13.1 或更高版本。

您可以通过多重身份验证 (MFA) 密码连接到 Snowflake，而不必等待外部确认，例如来自 Duo 的推送通知。驱动程序提供以下方法来指定 MFA 密码：

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

    const connection = snowflake.createConnection({
  account: '<account_identifier>',
  username: '<username>',
  ...
  authenticator: 'USERNAME_PASSWORD_MFA',
  password: 'abc123987654', // passcode 987654 is part of the password
  passcodeInPassword: true // because passcodeInPassword is true
});

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

    const connection = snowflake.createConnection({
  account: '<account_identifier>',
  username: '<username>',
  ...
  authenticator: 'USERNAME_PASSWORD_MFA',
  password: 'abc123', // password and MFA passcode are input separately
  passcode: '987654'
});

    To use this approach, ensure that the passcodeInPassword option is false (the default value).

Note

If you enable the passcodeInPassword option and set the passcode option, the passcodeInPassword option takes precedence.

For more information about these options, see passcode.

身份验证令牌缓存

Snowflake Node.js 驱动程序提供了缓存 SSO 和 MFA 令牌的功能。

Important

默认情况下，令牌缓存功能处于禁用状态。在本地缓存令牌会增加安全风险。由于令牌在四小时内不会过期，因此在本地系统上访问令牌的人员可以冒充令牌所有者，直到令牌自然过期。因此，在选择缓存令牌之前，请考虑以下事项：

  • 注意并留意潜在的风险。
  • 请咨询您的内部安全和合规人员，检查您的组织的策略是否允许令牌缓存。
  • With the default settings, the file that stores the cached tokens is written in your $HOME directory, or in a path you configure. You are responsible for the security of the data in the designated directory.
  • 您有责任确保该文件具有适当的权限，只有文件所有者才能访问。

缓存 SSO (ID) 令牌

An SSO (ID) token is generated from the request when you connect to Snowflake with external browser authentication. Caching SSO (ID) tokens on the client driver’s side only works if the server allows them to be cached. Caching SSO tokens can be enabled on the server-side with executing the following SQL statement, as described in Using SSO with client applications that connect to Snowflake:

ALTER ACCOUNT SET ALLOW_ID_TOKEN = TRUE;

To use an SSO token cache in the Node.js driver, set the following options in the snowflake.createConnection() call:

  • Set authenticator to EXTERNALBROWSER. For details, see Authentication options.
  • Set clientStoreTemporaryCredential to true.
const connection = snowflake.createConnection({
  account: '<account_identifier>',
  username: '<username>',
  authenticator: 'EXTERNALBROWSER',
  clientStoreTemporaryCredential: true
});

启用后，驱动程序将使用缓存的令牌进行后续连接，直到令牌过期。如果驱动程序打开浏览器再次验证连接，则驱动程序无法在本地凭证存储中找到令牌信息，或者令牌已过期。

缓存 MFA 令牌

An MFA token is generated from the request when you connect to Snowflake with USERNAME_PASSWORD_MFA authentication. Caching MFA tokens on the client driver’s side only works if the server allows them to be cached. Caching MFA tokens can be enabled on the server-side with executing the following SQL statement, as described in Using MFA token caching to minimize the number of prompts during authentication — *optional*:

ALTER ACCOUNT SET ALLOW_CLIENT_MFA_CACHING = TRUE;

To use an MFA token cache in the Node.js driver, set the following options in the snowflake.createConnection() call:

  • Set authenticator to USERNAME_PASSWORD_MFA. For details, see Authentication options.
  • Set clientRequestMFAToken to true.
const connection = snowflake.createConnection({
  account: '<account_identifier>',
  username: '<username>',
  password: '<password>',
  authenticator: 'USERNAME_PASSWORD_MFA',
  clientRequestMFAToken: true
});

启用后，驱动程序将使用缓存的令牌进行后续连接，直到令牌过期。如果驱动程序再次联系 MFA 提供商，则驱动程序无法在本地凭证存储中找到令牌信息，或者令牌已过期。

使用默认凭据管理器

The Snowflake Node.js driver provides a credential manager and credential storage. By default, the driver stores cached tokens in your $HOME directory.

If you want to store the cached tokens in an alternate location, you can specify the desired location in the credentialCacheDir parameter of the snowflake.createConnection() function. You can specify either a relative or absolute path, as shown below:

  • 相对路径

    const connection = snowflake.createConnection({
  credentialCacheDir: '../../<folder name>'
});

  • 绝对路径

    const connection = snowflake.createConnection({
  credentialCacheDir: 'C:\\<folder name>\\<subfolder name>'
});

If you do not configure credentialCacheDir, the Snowflake Node.js driver uses ${HOME}/temporary_credential.json to store the credentials.

使用自定义凭据管理器

Snowflake node.js 驱动程序提供了一个默认的凭据管理器，它使用本地 JSON 文件以存储凭据。如果没有显式配置凭据管理器，驱动程序将使用此默认凭据管理器。

如果您不想使用默认凭据管理器，您可以创建自定义凭据管理器。自定义凭据管理器必须满足以下要求：

  • It must minimally contain read, write, and remove functions. You can include other functions as well.
  • It must be an object data type.

以下示例显示了最小自定义凭证管理器的模板。

const sampleCustomManager = {
  read: function (key) {
    // (do something with the key)
    return token;
  },
  write: function (key, token) {
    // (do something with the key and token)
  },
  remove: function (key) {
    // (do something with the key)
  }
};

After completing your custom credential manager, you can configure it for the driver in the snowflake.configure() method, as shown. This example reflects MFA tokens, though you can also create custom credential managers for SSO tokens.

import snowflake from 'snowflake-sdk';
import myCredentialManager from '<your custom credential manager module>';

snowflake.configure({
  customCredentialManager: myCredentialManager
});

const connection = snowflake.createConnection({
  account: '<account_identifier>',
  username: '<username>',
  password: '<password>',
  authenticator: 'USERNAME_PASSWORD_MFA',
  clientRequestMFAToken: true
});

Although the Snowflake Node.js driver provides a plugin-like interface to implement and use custom credential managers, Snowflake is not responsible for creating, implementing, or supporting custom credential managers for the customers.