DOCSEARCHbyAlgolia
Submit Docs

Snowflake NodeJS Driver

repository·master·Indexed 41 days ago

https://github.com/snowflakedb/snowflake-connector-nodejs

The official Node.js driver (snowflake-sdk v3.3.0) for interacting with Snowflake accounts. It enables developers to execute queries, manage data, and configure connections using various authentication methods including SNOWFLAKE, EXTERNALBROWSER, SNOWFLAKE_JWT, and OAUTH. Features include CRL validation, AWS Workload Identity authentication, and configurable client logging via sf_client_config.json.

Tokens
6.6K
Snippets
26
Records
36
Agent score
50%

What's inside Snowflake

  2. Verify the snowflake-sdk package signature

    master

    Starting from version v1.13.0, the driver package is signed to allow verification of its authenticity and integrity.

    To verify a package:

    1. Install cosign.
    2. Download the driver package file (.tgz) from npmjs.org.
    3. Download the corresponding signatures file (.sig and .pub) from the Snowflake releases page.
    4. Use cosign verify-blob to validate the package against the public key and signature.
    cosign verify-blob snowflake-sdk-1.13.0.tgz --key snowflake-connector-nodejs-v1.13.0.pub --signature resources.snowflake-sdk-1.13.0.tgz.sig

  5. Use CRLValidatorConfig checkMode options

    master

    The checkMode property determines the enforcement level of CRL validation:

    • 'DISABLED': CRL validation is turned off.
    • 'ENABLED': CRL validation is strictly enforced. If a certificate is revoked or validation fails, the connection is terminated.
    • 'ADVISORY': CRL validation is attempted. If validation fails (e.g., due to network issues or invalid signatures), a warning is logged but the connection is allowed to proceed.

  6. Locate the client configuration file

    master

    The driver searches for the sf_client_config.json file using the following priority order:

    1. Connection String: If a path is explicitly provided within the connection string.
    2. Environment Variable: The SF_CLIENT_CONFIG_FILE environment variable.
    3. Default Directories:
      • The driver's installation directory.
      • The user's home directory.

    If no configuration is found through these methods, the driver proceeds without custom client configuration.

  7. Configure Workload Identity authentication

    master

    The WORKLOAD_IDENTITY authenticator allows the driver to automatically retrieve credentials from cloud environments (AWS, Azure, or GCP).

    To use it, set authenticator: 'WORKLOAD_IDENTITY' and specify the workloadIdentityProvider:

    • AWS: Uses @aws-sdk. Supports GetCallerIdentity (default) or GetWebIdentityToken (set via workloadIdentityAwsUseOutboundToken: true).
    • AZURE: Uses @azure/identity.
    • GCP: Uses google-auth-library.
    • OIDC: Reads the JWT token from the token option.

    Advanced AWS Configuration:

    • workloadIdentityAwsUseOutboundToken: Set to true to use the recommended GetWebIdentityToken method (requires sts:GetWebIdentityToken permission).
    • workloadIdentityHost: Overrides the AWS STS host (e.g., sts.sc2s.sgov.gov).
    const workloadIdentityOptions = {
  authenticator: 'WORKLOAD_IDENTITY',
  workloadIdentityProvider: 'AWS',
  workloadIdentityAwsUseOutboundToken: true
};

  8. Configure a custom workloadIdentityHost

    master

    If you are working in an AWS environment with a non-standard partition or require a specific STS endpoint, you can provide a workloadIdentityHost.

    When a workloadIdentityHost is provided:

    1. It is parsed into an StsEndpoint.
    2. The driver uses the provided baseUrl for all STS requests.
    3. Note: When using a custom host, AWS FIPS and Dualstack endpoint preferences (AWS_USE_FIPS_ENDPOINT or AWS_USE_DUALSTACK_ENDPOINT) are ignored because the driver must use the exact endpoint you specified.

  9. Configure client logging via `sf_client_config.json`

    master

    The Snowflake NodeJS driver supports a client configuration file named sf_client_config.json to manage logging settings. This file allows you to set a global log level and a specific log path for the driver's operations.

    The configuration must follow a specific JSON structure where settings are placed under a common key.

    Supported Log Levels

    LevelValueDescription
    OffOFFDisables logging
    ErrorERRORLogs only errors
    WarnWARNLogs warnings and errors
    InfoINFOLogs informational messages
    DebugDEBUGLogs detailed debug information
    TraceTRACELogs highly detailed trace information

    Configuration File Example

    {
  "common": {
    "log_level": "DEBUG",
    "log_path": "/path/to/your/snowflake_driver.log"
  }
}

  10. Configure OAuth authentication

    master

    For OAuth flows, the driver requires specific parameters depending on the flow type.

    Common OAuth options:

    • oauthClientId: The client ID from your identity provider.
    • oauthClientSecret: The client secret from your identity provider.
    • oauthScope: Space-separated list of requested scopes.
    • oauthRedirectUri: Custom URI for redirection (used with OAUTH_AUTHORIZATION_CODE). Defaults to http://127.0.0.1:{randomAvailablePort}.
    • oauthEnableSingleUseRefreshTokens: Enables single-use refresh tokens.

    Customizing the Browser Experience: When using EXTERNALBROWSER or OAUTH_AUTHORIZATION_CODE, you can customize the landing page shown to the user after sign-in using browserResponseRenderer:

    browserResponseRenderer: ({ error }) => {
  const message = error
    ? `<h1>Login failed</h1><p>${error}</p>`
    : '<h1>All set! You can close this tab.</h1>';
  return `<html><body>${message}</body></html>`;
}

  11. Manage authentication token caching

    master

    You can enable MFA/SSO token caching to improve performance and user experience by setting clientStoreTemporaryCredential: true.

    When enabled, the driver stores tokens in a directory specified by credentialCacheDir. If credentialCacheDir is not provided, the driver searches in this order:

    1. The SF_TEMPORARY_CREDENTIAL_CACHE_DIR environment variable.
    2. Platform-specific defaults:
      • Windows: <home>/AppData/Local/Snowflake/Caches
      • Linux: $XDG_CACHE_HOME/snowflake or ~/.cache/snowflake
      • macOS: ~/Library/Caches/Snowflake