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