# User Impersonation

Impersonation allows users to query data as another Immuta user.

User impersonation is supported with

* [Amazon Redshift](#user-impersonation-with-amazon-redshift)
* [Azure Synapse Analytics](#user-impersonation-with-azure-synapse-analytics)
* [Databricks Spark](#user-impersonation-with-databricks-spark)
* [Starburst (Trino)](#user-impersonation-with-starburst-trino)
* [Snowflake](#user-impersonation-with-snowflake)

{% hint style="info" %}
**Impersonating users in projects**

If you are impersonating a user who is currently in a project, you will only see data sources within that project. For details about this behavior, see the description of [project contexts](https://documentation.immuta.com/2024.2/secure-your-data/projects-and-purpose-based-access-control/projects-and-purpose-controls/reference-guides/projects#project-contexts).
{% endhint %}

## User Impersonation with Amazon Redshift

### 1 - Enable User Impersonation

Select **Enable Impersonation** when configuring the Redshift integration on the [App Settings page](https://documentation.immuta.com/2024.2/data-and-integrations/redshift/how-to-guides/redshift).

### 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.**

{% tabs %}
{% tab title="Permission in Immuta" %}
As an Immuta user with the permission USER\_ADMIN,

1. Click the **People** icon in the navigation and select the **Users** tab.
2. Select the user you want to edit and select the **Settings** tab.
3. Click **Add Permissions**.
4. Click the **Select Permission** dropdown, and select the **IMPERSONATE\_USER** permission.
   {% endtab %}

{% tab title="Permission in Amazon Redshift" %}
As a Redshift superuser,

1. Navigate to your Redshift instance.
2. Run `ALTER GROUP <Impersonation Group> ADD USER <Redshift User>`.
   {% endtab %}
   {% endtabs %}

### 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,

{% tabs %}
{% tab title="Revoke Permission in Immuta" %}
As an Immuta user with the permission USER\_ADMIN,

1. Click the **People** icon in the navigation and select the **Users** tab.
2. Select the user you want to edit and select the **Settings** tab.
3. Click **Add Permissions**.
4. Click the **Select Permission** dropdown, and select the **IMPERSONATE\_USER** permission.
   {% endtab %}

{% tab title="Permission in Amazon Redshift" %}
As a Redshift superuser,

1. Navigate to your Redshift instance.
2. Run `ALTER GROUP <Impersonation Group> DROP USER <Redshift User>`.
   {% endtab %}
   {% endtabs %}

### 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](https://documentation.immuta.com/2024.2/data-and-integrations/azure-synapse-analytics/configure-azure-synapse-analytics-integration).

### 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.**

{% tabs %}
{% tab title="Permission in Immuta" %}
As an Immuta user with the permission USER\_ADMIN,

1. Click the **People** icon in the navigation and select the **Users** tab.
2. Select the user you want to edit and select the **Settings** tab.
3. Click **Add Permissions**.
4. Click the **Select Permission** dropdown, and select the **IMPERSONATE\_USER** permission.
   {% endtab %}

{% tab title="Permission in Azure Synapse Analytics" %}
As a Synapse user,

1. Navigate to your Synapse instance.
2. Run `EXEC sp_addrolemember N'<Impersonation Role>', N'<Synapse User>'`.
   {% endtab %}
   {% endtabs %}

### 3 - Impersonate a User

To impersonate another user in Synapse,

1. Run the following command:

   ```shell
   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,

{% tabs %}
{% tab title="Revoke Permission in Immuta" %}
As an Immuta user with the permission USER\_ADMIN,

1. Click the **People** icon in the navigation and select the **Users** tab.
2. Select the user you want to edit and select the **Settings** tab.
3. Click **Remove** for the **IMPERSONATE\_USER** permission.
   {% endtab %}

{% tab title="Revoke Permission in Azure Synapse Analytics" %}
As a Synapse user,

1. Navigate to your Synapse.
2. Run `EXEC sp_droprolemember N'<Impersonation Role>', N'<Synapse User>'`.
   {% endtab %}
   {% endtabs %}

### 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

{% hint style="warning" %}
**Scala Clusters**

Immuta discourages use of this feature with Scala clusters, as the proper security mechanisms were not built to account for [user isolation limitations in Scala clusters](https://documentation.immuta.com/2024.2/data-and-integrations/databricks-spark/reference-guides/configuration-settings/scala-security). Instead, this feature was developed for the BI tool use case in which service accounts connecting to the Databricks cluster need to impersonate Immuta users so that policies can be enforced.
{% endhint %}

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**](https://documentation.immuta.com/2024.2/data-and-integrations/databricks-spark/how-to-guides/configuration/simplified#2-configure-cluster-policies), 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.

  ```json
  "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.

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

{% hint style="info" %}
**Prevent Users from Changing Impersonation User in a Given Session**

If your BI tool or other service allows users to submit arbitrary SQL or issue SET commands, set `IMMUTA_SPARK_DATABRICKS_SINGLE_IMPERSONATION_USER` to `true` to prevent users from changing their impersonation user once it has been set for a given Spark session.
{% endhint %}

### 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
%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`](https://documentation.immuta.com/2024.2/data-and-integrations/databricks-spark/reference-guides/configuration-settings/configuration) environment variable.

### 3 - Query Data

Run queries as the impersonated Immuta user:

```sql
%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.

{% tabs %}
{% tab title="Without User Impersonation" %}
**Without User Impersonation**

Policies on this data source mask sensitive values unless users possess a specified attribute.

If the user querying the data possesses that attribute, they can see the unmasked values.
{% endtab %}

{% tab title="With User Impersonation" %}
**With User Impersonation**

Policies on this data source mask sensitive values unless users possess a specified attribute.

If the user queries the data source impersonating an Immuta user (`smwilliams@example.com`) who does not possess that attribute, the sensitive data is masked.
{% endtab %}
{% endtabs %}

#### Audited Queries

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

```json
{
  "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
%sql
set immuta.impersonate.user=
```

### Databricks-Specific Caveat

The only way to enable this feature is through cluster configuration. The `IMPERSONATE_USER` permission in Immuta will not allow a user to perform 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](https://documentation.immuta.com/2024.2/data-and-integrations/starburst-trino/how-to-guides/configure#2-configure-the-immuta-system-access-control-plugin-in-starburst).

To grant the user IMPERSONATE\_USER permission, as an Immuta user with the permission USER\_ADMIN,

1. Navigate to your Immuta homepage.
2. Click the **People** icon and select **Users** in the left sidebar. Then select the user.
3. Click **Add Permissions**.
4. Click the **Select Permission** dropdown, and select the **IMPERSONATE\_USER** permission.
5. Click **Close**.

### 2 - Impersonate a User

The Starburst (Trino) integration supports the native Starburst or 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 [Starburst JDBC driver documentation](https://docs.starburst.io/latest/client/jdbc.html#connection-parameters) 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](https://docs.starburst.io/data-consumer/clients/cli.html). See the [Trino release notes](https://trino.io/docs/current/release/release-352.html#cli) 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 in the navigation and select the **Users** tab.
2. Select the user you want to edit and select the **Settings** tab.
3. Click **Remove** for the **IMPERSONATE\_USER** permission.

### Caveat

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](https://documentation.immuta.com/2024.2/data-and-integrations/snowflake/how-to-guides/enterprise).

### 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.**

{% tabs %}
{% tab title="Permission in Immuta" %}
As an Immuta user with the permission USER\_ADMIN,

1. Click the **People** icon in the navigation and select the **Users** tab.
2. Select the user you want to edit and select the **Settings** tab.
3. Click **Add Permissions**.
4. Click the **Select Permission** dropdown, and select the **IMPERSONATE\_USER** permission.
   {% endtab %}

{% tab title="Permission in Snowflake" %}
As a Snowflake user with the ACCOUNTADMIN role,

1. Navigate to your Snowflake instance.
2. In a worksheet run `GRANT ROLE <<Impersonation_Role>> TO USER "<<Snowflake User>>"`.

   *In this example, the `Impersonation Role` is the name entered on the Immuta App Settings page when the feature was enabled. The default is **IMMUTA\_IMPERSONATION**, but the admin may have customized it. The `Snowflake User` is the username of the Snowflake user that will now have permission to impersonate other users.*
   {% endtab %}
   {% endtabs %}

### 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,

{% tabs %}
{% tab title="Revoke Permission in Immuta" %}
As an Immuta user with the permission USER\_ADMIN,

1. Click the **People** icon in the navigation and select the **Users** tab.
2. Select the user you want to edit and select the **Settings** tab.
3. Click **Remove** for the **IMPERSONATE\_USER** permission.
   {% endtab %}

{% tab title="Revoke Permission in Snowflake" %}
As a Snowflake user with the ACCOUNTADMIN role,

1. Navigate to your Snowflake instance.
2. In a worksheet run `REVOKE ROLE <<Impersonation Role>> FROM USER "<<Snowflake User>>"`.

   *In this example, the `Impersonation Role` is the name entered on the Immuta App Settings page when the feature was enabled. The default is **IMMUTA\_IMPERSONATION**, but the admin may have customized it. The `Snowflake User` is the username of the Snowflake user that will now have permission to impersonate other users.*
   {% endtab %}
   {% endtabs %}

### Snowflake-Specific Caveats

* 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.