Connecting the Agent to the Data Platform
Connect the agent you registered in Immuta to your data platform so the agent can run queries on behalf of users
In order for agents registered in Immuta to run queries or act on behalf of users, you must connect the agent to your data platform. The sections below outline dependencies, scripts, and example requests for connecting agents to Databricks and Snowflake.
Databricks
Dependencies
Ensure your Immuta customer success representative has enabled the Immuta Agentic Data Access private preview feature.
You must be using the group grants version of the Immuta Databricks integration. If you're unsure of whether or not you're using that version, contact your customer success representative.
Enable the Databricks Role-based access control (RBAC) public preview feature.
If you are planning to use the Agentic Data Access feature on a Databricks connection that already existed in Immuta prior to the feature being enabled, you must run this script using the same user account that created the Immuta Databricks connection in question. This must be done manually since the original setup script was run by you, the customer, when setting up the connection and Immuta does not have permission to create tables.
--
-- System table used for data-only impersonation for OBO (on-behalf-of) agents
--
-- Primary keys are informational, not enforceable, in Databricks.
-- Uniqueness is enforced by the application layer via MERGE on vended_group.
-- vended_group is the logical primary key: one agent maps to one impersonated user at a time.
CREATE TABLE IF NOT EXISTS `<immuta system catalog>`.`immuta_system`.`__immuta_obo_agent_impersonation` (
vended_group STRING NOT NULL PRIMARY KEY,
impersonated_user STRING NOT NULL,
created_at TIMESTAMP NOT NULL
);
-- Enable default values so the created_at column can have a default
ALTER TABLE `<immuta system catalog>`.`immuta_system`.`__immuta_obo_agent_impersonation` SET TBLPROPERTIES('delta.feature.allowColumnDefaults' = 'supported');
-- Set the default value for created_at to the current time
ALTER TABLE `<immuta system catalog>`.`immuta_system`.`__immuta_obo_agent_impersonation` ALTER COLUMN created_at SET DEFAULT CURRENT_TIMESTAMP();
--
-- Revoke direct access from account users - only the Immuta service account should
-- read and write this table
--
REVOKE SELECT,MODIFY ON TABLE `<immuta system catalog>`.`immuta_system`.`__immuta_obo_agent_impersonation` FROM `account users`;
--
-- Transfer ownership to the Immuta service account
--
ALTER TABLE `<immuta system catalog>`.`immuta_system`.`__immuta_obo_agent_impersonation` OWNER TO `<immuta system account>`;
CREATE OR REPLACE VIEW `<immuta system catalog>`.`immuta_system`.`__immuta_user` AS
SELECT p.*
FROM `<immuta system catalog>`.`immuta_system`.`__immuta_profiles` p
LEFT JOIN `<immuta system catalog>`.`immuta_system`.`__immuta_obo_agent_impersonation` obo
ON upper(obo.vended_group) = upper(current_user())
WHERE upper(p.`immuta__userid`) =
CASE
-- OBO Agent Impersonation
WHEN obo.impersonated_user IS NOT NULL THEN upper(obo.impersonated_user)
-- Default Identity
ELSE upper(current_user())
END;Creating and mapping the agent account in Databricks
It is best practice for the agent account in Databricks to be a service principal. Follow Databricks' documentation for creating service principals.
Once your service principal is created, map it to the agent in Immuta. The external username must be the service principal UUID (the application ID) and not the name. You can retrieve the service principal's UUID from Databricks.
Connecting to Databricks as the agent
You must connect to Databricks exclusively via OAuth M2M (machine-to-machine) authentication using a scoped token.
Rather than connecting as a static service account, the agent harness (not the agent itself) first calls Immuta's on-behalf-of (OBO) API to obtain an ephemeral vended group scoped to the end user's entitlements, and then exchanges the service principal credentials for a short-lived OAuth token that assumes that group's identity. This ensures every query executed against Databricks is scoped to exactly what the end user is permitted to access, with full auditability via the vended group name in query history.
See the Databricks documentation for guidance, but here is an example request:
In this example, assume_group=<nativeRoleId> is the group ID that was returned from the Immuta agentic access V1 API. This ensures the access is scoped to that group only. The response from the Immuta agentic access V1 API will include the name and the ID of the vended group. You must use the ID in the OAuth M2M authentication's assume_group.
You may require more scopes for your agent than sql, but if you only intend to have it fetch data over SQL, that is the least-privileged scope necessary.
Databricks groups are an eventually consistent system, meaning changes are not reflected immediately. Because of this, you may see a worst-case delay of up to 15 seconds waiting for the vended group because Immuta must wait for all changes generated from the request to propagate. However, most of the time, the delay is less than 3 seconds.
Ensuring the agent account can run queries
Immuta does not manage access to compute, so in order for the agent to execute queries, remembering that the agent connects as itself, you must manually assign a warehouse.
See the Databricks documentation for guidance, but here is an example statement that grants the agent USAGE on a warehouse:
Snowflake
Dependencies
Ensure your Immuta customer success representative has enabled the Immuta Agentic Data Access private preview feature.
Creating and mapping the agent account in Snowflake
It is best practice for the agent account in Snowflake to be a SERVICE_AGENT type user. See the Snowflake documentation for guidance, but here is an example statement that sets the agent as a SERVICE_AGENT type user:
Once your SERVICE_AGENT account is created, map it to the agent in Immuta.
Connecting to Snowflake as the agent
The agent connects to Snowflake using key-pair authentication (RSA private/public key pair). This is Snowflake's recommended authentication method for service accounts and automated processes, as it eliminates password rotation requirements and supports mutual authentication.
At connection time, the agent harness (not the agent itself) explicitly sets the active role to the ephemeral vended role returned by Immuta's OBO API using the role connection parameter. This ensures the session operates exclusively under the vended role's entitlements from the moment the connection is established.
See the Snowflake documentation for details.
Why not use programmatic access tokens (PAT)?
Snowflake enforces a hard limit of 15 active PATs per user; since the agent connects as itself leveraging the vended role per user, in a multi-user concurrent environment this limit is quickly exhausted, causing connection failures. Key-pair authentication with role pinning avoids this constraint entirely since no tokens are created or accumulated.
Prerequisites
The agent must have its RSA public key registered in Snowflake.
Set the RSA public key
This is required for key-pair JWT authentication. See the Snowflake documentation for guidance, but here is an example of setting the RSA public key:
To verify it was registered correctly:
Look for the RSA_PUBLIC_KEY_FP field. It should show a SHA256:... fingerprint matching your key.
Required Snowflake configuration
To ensure the agent session is restricted to the vended role and cannot access permissions granted to the service account user directly, a session policy must be applied to block secondary roles:
Without this policy, Snowflake may allow the session to activate secondary roles beyond the vended role, potentially exposing data the end user is not entitled to see.
See Snowflake documentation on session policies and secondary roles for more details.
Execute queries using key-pair auth pinned to the vended role
See the Snowflake documentation for guidance, but here is an example request where key-pair authentication is used to connect:
The role field must be set to the vended role name returned in the metadata.roleName field from the Immuta agentic access V1 API response. This ensures the query executes exclusively under the vended role's entitlements.
You must double quote the role name since the vended role is always mixed case with special characters. Because of this, "QUOTED_IDENTIFIERS_IGNORE_CASE": false is required if your Snowflake account has "QUOTED_IDENTIFIERS_IGNORE_CASE": true configured.
Note that <account-locator> is the short account locator only (e.g., cna957322), not the full regional hostname and not the organization name. For example, for cna957322.us-east-1.snowflakecomputing.com the locator is cna957322.
Ensuring the agent account can run queries
Immuta does not manage access to compute, so in order for the agent to execute queries, you must manually assign a warehouse.
See the Snowflake documentation for guidance, but here is an example statement that grants the agent USAGE on a warehouse to the agent's standing role:
<agent_role_created_by_immuta> is not the vended role. Rather, it's the role that is permanently assigned to the agent in Snowflake. The creation of this role occurs once you map the Immuta agent to the Snowflake account and it is named <immuta_integration_prefix>_AGENT_<agent_name>.
Last updated
Was this helpful?