Skip to content

You are viewing documentation for Immuta version 2023.3.

For the latest version, view our documentation for Immuta SaaS or the latest self-hosted version.

cancel

Query Engine Authentication

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 with linkPostgresAccount, 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,

plugins:
  ldapIAM:
    id: myOrgLDAPIAM
    # ...

Immuta creates accounts in the Query Engine for users belonging to that IAM and assign the role myOrgLDAPIAM_user to them.

This page describes authentication methods that are fully supported by Immuta.

Query Engine Authentication Methods

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.

Built-in Authentication

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.

LDAP Authentication

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.

Simple 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:

hostssl immuta +myOrgLDAPIAM_user 0.0.0.0/0 ldap ldapserver=ldap.my.org ldapprefix="cn=" ldapsuffix=" ,ou=Users, dc=my, dc=org"

Search and Bind

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:

hostssl immuta +myOrgLDAPIAM_user 0.0.0.0/0 ldap ldapserver=ldap.my.org ldapbasedn="dc=my, dc=org" ldapsearchattribute="cn"

When using search and bind, a bind username and password may be required if your LDAP server does not allow anonymous search.

Kerberos Authentication

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.

Configuring the Query Engine with Kerberos

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,

krb_server_keyfile = '/var/lib/pgsql/11/data/postgres.keytab'

Be sure that the keytab file is owned by the immutaqe user.

Configuring User Authentication for Kerberos

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.

hostssl immuta +myOrgLDAPIAM_user 0.0.0.0/0 gss include_realm=0 krb_realm=<REALM>

PKI Authentication

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.

hostssl immuta +myOrgLDAPIAM_user 0.0.0.0/0 cert clientcert=1

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

  1. Define a user mapping in pg_ident.conf:

    pki-map /^(.*)@domain\.com$ \1

  2. Then, in order to use the mapping in pg_hba.conf, add map=pki-map:

    hostssl immuta +myOrgLDAPIAM_user 0.0.0.0/0 cert clientcert=1 map=pki-map