Authenticating connections¶

Use single sign-on (SSO) through a web browser¶

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

In your application code:

1. Set the authenticator option to EXTERNALBROWSER.

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

For example:

// Use a browser to authenticate via SSO.
var connection = snowflake.createConnection({
  ...,
  authenticator: "EXTERNALBROWSER"
});
// Establish a connection. Use connectAsync, rather than connect.
connection.connectAsync(
  function (err, conn)
  {
    ... // Handle any errors.
  }
).then(() =>
{
  // Execute SQL statements.
  var statement = connection.execute({...});
});

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

Use native SSO through Okta¶

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.

In your application code:

1. Set the following options:

   • 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 connectAsync method, rather than the connect method.

For example:

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

// Establish a connection.
connection.connectAsync(
  function (err, conn)
  {
    ... // Handle any errors.
  }
);

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

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

Use key-pair authentication and key-pair rotation¶

The driver supports key pair authentication and key rotation. To use key-pair authentication and key rotation, follow the steps below:

1. Configure key pair authentication, as explained in Key-pair authentication and key-pair rotation.

2. In your application code:

   1. Set the authenticator option to SNOWFLAKE_JWT.

   2. Use the private key to authenticate in one of the following ways:

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

// Read the private key file from the filesystem.
var crypto = require('crypto');
var fs = require('fs');
var 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.
var privateKey = privateKeyObject.export({
  format: 'pem',
  type: 'pkcs8'
});

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

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

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

Copy

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.
var connection = snowflake.createConnection({
  ...
  authenticator: "SNOWFLAKE_JWT",
  privateKeyPath: "<path-to-privatekey>/privatekey.p8",
  privateKeyPass: '<passphrase_to_decrypt_the_private_key>'
});

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

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

Copy

Use 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.
var connection = snowflake.createConnection({
  ...
  authenticator: "OAUTH",
  token: "<your_oauth_token>"
});

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

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

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

Use the OAuth 2.0 Authorization Code flow¶

The OAuth 2.0 Authorization Code flow is a secure method for a client application to obtain an access token from an authorization server on behalf of a user, without revealing the user’s credentials.

To enable the OAuth 2.0 Authorization Code flow:

1. Set the authenticator connection parameter to oauth_authorization_code.

2. Set the following OAuth connection parameters:

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

Use the OAuth 2.0 Client Credentials flow¶

The OAuth 2.0 Client Credentials flow provides a secure way for machine-to-machine (M2M) authentication, such as the Snowflake Connector for Python connecting to a backend service. Unlike the OAuth 2.0 Authorization Code flow, this method does not rely on any user-specific data.

To enable the OAuth 2.0 Client Credentials flow:

1. Set the authenticator connection parameter to oauth_client_credentials.

2. Set the following OAuth connection parameters:

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

Use an MFA passcode¶

You can connect to Snowflake by passing a multi-factor authentication (MFA) passcode instead of waiting for an external confirmation, such as a push notification from Duo. The driver provides the following ways to specify an MFA passcode:

• 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: process.env.SNOWFLAKE_TEST_ACCOUNT,
      username: process.env.SNOWFLAKE_TEST_USER,
      ...
      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:

  const connection = snowflake.createConnection({
      account: process.env.SNOWFLAKE_TEST_ACCOUNT,
      username: process.env.SNOWFLAKE_TEST_USER,
      ...
      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).

For more information about these options, see passcode.

Authentication token caching¶

The Snowflake Node.js driver provides the ability to cache SSO and MFA tokens.

ALTER ACCOUNT SET ALLOW_ID_TOKEN = TRUE;

const connection = snowflake.createConnection({
  account: process.env.SNOWFLAKE_TEST_ACCOUNT,
  username: process.env.SNOWFLAKE_TEST_USER,
  database: process.env.SNOWFLAKE_TEST_DATABASE,
  schema: process.env.SNOWFLAKE_TEST_SCHEMA,
  warehouse: process.env.SNOWFLAKE_TEST_WAREHOUSE,
  authenticator: 'EXTERNALBROWSER',
  clientStoreTemporaryCredential: true,
});

ALTER ACCOUNT SET ALLOW_CLIENT_MFA_CACHING = TRUE;

const connection = snowflake.createConnection({
  account: process.env.SNOWFLAKE_TEST_ACCOUNT,
  username: process.env.SNOWFLAKE_TEST_USER,
  database: process.env.SNOWFLAKE_TEST_DATABASE,
  schema: process.env.SNOWFLAKE_TEST_SCHEMA,
  warehouse: process.env.SNOWFLAKE_TEST_WAREHOUSE,
  authenticator: 'USERNAME_PASSWORD_MFA',
  clientRequestMFAToken: true,
});

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)
  }
};

const myCredentialManager = require('<your custom credential manager module>')
const snowflake = require('snowflake-sdk');

snowflake.configure({
  customCredentialManager: myCredentialManager
})

const connection = snowflake.createConnection({
  account: process.env.SNOWFLAKE_TEST_ACCOUNT,
  database: process.env.SNOWFLAKE_TEST_DATABASE,
  schema: process.env.SNOWFLAKE_TEST_SCHEMA,
  warehouse: process.env.SNOWFLAKE_TEST_WAREHOUSE,
  authenticator: 'USERNAME_PASSWORD_MFA',
  clientRequestMFAToken: true,
});