Query Engine User Impersonation

Audience: Users with the IMPERSONATE_USER permission and System Administrators

Content Summary: This page outlines how to use the IMPERSONATE_USER permission for Immuta instances using the Query Engine.

Query Engine Must Be Enabled

If the Query Engine has been disabled by an Administrator on the App Settings page, Query Engine User Impersonation will be unavailable.

Overview

There are two general use cases for user impersonation:

• The Project Path: The user wants multiple users to use the same dashboard and needs everyone to see the same data. An Immuta project is created and equalized. Then it is exposed to a PostgreSQL connection for projects; this gives the project a single connection for all the users to impersonate. A dashboard can then be created with the project's connection. After this creation multiple users can see the same data with the correct policies enforced.

• The Impersonation Path: The IMPERSONATE_USER permission allows a user to identify themselves while watching a dashboard that is not their own. An identifier of the user requesting the data is presented with a special, sensitive access token. With this information the data on the dashboard can be personalized to the person viewing it, while still remaining a multi-user connection.

The tutorial below illustrates the Impersonation Path.

Configuration and Usage

1. A User Admin grants a user the IMPERSONATE_USER permission.

2. As a user with the IMPERSONATE_USER permission, connect your analytic tool to Immuta's Query Engine using the Immuta SQL credentials on your Profile page.

3. In your Immuta Query Engine session, enter the iamid that is associated with the Immuta user account you want to impersonate.

   The iamid is the name of the Identity and Access Management (IAM) provider that the Immuta user you want to impersonate is associated with.

   For example, if using the iamid of "Okta", the full SQL command would be

   SET immuta.impersonation_iamid = 'Okta';

   Note: The iamid is a case-sensitive value.

4. Enter the userid that is associated with the Immuta user account you want to impersonate.

   The userid could be an email address (if using Immuta's built-in identity manager - or bim), or it could be a shortened form of the username like a sAMAccountName in Active Directory.

   For example, to specify a userid of jdoe, run

   SET immuta.impersonation_userid = 'jdoe';

   Note: The userid is a case-sensitive value.

5. In certain cases, it may be necessary to convert a shortened form of the username, like a sAMAccountName, to an email address in order to match it to an Immuta account. To handle this special case, Immuta has a capability that augments the userid by a specified template.

   For example, a sAMAccountName of jdoe can be converted into an email address at mycompany.com using a string template that substitutes the value of {userid} with the userid provided. The resulting value would be [e-mail].

   SET immuta.impersonation_userid_template = '{userid} @mycompany.com';

6. Now that your Immuta Query Engine session is configured to impersonate the desired Immuta user, your queries will be executed as the impersonated user as long as your session remains active.

Caveats

• The Immuta user account with the IMPERSONATE_USER permission must have valid SQL credentials configured to conduct user impersonation via the Immuta Query Engine.

• Once impersonation is set, all subsequent SQL calls will be made as the impersonated user.

• User impersonation lasts the duration of the SQL connection. To stop impersonating a user, simply close the connection.

• It is not possible to switch impersonated users within a single SQL connection. Each connection supports at most one impersonation setting. After user impersonation has been enabled, attempts to set a different user to impersonate will fail.