--- title: Usernames and Passwords description: Couchbase Server requires that administrators and applications authenticate, in order to gain access to data, settings, and statistics. pubDate: 2026-08-17T09:53:44.266Z antora: editUrl: https://github.com/couchbase/docs-server/edit/release/8.0/modules/learn/pages/security/usernames-and-passwords.adoc xref: xref:server:learn:security/usernames-and-passwords.adoc[] --- [Consult the llms.txt file for a full list of contents](/llms.txt) [View original HTML](/server/current/learn/security/usernames-and-passwords.html) # Usernames and Passwords > Couchbase Server requires that administrators and applications _authenticate_, in order to gain access to data, settings, and statistics. Authentication may require that a _username_ and _password_ be provided. ## [](#introduction-to-usernames-and-passwords)Introduction to Usernames and Passwords _Users_ of Couchbase Server frequently require a username and password. A user may be either an _administrator_ or an _application_. An application may be a program or server, or may be a simple, single command-line query. The _Full Administrator_ who installs and configures Couchbase Server (and so has full read-write access to the whole system), defines their own username and password during the configuration-process: see [Create a Cluster](../../manage/manage-nodes/create-cluster.md), for details. Subsequently, this administrator can add additional administrators to the system; assigning a username and password to each. Whenever any needs to log into Couchbase Web Console in order to inspect data, statistics, and settings (and possibly make changes), they must specify their own unique username-password combination, at the authentication-prompt provided by the server. An application, if it is not using a client certificate for purposes of authentication, must pass its username and password as parameters. Therefore, Couchbase CLI commands, SQL++ queries, and executables supported by the Couchbase SDK all provide syntax to allow the passing of a username and password. Additionally, a special _master password_ may be designed and used by the Full Administrator, in order to manage system secrets. See [Manage System Secrets](../../manage/manage-security/manage-system-secrets.md), for details. Note that a cluster running Couchbase Server _Enterprise Edition_ can have any number of users. A cluster running _Community Edition_ can have a maximum of twenty users. The _Full Administrator_ username and password are established during initialization of Couchbase Server: see [Create a Cluster](../../manage/manage-nodes/create-cluster.md) for details. Subsequently, additional users can be added to the cluster as _local_ users: each is at that time assigned a unique _username_, and a unique _password_. Passwords can be changed by means of the password-reset tool, [reset-admin-password](../../cli/cbcli/couchbase-cli-reset-admin-password.md); or by Couchbase Web Console, as described in [Editing Users and Groups](../../manage/manage-security/manage-users-and-roles.md#editing-users-and-groups). A local user can change their own password by means of the REST API: see [Change Password](../../rest-api/rest-set-password.md). Users can also be added to the cluster as _external_ users, for whom no password need be specified; since the external user is to be authenticated externally. ### [](#authentication-with-optimal-security)Authentication for Administrators and Applications In a modern environment, authenticating by means of username and password, by either an administrator or an application, is less than optimally secure. Therefore, the best practice for administrator-authentication is to use _single sign-on_, with a provider that is configured to require _Multi-Factor Authentication_ (MFA). The best practice for application-authentication is to use x.509 _certificate-based_ authentication. For details on authenticating with optimal security, see [Understanding Authentication](authentication-overview.md). ## [](#password-strengthd)Password Strength Couchbase Server provides a default password-policy. This demands only that the password have a minimum of six characters. For pre-production purposes, it may be desirable to strengthen this default password-policy. For production purposes, it should be considered essential to do so. The password-policy can be set by the Full Administrator, by means either of the Couchbase CLI command [setting-password-policy](../../cli/cbcli/couchbase-cli-setting-password-policy.md), or of the REST API — as described in [Setting Password Policy](../../rest-api/rest-set-password-policy.md). This allows you to specify that every Couchbase Server-password should: * Contain a minimum-number of characters. If established with the CLI, this can be any number between 1 and 100\. If established with the REST API, this can be any number between 0 and 100\. (Note that if 0 is selected, the definition of password-free users is thereby enabled: this is highly insecure, and is _not_ recommended.) * Contain at least one uppercase character. * Contain at least one lowercase character. * Contain at least one special character. * Contain at least one digit. It is recommended that passwords be managed with a password manager, and that each password be designed as one of the following: * A password of at least 12 characters that includes letters, numbers, and special characters. * A unique passphrase of at least 15 characters, with individual words separated from one another by means of one or more special characters. ## [](#usernames-and-roles)Usernames and Roles Couchbase Server-users can typically authenticate by means of a _username_, specified with a password. The restrictions on username-design are that each should be unique to the cluster; and that none of the following characters be used: `( ) < > , ; : \ " / [ ] ? = { }`. Note additionally that the `@` character cannot be used in a username on any Couchbase Server version before 6.5.1\. On versions 6.5.1 and beyond, a username may contain the `@` character, as long as it does not occur at the start: for example, `first.last@domain`. Usernames _cannot_ be more than 128 UTF-8 characters in length; and it is recommended that they be no more than 64 UTF-8 characters in length, in order to ensure successful onscreen display. Each user is associated with one or more _roles_, which permit limited access-privileges. Therefore, once a user has authenticated, their role-assignment is examined, and an appropriate degree of access is granted to them by Couchbase Server. See [Authorization](authorization-overview.md), for details. Note that usernames and role-names are _case sensitive_. ## [](#changing-passwords)Changing Passwords Administrators can configure and enforce security policies to make sure that users maintain secure and up-to-date passwords. Couchbase Server supports temporary passwords. These controls help prevent unauthorized access and reduce the risk of weak or repeated passwords. All local users can change their passwords through the UI, REST API, or CLI. When local users authenticate with the UI, the system prompts them to change their password at their next login. The CLI provides the `couchbase-cli user-change-password` command, and the REST API supports password updates through the `/controller/changePassword` endpoint. For more information, see [Manage Passwords](../../manage/manage-security/manage-passwords.md). Even users whose accounts do not have privileges to use the Couchbase Web Console can sign in using the UI login page to change their password. The users managed by external systems, such as LDAP or SAML, must use the tools provided by their external authentication provider to update their passwords. ### [](#force-password-change)Force Password Change Administrators can enforce a password change on the user's next login. This option is useful when issuing a temporary password or resetting a compromised account. Enforcing password change results in the following: * The user is prompted to set a new password before accessing the Couchbase Server. The user can set a new password using the UI or the REST API. * When authenticating from the UI, users are prompted to set a new password and cannot access any features until they have updated their password. This feature ensures that only the user knows their active password and that temporary or shared credentials cannot be reused indefinitely. For more information, see [Force Password Update](../../manage/manage-security/manage-passwords.md#force-password-update).