# Register a PostgreSQL Connection

{% hint style="info" %}
**Public preview**: This integration is available to all accounts that request to enable it for their tenant. Contact your Immuta representative to enable it.
{% endhint %}

## 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
* The account credentials you provide to register the connection must have these PostgreSQL privileges:

  * Database superuser OR all of the privileges listed below.
    * `CREATEROLE`
    * `CONNECT` on the databases to be protected `WITH GRANT OPTION`
    * `USAGE` on the schemas to be protected `WITH GRANT OPTION`
    * The following privileges on tables to be protected `WITH GRANT OPTION`:
      * `SELECT`
      * `DELETE`
      * `INSERT`
      * `TRUNCATE`
      * `UPDATE`

  For descriptions and explanations of privileges Immuta needs to enforce policies and maintain state in PostgreSQL, see the [PostgreSQL integration reference guide](https://documentation.immuta.com/SaaS/configuration/integrations/reference-guides/postgresql-connection#required-postgresql-privileges).

## 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 <i class="fa-database">:database:</i> **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. **Self-Managed**
   2. **Aurora**
   3. **RDS**
   4. **Neon**
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. Avoid the use of periods (`.`) or [restricted words](#user-content-fn-1)[^1] in your connection name.
   2. **Hostname**
   3. **Port**
   4. **Database:** Enter the name of the Immuta database you created in your PostgreSQL environment. Immuta will register [all supported databases and data objects](https://documentation.immuta.com/SaaS/configuration/integrations/reference-guides/postgresql-connection#supported-object-types) through this database connection.
7. Enter privileged credentials to register the connection. Select your deployment method below for guidance.

<details>

<summary>Amazon Aurora or Amazon RDS</summary>

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 [PostgreSQL privileges outlined above](#permissions).

**AWS Assumed Role (recommended)**

Immuta will assume this IAM role from Immuta's AWS account in order to perform any operations in your AWS account.

1. Create an IAM policy with the following permissions. You will attach this to your service principal once created.

```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "rds-db:connect",
            "Resource": "arn:aws:rds-db:<REGION>:<AWS_ACCOUNT_ID>:dbuser:<RDS_DB_RESOURCE_ID>/<DB_USERNAME>"
        }
    ]
}
```

2. [Create an IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html) and select **AWS Account** as the trusted entity type. This role will be used by Immuta to set up the connection and orchestrate policies.
3. Add the IAM policy from step 1 to your service principal. These permissions will allow the service principal to register data sources and apply policies on Immuta's behalf.

   Before proceeding, contact your Immuta representative for the account and external ID to add to your trust relationship. Then, complete the steps below.
4. Add a trust policy to your service principal, replacing **\<AWS ACCOUNT ID>** and **\<EXTERNAL ID>** with the values provided by Immuta. See the [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html) for guidance.

```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "assumeRole",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<AWS ACCOUNT ID>:root"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "sts:ExternalId": "<EXTERNAL ID>"
                }
            }
        }
    ]
}
```

5. Grant your service principal the `rds_iam` role in PostgreSQL. See the [AWS documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.DBAccounts.html#UsingWithRDS.IAMDBAuth.DBAccounts.PostgreSQL) for guidance.
6. In Immuta, enter the IAM role name of your service principal in the **Username** field.
7. Enter the **Role ARN**. Immuta will assume this role when interacting with AWS.
8. Enter the **External ID** provided by Immuta.

**Username and Password**

Enter the credentials for an AWS account with the [PostgreSQL privileges outlined above](#permissions).

</details>

<details>

<summary>PostgreSQL OSS or Neon</summary>

Enter the **Username** and **Password** of a PostgreSQL account with the [PostgreSQL privileges outlined above](#permissions).

</details>

8. Click **Save connection**.

## 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](https://documentation.immuta.com/SaaS/people/users-index/how-to-guides/external-user-mapping#configure-external-user-id-mapping-on-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.

<details>

<summary>Amazon Aurora or Amazon RDS</summary>

If your PostgreSQL users are using AWS IAM roles or AWS IDC users,

1. Click **Edit** in the **AWS User** row.
2. Use the dropdown menu to select the **User Type**. User and role names are case-sensitive. See the [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html) for details.
   1. [**AWS IAM role**](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-roles): 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**](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-users)
      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.
3. Click **Save**.

See the [Mapping IAM principals in Immuta section](https://documentation.immuta.com/SaaS/configuration/integrations/reference-guides/postgresql-connection#mapping-iam-principals-in-immuta) for details about supported principals.

If your PostgreSQL users are using PostgreSQL usernames,

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.**

</details>

<details>

<summary>PostgreSQL OSS or Neon</summary>

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.**

</details>

[^1]: Your display name cannot be any of the following words: `data`, `connection`, `object`, `crawl`, `search`, `settings`, `metadata`, `permission`, `sync`, `bulk`, and `upgrade`.