Pass-Through Authentication

Pass-through authentication uses the credentials of the logged-in user when creating a data source connection for the purpose of querying a virtual graph. Pass-through authentication is currently supported with Databricks or Snowflake as the data source using either Microsoft Entra ID (Azure AD, Microsoft Identity) or Okta as the identity provider, and with Amazon Aurora as the data source using any OAuth identity provider (such as Okta).

This page covers the configuration options and examples for pass-through authentication.

Page Contents

Pass-Through Authentication

Overview

The configuration of a data source requires the credentials for a Stardog system account that has access to the backing database. By default, these credentials will be used for all interactions with the database - creating virtual graphs, loading table metadata, and, in particular, submitting virtual graph queries. The virtual graph queries for all Stardog users are executed using these common, shared credentials. Access to sensitive databases (entire virtual graphs) can be secured through the use of Named Graph Security, and access to specific mapped relationships can be secured through the configuration of fine-grained security / sensitive properties.

Pass-through authentication can provide an elegant alternative to either named-graph or fine-grained security when access to an external database has already been configured to mask sensitive columns based on user roles, as it relies on that existing security. This eliminates the need to duplicate the role-based access rules in Stardog.

For Databricks and Snowflake, pass-through authentication uses OAuth 2.0 token exchange to obtain an access token for the data source from the user’s Stardog token. With Entra ID, this is implemented via Microsoft’s on-behalf-of flow. With Okta, it uses standard RFC 8693 token exchange. For Amazon Aurora, pass-through instead uses AWS STS web-identity federation together with Aurora IAM database authentication; see AWS Aurora below.

Requirements

The requirements for pass-through authentication with Databricks or Snowflake are:

Stardog configured for OAuth authentication with Microsoft Entra ID or Okta as the IdP
Databricks or Snowflake configured for authentication against the same IdP
Role-based data masking. See Databricks data masking or Snowflake column-level security

Note, while not strictly required, a data masking approach is highly recommended so that all users will see the same database schema while seeing different content based upon their authorization level. This approach ensures SQL queries will parse and execute without error.

The requirements for pass-through authentication with Amazon Aurora are:

Stardog configured for OAuth authentication with an OAuth identity provider (such as Okta) as the IdP
The AWS-side setup described in AWS Aurora IAM Pass-Through Setup: IAM database authentication enabled on the cluster, the identity provider registered in IAM, an IAM role for Stardog to assume, and a database user for each identity

Configuration

Databricks

The following is a sample data source options file for a Databricks database, using Microsoft Entra ID as the identity provider:

jdbc.url=jdbc:databricks://adb-875...15.azuredatabricks.net:443/default;UseNativeQuery=1;transportMode=http;ssl=1;httpPath=/sql/1.0/endpoints/7b80d...
jdbc.username=token
jdbc.password=dapi4b760ab0...-3
jdbc.driver=com.databricks.client.jdbc.Driver
ext.AuthMech=3

jdbc.passthrough=OAUTH
# This is Databricks' client id, plus .default scope
jdbc.passthrough.scope=2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default

passthrough.AuthMech=11
passthrough.Auth_Flow=0
passthrough.Auth_AccessToken={ACCESS_TOKEN}

Note that the top section of the properties file is unchanged, with the exception that the AuthMech query parameter was moved from the URL to an external ext. property.

The remaining built-in properties are:

`jdbc.passthrough`

Set to OAUTH to enable pass-through authentication.

`jdbc.passthrough.scope`

The scope of the OAuth resource required. Use 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default for Databricks with Entra ID. For Okta, use a scope defined on the Okta authorization server (see Databricks with Okta below).

Overriding Specific Databricks JDBC Connection Parameters

The Databricks JDBC driver requires AuthMech=11, Auth_Flow=0, and Auth_AccessToken connection parameters when connecting using OAuth. To configure these parameters, include them in the properties file with a passthrough. prefix, as indicated in the example.

The built-in ACCESS_TOKEN variable can be included in curly braces as a substitute for the Databricks access token.

Databricks with Okta

When Okta is the identity provider, the data source configuration is identical to the Entra ID example above except for jdbc.passthrough.scope, which must be set to a scope defined on the Okta authorization server (e.g., all-apis). The Databricks JDBC driver parameters (passthrough.AuthMech, passthrough.Auth_Flow, passthrough.Auth_AccessToken) are unchanged.

jdbc.url=jdbc:databricks://adb-875...15.azuredatabricks.net:443/default;UseNativeQuery=1;transportMode=http;ssl=1;httpPath=/sql/1.0/endpoints/7b80d...
jdbc.username=token
jdbc.password=dapi4b760ab0...-3
jdbc.driver=com.databricks.client.jdbc.Driver
ext.AuthMech=3

jdbc.passthrough=OAUTH
# A scope defined on the Okta authorization server
jdbc.passthrough.scope=all-apis

passthrough.AuthMech=11
passthrough.Auth_Flow=0
passthrough.Auth_AccessToken={ACCESS_TOKEN}

The Okta authorization server must have a Token Exchange policy that permits this scope, and a separate API Services application registered for Databricks. The credentials of that application (its client ID and secret, together with the Okta token endpoint URL) are configured in Stardog’s jwt.yaml on the corresponding issuer; see Okta token-exchange configuration for the YAML fields.

Snowflake

Snowflake pass-through assumes Stardog has been configured to connect to Snowflake using Microsoft Entra ID or Okta as the OAuth provider. For details on setting up an Entra ID configuration, see here; for the Okta-side configuration, see Snowflake with Okta below.

The following is a sample data source options file for a Snowflake database, using Microsoft Entra ID as the identity provider:

jdbc.url=jdbc:snowflake://ywa12345.us-east-1.snowflakecomputing.com/?db=mydb&warehouse=COMPUTE_WH
jdbc.username=service_account_username
jdbc.password=service_account_password
jdbc.driver=net.snowflake.client.jdbc.SnowflakeDriver

jdbc.passthrough=OAUTH
jdbc.passthrough.scope=api://08bcca47-abcd-48ae-b92e-24f52263d55f/session:scope:sysadmin
passthrough.authenticator=oauth
passthrough.token={ACCESS_TOKEN}

Note that the top section of the properties file is unchanged.

The remaining built-in properties are:

`jdbc.passthrough`

Set to OAUTH to enable pass-through authentication.

`jdbc.passthrough.scope`

The scope of the OAuth resource required. For Entra ID, this is the scope of the Snowflake registered application that was defined under “Expose an API” in the Azure portal. For Okta, use a scope defined on the Okta authorization server, conventionally named session:role:<snowflake-role> (see Snowflake with Okta below).

Overriding Specific Snowflake JDBC Connection Parameters

The Snowflake JDBC driver requires authenticator=oauth and token={ACCESS_TOKEN} connection parameters when connecting using OAuth. To configure these parameters, include them in the properties file with a passthrough. prefix, as indicated in the example.

The built-in ACCESS_TOKEN variable can be included in curly braces as a substitute for the Snowflake access token.

Snowflake with Okta

When Okta is the identity provider, two adjustments to the Entra ID example above are required:

jdbc.passthrough.scope is an Okta scope that conventionally names a Snowflake role using the form session:role:<role>.
A passthrough.role property is added to activate that role on the Snowflake side at connect time.

jdbc.url=jdbc:snowflake://ywa12345.us-east-1.snowflakecomputing.com/?db=mydb&warehouse=COMPUTE_WH
jdbc.username=service_account_username
jdbc.password=service_account_password
jdbc.driver=net.snowflake.client.jdbc.SnowflakeDriver

jdbc.passthrough=OAUTH
# An Okta scope of the form session:role:<snowflake-role>
jdbc.passthrough.scope=session:role:my_snowflake_role
passthrough.authenticator=oauth
passthrough.role=my_snowflake_role
passthrough.token={ACCESS_TOKEN}

On the Snowflake side, the external OAuth security integration must be configured with external_oauth_type = okta and the Okta authorization server’s issuer URL, keys URL, and audience. On the Okta side, the authorization server must define the session:role:<role> scope and have a Token Exchange policy permitting it, plus a separate API Services application registered for Snowflake. The credentials of that application (its client ID and secret, together with the Okta token endpoint URL) are configured in Stardog’s jwt.yaml on the corresponding issuer; see Okta token-exchange configuration for the YAML fields.

AWS Aurora

Aurora pass-through differs from the Databricks and Snowflake flows above. Rather than passing the user’s OAuth token directly into the JDBC connection, Stardog uses the user’s token to perform AWS STS web-identity federation and then connects to Aurora using IAM database authentication. The complete AWS-side setup is described in AWS Aurora IAM Pass-Through Setup and must be in place before configuring the data source.

The following is a sample data source options file for an Aurora PostgreSQL database:

jdbc.url=jdbc:postgresql://mycluster.cluster-xxxxxxxx.us-east-1.rds.amazonaws.com:5432/mydb?sslmode=require
jdbc.driver=org.postgresql.Driver
jdbc.username=service_account_username
jdbc.password=service_account_password

jdbc.passthrough=OAUTH

aws.region=us-east-1
aws.role.arn=arn:aws:iam::123456789012:role/stardog-aurora-passthrough-role

aws.db.user.regex=^[a-zA-Z0-9]+
aws.db.user.lowercase=true

passthrough.user={DB_USER}
passthrough.password={ACCESS_TOKEN}

Note that the jdbc.username and jdbc.password service account credentials are used only when registering the data source (to load table metadata); per-user virtual graph queries connect through the pass-through path instead.

The remaining built-in properties are:

`jdbc.passthrough`

Set to OAUTH to enable pass-through authentication.

`aws.region`

The AWS region of the Aurora cluster and the IAM role.

`aws.role.arn`

The ARN of the IAM role Stardog assumes through AssumeRoleWithWebIdentity. This is the role created in AWS Aurora IAM Pass-Through Setup.

Deriving the database username

By default, Stardog uses the token’s sub claim verbatim as the Aurora database username. The following optional properties transform the value when sub is not directly usable as a database identifier. The derived username must match a database user provisioned during the AWS-side setup.

`aws.db.user.claim`

The JWT claim to read the database username from. The value is used verbatim. Defaults to sub.

`aws.db.user.regex`

Optional. A regular expression applied to the claim value, whose match becomes the database username. For example, ^[a-zA-Z0-9]+ extracts vega from an email-like value such as vega.test@example.com. When not set, the claim value is used as-is.

`aws.db.user.lowercase`

Optional. Set to true to convert the derived username to lowercase. Defaults to false.

If you harden the IAM role with session-tag pinning, do not use aws.db.user.regex or aws.db.user.lowercase. With pinning, the username Stardog connects with must exactly equal the dbuser session tag (which is the user’s identity from the token), so any transformation would cause a mismatch and the connection would be denied. In that case the identity-provider username, the session tag, and the Aurora database user must all be the same value.

Overriding Specific Aurora JDBC Connection Parameters

Aurora IAM authentication connects with the derived database user as the username and an IAM authentication token as the password. These connection parameters must be set in the properties file with a passthrough. prefix, using the two built-in variables (enclosed in curly braces) shown in the example:

passthrough.user={DB_USER}: DB_USER is substituted with the database username derived from the token.
passthrough.password={ACCESS_TOKEN}: ACCESS_TOKEN is substituted with the Aurora IAM authentication token Stardog generates for the connection.

Both variables are required for pass-through authentication, and the variable names must appear exactly as shown.

The IAM authentication token is short-lived, but it is only used to establish the connection. Aurora does not drop a connection when the token’s validity window elapses, so long-running operations such as virtual graph materialization are unaffected once the connection is open.

Configuring OAuth

For Databricks and Snowflake, using pass-through authentication requires configuring client credentials for the Stardog server on the issuer in jwt.yaml. The specific YAML fields differ by IdP:

With Entra ID, set clientSecret (or clientCertificatePath / clientCertificatePassword) on the issuer; see Client Credentials For Stardog Server.
With Okta, set clientId, clientSecret, and tokenEndpoint on the issuer, referring to the API Services application registered in Okta for the target data source (Databricks or Snowflake); see Okta token-exchange configuration.

This step is not required for Aurora: Stardog presents the user’s token directly to AWS STS, so no client credentials for the Stardog server are needed.

This section applies to the Databricks and Snowflake flows with Entra ID. It is not required for the Okta flows (Okta uses RFC 8693 token exchange, which does not require interactive user consent for trusted client applications) or for Aurora (which uses AWS IAM database authentication rather than OAuth consent).

Pass-through authentication is based on OAuth, which is, at its core, a standard for users to grant client applications access to resources that are secured by other applications. In a datasource (e.g.: Databricks/Snowflake) use case, the user must consent to Stardog accessing the user’s resources on the datasource. This can be configured by the Entra ID administrator by following the directions here.

If this consent is not granted, Entra ID will respond with an error message similar to:

AADSTS65001: The user or administrator has not consented to use the application with ID 5439b38f-21f3-459c-b417-c7f6ec3ef55a named Stardog. Send an interactive authorization request for this user and resource.

This permission can be granted interactively by the user by pointing their browser to:

https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/authorize?client_id=<stardog_client_id>&response_type=code&redirect_uri=<url-encoded redirect_url>&response_mode=query&state=<random_string>&scope=2ff814a6-3304-4ab8-85cb-cd0e6f879c1d%2F.default

For example,

https://login.microsoftonline.com/edd2bda3-1234-abcd-a45e-6ce1-c7b8f82/oauth2/v2.0/authorize?client_id=546fcaef-1234-dd75-abd9-b005a2ffe621&response_type=code&redirect_uri=http%3A%2F%2Flocalhost&response_mode=query&state=xyzzy&scope=2ff814a6-3304-4ab8-85cb-cd0e6f879c1d%2F.default

If all query parameters are correct, the user should be asked to choose the Microsoft account to use and then to consent to Stardog having access to Databricks. Once the consent is granted, they will be redirected to the redirect URL (if configured in Azure), which might not be found, which is fine. Once consent is granted, the user should be able to use pass-through authentication with the datasource.

Overview
- Requirements
Configuration
Granting User Consent

Pass-Through Authentication

Overview

Requirements

Configuration

Databricks

jdbc.passthrough

jdbc.passthrough.scope

Overriding Specific Databricks JDBC Connection Parameters

Databricks with Okta

Snowflake

jdbc.passthrough

jdbc.passthrough.scope

Overriding Specific Snowflake JDBC Connection Parameters

Snowflake with Okta

AWS Aurora

jdbc.passthrough

aws.region

aws.role.arn

Deriving the database username

aws.db.user.claim

aws.db.user.regex

aws.db.user.lowercase

Overriding Specific Aurora JDBC Connection Parameters

Configuring OAuth

Granting User Consent

`jdbc.passthrough`

`jdbc.passthrough.scope`

`jdbc.passthrough`

`jdbc.passthrough.scope`

`jdbc.passthrough`

`aws.region`

`aws.role.arn`

`aws.db.user.claim`

`aws.db.user.regex`

`aws.db.user.lowercase`