Manage database accounts in the console

Updated at:

When you create accounts for applications, adjust permissions, or clean up accounts that are no longer in use, the ApsaraDB for MongoDB console lets you query, create, and delete accounts, reset passwords, change permissions, and modify descriptions. This topic describes the limits of each operation and how to confirm its result, which helps you avoid failures caused by a mismatched account database, role definition database, or sharded cluster account type.

Limits

  • MongoDB accounts are isolated by database. An account name must be unique within a database, but the same account name can exist in different databases. The database that you specify when you create an account is the authentication database of that account, which defaults to admin. To manage the account later, you must use its actual database.

  • A replica set account uses the normal account type. In a sharded cluster, a ConfigServer account uses the cs account type, and a direct shard account uses the db account type.

  • Do not run write operations while the instance is being changed. If the instance is not in the Running state, a write operation may return OperationDenied.DBInstanceStatus. Account creation, password reset, permission change, description change, and deletion are asynchronous operations. A successful submission only means that the request was accepted. Wait for the instance to return to the Running state and refresh the account list before you confirm the final result.

  • root is a system-reserved account that comes with the instance. You cannot create another account with the same name, and you cannot delete it. You can reset its password and modify its description, but you cannot change its roles as you would for an ordinary account.

    The following table compares the constraints of the other three account types for each operation:

    Account type Role configuration Operation constraints
    Replica set account (normal) Roles are required at creation No account-type-specific constraints
    ConfigServer account (cs) Roles are required at creation You must use the cs account type when you reset the password or modify the description
    Direct shard account (db) Permissions are fixed. Roles cannot be configured at creation or when you change permissions You must use the db account type when you reset the password or modify the description

View accounts

Open the target instance. In the left-side navigation pane, click Accounts. The account list shows details such as Account Name, Database, Account Type, Roles, Description, Account Status, and Actions. To refresh the account list, click Refresh. Note the following when you use the account list:

  • When you manage a target account, use the account name, database, and account type shown in the list. Do not manually change the database.

  • An account status is either available (Available) or unavailable (Unavailable).

  • Account management operations are asynchronous and subject to a caching delay. An account that is being created may not appear in the list until creation completes. An account that is being deleted disappears from the list immediately. Confirm the result of an operation in the refreshed account list.

Create an account

  1. On the Accounts page, click Create Account.

  2. Configure the account information and roles. The following table describes each setting. A replica set account and a sharded cluster cs account must have roles specified. A sharded cluster direct shard account, which uses the db account type, does not support role configuration. For the detailed role limits, see Configure roles.

  3. Submit the creation request. Creation is complete when the target account appears in the list and its status is available.

Setting Description
Account Name (AccountName) Must be 2 to 16 characters in length. It must start with a lowercase letter and end with a lowercase letter or digit. The characters in between can only be lowercase letters, digits, and underscores. The system-reserved name root is not allowed, regardless of case. The name also cannot start with __cloud.
Password (AccountPassword) Must be 8 to 32 characters in length and contain at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters. The allowed special characters are !@#$%^&*()_+-=.
Database (DBName) The authentication database of the account. Default value: admin. A non-empty name must be 1 to 63 characters in length and cannot contain a NUL character, a forward slash, a backslash, a period, a space, a double quotation mark, or a dollar sign. It also cannot be local. The database list of the instance may contain local, but you cannot use it as the database of an account.
Roles (Roles) Specify the role name and the role definition database as a pair for each role. Select a custom role from the role list of the instance. The role definition database must be the database in which the role is actually defined, which is not necessarily the authentication database of the account.
Description (AccountDescription) Optional. Must be 2 to 256 characters in length and start with a letter or a common Chinese character (U+4E00 to U+9FA5). The remaining characters can only be letters, Chinese characters in that range, digits, underscores, periods, and hyphens.

Configure roles

The same role limits apply when you create an account and when you change permissions. The authentication database and the role definition database are different concepts. If an account is created in the order database, use DBName=order to manage the account later. If you grant the account a custom role that is defined in the admin database, for example order_reader, the role definition database of that role remains admin. Do not change it to the authentication database of the account.

Role Role definition database restriction
read, userAdmin, and enableSharding Any database, including admin.
readWrite, dbAdmin, and dbOwner Any database except admin.
readAnyDatabase, readWriteAnyDatabase, userAdminAnyDatabase, dbAdminAnyDatabase, clusterMonitor, backup, and alibabaCloudAdmin Only admin.
Custom role Must be the database in which the role is actually defined. Do not use another database.

Do not grant root, clusterAdmin, hostManager, clusterManager, __system, __queryableBackup, or restore. alibabaCloudAdmin is supported only for instances that run MongoDB 4.4 or later. In a sharded cluster, a direct shard account that uses the db account type has fixed permissions and does not use the role configuration process.

Reset a password

  1. On the Accounts page, find the target account by its account name and database, and then click Reset Password.

  2. Enter a new password that meets the password rules for account creation, and then submit the request.

  3. Wait for the instance to return to the Running state, and then verify the connection with the new password.

    The database of an account must remain the same as the database specified at creation. For example, if the account test01 is created in the order database, a lookup by the default admin database reports that the account does not exist. When you reset the password of a sharded cluster account, you must use the correct cs or db account type. Using normal or an empty value returns InvalidCharacterType.

Change permissions

This operation applies only to accounts that support role changes. In a sharded cluster, a direct shard account that uses the db account type has fixed permissions and cannot be configured with roles.

  1. On the Accounts page, find the target account and click Modify Permissions.

  2. Select a mode and roles. Use the account name and database from the row of the target account. The role definition database must follow the limits in Configure roles.

  3. Submit the request, and then check whether the roles of the target account are updated in the account list.

    The following table describes each mode (ResetType):

Mode Description
update Full replacement. Replaces the current roles with the roles specified in this request. Before you submit the request, verify that the change does not remove permissions that you still need.
grant Add roles. Retains the current roles and adds the roles specified in this request.
revoke Revoke specified roles. A role to be revoked must be a role that the target account currently holds. For accounts other than root, you can revoke a granted alibabaCloudAdmin role.

Modify a description

  1. On the Accounts page, find the target account and click Modify Description.

  2. Enter a description that meets the description rules for account creation, and then submit the request.

  3. Check whether the description of the target account is updated in the account list.

    When you modify the description of a sharded cluster account, use the correct cs or db account type.

Delete an account

  1. On the Accounts page, find the target ordinary account and delete it.

  2. In the confirmation dialog box, verify the account name and database to avoid deleting an account with the same name.

  3. Confirm the deletion. The deletion is complete when the target account disappears from the list.

    You cannot delete the root account. In a sharded cluster, a direct shard account that uses the db account type can be deleted, but you must use the correct account type and database.

FAQ

Why do later operations report that an account created outside the admin database does not exist?

Check the actual database of the account. If the account was created in a database other than admin, you must use the same database that you specified at creation for password resets, permission changes, description changes, and deletions. The system does not search all databases, because doing so could apply an operation to a different account with the same name.

Why does role validation fail when I change permissions?

Check whether the role is one of the roles that cannot be granted. Verify that the role name and the role definition database are specified as a pair, and that the role definition database and the instance version meet the limits. When you revoke a role, also verify that the target account currently holds that role.