--- title: Couchbase User Authentication pubDate: 2026-08-17T09:53:44.266Z antora: editUrl: https://github.com/couchbase/docs-operator/edit/release/2.9/modules/ROOT/pages/tutorial-rbac-auth.adoc xref: xref:operator::tutorial-rbac-auth.adoc[] --- [Consult the llms.txt file for a full list of contents](/llms.txt) [View original HTML](/operator/current/tutorial-rbac-auth.html) # Couchbase User Authentication > A tutorial for configuring Couchbase user authentication and authorization using the Kubernetes Operator. > [!WARNING] > Tutorials are accurate at the time of writing but rely heavily on third party software. Tutorials are provided to demonstrate how a particular problem may be solved. Use of third party software is not supported by Couchbase. For further help in the event of a problem, contact the relevant software maintainer. ## [](#overview)Overview This tutorial describes how to use the Kubernetes Operator to create authenticated users and bind them to specific roles to provide different levels of authorization. User authentication can be provided by Couchbase itself or an external LDAP service (such as OpenLDAP). The Kubernetes Operator refers to [Couchbase Authentication](#couchbase-authentication) as the `local` domain, and [LDAP Authentication](#ldap-authentication) as the `external` domain. ## [](#couchbase-authentication)Couchbase Authentication The local Couchbase domain performs internal password management and requires a password to be provided during user creation. ### [](#create-a-user-secret)Create a User Secret When using Couchbase for authentication, a Kubernetes Secret containing the user password needs to be created. The following command creates a secret with `mypass` set as the password: ```console $ cat << EOF | kubectl apply -f - --- apiVersion: v1 kind: Secret metadata: name: my-password-secret type: Opaque data: password: bXlwYXNz # mypass EOF ``` ### [](#create-and-authorize-a-user)Create and Authorize a User Utilizing the Secret from the previous step, create a user and bind it to a set of roles which could be used for basic application development. The following command creates a new user, a new group containing the roles, and a new role binding to aggregate the the user and the group together: ```console $ cat << EOF | kubectl apply -f - --- apiVersion: couchbase.com/v2 kind: CouchbaseUser metadata: name: developer (1) spec: fullName: "Jane Doe" authDomain: local authSecret: my-password-secret (2) --- apiVersion: couchbase.com/v2 kind: CouchbaseGroup metadata: name: my-group (3) spec: roles: (4) - name: replication_admin - name: data_reader bucket: default (5) - name: data_writer buckets: (6) kind: CouchbaseBucket name: default scopes: (7) kind: CouchbaseScope name: seasia collections: (8) kind: CouchbaseCollection name: templates --- apiVersion: couchbase.com/v2 kind: CouchbaseRoleBinding metadata: name: my-group-binding (9) spec: subjects: - kind: CouchbaseUser name: developer roleRef: kind: CouchbaseGroup name: my-group EOF ``` | **1** | The new user, with username developer. | | ----- | -------------------------------------------------------------------------------------------------------------------- | | **2** | The Secret from the previous step. | | **3** | The new group, with name my-group. | | **4** | The [Couchbase roles](../../server/current/learn/security/roles.md) that we want to assign to the new user. | | **5** | You can optionally specify a bucket name to apply the role against. This bucket need not be managed by the operator. | | **6** | You can also optionally specify bucket resources to apply the role against for managed buckets. | | **7** | In Couchbase server 7.0+, you can optionally specify scope resources to apply the role against. | | **8** | In Couchbase server 7.0+, you can optionally specify collection resources to apply the role against. | | **9** | The new role binding, with name my-group-binding, that binds the new user (developer) with the new group (my-group). | To test that the new user was created and assigned the desired roles, [connect to the Couchbase Web Console](howto-ui.md) and log in as user `developer` with password `mypass`. ```console # forward the ui port of a couchbase pod $ kubectl port-forward --namespace default 8091:8091 # open localhost:8091 ``` ### [](#create-and-authorize-additional-users)Create and Authorize Additional Users Additional users can be added to the development group with a similar set of roles. To authorize the additional users with the same roles as the user from the previous section, you only need to update the role binding to include the new users, since the group is already created. The following command creates two new users, and updates the role binding to bind them to the group that was created in the previous section: ```console $ cat << EOF | kubectl apply -f - --- apiVersion: couchbase.com/v2 kind: CouchbaseUser metadata: name: admin spec: fullName: "Joe Day" authDomain: local authSecret: my-password-secret --- apiVersion: couchbase.com/v2 kind: CouchbaseUser metadata: name: security spec: fullName: "Bin Nash" authDomain: local authSecret: my-password-secret --- apiVersion: couchbase.com/v2 kind: CouchbaseRoleBinding metadata: name: my-group-binding spec: subjects: (1) - kind: CouchbaseUser name: developer - kind: CouchbaseUser name: admin - kind: CouchbaseUser name: security roleRef: kind: CouchbaseGroup name: my-group EOF ``` | **1** | Updates the role binding to include the two new users alongside the user from the previous section. The group now contains three users, and each user is bound to same set of roles. | | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | > [!NOTE] > In this example, the two new users reference the same Secret as the user from the previous section. In production, you will want to create an individual secret for each user. At this point, you can modify the roles of all three users at once by updating the group. To do this, use the following command to edit the `CouchbaseGroup` resource and add the `security_admin` role: ```console $ kubectl edit couchbasegroup my-group ... # Please edit the object below. Lines beginning with a '#' will be ignored, spec: roles: - name: replication_admin - bucket: '*' name: data_reader - bucket: default name: data_writer - name: security_admin ``` ## [](#ldap-authentication)LDAP Authentication Couchbase is able to delegate authentication to an external LDAP service. Using LDAP for authentication adds an additional level of security and places password management within an external domain. ### [](#running-an-openldap-server)Running an OpenLDAP server The OpenLDAP service will be created using Helm. To seed the service with users and groups, a value override file needs to be created: ```console $ echo " customLdifFiles: 01-default-users.ldif: |- dn: ou=People,dc=example,dc=org objectClass: organizationalUnit ou: People dn: uid=jbrown,ou=People,dc=example,dc=org objectclass: top objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson uid: jbrown cn: James sn: Brown userPassword: password" > ldap-values.yaml ``` Now run the OpenLDAP server with the custom values in `ldap-values.yaml`: ```console # helm 3.1 $ helm install my-release --set adminPassword=ldappassword -f ldap-values.yaml stable/openldap ``` Couchbase will communicate with the OpenLDAP server using the service created by the Helm Chart. Run `helm status` to see the service endpoint: ```console $ helm status my-release NOTES: OpenLDAP has been installed. You can access the server from within the k8s cluster using: my-release-openldap.default.svc.cluster.local:389 ``` The Couchbase service will also need to authenticate with OpenLDAP in order to query for user records and groups. Therefore, a Kubernetes secret will need to be created with the `adminPassword` which has been set to `ldappassword`: ```console $ cat << EOF | kubectl apply -f - --- apiVersion: v1 data: password: bGRhcHBhc3N3b3Jk # ldappassword kind: Secret metadata: name: ldap-secret type: Opaque ``` ### [](#edit-the-couchbasecluster-resource)Edit the `CouchbaseCluster` Resource The LDAP configuration must be added to the `CouchbaseCluster` resource in order to authenticate external users. Add the OpenLDAP service endpoint as one of the hosts along with organizational information required to communicate with the service. ```yaml apiVersion: couchbase.com/v2 kind: CouchbaseCluster metadata: name: cb-example spec: image: couchbase/server:6.5.0 security: rbac: managed: true ldap: hosts: - my-release-openldap.default.svc.cluster.local port: 389 encryption: None bindDN: "cn=admin,dc=example,dc=org" bindSecret: ldap-secret userDNMapping: template: "uid=%u,ou=People,dc=example,dc=org" ... ``` > [!NOTE] > In production you will want to set `encryption` to `StartTLS` or `TLS`. After updating the `CouchbaseCluster` resource, you can test LDAP authentication from the Couchbase Web Console. Start by [connecting to the Couchbase Web Console](howto-ui.md). ```console # forward the ui port of a couchbase pod $ kubectl port-forward --namespace default 8091:8091 # open localhost:8091 ``` After logging in, go to the **Security** view, and click **LDAP**. Under "Test User Authentication", enter the username `jbrown` and the password `password`, and then click **Test User Authentication**. Couchbase Server will map the specified username to an LDAP DN, and perform authentication on the LDAP server. If your LDAP configuration is set up correctly, you'll get a notification that the test was successful. #### [](#grant-roles-to-an-ldap-user)Grant Roles to an LDAP User LDAP users are added to Couchbase using the same steps as [local users](#couchbase-authentication) except that the `authDomain` is set to `external`. Create a `CouchbaseUser` resource for the LDAP user: ```console $ cat << EOF | kubectl apply -f - --- apiVersion: couchbase.com/v2 kind: CouchbaseUser metadata: name: jbrown spec: fullName: "James Brown" authDomain: external EOF ``` The next step is to bind the user to a group that contains the roles that you want the user to have. If you were to use the same groups and bindings from the [local users section](#couchbase-authentication), the command would be as follows: ```console $ cat << EOF | kubectl apply -f - --- apiVersion: couchbase.com/v2 kind: CouchbaseRoleBinding metadata: name: my-group-binding spec: subjects: - kind: CouchbaseUser name: developer - kind: CouchbaseUser name: admin - kind: CouchbaseUser name: security - kind: CouchbaseUser name: jbrown roleRef: kind: CouchbaseGroup name: my-group EOF ``` If you followed this setup, the LDAP user has the same roles as the other uses, even though it relies on a different authentication path (`external` vs `local`). You can test authentication/authorization by logging into the Couchbase Web Console with the username `jbrown` and password `password`. ## [](#further-reading)Further Reading * [Learn RBAC Concepts](concept-user-rbac.md)