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 using Microsoft Entra ID (Azure AD, Microsoft Identity) as the identity provider and Databricks or Snowflake as the datasource.
This page covers the configuration options and examples for pass-through authentication.
Page Contents
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.
Pass-through authentication uses Microsoft’s on-behalf-of flow to implement OAuth token exchange.
Requirements
The requirements for pass-through authentication are:
- Stardog configured for OAuth authentication with Azure AD as the IdP
- Databricks or Snowflake configured for Azure AD authentication
- 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.
Configuration
Databricks
The following is a sample data source options file for a Databricks database:
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.
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.
Snowflake
These instructions assume Stardog has been configured to connect to Snowflake using Microsoft Entra ID as an OAuth provider. For details on setting up this type of Azure configurations, see here.
The following is a sample data source options file for a Snowflake database:
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. This is the scope of the Snowflake registered application that was defined under “Expose an API” in the Azure portal.
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.
Configuring OAuth
Using pass-through authentication requires configuring OAuth with client credentials for the Stardog server. See Client Credentials For Stardog Server for configuration instructions.
Granting User 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 Azure AD administrator by following the directions here.
If this consent is not granted, Azure AD 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.