Skip to content

Connecting to Snowflake

Prerequisites

  • PuppyGraph version 1.0 or higher.
  • The Snowflake instance is accessible over the network from the PuppyGraph instance.

Overview

PuppyGraph supports connecting to Snowflake in three ways:

  • Connecting with key-pair authentication
  • Connecting with OAuth 2.0 client credentials
  • Connecting with a JDBC connection string

Snowflake query impersonation can be enabled on top of these connection methods when PuppyGraph is configured with SSO. With query impersonation, PuppyGraph still connects to Snowflake through one service account, but before sending SQL queries to Snowflake, it calls a configured proxy-user stored procedure. That procedure receives the current SSO user value and sets the Snowflake user context used by your access-control logic.

Connecting with key-pair authentication

See Querying Snowflake Data as a Graph for a complete demo. The demo includes setting up the connection to a Snowflake database with key-pair authentication.

Connecting with OAuth 2.0 client credentials

This option is suitable if your Snowflake instance already has an OAuth 2.0 integration.

Configuration

Configuration Explanation
Snowflake Auth Type OAuth (client credentials)
Snowflake Server URL https://<account_identifier>.snowflakecomputing.com
Snowflake Database Name Name of the Snowflake database to connect to.
Snowflake Warehouse Name Name of the Snowflake warehouse to connect to.
OAuth Client ID The client ID issued by the OAuth 2.0 identity provider.
OAuth Client Secret The client secret issued by the OAuth 2.0 identity provider.
OAuth Token Request URL The token endpoint URL of the OAuth 2.0 identity provider.
OAuth Scope (optional) The OAuth 2.0 scope to request. Required only if the identity provider enforces scope.

Connecting with a JDBC connection string

If you prefer to supply the full connection string manually, choose JDBC authentication as the Auth Type and provide a JDBC URL. The example below configures OAuth 2.0 client credentials:

jdbc:snowflake://<account_identifier>.snowflakecomputing.com/?
authenticator=oauth_client_credentials
&oauthClientId=<client_id>
&oauthClientSecret=<client_secret>
&oauthTokenRequestUrl=<token_endpoint_url>
&oauthScope=<scope>
&db=<DATABASE>
&warehouse=<WAREHOUSE>
&role=<ROLE>

Username and password are not used when JDBC authentication is selected.

Query impersonation for SSO users

Use Snowflake query impersonation when the same PuppyGraph graph should return different Snowflake rows for different SSO users. The common pattern is:

  1. PuppyGraph authenticates the user through SSO.
  2. PuppyGraph reads the configured SSO user claim, such as preferred_username.
  3. Before sending SQL queries to Snowflake, PuppyGraph calls the configured proxy-user stored procedure with that user value.
  4. Snowflake evaluates the query under the user context set by that procedure and returns the corresponding result.

For a complete runnable example with Keycloak, Snowflake, and validation queries, see Setting Up Snowflake User Impersonation for SSO.

Snowflake requirements

Prepare these objects and privileges in Snowflake before enabling the catalog:

Requirement Details
Service account The Snowflake user that PuppyGraph uses to connect. It can authenticate with key-pair authentication, OAuth, or a manually supplied JDBC URL.
Proxy-user stored procedure The Snowflake stored procedure configured by queryImpersonation.proxyUserProcedure. It accepts one string parameter: the current PuppyGraph SSO user value. The procedure should set the Snowflake user context used by your access-control logic.
Procedure privilege The service account must be able to call the proxy-user stored procedure.
Table privileges The service account must be able to query the Snowflake tables referenced by the graph schema.
Warehouse privilege The service account must be able to use the configured warehouse.
Snowflake access controls Snowflake policies, secure views, or equivalent controls should use the context set by the proxy-user stored procedure.

For example, if PuppyGraph should call:

CALL "PUPPYGRAPH_SECURITY"."UTIL"."SET_PROXY_USER"(?);

then the procedure must accept the current user value as its only argument and must be executable by the service account.

PuppyGraph requirements

Enable SSO for PuppyGraph and choose the claim that should be passed to Snowflake:

SSO_ENABLED: "true"
SSO_CLAIM_AS_USER_ID: preferred_username

With this configuration, if the SSO token contains preferred_username: alice, PuppyGraph passes alice to the Snowflake procedure.

Schema configuration

Add queryImpersonation.proxyUserProcedure to the Snowflake catalog's jdbc configuration. Although the field name is proxyUserProcedure, the value is the fully qualified Snowflake proxy-user stored procedure name that PuppyGraph invokes.

Use the identifier form that matches how the Snowflake procedure was created. Snowflake resolves unquoted identifiers in uppercase, so a procedure created with regular unquoted identifiers can be configured without double quotes:

"proxyUserProcedure": "PUPPYGRAPH_SECURITY.UTIL.SET_PROXY_USER"

If a customer omits double quotes for a procedure created with regular unquoted identifiers, the configuration still works because Snowflake resolves each identifier in uppercase. Double quotes are needed only when Snowflake must receive the exact quoted identifier, for example because the procedure was created with case-sensitive, mixed-case, lowercase, or special-character identifiers. Because the schema value is a JSON string, each double quote that should be sent to Snowflake must be escaped as \". If the configured value does not match the Snowflake identifier, Snowflake cannot find the procedure.

{
  "catalog": [
    {
      "name": "snowflake_data",
      "type": "snowflake",
      "jdbc": {
        "username": "<service_account_username>",
        "jdbcUri": "jdbc:snowflake://<account_identifier>.snowflakecomputing.com/?db=<DATABASE>&warehouse=<WAREHOUSE>&private_key_file=/home/keys/snowflake_rsa_key.p8&private_key_file_pwd=<private_key_password>",
        "driverClass": "net.snowflake.client.jdbc.SnowflakeDriver",
        "enableMetaCache": "false",
        "queryImpersonation": {
          "proxyUserProcedure": "\"PUPPYGRAPH_SECURITY\".\"UTIL\".\"SET_PROXY_USER\""
        }
      }
    }
  ]
}

After the schema is uploaded, sign in through SSO before running data queries. Local PuppyGraph users do not have an SSO identity to pass to Snowflake, so queries against an impersonation-enabled Snowflake catalog are rejected.