Integrate Active Directory user support on Kubernetes

Select a documentation version:

This document describes how to enable Active Directory integration on your Kubernetes-based AlloyDB Omni database cluster so that you can allow your existing Active Directory-based users to access your AlloyDB Omni database. Active Directory integration provides authorization using GSSAPI for users authenticated using the Kerberos mechanism to access AlloyDB Omni.

For more information, see Active Directory overview .

This document assumes that you're familiar with applying Kubernetes manifest files and using the kubectl command-line tool. For more information, see Command line tool (kubectl) .

Before you begin

To enable Active Directory integration, you must have the following:

An AlloyDB Omni cluster deployed in a Kubernetes environment
An Active Directory server keytab

Migrate from AlloyDB Omni Kubernetes operator 1.4.0 to 1.5.0

If you're using Active Directory Integration in AlloyDB Omni operator version 1.4.0 or earlier, you must migrate to AlloyDB Omni operator version 1.5.0.

To migrate to AlloyDB Omni operator version 1.5.0, follow these steps:

Upgrade the AlloyDB Omni operator to version 1.5.0 .
Create a user defined authentication resource.
1. Create a new UserDefinedAuthentication resource manifest.
2. Populate spec.dbclusterRef with the target DBCluster name.
3. Populate spec.keytabSecretRef with the name of the keytab secret.
4. Copy the existing pg_hba.conf rules that are relevant to the Active Directory and Kerberos authentication into the spec.pgHbaEntries field.
5. Copy the existing pg_ident.conf rules (if any) into the spec.pgIdentEntries field.
6. Apply this new manifest, for example, kubectl apply -f user-auth-crd.yaml .
Remove the Preview Configuration & Redeploy Cluster.
1. In the DBCluster resource definition, remove all annotations that you previously used to configure Active Directory integration, for example, host based authentication (HBA) rules, ident rules, and keytab file annotation.
2. Delete the pg_hba and pg_ident config maps that you created.
3. Re-apply the updated DBCluster manifest.

Configure Active Directory support

Create and apply a secret with the keytab:

  apiVersion 
 : 
  
 v1 
 kind 
 : 
  
 Secret 
 metadata 
 : 
  
 name 
 : 
  
  KEYTAB_SECRET_NAME 
 
  
 namespace 
 : 
  
  DB_CLUSTER_NAMESPACE 
 
 type 
 : 
  
 Opaque 
 data 
 : 
  
 krb5.keytab 
 : 
  
 | 
  
  KEYTAB_FILE_CONTENT

The following is an example command that generates a keytab on on the Active Directory server:

ktpass /princ postgres/ DBCLUSTER_HOST 
@ REALM 
/Pass PASSWORD 
/mapuser postgres /crypto ALL /ptype KRB5_NT_Principal /out OUTPUT_PATH

ALLOYDB_HOST is the host which points to the DBCluster or the DBCluster IP Address.

Apply the following user defined authentication custom resource manifest:

  apiVersion 
 : 
  
 alloydbomni.dbadmin.goog/v1 
 kind 
 : 
  
 UserDefinedAuthentication 
 metadata 
 : 
  
 name 
 : 
  
  USER_DEFINED_AUTHENTICATION_NAME 
 
  
 namespace 
 : 
  
  DB_CLUSTER_NAMESPACE 
 
 spec 
 : 
  
 dbclusterRef 
 : 
  
 name 
 : 
  
  DB_CLUSTER_NAME 
 
  
 keytabSecretRef 
 : 
  
 name 
 : 
  
  KEYTAB_SECRET_NAME 
 
  
 pgHbaEntries 
 : 
  
  PG_HBA_ENTRIES 
 
  
 pgIdentEntries 
 : 
  
  PG_IDENT_ENTRIES

Replace the following:

USER_DEFINED_AUTHENTICATION_NAME : the name of the UserDefinedConfiguration, for example, DB_CLUSTER_NAME -ad-auth .
DB_CLUSTER_NAMESPACE : the Kubernetes namespace for this backup plan. The namespace must match the namespace of the database cluster.
DB_CLUSTER_NAME : the name of your database cluster, which you assigned when you created it .
KEYTAB_SECRET_NAME : the name of the keytab that you created.
PG_HBA_ENTRIES : pg_hba.conf entries as a string list. These entries overwrite the default entries in pg_hba.conf . If you add an invalid configuration, users can't sign in.

In the preceding example, you added entries for GSS-based authentication followed by password-based authentication. This means that the user is signed in using the GSS API. If this signin approach fails, then password-based authentication is used as a fallback.

For more information, see The pg_hba.conf File .

PG_IDENT_ENTRIES : pg_ident.conf entries as a string list. To implement username mapping, specify map= in the options field in the pg_hba.conf file. For more information, see Ident Maps .

See the following example:

   
 apiVersion 
 : 
  
 v1 
  
 kind 
 : 
  
 Secret 
  
 metadata 
 : 
  
 name 
 : 
  
 db-keytab-dbcluster-sample 
  
 type 
 : 
  
 Opaque 
  
 data 
 : 
  
 krb5.keytab 
 : 
  
 | 
  
 DUMMY_KEYTAB 
  
 --- 
  
 apiVersion 
 : 
  
 alloydbomni.dbadmin.goog/v1 
  
 kind 
 : 
  
 UserDefinedAuthentication 
  
 metadata 
 : 
  
 name 
 : 
  
 dbcluster-sample-ad-auth 
  
 spec 
 : 
  
 dbclusterRef 
 : 
  
 name 
 : 
  
 dbcluster-sample 
  
 keytabSecretRef 
 : 
  
 name 
 : 
  
 db-keytab-dbcluster-sample 
  
 pgHbaEntries 
 : 
  
 - 
  
 hostgssenc all           all      0.0.0.0/0     gss 
  
 - 
  
 hostgssenc all           all      ::1/128       gss 
  
 - 
  
 hostssl all all 0.0.0.0/0 scram-sha-256 
  
 - 
  
 hostssl all all ::/0 scram-sha-256 
  
 pgIdentEntries 
 : 
  
 - 
  
 usermap  active_directory_user postgres_user

Create database roles as an Active Directory user

Create a role in your database that matches the Active Directory user. To create a role for your Active Directory user, connect to the cluster and run the following commands:
```
username=# CREATE ROLE " USERNAME 
@ REALM 
" WITH LOGIN;
```

Sign into the database using the Active Directory user. You must have kinit enabled in the client where you are connecting. In this example, the postgres-client pod has kinit and psql installed and is configured to connect to the AlloyDB Omni cluster using psql client.

kubectl exec -it postgres-client -n DB_CLUSTER_NAMESPACE 
-- bash
root:/# kinit USERNAME 
Password for USERNAME 
@ REALM 
:

root:/# psql -h HOSTNAME 
-d DB_NAME 
-U USERNAME 
@ REALM 
psql (16.6 (Ubuntu 16.6-0ubuntu0.24.04.1), server 16.3)
GSSAPI-encrypted connection
Type "help" for help.

Run SQL queries.

  username 
 =# 
  
 select 
  
 * 
  
 from 
  
  TABLE_NAME 
 
 ;

Disable Active Directory authentication

To disable Active Directory authentication, run the following Helm command:

helm upgrade alloydbomni-operator PATH_TO_CHART 
-n alloydb-omni-system --set userDefinedAuthentication.enabled=false

The command returns the following output:

Release "alloydbomni-operator" has been upgraded. Happy Helming!
NAME: alloydbomni-operator
LAST DEPLOYED: CURRENT_TIMESTAMP
NAMESPACE: alloydb-omni-system
STATUS: deployed
REVISION: 2
TEST SUITE: None