Skip to content

You are viewing documentation for Immuta version 2020.2.

For the latest version, view our documentation for Immuta SaaS or the latest self-hosted version.

cancel

User Impersonation

Audience: System Administrators, Data Owner

Content Summary: Some use cases require a trusted Immuta user that has the ability to impersonate other Immuta users.

This page details how general user impersonation works in Immuta versions 2020.2.0+.

Use with Caution

Immuta user impersonation is an extremely powerful permission that can be granted to any Immuta user account, but its use should be considered carefully. Wherever possible, it is preferred to have users act as themselves to ensure governance. When impersonation is necessary, it is likely that controls and policies outside of Immuta will be necessary to ensure the credentials cannot be misused.

Query Engine User Impersonation

Users with the IMPERSONATE_USER permission within Immuta are able to impersonate other Immuta users by using their own SQL credentials to authenticate with the Immuta Query Engine, and then specify which user they would like to impersonate. The steps to do so are below.

Overview

To configure User Impersonation in Immuta

  1. Grant a selected Immuta user the IMPERSONATE_USER permission.
  2. Use that user's Immuta SQL credentials to log into the Query Engine.

  3. Issue the following SQL statements to configure your session to impersonate another Immuta user:

    SET immuta.impersonation_iamid = 'Okta';
SET immuta.impersonation_userid = 'jdoe';
-- Next line OPTIONAL. Use if you need to template shortnames to email addresses for example
SET immuta.impersonation_userid_template = '{userid}@mycompany.com';

  4. All SQL executed from there forward in this session will be executed as the user being impersonated.

Usage Details

Notes and Caveats

  • The Immuta user account with the IMPERSONATE_USER permission must have valid SQL credentials configured in order 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.

Configuration and Usage

Step 1: Grant the Immuta IMPERSONATE_USER permission to an Immuta user
  1. As a user with the USER_ADMIN permission, access the Admin page of Immuta.
  2. Either create a new user or select an existing user to have this ability.
  3. Now select + Add Permissions, and grant that user account the IMPERSONATE_USER permission.
Step 2: Login into the Query Engine

Use a tool capable of establishing a PostgreSQL-based SQL connection to connect to Immuta's Query Engine using the Immuta SQL credentials of the user with the IMPERSONATE_USER permission.

Step 3: Set the iamid of the user to be impersonated

Now tell the Immuta Query Engine the iamid that is associated with the Immuta user account you wish to impersonate.

The iamid is the name of the Identity and Access Management (IAM) provider that the Immuta user you wish to impersonate is associated with. The image below shows where the iamid can be located.

Finding IAMID

The iamid is Case-Sensitive

Please note that the iamid is a case-sensitive value.

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

SET immuta.impersonation_iamid = 'Okta';
Step 4: Set the userid of the user to be impersonated

Now tell the Immuta query engine the userid that is associated with the Immuta user account you wish to impersonate.

The userid could be an email address (and will be 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.

The userid is Case-Sensitive

In order to account for external IAM systems that require case-sensitivity Immuta treats the userid as a case-sensitive value.

For example, to specify a userid of jdoe

SET immuta.impersonation_userid = 'jdoe';
Step 5: (OPTIONAL) Apply a template to the userid

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 added a template capability such that the userid can be augmented 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 jdoe@mycompany.com.

SET immuta.impersonation_userid_template = '{userid}@mycompany.com';
Step 6: Execute SQL as the impersonated user

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