Users

class couchbase.management.users.Group(name: str | None = None, description: str | None = None, roles: set[Role] | list[Role] | tuple[Role, ...] | Role | None = None, ldap_group_reference: str | None = None, **kwargs: Any)

A group of users, which gives every user in it the same roles.

Parameters:
  • name (str) – The name of the group.

  • description (str, optional) – What the group is for.

  • roles (SetInputType[Role], optional) – The roles the group gives its users. A set, list or tuple of roles, or a single role.

  • ldap_group_reference (str, optional) – The LDAP group whose members the group takes in.

Raises:

InvalidArgumentException – If name is missing or empty.

property description: str | None

What the group is for.

property ldap_group_reference: str | None

The LDAP group whose members the group takes in.

property name: str

The name of the group.

property raw_data: dict[str, Any] | None

The data the group was created from, if it was given any.

property roles: set[Role]

The roles the group gives its users.

class couchbase.management.users.Origin(type: str | None = None, name: str | None = None)

Why a user has a role.

A type of user means the role is assigned to the user directly. A type of group means the user has it through the group that name names.

property name: str | None

The name of the group the role comes from, when type is group.

property type: str | None

user if the role is assigned to the user directly, group if it comes from a group.

class couchbase.management.users.Role(name: str | None = None, bucket: str | None = None, scope: str | None = None, collection: str | None = None)

A role, optionally limited to a bucket, a scope or a collection.

Parameters:
  • name (str) – The name of the role.

  • bucket (str, optional) – The bucket the role is limited to.

  • scope (str, optional) – The scope the role is limited to, within bucket.

  • collection (str, optional) – The collection the role is limited to, within scope.

Raises:

InvalidArgumentException – If name is missing or empty.

property bucket: str | None

The bucket the role is limited to, or None if it is not limited to one.

property collection: str | None

The collection the role is limited to, or None if it is not limited to one.

property name: str

The name of the role.

property scope: str | None

The scope the role is limited to, or None if it is not limited to one.

class couchbase.management.users.RoleAndDescription(role: Role, display_name: str | None = None, description: str | None = None, ce: bool | None = None)

A role the cluster offers, with its description, as UserManager.get_roles() returns it.

property ce: bool | None

Whether the role is available in Couchbase Server Community Edition.

property description: str | None

What the role allows.

property display_name: str | None

The role’s name as the server displays it.

property role: Role

The role.

class couchbase.management.users.RoleAndOrigins(role: Role, origins: list[Origin])

A role a user has, with every reason the user has it.

property origins: list[Origin]

Every reason the user has the role.

property role: Role

The role.

class couchbase.management.users.User(username: str | None = None, display_name: str | None = None, groups: set[str] | list[str] | tuple[str, ...] | str | None = None, roles: set[Role] | list[Role] | tuple[Role, ...] | Role | None = None, password: str | None = None)

A user, as UserManager.upsert_user() takes it.

Parameters:
  • username (str) – The name the user authenticates with.

  • display_name (str, optional) – The name the server displays for the user.

  • groups (SetInputType[str], optional) – The names of the groups the user is in, as a set, list or tuple, or a single name.

  • roles (SetInputType[Role], optional) – The roles assigned to the user directly. A set, list or tuple of roles, or a single role.

  • password (str, optional) – The password to set for the user.

Raises:

InvalidArgumentException – If username is missing or empty.

property display_name: str | None

The name the server displays for the user.

property groups: set[str]

The names of the groups the user is in.

property password: str

The password to set for the user.

It is write-only.

Raises:

AttributeError – On every read.

property roles: set[Role]

The roles assigned to the user directly, leaving out those it has through a group.

property username: str

The name the user authenticates with.

class couchbase.management.users.UserAndMetadata(domain: AuthDomain, user: User, effective_roles: list[RoleAndOrigins], password_changed: datetime | None = None, external_groups: set[str] | None = None, *, raw_data: dict[str, Any])

A user and what the server derives from it, as UserManager.get_user() returns it.

Besides the user itself, it holds what only the server knows, such as the roles the user has through its groups.

property domain: AuthDomain

Whether the user is local to the cluster or comes from an external directory.

property effective_roles: list[RoleAndOrigins]

Every role the user has, whether assigned directly or through a group.

property external_groups: set[str] | None

The groups in the external directory the user is in.

property password_changed: datetime | None

When the user’s password was last changed, if the server reported it.

property raw_data: dict[str, Any]

The server’s description of the user, as it was received.

property user: User

A copy of the user.

Changing the copy, to pass it to UserManager.upsert_user(), does not change this object.

class couchbase.management.users.UserManager(impl: UserMgmtInterface)

Performs management operations on users, groups and roles.

change_password(new_password: str, options: ChangePasswordOptions | None = None, **kwargs: Unpack[ChangePasswordOptionsKwargs]) → None

Changes the password of the currently authenticated user.

The previous credentials stop being valid, so the SDK must be restarted and a new connection established with the new password.

Parameters:
  • new_password (str) – The new password for the user.

  • options (ChangePasswordOptions) – Optional parameters for this operation.

  • **kwargs – keyword arguments that can be used as optional parameters for this operation.

Raises:

InvalidArgumentException – If the new password is not a valid value or type.

drop_group(group_name: str, options: DropGroupOptions | None = None, **kwargs: Unpack[DropGroupOptionsKwargs]) → None

Drops an existing group.

Parameters:
  • group_name (str) – The name of the group to drop.

  • options (DropGroupOptions) – Optional parameters for this operation.

  • **kwargs – keyword arguments that can be used as optional parameters for this operation.

Raises:

GroupNotFoundException – If the group does not exist.

drop_user(username: str, options: DropUserOptions | None = None, **kwargs: Unpack[DropUserOptionsKwargs]) → None

Drops an existing user.

Parameters:
  • username (str) – The name of the user to drop.

  • options (DropUserOptions) – Optional parameters for this operation.

  • **kwargs – keyword arguments that can be used as optional parameters for this operation.

Raises:

UserNotFoundException – If the user does not exist.

get_all_groups(options: GetAllGroupsOptions | None = None, **kwargs: Unpack[GetAllGroupsOptionsKwargs]) → Iterable[Group]

Returns a list of all existing groups.

Parameters:
  • options (GetAllGroupsOptions) – Optional parameters for this operation.

  • **kwargs – keyword arguments that can be used as optional parameters for this operation.

Returns:

A list of existing groups.

Return type:

Iterable[Group]

get_all_users(options: GetAllUsersOptions | None = None, **kwargs: Unpack[GetAllUsersOptionsKwargs]) → Iterable[UserAndMetadata]

Returns a list of all existing users.

Parameters:
  • options (GetAllUsersOptions) – Optional parameters for this operation.

  • **kwargs – keyword arguments that can be used as optional parameters for this operation.

Returns:

A list of existing users.

Return type:

Iterable[UserAndMetadata]

get_group(group_name: str, options: GetGroupOptions | None = None, **kwargs: Unpack[GetGroupOptionsKwargs]) → Group

Returns a group by it’s name.

Parameters:
  • group_name (str) – The name of the group to retrieve.

  • options (GetGroupOptions) – Optional parameters for this operation.

  • **kwargs – keyword arguments that can be used as optional parameters for this operation.

Returns:

A Group instance.

Return type:

Group

Raises:

GroupNotFoundException – If the group does not exist.

get_roles(options: GetRolesOptions | None = None, **kwargs: Unpack[GetRolesOptionsKwargs]) → Iterable[RoleAndDescription]

Returns a list of roles available on the server.

Parameters:
  • options (GetRolesOptions) – Optional parameters for this operation.

  • **kwargs – keyword arguments that can be used as optional parameters for this operation.

Returns:

A list of roles available on the server.

Return type:

Iterable[RoleAndDescription]

get_user(username: str, options: GetUserOptions | None = None, **kwargs: Unpack[GetUserOptionsKwargs]) → UserAndMetadata

Returns a user by its username.

Parameters:
  • username (str) – The name of the user to retrieve.

  • options (GetUserOptions) – Optional parameters for this operation.

  • **kwargs – keyword arguments that can be used as optional parameters for this operation.

Returns:

The user, with what the server records about it.

Return type:

UserAndMetadata

Raises:

UserNotFoundException – If the user does not exist.

upsert_group(group: Group, options: UpsertGroupOptions | None = None, **kwargs: Unpack[UpsertGroupOptionsKwargs]) → None

Creates a new group or updates an existing group.

Parameters:
  • group (Group) – The group to create or update.

  • options (UpsertGroupOptions) – Optional parameters for this operation.

  • **kwargs – keyword arguments that can be used as optional parameters for this operation.

Raises:

InvalidArgumentException – If the provided group argument contains an invalid value or type.

upsert_user(user: User, options: UpsertUserOptions | None = None, **kwargs: Unpack[UpsertUserOptionsKwargs]) → None

Creates a new user or updates an existing user.

Parameters:
  • user (User) – The user to create or update.

  • options (UpsertUserOptions) – Optional parameters for this operation.

  • **kwargs – keyword arguments that can be used as optional parameters for this operation.

Raises:

InvalidArgumentException – If the provided user argument contains an invalid value or type.