Skip to content

Managing Personas and Permissions

Audience: Data Governors and System Administrators

Content Summary: This document outlines step-by-step instructions for creating users, adding permissions to a user, removing users' permissions , and configuring user impersonation in Immuta. For more information on user permissions, see the Personas and Permissions Overview.

Use Case

Compliance Requirement: Users can only interact with Dev data.

For this requirement, the User Admin should assign the GOVERNANCE permission to users on the Compliance team. This permission will allow them to create and assign tags that identify Dev, Test, and Prod data and write Global Policies that restrict data access to Dev for users.

Best Practice: Use External and Internal IAM

Use an external IAM for authentication and Immuta's internal IAM to manage attributes.

1 - Create Users

  1. Click the Admin icon in the left sidebar, and select the Users tab.
  2. Click the Add User button in the top right of the page.

    Add 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 User Dialog

2 - Add Permission to User

  1. Click the Admin icon in the left sidebar, and select Team Lead 1 from the Users tab.

  2. Scroll to the Permissions section on the user details page, and click Add Permissions.

    Add Permission Link

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

    Select Permission

  4. Click Close.

Results

Now all Compliance team members have been added to Immuta, and they have the GOVERNANCE permission added in addition to the default permissions to create a project and create a data source in a project.

Results

Additional Tutorials

Disable Users

  1. Click the Admin icon in the left sidebar, and then select the Users tab.

  2. Select the user you would like to disable, and click the dropdown menu button in the upper right of the user details page.

  3. Select Disable.

    Delete User

  4. Click Disable in the confirmation dialog.

Manage User Impersonation in Immuta

Use Cases

  • The Project Path: In this case, 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: This feature 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.

Create an Impersonation User

Creation of an impersonation user can be done by connecting to the immuta database of the Query Engine as a superuser and running a simple script.

  1. Create a file named create-impersonation-user.sql with the contents below. This script will prompt you for a username and password and then create the user and give it the ability to impersonate Immuta users.

    \prompt 'Impersonation username: ' username
    
    CREATE USER :username;
    \password :username
    
    ALTER ROLE :username SET search_path=immuta,public;
    GRANT bodata_impersonate_user TO :username;
    
  2. Steps for connecting to the immuta database of the Query Engine depend on the type of Immuta installation you are working with. Choose the tab below corresponding to your Immuta deployment to get connected and run the create-impersonation-user.sql script.

    namespace="immuta"
    podname=$(kubectl -n "${namespace}" get pod \
      -l app=immuta,component=postgres,immuta-database-role=immuta,immuta-ha-postgres-role=master \
      -o jsonpath='{.items[0].metadata.name}'
    )
    kubectl -n "${namespace}" cp create-impersonation-user.sql ${podname}:/tmp/ \
    -c query-engine -- psql -d immuta
    kubectl -n "${namespace}" exec -ti ${podname} -c query-engine -- \
    psql -d immuta -f /tmp/create-impersonation-user.sql
    
    container=$(docker-compose ps -q db)
    docker cp create-impersonation-user.sql ${container}:/tmp/
    docker-compose exec db psql -d immuta -f /tmp/create-impersonation-user.sql
    
    # This assumes you are logged in as root. Adjust accordingly if you have other
    # privilege escalation mechanisims in place.
    
    cp create-impersonation-user.sql /var/lib/pgsql/
    su - postgres
    psql -d immuta -f create-impersonation-user.sql
    

The impersonation user does not have access to data without a user's Immuta token; however, it should be stored securely as any other password.

Impersonate Users

The basic flow when impersonating users includes these steps:

  1. Impersonation user connects to the Immuta Query Engine.
  2. User authenticates with application managing impersonation user. (See Handling User Authentication for details.)
  3. In a SQL connection, the impersonation user begins a transaction and sets a session variable, immuta.impersonation_token to the logged in user's Immuta token.
  4. User's queries are executed in the context of this transaction.
  5. Transaction ends.

Examples:

BEGIN;
set local immuta.impersonation_token = '<token>';
-- Execute query as proxied user
END;
user = ""
password = ""
hostport = ""
token = ""

conn = psycopg2.connect("postgresql://{}:{}@{}/immuta?sslmode=require".format(
                        user, password, hostport))

with conn:
    with conn.cursor() as curs:
        curs.execute("set local immuta.impersonation_token = '{}'".format(token))
        # Execute query as proxied user
        # curs.execute('.....')
        # print curs.fetchone()
User-based Impersonation (Optional)
  1. Impersonation user connects to the Immuta Query Engine.
  2. In a SQL connection, the impersonation user begins a transaction and sets 2 session variables:

  3. immuta.impersonation_userid to the immuta userId of the user to impersonate

  4. immuta.impersonation_iamid to the IAM associated with the user being impersonated

  5. User's queries are executed in the context of this transaction.

  6. Transaction ends.

Examples:

BEGIN;
SET LOCAL immuta.impersonation_userid = 'jdoe@immuta.com';
SET LOCAL immuta.impersonation_iamid = 'LDAP';
-- Execute query as proxied user
END;
user = ""
password = ""
hostport = ""
immuta_user = ""
conn = psycopg2.connect("postgresql://{}:{}@{}/immuta?sslmode=require".format(
                        user, password, hostport))
with conn:
    with conn.cursor() as curs:
        curs.execute("SET LOCAL immuta.impersonation_userid = '{}'".format(immuta_user))
        curs.execute("SET LOCAL immuta.impersonation_iamid = 'LDAP'")
        # Execute query as proxied user
        # curs.execute('.....')
        # print curs.fetchone()

Authenticate Users

It is the responsibility of the application using the impersonation user to authenticate users properly and obtain the users' Immuta API tokens.

There are two options for authenticating users:

  1. The application can use the Immuta API to authenticate users with username and password.
  2. The application can ask user for Immuta API keys and use these to authenticate users with Immuta.

In both scenarios the token will expire after 1 hour of inactivity. In this case, activity means any query using impersonation. You can check if the token has expired by calling the current user endpoint with the user's token. If this endpoint returns status code 401, then it is expired, and the user must be re-authenticated. This process differs depending on the chosen option.

Authenticate with Username and Password
  1. Users enter their Immuta username and password in the login screen in your application. The authentication endpoint on the back end can pass the username and password to the Immuta authenticate endpoint.

  2. The response from the authenticate endpoint contains a short-lived token, which is generally valid for 1 hour from the last activity in the Immuta API.

    Note: This endpoint contains a parameter, iamid, which corresponds to the IAM system the user selects when logging into Immuta. If possible, you should use a single IAM system, such as a corporate LDAP server.

  3. The token returned in the authenticate response is used to make calls on behalf of the user through the impersonation user's SQL connection.

Since the Immuta tokens expire after 1 hour of inactivity, you may want to cache them in the user's session. If the token expires, you will need to prompt the user for their username and password and authenticate them against the Immuta API.

Authenticate with Immuta API Key

In this workflow your application must have the ability to associate Immuta API keys with a user account, most likely through a page in your application.

  1. The user first needs to generate an API key in the Immuta UI on their profile page. See Generate API Keys for details.

  2. When the application needs to obtain an Immuta token, it can use the API key with the authentication endpoint. The response from the authenticate endpoint contains a short-lived token, which is generally valid for 1 hour from the last activity in the Immuta API.

  3. The token returned in the authenticate response is used to make calls on behalf of the user through the impersonation user's SQL connection.

Since the Immuta tokens expire after 1 hour of inactivity, you may want to cache them in the user's session. If the token expires, you can authenticate on behalf of the user with their API key.

Use User Impersonation for Query Engine

  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.

Configuration and Usage

  1. Grant a selected Immuta user the IMPERSONATE_USER permission.
  2. Use a tool capable of establishing a PostgreSQL-based SQL (see Analytic Tools for specifics on which tool to use) connection to connect to Immuta's Query Engine using the Immuta SQL credentials of the user with the IMPERSONATE_USER permission.
  3. Enter into the Immuta Query Engine 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. The image below shows where the iamid can be located.

    Finding IAMID

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

    SET immuta.impersonation_iamid = 'Okta';
    

    Note: The iamid is a case-sensitive value.

  4. Enter into the Immuta Query Engine 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 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';
    
  6. 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.

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.

Migrate Users from Another IAM

  1. Click the Admin icon in the left sidebar, and select the user from the Users tab.
  2. Click the dropdown menu to the right of their name and select Migrate User.

Migrate User 2

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

Remove Permission from User

  1. Click the Admin icon in the left sidebar, and select the user from the Users tab.

  2. Scroll to the Permissions section, and click the delete icon on the permission you want to remove.

    Remove Permission

What's Next

Now that you've managed the user's permissions, continue to the next page or to this tutorial: Manage Attributes and Groups.