Register a PostgreSQL Connection

Public preview: This feature is available to all accounts. Contact your Immuta representative for details.

Requirements

• Immuta supports the following PostgreSQL versions:

  • PostgreSQL 16

  • PostgreSQL 17

• Data consumers must access data directly through PostgreSQL. Immuta governs PostgreSQL data for consumers accessing data directly through PostgreSQL. Transactional use cases where users access data through downstream applications that are writing data from PostgreSQL are outside of the scope of Immuta’s governance.

Permissions

The user registering the connection must have the permissions below.

• APPLICATION_ADMIN Immuta permission to register the connection

• The account credentials you provide to register the connection must have these PostgreSQL privileges:

  • Ownership of the database, schemas, and tables registered in Immuta OR all of the privileges listed below.

    • CONNECT on the database to be protected

    • USAGE on the schema to be protected

    • The following privileges on tables to be protected with GRANT OPTION:

      • SELECT

      • DELETE

      • INSERT

      • TRUNCATE

      • UPDATE

      • ALTER TABLE

  • Database superuser OR CREATEROLE privilege

  For descriptions and explanations of privileges Immuta needs to enforce policies and maintain state in PostgreSQL, see the PostgreSQL connection reference guide.

Register a PostgreSQL connection

1. In your PostgreSQL environment, create an Immuta database that Immuta can use to connect to your PostgreSQL instance to register the connection and maintain state with PostgreSQL.

   Having this separate database for Immuta prevents custom ETL processes or jobs deleting the database you use to register the connection, which would break the connection.

2. In Immuta, click Data and select Connections in the navigation menu.

3. Click the + Add Connection button.

4. Select the PostgreSQL tile.

5. Select your deployment type:

   1. Neon

   2. Self Managed

6. Enter the host connection information:

   1. Display Name: This is the name of your new connection. This name will be used in the API (connectionKey), in data source names from the host, and on the connections page.

   2. Hostname

   3. Port

   4. Database: Enter the name of the Immuta database you created in your PostgreSQL environment.

7. Click Next.

8. Enter privileged credentials to register the connection. Select your deployment method below for guidance.

AWS Aurora or RDS

Select an authentication method from the dropdown menu.

• AWS Access Key and Secret Access Key: Provide the access key ID and secret access key for an AWS account with the AWS permissions listed in the set up the Immuta service principal section.

• AWS IAM Role (recommended): Immuta will assume this IAM role from Immuta's AWS account in order to perform any operations in your AWS account. Before proceeding, contact your Immuta representative for the AWS account to add to your trust policy. Then, complete the steps below.

  1. Enter the role ARN in the AWS IAM Role field. Immuta will assume this role when interacting with AWS.

  2. Set the external ID provided in a condition on the trust relationship for the cross-account IAM specified above. See the AWS documentation for guidance.

PostgreSQL OSS or Neon

Enter the Username and Password of a PostgreSQL account with the PostgreSQL privileges outlined above.

1. Click Save Connection.

2. Copy the provided script and run it in PostgreSQL as a user with the privileges listed above.

3. Click Validate Connection.

4. If the connection is successful, click Next. If there are any errors, check the connection details and credentials to ensure they are correct and try again.

5. Ensure all the details are correct in the summary and click Complete Setup.

Map users

Requirement: USER_ADMIN Immuta permission

Map AWS IAM principals or PostgreSQL usernames to each Immuta user account to ensure Immuta properly enforces policies.

The instructions below illustrate how to do this for individual users, but you can also configure user mapping in your IAM connection on the app settings page.

1. Click People and select Users in the navigation menu.

2. Click the user's name to navigate to their page and scroll to the External User Mapping section.

3. Select your deployment method below for guidance on mapping users.

AWS Aurora or RDS

1. Click Edit in the AWS User row.

1. Use the dropdown menu to select the User Type. User and role names are case-sensitive. See the AWS documentation for details.

   1. AWS IAM role: Only a single Immuta user can be mapped to an IAM role. This restriction prohibits enforcing policies on AWS users who could assume that role. Therefore, if using role principals, create a new user in Immuta that represents the role so that the role then has the permissions applied specifically to it.

      1. AWS IAM user

      2. AWS Identity Center user IDs: You must use the numeric User ID value found in AWS IAM Identity Center, not the user's email address.

      3. Unset (fallback to Immuta username): When selecting this option, the AWS username is assumed to be the same as the Immuta username.

2. Click Save.

See the Mapping IAM principals in Immuta section for details about supported principals.

PostgreSQL OSS or Neon

1. Click Edit in the PostgreSQL row.

2. Select one of the following options from the dropdown:

   1. Select PostgreSQL Username to map the PostgreSQL username to the Immuta user and enter the PostgreSQL username in the field. Username mapping is case insensitive.

   2. Select Unset (fallback to Immuta username) to use the Immuta username as the assumed PostgreSQL username. Use this option if the user's PostgreSQL username exactly matches the user's Immuta username. Username mapping is case insensitive.

   3. Select None (user does not exist in PostgreSQL) if this is an Immuta-only user. This option will improve performance for Immuta users who do not have a mapping to PostgreSQL users and will be automatically selected by Immuta if an Immuta user is not found in PostgreSQL. To ensure your PostgreSQL users have policies correctly applied, manually map their usernames using the first option above.

3. Click Save.