Select a documentation version: <button class="button button-with-icon cloud-select-dropdown__button button-primary" aria-haspopup="true">16.3.0</button>

- [Current (18.4.0)](https://docs.cloud.google.com/alloydb/omni/containers/current/docs/integrate-active-directory.md.txt)
- [18.4.0](https://docs.cloud.google.com/alloydb/omni/containers/18.4.0/docs/integrate-active-directory.md.txt)
- [18.3.0](https://docs.cloud.google.com/alloydb/omni/containers/18.3.0/docs/integrate-active-directory.md.txt)
- [18.1.0](https://docs.cloud.google.com/alloydb/omni/containers/18.1.0/docs/integrate-active-directory.md.txt)
- [17.10.0](https://docs.cloud.google.com/alloydb/omni/containers/17.10.0/docs/integrate-active-directory.md.txt)
- [17.9.0](https://docs.cloud.google.com/alloydb/omni/containers/17.9.0/docs/integrate-active-directory.md.txt)
- [17.7.0](https://docs.cloud.google.com/alloydb/omni/containers/17.7.0/docs/integrate-active-directory.md.txt)
- [17.5.0](https://docs.cloud.google.com/alloydb/omni/containers/17.5.0/docs/integrate-active-directory.md.txt)
- [16.14.0](https://docs.cloud.google.com/alloydb/omni/containers/16.14.0/docs/integrate-active-directory.md.txt)
- [16.13.0](https://docs.cloud.google.com/alloydb/omni/containers/16.13.0/docs/integrate-active-directory.md.txt)
- [16.11.0](https://docs.cloud.google.com/alloydb/omni/containers/16.11.0/docs/integrate-active-directory.md.txt)
- [16.9.0](https://docs.cloud.google.com/alloydb/omni/containers/16.9.0/docs/integrate-active-directory.md.txt)
- [16.8.0](https://docs.cloud.google.com/alloydb/omni/containers/16.8.0/docs/integrate-active-directory.md.txt)
- [16.3.0](https://docs.cloud.google.com/alloydb/omni/containers/16.3.0/docs/integrate-active-directory.md.txt)

<br />

This page describes how to integrate AlloyDB Omni with your existing [Active Directory](https://en.wikipedia.org/wiki/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. For more information, see [Active Directory overview](https://docs.cloud.google.com/alloydb/omni/containers/16.3.0/docs/active-directory-overview).

<br />

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

## 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](https://en.wikipedia.org/wiki/Generic_Security_Services_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](https://www.postgresql.org/docs/current/auth-pg-hba-conf.html).
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
   ```

   > [!NOTE]
   > **Note:** The keytab file must be owned by the PostgreSQL user and must have 600 permissions.

   The keytab file is generated by Kerberos for the PostgreSQL server. To
   learn more about authentication, see
   [GSSAPI Authentication](https://www.postgresql.org/docs/current/gssapi-auth.html).
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](https://www.postgresql.org/docs/current/runtime-config-connection.html#GUC-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
   ```

   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](https://www.postgresql.org/docs/8.0/auth-methods.html#:%7E:text=19.2.4.3.%20Ident%20Maps).
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=#
   ```

   > [!NOTE]
   > **Note:** To ensure that Active Directory authentication is working, make sure that the user in Active Directory has a role in AlloyDB Omni, or ensure that the user has a valid mapping in the `pg_ident.conf` file.

## 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 CONTAINER_NAME psql -h localhost -U postgres
   psql (16.3)
   Type "help" for help.
   postgres=# select pg_reload_conf();
   ```

## What's next

- [Integrate Active Directory group support with AlloyDB Omni](https://docs.cloud.google.com/alloydb/omni/containers/16.3.0/docs/integrate-ad-group-support-alloydb-omni).
- [Troubleshoot Active Directory in AlloyDB Omni](https://docs.cloud.google.com/alloydb/omni/containers/16.3.0/docs/troubleshoot-active-directory-integration.md.txt).