Integrate Active Directory user support on Kubernetes

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:

  1. Upgrade the AlloyDB Omni operator to version 1.5.0.
  2. 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.
  3. 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

  1. 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.

  2. 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

  1. 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;

  2. 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.

  3. 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

What's next