Integrate Active Directory with AlloyDB Omni

Select a documentation version:

This page describes how to integrate AlloyDB Omni with your existing Active Directory implementation so that you can use your existing usernames and passwords to access your AlloyDB Omni database. Active Directory integration provides Kerberos as the default authentication mechanism to communicate with AlloyDB Omni.

Active Directory configuration in AlloyDB Omni is optional and is disabled by default. Only environments using Active Directory Server for authentication can use this configuration mechanism.

Before you begin

Before you integrate AlloyDB Omni with your Active Directory implementation, make sure that you do the following:

  • Set up and configure the Active Directory server.
  • Ensure that you have the permissions to generate and manage Kerberos key tables or keytab files in Active Directory.

Enable Active Directory authentication

To enable Active Directory authentication in AlloyDB Omni, follow these steps, which include configuring the Generic Security Service Application Program Interface (GSSAPI), which is an application programming interface that enables programs to access security services.

  1. Add the following entries to the /var/lib/postgresql/data/pg_hba.conf file, before the
    host all all all scram-sha-256 entry.

    1. Run the following Docker command to add gss inside the container:

      docker exec CONTAINER_NAME> sed -i 's;^host all all all scram-sha-256$;hostgssenc all all 0.0.0.0/0 gss map=gssmap\n&;' /var/lib/postgresql/data/pg_hba.conf

    2. Run the following Docker command to verify that the pg_hba.conf file is inside the container:

      docker exec CONTAINER_NAME cat /var/lib/postgresql/data/pg_hba.conf

    3. Verify that the following entry is in the file:

      hostgssenc all all 0.0.0.0/0 gss map=gssmap

      For more information, see The pg_hba.conf File.

  2. Copy the key tab file to the data directory inside the AlloyDB Omni image.

    docker cp PATH TO KEYTAB FILE CONTAINER_NAME:/var/lib/postgresql/data/alloydb.keytab
docker exec CONTAINER_NAME chmod 600 /var/lib/postgresql/data/alloydb.keytab
docker exec CONTAINER_NAME chown postgres:postgres /var/lib/postgresql/data/alloydb.keytab

    The keytab file is generated by Kerberos for the PostgreSQL server. To learn more about authentication, see GSSAPI Authentication.

  3. Add an entry for the keytab file to the /var/lib/postgresql/data/DATA_DIR/postgresql.conf file.

    1. Run the following Docker command to add the entry inside the container:

      docker exec CONTAINER_NAME sed -i '$akrb_server_keyfile='"'"'/var/lib/postgresql/data/alloydb.keytab'"'" /var/lib/postgresql/data/postgresql.conf

    2. Run the following Docker command verify the postgresql.conf file inside the container:

      docker exec CONTAINER_NAME tail  /var/lib/postgresql/data/postgresql.conf

    3. Ensure that the following entry is in the file:

      krb_server_keyfile=/var/lib/postgresql/data/alloydb.keytab

      For more information, see krb_server_keyfile.

  4. Optional: Add entries to the /var/lib/postgresql/data/DATA_DIR/pg_ident.conf file.

    When you use an external authentication system like GSSAPI, the name of the operating system user that initiated the connection might not be the same as the database user (role) that you want to use.

    In this case, specify the system user-to-PostgreSQL user mapping in the /var/lib/postgresql/data/DATA_DIR/pg_ident.conf file:

    docker exec -it CONTAINER_NAME bash
$ echo -e "
gssmap              /^(.*)@EXAMPLE\.COM$     \1
gssmap              /^(.*)@example\.com$     \1
" | column -t | tee -a /var/lib/postgresql/data/pg_ident.conf
( EOF )

    To implement username mapping, specify map=gssmap in the options field in the pg_hba.conf file.

    For more information about ident-based authentication, see Ident Maps.

  5. Reload the PostgreSQL configurations using the following command:

    docker exec -it CONTAINER_NAME psql -h localhost -U postgres
psql (16.3)
Type "help" for help.
postgres=# select pg_reload_conf();

Test Active Directory authentication

To verify that Active Directory authentication is working, follow these steps:

  1. Sign into Active Directory using kinit.

  2. Run the following psql command from the machine where you usually run kinit:

    root@4f6414ad02ef:/# kinit AD_USER_NAME
Password for user1@YOUR.REALM:

root@4f6414ad02ef:/# psql --h ALLOYDB_SERVER_HOST_NAME -U AD_USER_NAME
psql (16.6 (Ubuntu 16.6-0ubuntu0.24.04.1), server 16.3)
GSSAPI-encrypted connection
Type "help" for help.

user1=#

Disable Active Directory authentication

To disable Active Directory authentication in AlloyDB Omni, follow these steps, which disable the GSSAPI:

  1. Remove entries in the pg_hba.conf file that point to the gss authentication method:

    docker exec CONTAINER_NAME sed -i '/hostgssenc all all 0.0.0.0\/0 gss map=gssmap/d' /var/lib/postgresql/data/pg_hba.conf

  2. Reload the PostgreSQL configurations using the following command:

    docker exec -it alloydb_docs psql -h localhost -U postgres
psql (16.3)
Type "help" for help.
postgres=# select pg_reload_conf();

What's next