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 Active Directory, make sure that you meet the following
requirements:
Make sure that the Active Directory is set up.
Obtain the REALM of the Active Directory server.
Obtain the Key Distribution Center (KDC) hostname of the Active Directory
server. The hostname is stored in the Docker images.
Obtain the admin server hostname of the Active Directory server. This
hostname is stored in the Docker images.
Make sure that you have access to the Active Directory server so that you
can generate a .keytab file.
Choose an Active Directory user to use for testing and signin.
Get a .keytab file from the existing Active Directory server.
Obtain a .keytab file from the existing Active Directory server
To get a keytab from the Active Directory Server, follow
these steps:
Sign in as the administrator to the powershell terminal of the Active
Directory server.
Create a user called postgres by running the following command,
or by using the Active Directory user interface.
New-ADUser -Name "postgres" `
-SamAccountName "postgres" `
-UserPrincipalName "postgres@REALM" `
-Description "Service Account for AlloyDB Omni PostgreSQL Kerberos Authentication" `
-AccountPassword (Read-Host -AsSecureString "Set a strong password for the postgres service account") `
-Enabled $true `
-PasswordNeverExpires $true
Generate a service principal keytab that maps to this Active Directory
server.
ktpass /princ postgres/ALLOYDB_HOST_NAME@REALM /Pass ChangeMe123 /mapuser postgres /crypto ALL /ptype KRB5_NT_PRINCIPAL /mapOp set /out C:\Users\Public\postgres.keytab
Where <HOST> is the fully qualified domain name of the
server where you plan to deploy AlloyDB Omni—for example,
alloydb-server.ad.example.com. You must configure the same host in
the krb5.conf file in your domain realm mapping.
Copy the keytab file to your linux machine.
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.
Add the following entries to the /var/lib/postgresql/data/pg_hba.conf file,
before the host all all all scram-sha-256 entry.
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
Run the following Docker command to verify that the pg_hba.conf file
is inside the container:
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:
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-25 UTC."],[],[],null,["# Integrate Active Directory user support with AlloyDB Omni\n\nSelect a documentation version: Current (16.8.0)keyboard_arrow_down\n\n- [Current (16.8.0)](/alloydb/omni/current/docs/integrate-active-directory)\n- [16.8.0](/alloydb/omni/16.8.0/docs/integrate-active-directory)\n- [16.3.0](/alloydb/omni/16.3.0/docs/integrate-active-directory)\n\n\u003cbr /\u003e\n\nThis 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](/alloydb/omni/current/docs/active-directory-overview).\n\n\u003cbr /\u003e\n\nActive Directory configuration in AlloyDB Omni is optional and is\ndisabled by default. Only environments using Active Directory Server for\nauthentication can use this configuration mechanism.\n\nBefore you begin\n----------------\n\nBefore you integrate Active Directory, make sure that you meet the following\nrequirements:\n\n- Make sure that the Active Directory is set up.\n- Obtain the `REALM` of the Active Directory server.\n- Obtain the Key Distribution Center (KDC) hostname of the Active Directory server. The hostname is stored in the Docker images.\n- Obtain the admin server hostname of the Active Directory server. This hostname is stored in the Docker images.\n- Make sure that you have access to the Active Directory server so that you can generate a `.keytab` file.\n- Choose an Active Directory user to use for testing and signin.\n- Get a `.keytab` file from the existing Active Directory server.\n\n### Obtain a .keytab file from the existing Active Directory server\n\nTo get a keytab from the Active Directory Server, follow\nthese steps:\n\n1. Sign in as the administrator to the powershell terminal of the Active Directory server.\n2. Create a user called `postgres` by running the following command, or by using the Active Directory user interface. \n\n```\n New-ADUser -Name \"postgres\" `\n -SamAccountName \"postgres\" `\n -UserPrincipalName \"postgres@REALM\" `\n -Description \"Service Account for AlloyDB Omni PostgreSQL Kerberos Authentication\" `\n -AccountPassword (Read-Host -AsSecureString \"Set a strong password for the postgres service account\") `\n -Enabled $true `\n -PasswordNeverExpires $true\n \n```\n3. Generate a service principal keytab that maps to this Active Directory server. \n\n```\n ktpass /princ postgres/ALLOYDB_HOST_NAME@REALM /Pass ChangeMe123 /mapuser postgres /crypto ALL /ptype KRB5_NT_PRINCIPAL /mapOp set /out C:\\Users\\Public\\postgres.keytab\n \n```\n4. Where `\u003cHOST\u003e` is the fully qualified domain name of the server where you plan to deploy AlloyDB Omni---for example, `alloydb-server.ad.example.com`. You must configure the same host in the `krb5.conf` file in your domain realm mapping.\n5. Copy the keytab file to your linux machine.\n\n| **Important:** The keytab file is highly sensitive. It contains the secret key for your service. Transfer the keytab to your Linux machine using a secure method---like SCP or WinSCP---and make sure that its file permissions on the Linux server are highly restrictive---for example, that they are readable only by the PostgreSQL user.\n\nEnable Active Directory authentication\n--------------------------------------\n\nTo enable Active Directory authentication in AlloyDB Omni,\nfollow these steps, which include configuring the\n[Generic Security Service Application Program Interface](https://en.wikipedia.org/wiki/Generic_Security_Services_Application_Program_Interface)\n(GSSAPI), which is an application programming interface that enables programs to\naccess security services.\n\n1. Add the following entries to the `/var/lib/postgresql/data/pg_hba.conf` file,\n before the \n\n `host all all all scram-sha-256` entry.\n\n 1. Run the following Docker command to add `gss` inside the container:\n\n ```\n 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\n ```\n 2. Run the following Docker command to verify that the `pg_hba.conf` file\n is inside the container:\n\n ```\n docker exec CONTAINER_NAME cat /var/lib/postgresql/data/pg_hba.conf\n ```\n 3. Verify that the following entry is in the file:\n\n ```\n hostgssenc all all 0.0.0.0/0 gss map=gssmap\n ```\n\n For more information, see\n [The pg_hba.conf File](https://www.postgresql.org/docs/current/auth-pg-hba-conf.html).\n2. Copy the key tab file to the data directory inside the AlloyDB Omni image.\n\n ```\n docker cp PATH TO KEYTAB FILE CONTAINER_NAME:/var/lib/postgresql/data/alloydb.keytab\n docker exec CONTAINER_NAME chmod 600 /var/lib/postgresql/data/alloydb.keytab\n docker exec CONTAINER_NAME chown postgres:postgres /var/lib/postgresql/data/alloydb.keytab\n ```\n | **Note:** The keytab file must be owned by the PostgreSQL user and must have 600 permissions.\n\n The keytab file is generated by Kerberos for the PostgreSQL server. To\n learn more about authentication, see\n [GSSAPI Authentication](https://www.postgresql.org/docs/current/gssapi-auth.html).\n3. Add an entry for the keytab file to the `/var/lib/postgresql/data/`\u003cvar translate=\"no\"\u003eDATA_DIR\u003c/var\u003e`/postgresql.conf`\n file.\n\n 1. Run the following Docker command to add the entry inside the container:\n\n ```\n docker exec CONTAINER_NAME sed -i '$akrb_server_keyfile='\"'\"'/var/lib/postgresql/data/alloydb.keytab'\"'\" /var/lib/postgresql/data/postgresql.conf\n ```\n 2. Run the following Docker command verify the `postgresql.conf` file\n inside the container:\n\n ```\n docker exec CONTAINER_NAME tail /var/lib/postgresql/data/postgresql.conf\n ```\n 3. Ensure that the following entry is in the file:\n\n ```\n krb_server_keyfile=/var/lib/postgresql/data/alloydb.keytab\n ```\n\n For more information, see\n [krb_server_keyfile](https://www.postgresql.org/docs/current/runtime-config-connection.html#GUC-KRB-SERVER-KEYFILE).\n4. Optional: Add entries to the `/var/lib/postgresql/data/`\u003cvar translate=\"no\"\u003eDATA_DIR\u003c/var\u003e`/pg_ident.conf` file.\n\n When you use an external authentication system like GSSAPI, the name of\n the operating system user that initiated the connection might not be the\n same as the database user (role) that you want to use.\n\n In this case, specify the system user-to-PostgreSQL user mapping in the\n `/var/lib/postgresql/data/`\u003cvar translate=\"no\"\u003eDATA_DIR\u003c/var\u003e`/pg_ident.conf` file: \n\n ```\n docker exec -it CONTAINER_NAME bash\n $ echo -e \"\n gssmap /^(.*)@EXAMPLE\\.COM$ \\1\n gssmap /^(.*)@example\\.com$ \\1\n \" | column -t | tee -a /var/lib/postgresql/data/pg_ident.conf\n ```\n\n To implement username mapping, specify `map=gssmap` in the options field in\n the `pg_hba.conf` file.\n\n For more information about ident-based authentication, see\n [Ident Maps](https://www.postgresql.org/docs/8.0/auth-methods.html#:%7E:text=19.2.4.3.%20Ident%20Maps).\n5. Reload the PostgreSQL configurations using the following command:\n\n ```\n docker exec -it CONTAINER_NAME psql -h localhost -U postgres\n psql (16.3)\n Type \"help\" for help.\n postgres=# select pg_reload_conf();\n ```\n\nTest Active Directory authentication\n------------------------------------\n\nTo verify that Active Directory authentication is working, follow\nthese steps:\n\n1. Sign into Active Directory using `kinit`.\n2. Run the following `psql` command from the machine where you usually run `kinit`:\n\n ```\n root@4f6414ad02ef:/# kinit AD_USER_NAME\n Password for user1@YOUR.REALM:\n\n root@4f6414ad02ef:/# psql --h ALLOYDB_SERVER_HOST_NAME -U AD_USER_NAME\n psql (16.6 (Ubuntu 16.6-0ubuntu0.24.04.1), server 16.3)\n GSSAPI-encrypted connection\n Type \"help\" for help.\n\n user1=#\n ```\n | **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.\n\nDisable Active Directory authentication\n---------------------------------------\n\nTo disable Active Directory authentication in AlloyDB Omni,\nfollow these steps, which disable the GSSAPI:\n\n1. Remove entries in the `pg_hba.conf` file that point to the `gss`\n authentication method:\n\n ```\n 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\n ```\n2. Reload the PostgreSQL configurations using the following command:\n\n ```\n docker exec -it CONTAINER_NAME psql -h localhost -U postgres\n psql (16.3)\n Type \"help\" for help.\n postgres=# select pg_reload_conf();\n ```\n\nWhat's next\n-----------\n\n- [Integrate Active Directory user support on Kubernetes](/alloydb/omni/current/docs/integrate-active-directory-kubernetes-operator).\n- [Troubleshoot Active Directory in AlloyDB Omni](/alloydb/omni/current/docs/troubleshoot-active-directory-integration).\n- [Integrate Active Directory group support with AlloyDB Omni](/alloydb/omni/current/docs/integrate-ad-group-support-alloydb-omni).\n- [Integrate Active Directory group support on Kubernetes](/alloydb/omni/current/docs/integrate-ad-group-support-kubernetes-operator).\n- [Troubleshoot Active Directory integration in AlloyDB Omni](/alloydb/omni/current/docs/troubleshoot-active-directory-integration)."]]