Audience: Data Users
Content Summary: This page outlines how to create your SQL account, view your SQL connection information, update your password, and create SQL connections for projects.
Navigate to your Profile page.
Click on the SQL Credentials tab. Then Create Account.
Fill out the required fields following these guidelines:
Usernames must be unique and can only consist of lowercase letters, numbers, and underscores ( _ ).
Usernames cannot start with a number and can be no longer than 63 characters.
Passwords should not contain braces ( { ).
Your SQL password will never be displayed in the Immuta console, so be sure to store it in a secure location.
Click the Create button at the bottom of the center pane.
Note: Rather than requiring users to enter this user/password for authentication when accessing a data source, System Administrators may force users to use PKI or LDAP authentication.
Assuming an Immuta SQL Account has already been created, navigate to your Profile page.
Click on the SQL Credentials tab.
Click the dropdown menu button in the top right corner of the page, and then select the Copy to Clipboard button to copy the SQL connection information.
This connection can be used to connect your favorite BI tool to the Immuta database, where all the Immuta Data Sources you’re subscribed to will be available to you as tables.
Assuming an Immuta SQL Account has already been created, navigate to your Profile page.
Click on the SQL Credentials tab.
Click the dropdown menu button in the top right corner of the page, and then select the Change Password button.
Change the password and click Save.
Navigate to the Project details page.
Click SQL Connection in the right menu under Credentials.
A modal window will display with the requested connection information. Please make sure to store these credentials somewhere secure. If you misplace them, you will have to generate a new account and re-authenticate all services connected to Immuta via this account.
When done, click the Close button.
Project SQL accounts are unique to each project, and only provide access to the data sources in that project. Note that project SQL credentials cannot be retrieved from Immuta if they are lost. Credentials can only be re-generated using the instructions above. When a user generates new SQL credentials for a project, any existing SQL credentials for that project the user may have had are revoked.
Audience: System Administrators
Content Summary: By default, users authenticate with the Query Engine using credentials that they create in their Immuta profile.
It is possible to configure Immuta so that users authenticate with the Query Engine using external systems such as LDAP, Kerberos, or PKI. Any valid PostgreSQL authentication method should be possible, though not all have been tested. In order to use external authentication methods with the Query Engine, you must configure an IAM system with the supported action
linkPostgresAccount. When the IAM is configured withlinkPostgresAccount, Immuta attaches a special role to the user in the Query Engine of the format<IAM ID>_user. For example, given the following IAM configuration,Immuta creates accounts in the Query Engine for users belonging to that IAM and assign the role
myOrgLDAPIAM_userto them.This page describes authentication methods that are fully supported by Immuta.
Each Query Engine authentication method outlined below makes use of the IAM-specific role to target users for authentication. The configuration that is added to pg_hba.conf needs to come at the beginning of the file before the catch-all hostssl immuta all 0.0.0.0/0 md5 that is used to authenticate users using the built-in SQL account management.
The built-in Query Engine authentication does not require any additional configuration. Users authenticate using a username and password configured on their Immuta profile page.
See SQL Account Management for more information on how these accounts are managed.
Users can authenticate with the Query Engine using their LDAP IAM credentials, but the Query Engine must be configured using the PostgreSQL ldap authentication method.
The full documentation for this pg_hba.conf configuration is available in the PostgreSQL documentation under LDAP Authentication.
PostgreSQL has two methods of authenticating with LDAP: simple bind and search and bind.
In this method, a DN pattern is specified as a username prefix and suffix. When a user makes an authentication attempt, the prefix, username, and suffix are concatenated and used as DN along with the supplied password to bind as the user. On a successful bind the user authentication to the Query Engine succeeds.
Simple Bind Example:
In this method, PostgreSQL performs an LDAP search using the given ldapbasedn and ldapsearchattribute with the given username to find the user DN to bind with. This method can be useful when users exist in multiple OUs such that a single prefix and suffix will not satisfy all valid user DN patterns.
Search and Bind Example:
When using search and bind, a bind username and password may be required if your LDAP server does not allow anonymous search.
Users can authenticate with the Query Engine using Kerberos credentials by using the PostgreSQL gss authentication method.
The full documentation for this pg_hba.conf configuration is available in the PostgreSQL documentation under GSSAPI Authentication.
Before users can authenticate against the Query Engine using Kerberos, the PostgreSQL configuration must be updated with a keytab file. Kerberos principals must be generated for postgres/<host>@<REALM> for each Query Engine server and any replication load balancers that may be in use.
Generate a keytab for these service principals, copy it to each Query Engine host, and set the path to the keytab in postgresql.conf as krb_server_keyfile. For example,
Be sure that the keytab file is owned by the immutaqe user.
The configuration for Kerberos authentication should always have include_realm=0, and the krb_realm will need to be set. When users connect to the Query Engine they will need to present valid Kerberos credentials. If the Kerberos credentials match an Immuta user, authentication to the Query Engine succeeds.
PKI authentication makes use of certificates signed by a trusted authority to perform authentication.
The full documentation for this pg_hba.conf configuration is available in the PostgreSQL documentation under Certificate Authentication.
An example pg_hba.conf configuration is below.
By default, the cn attribute from the certificate will be compared to the database username. If the Immuta user ID is something else, such as an email address, then
Define a user mapping in pg_ident.conf:
Then, in order to use the mapping in pg_hba.conf, add map=pki-map:
Audience: Data Users
Content Summary: This page explains the Immuta Query Engine.
Once subscribed to a data source, one of the mechanisms the user has for accessing data in that source is the Immuta SQL connection. The connection is a regular PostgreSQL connection, and the data sources look like PostgreSQL tables, but these tables abstract the true underlying database technology, allowing users to visit a single place for all of their data. However, the data still resides in its original location, not within Immuta. When a user queries the Immuta database, the query is transformed to sync with the underlying data platform for any data source. When the data is returned from the original location, Immuta applies policies based on the querying user's attributes and forwards the data on to that user.
All policy types are supported by the Immuta Query Engine. See the Subscription Policies or Data Policies overview for details about policy types.
Users can add their SQL connection to their analytic tools, such as Excel, Tableau, RStudio, etc. to query protected data through the Query Engine.
Once you’ve hooked in your BI tool and have subscribed to data sources in Immuta, you will see available tables in the Immuta database — these tables are the exposed Immuta data sources. All of the Immuta data sources look and feel just like PostgreSQL tables (when they are actually a proxy for the real data source). This means you can execute cross-database technology queries since to you, they are just PostgreSQL tables.
You will only be allowed to run queries on data sources you are subscribed to and against data you have appropriate entitlements to view.
To access data sources in the context of a project, Immuta users can also obtain unique SQL credentials for each project that they are a member of.
These credentials will only provide access to the data sources in their respective projects and allow Data Governors to enforce purpose-based restrictions on project data.
See Creating Project Based SQL Connections for more information.
Audience: Users with the IMPERSONATE_USER permission and System Administrators
Content Summary: This page outlines how to use the
IMPERSONATE_USERpermission 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.
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.
A User Admin grants a user the IMPERSONATE_USER permission.
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.
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
Note: The iamid is a case-sensitive value.
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
Note: The userid is a case-sensitive value.
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 jdoe@mycompany.com.
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.
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.