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

- [Current (18.4.0)](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/configure-client-authentication.md.txt)
- [18.4.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/18.4.0/docs/configure-client-authentication.md.txt)

<br />

This document describes how to configure client authentication on your Kubernetes-based AlloyDB Omni database cluster using the [`UserDefinedAuthentication`](https://docs.cloud.google.com/alloydb/omni/kubernetes/18.4.0/docs/reference/kubernetes-crds-1.9.0/userdefinedauthentication.md.txt) custom resource (`alloydbomni.dbadmin.goog/v1`). You can customize client authentication behavior---such as restricting client subnets, enforcing SSL/TLS, specifying custom authentication methods, or configuring user mapping---by defining custom `pg_hba.conf` and `pg_ident.conf` entries independently of Active Directory setup.

<br />

This document assumes that you're familiar with
[applying Kubernetes manifest files](https://kubernetes.io/docs/concepts/overview/working-with-objects/)
and using the `kubectl` command-line tool. For more information, see
[Command line tool (kubectl)](https://kubernetes.io/docs/reference/kubectl/).

## Before you begin

To configure client authentication, you must have the following:

- An AlloyDB Omni cluster deployed in a Kubernetes environment.
- Database users and roles configured in the cluster.
- The `kubectl` CLI installed and configured.

## Apply the custom resource manifest

Apply the following user-defined authentication custom resource manifest:

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

Replace the following:

- `USER_DEFINED_AUTHENTICATION_NAME`: the name of the `UserDefinedAuthentication` custom resource---for example, `DB_CLUSTER_NAME-client-auth`.
- `DB_CLUSTER_NAMESPACE`: the Kubernetes namespace for this custom resource. 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](https://docs.cloud.google.com/alloydb/omni/kubernetes/18.4.0/docs/deploy-kubernetes.md.txt#create).
- `PG_HBA_ENTRIES`: `pg_hba.conf` entries as a string list. These entries overwrite the default entries in `pg_hba.conf`. For example, to restrict connections to a specific subnet, use `- "host all all 192.168.1.0/24 scram-sha-256"`. For more information, see [The pg_hba.conf File](https://www.postgresql.org/docs/current/auth-pg-hba-conf.html).

  > [!NOTE]
  > PostgreSQL evaluates entries sequentially from top to bottom and uses the first matching rule.

- `PG_IDENT_ENTRIES`: (Optional) `pg_ident.conf` entries as a string list. To implement username mapping, specify `map=` in the options field in the `pg_hba.conf` file. If you don't need username mapping, omit the `pgIdentEntries` field from the manifest. For more information, see [User Name Maps](https://www.postgresql.org/docs/current/auth-username-maps.html).

## Verify the client authentication rules

To check the status of the `UserDefinedAuthentication` resource, run the following command:

```
kubectl get userdefinedauthentication -n DB_CLUSTER_NAMESPACE
```

Verify that the `STATE` column displays `Ready`.

To view resource details and conditions, run the following command:

```
kubectl describe userdefinedauthentication USER_DEFINED_AUTHENTICATION_NAME -n DB_CLUSTER_NAMESPACE
```

## Update client authentication rules

To update client authentication rules or user mappings, update `spec.pgHbaEntries`
or `spec.pgIdentEntries` in your manifest file and re-apply it:

```
kubectl apply -f CLIENT_AUTH_MANIFEST.yaml
```

The AlloyDB Omni operator dynamically reloads the PostgreSQL configuration
(`pg_ctl reload`) without database pod restart or downtime.

## Delete client authentication rules

To delete the custom authentication rules and revert to the default authentication rules, run the following command:

```
kubectl delete userdefinedauthentication USER_DEFINED_AUTHENTICATION_NAME -n DB_CLUSTER_NAMESPACE
```

When you delete the `UserDefinedAuthentication` resource, the
AlloyDB Omni operator dynamically reloads `pg_hba.conf` (`pg_ctl reload`)
to restore the default authentication rules without requiring a database pod
restart.

## What's next

- [Manage users and roles](https://docs.cloud.google.com/alloydb/omni/kubernetes/18.4.0/docs/database-users/manage-users.md.txt)
- [Manage password policies](https://docs.cloud.google.com/alloydb/omni/kubernetes/18.4.0/docs/manage-password-policy.md.txt)
- [`UserDefinedAuthentication` CRD reference](https://docs.cloud.google.com/alloydb/omni/kubernetes/18.4.0/docs/reference/kubernetes-crds-1.9.0/userdefinedauthentication.md.txt)