Audience: Application Admins

Content Summary: This page explains what the Okta LDAP Interface is and the set up process.

Introduction

Okta LDAP Interface is a built-in Okta integration that enables you to expose your Okta directory over standard LDAP wire. The Okta LDAP Interface exposes the entire Okta directory.

1 - Enable LDAP Interface in Your Okta Account

1. Go to the Admin Console in your Okta account.

2. Select Directory, and then click Directory Integrations.

3. Select Add Directory and Add LDAP Interface. You will be presented with the details required to make a successful LDAP connection.

2 - Set Up Query Engine Authentication with the LDAP Interface

1. Configure your IAM in Immuta.

   1. Navigate to the App Settings page in Immuta.

   2. Click the Add IAM button.

   3. Complete the Display Name field and select your IAM type from the Identity Provider Type dropdown: LDAP/Active Directory, SAML, or OpenID.

      For a tutorial on setting up an Okta IAM see the App Settings page.

2. Follow these parameters to set up the Query Engine with LDAP (Search and Bind Method):

   Parameter in pg_hba.conf	Example value

3. In a Kubernetes deployment with the Immuta Helm Chart, you will need to add an entry to queryEngine.clientPgHBARules. Here’s an example of a possible pg_hba.conf entry to add to your Helm values YAML file (notice the placeholders):

queryEngine:
  clientPgHBARules:
  - hostssl immuta +<IAMID>_user 0.0.0.0/0 ldap ldapserver="<HOST>" ldapscheme=ldaps ldapbasedn="<BASE_DN>" ldapsearchattribute="uid" ldapbinddn="uid=`<OKTA_BIND_USERNAME>`,dc=`<OKTA_ORGANIZATION>`,dc=okta,dc=com" ldapbindpasswd="`<OKTA_BIND_PASSWORD>`" ldapport="636"

3 - Configure MFA in Okta

To enforce directory-wide MFA, create an authentication policy in Okta (if you do not yet have MFA policies in place).

1. Navigate to Security in the Okta Admin console.

2. Select Authentication, and then click Sign On.

   Note: If you enforce MFA on the user that’s configured as your LDAP bind user, the integration won’t work. You will therefore need to make that user exempt in your MFA policies.

Supported Features

The following Okta provisioning features are supported by Immuta:

• Import Users from Okta: Okta users who had previously been assigned to an Okta application can be imported to your Immuta instance.

• Push Users to Immuta: Okta users who are assigned to the Immuta application in Okta are automatically added as members to your Immuta instance.

• Deactivate Users in Immuta: Okta users who are unassigned from the Immuta application in Okta or are deleted or deactivated from Okta are automatically deactivated in your Immuta instance.

• Push Groups to Immuta: Groups and their members in Okta can be pushed to your Immuta instance.

• Remove Groups from Immuta: Groups in Okta are removed from your Immuta instance when they are no longer mapped to your Immuta application in Okta.

• Map User Attributes from Okta to Immuta: You can map user attributes between Okta and your Immuta instance. The mapping will remain synced by detecting profile changes in Okta.

Configuration Instructions

1 - Add SAML Application in Okta

1. Log in to your Okta instance and click Applications in the menu in the left pane.

2. Click Browse App Catalog, and then search for and select Immuta.

3. Click Add.

4. In General Settings, opt to change the Application label. Then, click Next.

5. Click View Setup Instructions and complete the tutorial to configure the IAM in Immuta. Note: You will complete all steps outlined for the Immuta App Settings page except Test User Login. You cannot test the login or save the IAM configuration in Immuta until you have added yourself as a user to the application in Okta. These steps are outlined in the next section.

6. In the Okta console under Advanced Sign-on Settings, fill in the following fields.

   • Base URL (typically your Immuta instance URL)

   • IAM ID (found on the Immuta App Settings page)

7. Click Done.

2 - Add a User to the Application

1. Click the Assignments tab.

2. Click Assign and then Assign to People.

3. Enter your name in the search field to filter results, and then click Assign.

4. Click Save and Go Back, and then click Done.

5. Return to the Immuta console and click Test User Login. Once this test passes, click Save.

3 - Configure Immuta to Use SCIM External IAM

1. Navigate to the App Settings page in Immuta, and click the Add IAM button.

2. Complete the Display Name field and select SAML as your IAM type from the Identity Provider Type dropdown.

3. Adjust Default Permissions granted to users by selecting from the list in this dropdown menu, and then complete the required fields in the Client Options section.

4. Enable SCIM support for SAML by clicking the checkbox, which will generate a SCIM API Key.

5. In the Profile Schema section, map attributes in SAML to automatically fill in a user's Immuta profile. Note: Fields that you specify in this schema will not be editable by users within Immuta.

6. Enable Sync groups from SAML to Immuta and Sync attributes from SAML to Immuta by selecting the checkboxes, and then click the Test Connection button.

7. Once the connection is successful, click the Test User Login button.

8. Before you save the configuration, store the SCIM information that displays on the Immuta App Settings page, as it will be used in subsequent steps.

4 - Update Existing Okta Application to Enable SCIM

1. In Okta, navigate to your application and click the Provisioning tab.

2. Click Configure API Integration and then select the Enable API integration checkbox.

3. Fill in the following fields:

   • Base URL (found on the Immuta App Settings page as SCIM URL)

   • API Token (found on the Immuta App Settings page as SCIM Api Key)

4. Click Test API Credentials.

5. Once that test passes, click Save.

6. You will automatically navigate to the Provisioning tab. To make sure everything syncs as expected, select To App in the Settings pane, click Edit, and enable the following fields:

   • Create Users

   • Update User Attributes

   • Deactivate Users

7. Click Save.

Known Issues and Limitations

• Using the same group to assign users to Okta (groups added to the Okta Assignments tab) and to push groups and users to Immuta (groups added to the Okta Push Groups tab) is not supported. See the Okta troubleshooting guide for details.

• The Okta directory cannot be synced with Immuta's internal IAM (BIM). You must configure an external IAM in Immuta to push users and groups from Okta to Immuta.

• You should create a new Immuta IAM and a new Okta application for Immuta to set up the provisioning. An existing setup can cause discrepancies between the Okta directory and the app, leading to syncing failures.

• When making a GET request for a user, there are extra attributes in the response.

Additional Tutorials

Immuta can integrate with Microsoft Entra ID as an IAM over SAML 2.0. This page outlines how to register Immuta as an Azure Enterprise Application with Single Sign-On over SAML 2.0.

Create an Enterprise Application

1. In the Microsoft Azure portal, browse to Enterprise Applications.

2. Click the New Application button and then select Create your own application.

3. Name the application with the name of your choice, select Integrate any other application you don't find in the gallery (Non-gallery), and click Create.

4. On the left menu, choose the Single sign-on menu item and then pick the SAML tile.

5. In the first section (Basic SAML Configuration), click the Edit icon and fill in Identifier (Entity ID) field with the full URI of your Immuta app (e.g., https://immuta.my-comany.com).

6. In the second section (User Attributes & Claims), specify the unique user identifier you want to use in Immuta. Common choices are the mail claim or the userprincipalname claim. You can also specify the user claims you want Azure to expose to Immuta. You will use the names of those claims to map them to Immuta user attributes when you create an IAM.

7. In the third section (SAML Signing Certificate), click the Download link next to Certificate (Base64) and save the file on your hard drive:

8. In the fourth section, copy the Login URL and save it for when you will create the IAM through the Immuta UI.

Now that you have an enterprise application in place, continue to create and configure an IAM in Immuta. You will need a few details from the Immuta UI to complete the configuration of the enterprise application.

Create an IAM

1. In Immuta, browse to App Settings, go to the Identity Managers section, and click Add IAM

2. Assign a name to the new IAM. Immuta will automatically derive the ID of the IAM from the name you pick.

3. Select SAML in the Identity Provider Type drop-down.

4. Start configuring the new IAM:

   • Default Permissions: The default permission that should be assigned to a Microsoft Entra ID user in Immuta.

   • Issuer: This field needs to have the same value as the Identifier (Entity ID) of the enterprise application (e.g., https://immuta.my-comany.com).

   • Entry Point: Paste the Login URL that you obtained in the previous section.

   • User ID Attribute: This field is the attribute that will contain the username of the user logging in.

   • Signing Certificate: Upload the certificate file you have previously downloaded and converted into a PEM encoded certificate.

   • Decryption Private Key: This field is the optional key for decrypting attribute assertions.

   • Enable SCIM support for SAML: Opt to enable SCIM support.

   • Profile Schema: Map user claims you have previously exposed in the application to Immuta user attributes.

   • Enable any optional settings:

     • Link SQL

     • Allow Identity Provider Initiated Single Sign On: After checking this option, set disableRequestedAuthnContext to true under Additional Config Parameters.

     • Sync groups from SAML to Immuta

     • Sync attributes from SAML to Immuta: After selecting this checkbox, map your Entra ID attributes to Immuta in the Attribute Schema section.

     • External Groups and Attributes Endpoint

   Before you can test the integration and save the new IAM, you will need to go back to the Microsoft Azure Portal and fill in the Reply URL.

5. In the Single sign-on page of your enterprise application, edit the first section with the title Basic SAML Configuration.

6. Fill in the Reply URL (Assertion Consumer Service URL) field with a value that adheres to the following format: ${IMMUTA_URL}/bim/iam/${IAM_ID}/user/authenticate/callback. For example, if the URL to your Immuta tenant is https://immuta.my-comany.com and the assigned IAM ID is MicrosoftEntraID, the value of the Reply URL field should be https://immuta.my-comany.com/bim/iam/MicrosoftEntraID/user/authenticate/callback. To save the changes, click Save. You can find the IAM ID that Immuta has assigned to the IAM in the form.

7. You should now be able to test the IAM and save it. After clicking Test Connection and letting Immuta hit the enterprise application URL, you will need to verify that the authentication flow works before you can save and create the IAM. To do so, click Test User Login and follow the instructions.

8. Save the changes in Immuta.

Microsoft Entra ID SCIM limitation

SCIM will skip updates and will not inform Immuta that an attribute should be removed from a user in the following scenarios, even if the attribute mapping has been deleted from the IAM configuration on the Immuta app settings page:

• Attribute is set to empty (removed) in Microsoft Entra ID

• Attribute is deleted in Microsoft Entra ID

In both of these scenarios, Azure doesn’t send Immuta a payload to remove the attribute, as it considers the action a redundant export. As a result, the attribute values that previously existed in Microsoft Entra ID will not get removed from the user in Immuta.

To remediate this limitation, take one of the following actions:

• Change the attribute to a non-impacting value other than empty in Microsoft Entra ID.

• Alternatively, remove the attribute mapping from the attribute schema section of the IAM configuration on the Immuta app settings page. Then, trigger an update for that user in Microsoft Entra ID by making a change to any value for that user. Microsoft Entra ID will send an update for that user to Immuta, and Immuta will remove the attribute from the user. Note that if that attribute mapping is ever re-added in Immuta on the app settings page, that attribute will be added to the user again.

See Known issues for provisioning in Microsoft Entra ID for more details about this limitation.

Audience: Application Admins

Content Summary: Immuta can consume user attributes from an external HTTP endpoint in an out-of-band fashion. This feature allows you to retrieve users' groups and authorizations from an additional resource, alongside the user attributes retrieved in the authentication flow. Such an external endpoint can be configured on any of the Identity Provider types that Immuta supports.

Implement the HTTP Service

The following section instructs how to implement the HTTP service.

Specifications

Authentication

The service can authenticate requests with both or either of the following methods:

1. Basic username and password Authorization header

2. SSL cert validation

For more information, please refer to Configuring an External User Info Endpoint.

Note: Immuta will expect non 200 error codes when the user info cannot be retrieved.

GET /user-info

The user info endpoint will be called each time Immuta needs to synchronize with a remote IAM on user groups and authorizations. Immuta will query the endpoint with the user ID specified in request's query.

Note: The endpoint's path does not necessarily have to be /user-info.

Parameters

Responses

Response Schema

Below is an example value that could be returned by the endpoint:

{
  "groups": [{
    "name":  "Accountants",
  }, {
    "name":  "Controllers",
  }],
  "authorizations": {
    "EMEA": ["Sales", "Expenses"],
    "APAC": ["Sales"]
  }
}

Configure an External User Info Endpoint

1. Click the App Settings icon in the left sidebar.

2. If you are modifying an existing IAM, click the name of the IAM. If you are creating a new IAM, click Add IAM.

3. At the very bottom of the IAM section, check the External Groups and Authorizations Endpoint checkbox.

4. In the External User Info URI field, enter the full path to your customer HTTP endpoint.

5. Optionally, check the Use Authentication checkbox and provide the username and password with which Immuta should authenticate when querying the user info endpoint. Immuta will subsequently send requests to the service with a Basic authorization header.

6. Optionally, enable SSL by checking the Enable SSL checkbox.

7. Optionally, if SSL is enabled, check the Require SSL Request Cert if your service requires SSL certificate validation. This step will require that you upload three files:

   • The SSL key file (*.pem)

   • The SSL cert file (*.pem)

   • The SSL CA file (*.pem)

There are additional configuration options available for the SAML 2.0 protocol than are referenced in this guide, which only outlines the required settings. For details about the additional options, see the .

1. Navigate to the Immuta App Settings page.

2. Scroll to the Identity Management section and click Add IAM.

3. Complete the Display Name field and select SAML from the Identity Provider Type dropdown.

4. Take note of the ID and copy the SSO Callback URL to use as the ACS URL in your identity provider.

5. Adjust Default Permissions granted to users by selecting from the list in this dropdown menu.

6. Complete the Entry Point field. This is the location of your single sign on application that will be redirected to from the Immuta login page.

7. Upload your Signing Certificate. This is your identity provider's public signing certificate.

8. In the Profile Schema section, map attributes in SAML to automatically fill in a user's Immuta profile. Note: Fields that you specify in this schema will not be editable by users within Immuta.

9. Click Test Connection and Test User Login.

10. Save your configuration.

Audience: User Admins

Content Summary: External IDs for integrations can be mapped in for Databricks, HDFS, Starburst (Trino), Snowflake, Azure Synapse Analytics, and Redshift based on attributes from an external IAM system, allowing you to link an external account to the corresponding Immuta account even when usernames do not match between Immuta and the external system.

This page illustrates the steps to map external user IDs to Immuta from Snowflake, Databricks, HDFS, Starburst (Trino), Azure Synapse Analytics, and Redshift from the App Settings page. Links to other tutorials for specific integrations are provided at the end of this tutorial.

Configure External User ID Mapping on App Settings Page

External IDs for integrations can be mapped in for Databricks, HDFS, Snowflake, and Starburst (Trino) based on attributes from an external IAM system.

1. Click the App Settings icon in the left sidebar and click Identity Management.

2. After you have clicked Add IAM, define the mapping in the Profile Schema section.

   Note: Mappings can also be disabled on the App Settings page, so it’s possible that not all of these fields will be available.

3. Click Save.

4. Test a login to ensure that the values are picked up correctly.

Manually Configure External User ID Mapping on a User's Page

For IAMs where no mapping has been defined (including Immuta's built-in IAM), the external user ID mappings can be set manually.

1. Click the People icon and select Users in the left sidebar.

2. Select a user and click the dropdown menu in the top right corner of the user's page.

3. Select Change Databricks Username, Change HDFS Principal, Change Snowflake Username, Change Trino Username, Change Azure Synapse Analytics Username, or Change Redshift Username in the dropdown (these options are only visible if the ID is not mapped to an IAM schema value).

4. Complete the Username field in the modal that appears and click Save.

All external IDs are displayed on the user profile page.

Audience: Application Administrators

Content Summary: This page details how to configure OneLogin as your identity manager in Immuta using OpenID.

Add IAM on the App Settings Page

1. Navigate to the App Settings page in the Immuta console and click the Add IAM button.

2. Complete the Display Name field and select OpenID from the Identity Provider Type dropdown.

3. Adjust Default Permissions granted to users by selecting from the list in this dropdown menu.

Add OpenID Connect in OneLogin

1. Navigate to OneLogin, click Administration, and then select Applications from the Applications menu.

2. Click Add App in the top right corner of the screen. Search for and select OpenID Connect (OIDC).

3. Complete the Display Name field and click Save.

Complete the Configuration

1. From the Identity and Access Management window in your Immuta instance, copy the SSO Callback URL to your clipboard.

2. Return to OneLogin, click the Configuration tab in the left panel, and paste the URL in the Login Url and Redirect URI's fields.

3. Click Save in the top right corner of this screen.

4. Click the SSO tab in the left panel of your OneLogin account. Copy the Client ID and the Client Secret and paste these values in the corresponding fields in your Immuta instance.

5. Then, right click the Well-known Configuration text from the SSO tab of OneLogin, and copy the link to your clipboard.

6. Return to your Immuta instance, and paste this link in the Discover URL field; pasting this link here prevents you from having to manually fill out the rest of the form.

7. Confirm email as the User ID claim, and fill out the Scopes section.

8. Return to OneLogin and scroll to the Token Endpoint section. Select POST from the Authentication Method dropdown.

9. Click Save.

10. Return to your Immuta console, opt to Enable SSL and Enable SCIM support for OpenID.

11. Opt to complete the Profile Schema section.

12. Opt to Allow Identity Provider Initiated Single Sign On, External Groups and Attributes Endpoint, and Migrate Users.

13. Click Test Connection. Once the connection is successful, click Test User Login.

14. Click Save.

Audience: Application Admins

Content Summary: This page outlines the requirements and process for adding OpenID Connect as your IAM in Immuta.

Requirements

• Administrator account in Okta.

Supported Features

Immuta's OpenID Connect integration supports the following features

• Service Provider (SP)-Initiated Authentication (SSO) Flow

• Identity Provider (IDP)-Initiated Authentication (SSO) Flow

Configuration Steps

1 - Add the Immuta Application in Okta

1. Log in to Okta as an Admin, navigate to the Applications tab, and click Add Application.

2. Search for Immuta in the search bar and click Add.

3. Choose a name for your integration and click Next. Then select the OpenID Connect button.

4. Scroll down and enter the Base URL for your Immuta instance.

5. Enter the IAM ID for your Immuta OIDC integration (if you have not created an IAM ID, you will complete that step in the next section).

6. Click Done and once the page reloads, navigate back to the Sign On tab and copy down the Client ID and Client secret.

2 - Add OpenID Connect in Immuta

1. Log in to Immuta and click the App Settings icon in the left sidebar.

2. Click the Add IAM button and enter a Display Name.

3. Select OpenID from the Identity Provider Type dropdown menu.

4. If required, navigate back to Okta and enter the IAM ID below the Base URL then complete the steps from the Okta section.

3 - Configure OpenID Connect

1. In the Identity Management section of the Immuta console, enter the Client ID and Client Secret you copied from Okta in the previous section.

2. Enter the following URL in the Discover URL field: https://<your_okta_workspace.com>/.well-known/openid-configuration.

3. Opt to add additional Scopes.

4. Opt to Enable SCIM support for OpenID by clicking the checkbox, which will generate a SCIM API Key.

5. In the Profile Schema section, map attributes in OpenID to automatically fill in a user's Immuta profile. Note: Fields that you specify in this schema will not be editable by users within Immuta.

6. Opt to Allow Identity Provider Initiated Single Sign On to use the IDP-Initiated SSO feature by selecting the checkbox.

7. Opt to Migrate Users from another IAM by selecting the checkbox.

4 - Test Connection and Save Configuration

1. Click the Test Connection button.

2. Once the connection is successful, click the Test User Login button.

3. Click Save.

Create users

1. Click the People icon.

2. Click the New User button.

3. Fill out the Full Name and Email fields in the dialog. Note: The user's email address will be used as the username and must be unique.

4. Click the Create button.

Add permission to user

1. Click the People icon and then select the user.

2. Click Add Permissions.

3. Click the Select Permission dropdown, and select the permission you want to give the user.

Disable users

1. Click the People icon.

2. Select the user you want to disable, and click the more actions menu in the user details section.

3. Select Disable.

4. Click Disable in the confirmation dialog.

Permanently delete users

Requirement: USER_ADMIN permission

Note: This action permanently deletes all data associated with this user from Immuta, including data source subscriptions, and a timestamp of this event will be captured in the audit logs. The ability to create governance reports against this user will no longer be possible. This action cannot be undone.

1. Click the People icon.

2. Select the user you want to delete, and click the more actions menu in the user details section.

3. Select Permanently Delete.

4. Click Permanently Delete User in the confirmation dialog.

5. Type Delete to confirm deleting the user permanently.

6. Click the Confirm Permanent Delete button.

Migrate users

Prerequisite: An IAM configured in Immuta

1. Click the People icon and then select the user.

2. Click the more actions menu in the user details section and select Migrate User.

3. Enter their username in the modal that appears and click Migrate User.

Remove a permission from a user

1. Click the People icon and then select the user.

2. Click the delete icon on the permission you want to remove.

Download metrics

1. Click the People icon.

2. Click the Metrics button.

3. Complete the Number of Days field in the dialog that appears, and then click Download to download the JSON file.

Show disabled accounts

Once an account has been disabled, it will not appear in the list of current Immuta users. To show the disabled accounts,

1. Click the People icon.

2. Click the more actions menu and select Include Disabled Accounts.

Create group

1. Click the People icon and select Groups.

2. Click the New Group button.

3. In the modal, enter the new group's name. You can opt to enter a description of and email address for the new group.

4. Click Save.

Add user to group

1. Click the People icon and select Groups.

2. Select the group.

3. Scroll to the members section, and click the Add Members button.

4. Begin typing in the Search by Member Name or Email text box.

5. Click on the name from the dropdown list to add this user to the group.

Add group or user attribute

1. Click the People icon and select Groups.

2. Select the group.

3. Click Add Attributes.

4. Begin typing the attribute name in the Attribute text box.

   • If the attribute already exists, select it from the dropdown list.

   • If the attribute does not exist yet, enter the full name of the attribute, and then select it from the dropdown.

5. In the Attribute Value text box, enter a value.

   • If the value already exists, select it from the dropdown list.

   • If the value does not exist, enter the full name, and then select it from the dropdown.

6. Click Close.

Remove a user from a group

1. Click the People icon and select Groups.

2. Select the group.

3. In the members section, click Remove to the right of the member you want to remove.

4. Click Delete to confirm.

Delete a group

1. Click the People icon and select Groups.

2. Select the group.

3. Click the more actions icon in the group details section, and select Delete.

4. Click Delete to confirm.

Remove a user or group's attribute

1. Click the People icon and select Users or Groups.

2. Select the user or group you would like to manage.

3. Scroll to the Attributes section, and click the delete icon on the attribute value you want to remove.

4. Click Confirm.

Native impersonation allows users to natively query data as another Immuta user.

User impersonation is supported with

• Amazon Redshift

• Azure Synapse Analytics

• Databricks Spark

• Starburst (Trino)

• Snowflake

User Impersonation with Amazon Redshift

1 - Enable User Impersonation

Select Enable Impersonation when configuring the Redshift integration on the App Settings page.

2 - Grant Users the IMPERSONATE_USER Permission

After enabling user impersonation with your Amazon Redshift integration, there are two ways to give a user permission to use the feature: in the Immuta UI or in Amazon Redshift. Use the tabs below to select one method.

3 - Impersonate a User

To impersonate another user in Redshift,

1. Run CALL immuta_procedures.impersonate_user(<Immuta username of the user to impersonate>).

2. Run queries.

4 - End User Impersonation

To end user impersonation in Redshift, run CALL immuta_procedures.impersonate_user(<NULL>).

5 - Revoke Users' IMPERSONATE_USER Permission

To revoke permission to impersonate users,

Redshift-Specific Caveats

User impersonation is specific to the script and session in which it was set. Using a new script or running a subset of script queries without setting the context will result in the queries being run as the regular user.

User Impersonation with Azure Synapse Analytics

1 - Enable User Impersonation

Select Enable Impersonation when configuring the Synapse Analytics integration on the App Settings page.

2 - Grant Users the IMPERSONATE_USER Permission

After enabling user impersonation with your Azure Synapse Analytics integration, there are two ways to give a user permission to use the feature: in the Immuta UI or in Azure Synapse Analytics. Use the tabs below to select one method.

3 - Impersonate a User

To impersonate another user in Synapse,

1. Run the following command:

   Copy

   EXEC sys.sp_set_session_context @key = N'immuta_user',
   @value = '<Synapse username linked to the Immuta user you want to impersonate>';

2. Run queries.

4 - End User Impersonation

To end user impersonation in Synapse, run EXEC sys.sp_set_session_context @key = N'NULL', @value = '<NULL>'.

5 - Revoke Users' IMPERSONATE_USER Permission

To revoke permission to impersonate users,

Synapse-Specific Caveats

• User impersonation is specific to the script and session in which it was set. Opening a new script will revert the user back to themselves.

User Impersonation with Databricks Spark

Databricks user impersonation allows a Databricks user to impersonate an Immuta user. With this feature,

• the Immuta user who is being impersonated does not have to have a Databricks account, but they must have an Immuta account.

• the Databricks user who is impersonating an Immuta user does not have to be associated with Immuta. For example, this could be a service account.

When acting under impersonation, the Databricks user loses their privileged access, so they can only access the tables the Immuta user has access to and only perform DDL commands when that user is acting under an allowed circumstance (such as workspaces, scratch paths, or non-Immuta reads/writes).

1 - Configure User Impersonation

Follow one of these methods to allow specified Databricks users to impersonate Immuta users:

• In the cluster policy JSON in the Immuta UI, add a comma-separated list of Databricks users who are allowed to impersonate Immuta users for the IMMUTA_SPARK_DATABRICKS_ALLOWED_IMPERSONATION_USERS Spark environment variable.

  Copy

  "spark_env_vars.IMMUTA_SPARK_DATABRICKS_ALLOWED_IMPERSONATION_USERS": {
    "type": "fixed",
    "value": "edixon@example.com,dakota@example.com"
  }

• In the Spark environment variables section of the Databricks UI, add IMMUTA_SPARK_DATABRICKS_ALLOWED_IMPERSONATION_USERS followed by a comma-separated list of Databricks users who are allowed to impersonate Immuta users.

  Copy

  IMMUTA_SPARK_DATABRICKS_ALLOWED_IMPERSONATION_USERS=edixon@example.com,dakota@example.com

• In the immuta_conf.xml file, add immuta.spark.databricks.allowed.impersonation.users followed by a comma-separated list of Databricks users who are allowed to impersonate Immuta users. Note: This file is no longer required or staged as a deployment artifact, but can still be used to set properties.

  Copy

  immuta.spark.databricks.allowed.impersonation.users edixon@example.com,dakota@example.com

2 - Impersonate a User

Once the cluster is configured with a list of Databricks users who are allowed to impersonate Immuta users, run the following SQL command to set the user you want to impersonate:

%sql
set immuta.impersonate.user=smwilliams@example.com

This command generates an API token for the specified user that queries Immuta for metadata pertinent to that user. When generating the token, the impersonated username is matched with the corresponding IAM user. The IAM used by default is the built-in IAM in Immuta, but can be set using the IMMUTA_USER_MAPPING_IAMID environment variable.

3 - Query Data

Run queries as the impersonated Immuta user:

%sql
set immuta.impersonate.user=smwilliams@example.com
select * from demo.hr_data limit 10;

Example Queries

Once impersonation is active, any query issued in the session will have the appropriate data and subscription policies applied for the impersonated user. Consider the example queries in the tabs below.

Audited Queries

Audited queries include an impersonationUser field, which identifies the Databricks user impersonating the Immuta user:

{
  "id": "query-a20e-493e-id-c1ada0a23a26",
  "dateTime": "1639684812845",
  "month": 1463,
  "profileId": 4,
  "userId": "smwilliams@example.com",
  "dataSourceId": 1,
  "dataSourceName": "Hr Data",
  "count": 1,
  "recordType": "spark",
  "success": true,
  "component": "dataSource",
  "accessType": "query",
  "query": "Relation[id#2644,first_name#2645,last_name#2646,email#2647,gender#2648,race#2649,ssn#2650,dept#2651,job#2652,skills#2653,salary#2654,type#2655] parquet\n",
  "extra": {
    "databricksWorkspaceID": "0",
    "maskedColumns": {},
    "metastoreTables": [
      "demo.hr_data"
    ],
    "clusterName": "your-cluster-name",
    "pathUris": [
      "dbfs:/user/hive/warehouse/demo.db/hr_data"
    ],
    "queryText": "select * from demo.hr_data limit 10;",
    "queryLanguage": "sql",
    "clusterID": "your-171358-cluster-id",
    "impersonationUser": "edixon@example.com"
  },
  "dataSourceTableName": "demo_hr_data",
  "createdAt": "2021-12-16T20:00:12.850Z",
  "updatedAt": "2021-12-16T20:00:12.850Z"
}

4 - End User Impersonation

To end user impersonation for the session, run

%sql
set immuta.impersonate.user=

Databricks-Specific Caveats

• The only way to enable this feature is through cluster configuration. The IMPERSONATE_USER permission in Immuta will not allow a user to perform native impersonation in Databricks.

User Impersonation with Starburst (Trino)

1 - Grant Users the IMPERSONATE_USER Permission

User impersonation is automatically enabled with your Starburst (Trino) integration, but the authenticated user must be given the IMPERSONATE_USER permission in Immuta or match the Starburst (Trino) immuta.user.admin regex configuration property.

To grant the user IMPERSONATE_USER permission, as an Immuta user with the permission USER_ADMIN,

1. Click the People icon and select Users in the left sidebar.

2. Select the user and click Add Permissions.

3. Click the Select Permission dropdown, and select the IMPERSONATE_USER permission.

4. Click Close.

2 - Impersonate a User

The Starburst (Trino) integration supports the native Trino impersonation approaches:

• JDBC method: In your JDBC connection driver properties, set the sessionUser property to the Immuta user you want to impersonate. See the Trino JDBC driver documentation for details.

• Trino CLI method: Set the --session-user property to specify the session user as the Immuta user you want to impersonate when invoking the Trino CLI. See the Trino release notes for details.

3 - Check User Impersonation

To view the user you are impersonating, run SHOW SESSION like 'immuta.immuta_user'.

4 - End User Impersonation

To end user impersonation, run RESET SESSION immuta.immuta_user.

5 - Revoke Users' IMPERSONATE_USER Permission

To revoke permission to impersonate users, as an Immuta user with the permission USER_ADMIN,

1. Click the People icon and select Users in the left sidebar.

2. Select the user and click the delete icon on the IMPERSONATE_USER permission.

Caveats

• The user's permissions to impersonate users are not checked until the query is run. If the user does not have the IMPERSONATE_USER permission in Immuta, they will be able to run the command to impersonate a role, but will not be able to query as that role.

User Impersonation with Snowflake

1 - Enable User Impersonation

Select Enable Impersonation when configuring the Snowflake integration on the App Settings page.

2 - Grant Users the IMPERSONATE_USER Permission

After enabling user impersonation with your Snowflake integration, there are two ways to give a user permission to use the feature: in the Immuta UI or in Snowflake. Use the tabs below to select one method.

3 - Impersonate a User

To impersonate another user in Snowflake,

1. Open a New Worksheet and set your role to the impersonation role specific to your organization.

2. Run SET immuta_user = '<<Immuta username of the user to impersonate>>'.

3. Run queries within that worksheet.

4 - Revoke Users' IMPERSONATE_USER Permission

To revoke permission to impersonate users,

Snowflake-Specific Caveats

• Native impersonation is specific to the workspace and session in which it was set. Opening a new worksheet will revert the user back to themselves.

• Snowflake auditing will show the user running the queries as the user logged in to Snowflake not as the user they are impersonating.