This page documents AlloyDB Omni version 16.3.0. Choose documentation for a different version.

Integrate Active Directory with AlloyDB Omni on Kubernetes
Stay organized with collections Save and categorize content based on your preferences.

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.

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.

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

Enable Active Directory authentication

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

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

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

Check Active Directory authentication status

To determine the status of Active Directory authentication, follow these steps:

Get the current deployment args for the fleet controller and ensure that enable-user-defined-authentication is set to true, run the following commands:

kubectl get deployment -n alloydb-omni-system fleet-controller-manager -o json | jq '.spec.template.spec.containers[0].args'

[
  "--health-probe-bind-address=:8081",
  "--metrics-bind-address=127.0.0.1:8080",
  "--leader-elect",
  "--image-registry=gcr.io",
  ...
  "--enable-user-defined-authentication=true"
]

Get the current deployment args for the local controller and ensure that enable-user-defined-authentication is set to true by running the following commands:

kubectl get deployment -n alloydb-omni-system local-controller-manager -o json | jq '.spec.template.spec.containers[0].args'

[
  "--health-probe-bind-address=:8081",
  "--metrics-bind-address=127.0.0.1:8080",
  "--leader-elect",
  "--deployment-platform=generic-k8s",
  "--enable-backup-from-standby=true",
  "--enable-user-defined-authentication=true"
]

Configure Active Directory support

Create and apply a config map using pg_hba.conf file entries:
```
kubectl apply -f - 
apiVersion: v1
kind: ConfigMap
metadata:
  name: pg-hba-config
data:
  pg_hba_entries: |
    # Active Directory-based users
    hostgssenc all all 0.0.0.0/0    gss
    hostgssenc all all ::1/128      gss
    # Database-based users
    hostssl    all all 0.0.0.0/0  scram-sha-256
    hostssl    all all ::/0       scram-sha-256
EOF
```
Modify these entries based on your requirements. 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 will be signed in using the GSS API. If this signin approach fails, then password-based authentication will be used as a fallback.

For more information, see The pg_hba.conf File.

Create and apply a secret with the keytab:

 kubectl apply -f - 
 apiVersion: v1
 kind: Secret
 metadata:
   name: db-keytab-dbcluster-sample
 type: Opaque
 data:
   krb5.keytab: |
    BASE64_ENCODED_KEYTAB
 EOF

Optional: Create and apply a config map using pg_ident.conf entries.

  kubectl apply -f - EOF
  apiVersion: v1
  kind: ConfigMap
  metadata:
    name: pg-ident-config
  data:
    pg_ident_entries: |

      MAP_NAME /^(.)@YOUR.REALM$/        \1
      MAP_NAME /^(.)@your.realm$/        \1
  EOF

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

For more information, see Ident Maps.

To enable Active Directory integration, add annotations to the DBCluster spec.

kubectl apply -f - DB_CLUSTER_NAME
type: Opaque
data:
  DB_CLUSTER_NAME: "ENCODED_PASSWORD"
---
apiVersion: alloydbomni.dbadmin.goog/v1
kind: DBCluster
metadata:
  name: DB_CLUSTER_NAME
  annotations:
    dbs.dbadmin.goog.com/pg-hba-config-map: pg-hba-config
    dbs.dbadmin.goog.com/pg-ident-config-map: pg-ident-config
    dbs.dbadmin.goog.com/keytab-ref: db-keytab-dbcluster-sample
spec:
  databaseVersion: "DB_VERSION"
  primarySpec:
    adminUser:
      passwordRef:
        name: db-pw-DB_CLUSTER_NAME
    resources:
      memory: MEMORY_SIZE
      cpu: CPU_COUNT
      disks:
      - name: DataDisk
        size: DISK_SIZE
EOF

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.

kubectl exec -it postgres -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 ;
```

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

You can check the Active Directory authentication status.