In the PostgreSQL integration, Immuta administers PostgreSQL privileges on data registered in Immuta. Then, Immuta users who have been granted access to the tables can query them with policies enforced.
The sequence diagram below outlines the events that occur when an Immuta user who is subscribed to a data source queries it in PostgreSQL.
PostgreSQL is configured and data is registered through connections, an Immuta feature that allows administrators to register data objects in a technology through a single connection to make data registration more scalable for your organization.
Once the PostgreSQL connection is registered, you can author subscription policies in Immuta to enforce access controls.
See the for more details about registering a connection.
After tables are registered in Immuta, you can author subscription policies in Immuta to enforce access controls.
When a policy is applied to a data source, users who meet the conditions of the policy will be automatically subscribed to the data source. Then, Immuta issues a SQL statement in PostgreSQL that grants the SELECT privilege to users on those tables.
Consider the following example that illustrates how Immuta enforces a subscription policy that only allows users in the analysts group to access the yellow-table. When this policy is authored and applied to the data source, Immuta issues a SQL statement in PostgreSQL that grants the SELECT privilege on yellow-table to users (registered in Immuta) that are part of the analysts group.
In the image above, the user in the analysts group accesses yellow-table , while the user who is a part of the research group is denied access.
See the for guidance on applying a subscription policy to a data source. See the page for details about the subscription policy types supported and PostgreSQL privileges Immuta grants on tables registered as Immuta data sources.
Immuta offers several features to provide security for your users and to prove compliance and monitor for anomalies.
See the and the guides for information about transmission of policy decision data, encryption of data in transit and at rest, and encryption key management.
The PostgreSQL integration supports the following authentication methods to register a connection:
Amazon Aurora and Amazon RDS deployments
Access using AWS IAM role (recommended): Immuta will assume this IAM role from Immuta's AWS account when interacting with the AWS API to perform any operations in your AWS account. This option allows you to provide Immuta with an IAM role from your AWS account that is granted a trust relationship with Immuta's IAM role.
Access using access key and secret access key: These credentials are used temporarily by Immuta to register the connection. The access key ID and secret access key provided must be for an AWS account with the permissions listed in the .
The built-in Immuta IAM can be used as a complete solution for authentication and user entitlement. However, you can connect your existing identity management provider to Immuta to use that system for authentication and user entitlement instead.
Each of the supported identity providers includes a specific set of configuration options that enable Immuta to communicate with the IAM system and map the users, permissions, groups, and attributes into Immuta.
See the for a list of supported providers and details.
See the for details about user provisioning and mapping user accounts to Immuta.
Immuta provides governance reports so that data owners and governors can monitor users' access to data and detect anomalies in behavior.
Immuta governance reports allow users with the GOVERNANCE Immuta permission to use a natural language builder to instantly create reports that delineate user activity across Immuta. These reports can be based on various entity types, including users, groups, projects, data sources, purposes, policy types, or connection types.
See the page for a list of report types and guidance.
Neon and PostgreSQL deployments
Username and password: These credentials are used temporarily by Immuta to register the connection. The credentials provided must be for an account with the permissions listed in the Register a PostgreSQL connection guide.
Once data is registered through the PostgreSQL connection, you will access your data through your PostgreSQL client as you normally would. If you are subscribed to the data source, Immuta grants you access to the data in PostgreSQL.
When you submit a query, the PostgreSQL client submits the SQL query to the PostgreSQL server, which then processes the query and determines what data your role is allowed to see. Then, the PostgreSQL server queries the database and returns the query results to the PostgreSQL client, which then returns policy-enforced data to you.
The diagram below illustrates how Immuta, the PostgreSQL server, and PostgreSQL client interact to access data.
The PostgreSQL integration allows you to register data from PostgreSQL in Immuta and enforce subscription policies on that data. Immuta supports the following deployment methods:
Amazon Aurora with PostgreSQL
Amazon RDS with PostgreSQL
Crunchy Data
Neon
Self-managed PostgreSQL
The sequence diagram below outlines the events that occur when an Immuta user who is subscribed to a data source queries that data in PostgreSQL.
PostgreSQL is configured and data is registered through , an Immuta feature that allows you to register your data objects through a single connection to make data registration more scalable for your organization. Instead of registering schema and databases individually, you can register them all at once and allow Immuta to monitor your data platform for changes so that data sources are added and removed automatically to reflect the state of data in your data platform.
During connection registration, you provide Immuta credentials with the . When the connection is registered, Immuta ingests and stores connection metadata in the Immuta metadata database.
In the example below, the Immuta application administrator connects the database that contains marketing-data , research-data , and cs-data tables. Immuta registers these tables as data sources and stores the table metadata in the Immuta metadata database.
Immuta presents a hierarchical view of your data that reflects the hierarchy of objects in PostgreSQL after registration is complete:
Host
Database
Schema
Table
Beyond making the registration of your data more intuitive, connections provides more control. Instead of performing operations on individual schemas or tables, you can perform operations (such as object sync) at the connection level.
See the for details about connections and how to manage them. To configure your PostgreSQL integration and register data, see the .
Immuta enforces read and write subscription policies on PostgreSQL tables by issuing SQL statements in PostgreSQL that grant and revoke access to tables according to the policy.
When a user is subscribed to a table registered in Immuta,
Immuta creates a role for that user in PostgreSQL, if one doesn't already exist.
PostgreSQL stores that role in its internal system catalog.
Immuta issues grants to that user's role in PostgreSQL to enforce policy. The provides an example of this policy enforcement.
See the for details about the PostgreSQL privileges granted to users when they are subscribed to a data source protected by a subscription policy.
The privileges that the PostgreSQL integration requires align to the least privilege security principle. The table below describes each privilege required by the IMMUTA_SYSTEM_ACCOUNT user.
The following user actions spur various processes in the PostgreSQL integration so that Immuta data remains synchronous with data in PostgreSQL:
Data source created: Immuta registers data source metadata and stores that metadata in the Immuta metadata database.
Data source deleted: Immuta deletes the data source metadata from the metadata database and removes subscription policies from that table.
: When a user account is mapped to Immuta, their metadata is stored in the metadata database.
User subscribed to a data source
When applying read and write access subscription policies to data sources, the privileges granted by Immuta may vary depending on the object type. See an outline of privileges granted by Immuta on the .
Immuta will not ingest the following objects:
The default postgres database and its objects will be ignored by object sync and will not be ingested into Immuta.
The PostgreSQL integration allows users to author to enforce access controls. Data policies are unsupported.
See the for details about policy enforcement.
The PostgreSQL integration supports the following authentication methods to register a connection:
Amazon Aurora and Amazon RDS deployments
Access using AWS IAM role (recommended): Immuta will assume this IAM role from Immuta's AWS account when interacting with the AWS API to perform any operations in your AWS account. This option allows you to provide Immuta with an IAM role from your AWS account that is granted a trust relationship with Immuta's IAM role.
Access using access key and secret access key: These credentials are used temporarily by Immuta to register the connection. The access key ID and secret access key provided must be for an AWS account with the permissions listed in the .
The built-in Immuta IAM can be used as a complete solution for authentication and user entitlement. However, you can connect your existing identity management provider to Immuta to use that system for authentication and user entitlement instead. Each of the includes a set of configuration options that enable Immuta to communicate with the IAM system and map the users, permissions, groups, and attributes into Immuta.
For policies to impact the right users, the user account in Immuta must be mapped to the user account in PostgreSQL or AWS. You can ensure these accounts are mapped correctly in the following ways:
: If usernames in PostgreSQL or AWS align with usernames in the external IAM and those accounts align with an IAM attribute, you can enter that IAM attribute on the app settings page to automatically map user IDs in Immuta to PostgreSQL.
: You can manually map user IDs for individual users.
For guidance on connecting your IAM to Immuta, see the .
Access can be managed in AWS using IAM users, roles, or Identity Center (IDC). Immuta for user provisioning in the Amazon Aurora or Amazon RDS with PostgreSQL deployments.
However, if you manage access in AWS through IAM roles instead of users, user provisioning in Immuta must be done using IAM role principals. This means that if users share IAM roles, you could end up in a situation where you over-provision access to everyone in the IAM role.
See the guidelines below for the best practices to avoid this behavior if you currently use IAM roles to manage access.
Enable (recommended): IDC is the best approach for user provisioning because it treats users as users, not users as roles. Consequently, access controls are enforced for the querying user, nothing more. This approach eliminates over-provisioning and permits granular access control. Furthermore, IDC uses trusted identity propagation, meaning AWS propagates a user's identity wherever that user may operate within the AWS ecosystem. As a result, a user's identity always remains known and consistent as they navigate across AWS services, which is a key requirement for organizations to properly govern that user. Enabling IDC does not impact any existing access controls; it is additive. Immuta will manage the GRANTs for you using IDC if it is enabled and configured in Immuta. See the for instructions on mapping users from AWS IDC to user accounts in Immuta.
Create an IAM role per user: If you do not have IDC enabled, create an IAM role per user that is unique to that user and assign that IAM role to each corresponding user in Immuta. Ensure that the IAM role cannot be shared with other users. This approach can be a challenge because there is an .
Immuta supports mapping an Immuta user to AWS in one of the following ways:
: 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.
See the for instructions on mapping principals to user accounts in Immuta.
The following Immuta features are unsupported:
Data policies
Impersonation
Tag ingestion
Query audit
Automatic subscription policy applied to or updated on a data source: Immuta calculates the users and data sources affected by the policy change and grants or revokes users' privileges on the PostgreSQL table. See the Protecting data page for details about this process.
Subscription policy deleted: Immuta revokes privileges from the affected roles.
User removed from a data source: Immuta revokes privileges from the user's role.
✅
Partitioned table
❌
❌
✅
Neon and PostgreSQL deployments
Username and password: These credentials are used temporarily by Immuta to register the connection. The credentials provided must be for an account with the permissions listed in the Register a PostgreSQL connection guide.
Request on behalf of IAM roles (not recommended): Create users in Immuta that map to each of your existing IAM roles. Then, when users request access to data, they request on behalf of the IAM role user rather than themselves. This approach is not recommended because everyone in that role will gain access to data when granted access through a policy, and adding future users to that role will also grant access. Furthermore, it requires policy authors and approvers to understand what role should have access to what data.
Database superuser OR all of the privileges listed below
This privilege is required so that the setup user can create and grant permissions to the Immuta system account role.
CONNECT on the database Immuta will protect WITH GRANT OPTION
This privilege allows Immuta to connect to the PostgreSQL database that contains the tables Immuta will protect.
USAGE on the schema Immuta will protect WITH GRANT OPTION
This privilege allows the Immuta system account to access schemas that contain tables it will protect.
CREATEROLE
Because PostgreSQL privileges are granted to roles, this privilege is required so that Immuta can create PostgreSQL roles and manage role membership to enforce access controls.
The following privileges WITH GRANT OPTION on tables registered in Immuta:
SELECT
INSERT
UPDATE
TRUNCATE
DELETE
ALTER TABLE
These privileges allow Immuta to apply read and write subscription policies on tables registered in Immuta. The ALTER TABLE privilege allows Immuta to enforce row-level policies, which will be available in a subsequent release.
Table
✅
❌
✅
View
✅
❌
✅
Materialized view
✅
❌