Manage Passwords

Couchbase Server lets you manage passwords for local users, and enforce password policies.

Couchbase Server manages passwords for users in the local domain when using password authentication. The administrator, who installs and configures Couchbase Server, can create, reset, and enforce password policies for these accounts through the Web UI, CLI, or REST API. Local user accounts also support additional security controls such as forced password changes.

External authentication systems such as LDAP or SAML manage user credentials in the external domain. Couchbase Server relies on these systems to verify user identity, which means that password creation, storage, and policy enforcement occur outside of Couchbase. This separation allows organizations to centralize identity management, apply consistent authentication policies across applications, and reduce administrative overhead.

User Password Changes

Local users and external users can change their own passwords.

Password Changes for Local Users

Users defined in the local domain can change their own passwords in the following ways through Couchbase Server:

On-demand.
When prompted by the administrator.

A local user can change their password from the following interfaces:

Couchbase Web Console/Web UI: The local users with the Couchbase Web Console UI access can sign in to their account and change their password. For more information about changing password on-demand from the UI, see Change Password On-demand from the UI.

An administrator can enforce a local user, existing or new, to change their password at the next login. For more information about changing password, prompted by administrator during a login, from the UI, see Change Password When Prompted.
CLI: The local users can change their password, either on-demand or when prompted by administrator, by using the couchbase-cli user-change-password command. For more information about changing password using the CLI, see Change Password On-demand Using the CLI.
REST API: The local users can change their password, either on-demand or when prompted by administrator, by calling the /controller/changePassword endpoint. For more information about changing password using the REST API, see Change Password On-demand Using the REST API.

This flexibility allows local users to manage their credentials without administrator involvement, which reduces administrative workload, and improves security by ensuring that only the user knows their active password. In addition, Couchbase Server can enforce policies such as forced password changes to improve security for local accounts.

Password Changes for External Users

External domain users can change their passwords through their identity provider (IdP) or authentication system.

Couchbase Server does not store or manage external user passwords.
External users must use external authentication systems such as LDAP or SAML to change their passwords.
After changing the password in the IdP, external users must use the new password to access Couchbase.

Administrative Password Controls

Administrators can set initial passwords for users when creating accounts in the local domain. They can also change passwords for existing users through the Web UI, CLI, or REST API, ensuring that accounts remain secure if credentials are compromised. In addition, administrators can force a user to change their password at the next login, which is useful when assigning temporary passwords or when stronger security is required.

This feature ensures that users set their own private password as soon as possible.

External users must use external authentication systems such as LDAP or SAML to change their passwords.

Reset Passwords for Existing Users

You can reset any local user’s password associated with your cluster.

You cannot reset the password for external domain user accounts. The Reset Password button appears on the Users section only if the user is locally defined.

To reset a local user’s password, do the following:

On the Security screen, select Users & Groups, and then select Users.
Select the user account from the list for which you want to reset the password and select Reset Password associated with that user. The Reset Password dialog is displayed.
In the Reset Password dialog, enter the new password for the user in the New Password field and re-enter to confirm the password in the Confirm Password field.
Select Save to save the password changes.

The local user’s password is reset.

Set Initial Password for a New User

As an administrator, you can set an initial password for a new local user, during the user creation process. The user can continue to use this password until they change it.

You can set the first password using the UI, CLI, or REST API.

Set Initial Password for a New User from the UI

To set an initial password for a new user from the UI, do the following:

On the Security screen, select Users & Groups, and then select Users.
Select Add User to create a new user.
In the Add New User dialog, enter the following user’s details:
- Enter the Username.
- Enter a temporary password in the Password field and re-enter it in the Verify Password field.
Select the necessary user roles and groups. For more information, see Add a Locally Authenticated User.
Select Add User to create the user with an initial password.

The local user can then log in with the initial password when prompted to change it upon first login.

Set Initial Password for a New User Using the CLI

As an administrator, you can use the command couchbase-cli user-manage with the arguments --rbac-username and --rbac-password to set an initial password for a new local user using the CLI.

Follow one of the procedures in the Manage Local Users with the CLI, as necessary.

See the following example:

/opt/couchbase/bin/couchbase-cli user-manage \
--cluster http://10.144.210.101 \
--username Administrator \
--password password \
--set \
--rbac-username dgreen \
--rbac-password firstpassword \
--roles cluster_admin \
--auth-domain local

The command sets the initial password to firstpassword for the new local user dgreen.

Set Initial Password for a New User Using the REST API

As an administrator, you can use the method and URI PUT /settings/rbac/users/local/<username> with the argument -d password to set an initial password for a new local user using the REST API.

Follow one of the procedures in the Manage Local Users Using the REST API, as necessary.

See the following example:

curl -v -X  PUT -u Administrator:password \
http://10.143.192.101:8091/settings/rbac/users/local/dgreen \
-d password=firstpassword \
-d roles=cluster_admin \

The API request sets the initial password to firstpassword for the new local user dgreen.

Force Password Update

As an administrator, you can force a password update for any local user, associated with your cluster, in the following ways:

When creating a local user, set a temporary initial password, and force a password change at their first login.
For an existing user, force a password change at their next login.

After authentication, the Couchbase Web Console UI prompts the user to set a new password.

Users can proceed to use Couchbase Server only after they change their password.

Create a Temporary Password for a New User

As an administrator, you can create a temporary password for a new local user during the user creation process. Then you can force the user to change their password at the first login.

Couchbase Server allows the new user to authenticate only after changing their temporary password.

Create a Temporary Password for a New User from the UI

As an administrator, to force a new user to change their password during their first login, do the following:

Begin by following steps from the section Set Initial Password for a New User.
In the Force Password Update panel, enable User must change password at next logon.
Select Add User to save the details.

When the local user logs in for the first time, the system prompts them to change their temporary password. For more information, see Change Password When Prompted.

Create a Temporary Password for a New User Using the REST API

As an administrator, you can use the method and URI PUT /settings/rbac/users/local/<new-username> with the attribute temporaryPassword=true to create a local user and force them to change their password at the first login, using the REST API.

See the following example:

curl -v -X  PUT -u Administrator:password \
http://10.143.192.101:8091/settings/rbac/users/local/dgreen \
-d password=firstpassword \
-d roles=cluster_admin \
-d temporaryPassword=true

The API request sets the temporary password to firstpassword for the new local user dgreen and prompts them to change their password at the first login.

Force Existing Users to Change Passwords

As an administrator, you can force an existing user to change their password at their next login.

Couchbase Server allows the user to authenticate only after changing their password.

Force Existing Users to Change Passwords from the UI

As an administrator, to force existing users to change their passwords, do the following:

On the Security screen, select Users & Groups, and then select Users.
Select the local user account from the list for which you want to force a password change and select Edit.
In the Edit User dialog, in the Force Password Update section, enable User must change password at next logon.

You cannot undo this setting once set from the Web UI. You can undo this setting only via the REST API.
Select Save Changes.

The system prompts the user to change their password during their next login. For more information, see Change Password When Prompted.

Force Existing Users to Change Passwords using the REST API

This section is similar to Create a Temporary Password for a New User Using the REST API. As an administrator, you can use the method and URI PUT /settings/rbac/users/local/<username> with the attribute temporaryPassword=true to force an existing local user to change their password at the next login, using the REST API.

See the following example:

curl -v -X  PUT -u Administrator:password \
http://10.143.192.101:8091/settings/rbac/users/local/dgreen \
-d password=nextpassword \
-d roles=cluster_admin \
-d temporaryPassword=true

The API request sets the new password to nextpassword for the existing local user dgreen and prompts them to change their password at the first login.

You can set the attribute temporaryPassword=false to undo this setting; to cancel the forcing of password change on a user.

Local User Password Changes

Local domain users can manage their own passwords, including changing and resetting them as needed. In this scenario, they do not have to rely on administrators.

However, administrators can enforce password policies and restrictions on local user accounts to make sure of the security compliance.

Change Password On-demand

Local users can change their passwords whenever needed using the UI, CLI, or REST API.

Change Password On-demand from the UI

As a local user, to change the password whenever needed, do the following:

Log in to the Couchbase Web Console UI.
Select your username on the top-right corner and select Change Password.
In the Change Password dialog, enter the current password in the Current Password field, and then enter the new password in the New Password field and re-enter it in the Confirm Password field.
Select Save to save the password changes.

Change Password On-demand Using the CLI

Local users can change their passwords using the Couchbase CLI command, user-change-password.

The command is as follows:

/opt/couchbase/bin/couchbase-cli user-change-password --cluster http://10.144.210.101 \
--username <username> \
--password <old-password> \
--new-password <new-password>

Change Password On-demand Using the REST API

Local users can change their passwords using the Couchbase REST API method and URI POST /controller/changePassword as follows:

curl -X POST http://<ip-address-or-domain-name>:8091/controller/changePassword
  -u <username>:<password>
  -d <new-password>

An example command to change the password using the REST API is as follows:

curl -X POST http://localhost:8091/controller/changePassword \
-u localuser:password \
-d password=localpassword

Successful call returns 200 OK and the local user password is changed.

Change Password When Prompted

An administrator can force a password change for a local user.

To change your password when prompted at the login screen, whether you’re a new user or an existing user, do the following:

Open the Couchbase Web Console UI.
Enter your temporary password if you’re a new user or current password if you’re an existing user. You’re redirected to the Provide New Password dialog.
Enter the new password in the New Password field and re-enter it in the Confirm Password field.
Select Change Password to save the new password.

For more information, see Password Changes for Local Users and Force Existing Users to Change Passwords.