IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Administration and management Create and manage groups »

› ›

Manage users and access to Workplace Search

edit

Manage users and access to Workplace Search

edit

Users' access to Workplace Search is determined by Workplace Search roles and group assignments.

You can manage users within Workplace Search, along with their Workplace Search roles and group assignments. Using this strategy, you can create and invite new Elastic users to Workplace Search or add existing Elastic users.

Alternatively, you can manage Workplace Search role mappings, which map user attributes to Workplace Search roles and group assignments. Using this strategy, you can rely on the default Workplace Search role mappings or define your own custom Workplace Search role mappings.

You can use one strategy exclusively, or both. Review the following sections to see which is right for your deployment:

Workplace Search roles and group assignments

edit

Each users' access to Workplace Search is determined by their Workplace Search role and group assignments.

A role is a named set of permissions that rougly aligns with a job or team function. See Workplace Search roles reference for a listing of all roles.

To restrict a user’s access to specific groups, use group assignments. These act as an allow list that determines which groups a particular user can access. The special value All allows access to all current and future groups.

Workplace Search roles and group assignments are data specific to Workplace Search. Do not confuse Workplace Search roles with Elastic Stack roles or a role managed within an external identify provider service.

You can manage users' roles and group assignments in two ways:

Manage users within Workplace Search, along with their Workplace Search roles and group assignments. See Manage users within Workplace Search.
Manage Workplace Search role mappings, which map user attributes to Workplace Search roles and group assignments. See Manage Workplace Search role mappings.

Workplace Search roles reference

edit

Role	Feature access
Admin	Admins have complete access to all organization-wide settings, including content source, group and user management functionality.
User	Users' feature access is limited to search interfaces and personal settings management.

Manage users within Workplace Search

edit

You can manage users within Workplace Search, along with their Workplace Search roles and group assignments. See Workplace Search roles and group assignments.

Using this strategy, you can create and invite new Elastic users to Workplace Search or add existing Elastic users to Workplace Search by choose a role and groups for each user. After creating and adding users, you can list, modify, and remove those users from Workplace Search.

You can use this strategy exclusively, or combine it with Workplace Search role mappings. See Manage Workplace Search role mappings.

Create and invite a new Elastic user to Workplace Search

edit

You can create a new Elastic user from within Workplace Search and simultaneously set their Workplace Search role and group assignments. See Workplace Search roles and group assignments.

This process creates an invitation that a person must accept to set the password for the new user.

To use this feature, you must have Enterprise Search role-based access control (RBAC) enabled. You can enable RBAC from either Workplace Search or Workplace Search, but once enabled, the setting applies to both products. See Enterprise Search role-based access control (RBAC) in the Enterprise Search documentation.

Create a new user:

Navigate to Enterprise Search > Workplace Search > Users and roles.
Choose Add a new user.
Choose Create a new user.
Enter a username for the new user. This cannot be changed later.
Enter an email for the new user.
Choose an Workplace Search role and group assignments for the new user. See Workplace Search roles and group assignments.
Save your changes.

Workplace Search will display an invitation URL:

Share the invitation URL with the person who will log in as the new user. Workplace Search will automatically send the invitation by email if an email service is configured for your deployment. To configure an email service, see Configure a mail service in the Enterprise Search documentation.

Until the invitation is accepted, you will see Invitation pending within the management UI:

By visiting the invitation URL, the owner of the account can set the password for the user and log in to Workplace Search.

Add an existing Elastic user to Workplace Search

edit

If you have existing Elastic users, you can grant them access to Workplace Search by choosing a role and group assignments for each user. See Workplace Search roles and group assignments.

There are many ways to manage users for your Elastic deployment. From this interface, you can add users managed through the Elastic Stack. You cannot add users managed through external IdPs or Elastic Cloud, and you cannot add default users.

Refer to the following sections in the Enterprise Search documentation:

To manage access for users from these other sources, use Workplace Search role mappings.

Manage created and added users:

Navigate to Enterprise Search > Workplace Search > Users and roles.
Choose Add a new user.
Choose Add existing user.
Choose a username. The username identifies the user.
Choose an Workplace Search role and group assignments for the new user. See Workplace Search roles and group assignments.
Save your changes.

The added user:

List, modify, and remove users' access to Workplace Search

edit

After creating users or adding users, you can list, modify, and remove those same users from within Workplace Search.

Manage created and added users:

Navigate to Enterprise Search > Workplace Search > Users and roles.
Locate the Users section.
Use the controls within each user row to modify the user’s role or group assignments or remove the user from Workplace Search.

Users UI:

Manage Workplace Search role mappings

edit

While you can manage users directly within Workplace Search, you may choose to manage users through other interfaces. Other options include the Elastic Stack user management interfaces, Elastic Cloud, and external identity providers (IdPs). See Manage users for your Elastic deployment in the Enterprise Search documentation.

To manage these users' access to Workplace Search, use Workplace Search role mappings. These map users, based on their attributes, to Workplace Search roles and group assignments. See Workplace Search roles and group assignments.

Using this strategy, you can rely on the default Workplace Search role mappings or define your own custom Workplace Search role mappings.

Default Workplace Search role mappings map Elastic Stack roles to Workplace Search roles and group assignments. When using Workplace Search’s default mappings, you manage access to Workplace Search indirectly, by managing Elastic Stack roles.

With custom mappings, you manage access to Workplace Search directly, by mapping your choice of user attributes to Workplace Search roles and groups.

You can use this strategy exclusively, or combine it with direct user management within Workplace Search. See Manage users within Workplace Search.

Workplace Search role mappings

edit

An Workplace Search role mapping maps an external user attribute value to an Workplace Search role and group assignments.

Components of a mapping:

External attribute

The name of the user attribute that will be checked for a match when the role mapping is evaluated. The possible values vary by identity provider. Choose one of the enumerated values.

Attribute value

A pattern that will be compared to the external attribute value when the role mapping is evaluated. Enter a text string composed of literal text characters and the meta character *, which matches zero or more characters.

Role

The Workplace Search role that will be granted to users who match the role mapping. See Workplace Search roles and group assignments.

Group assignments

A list of group names to grant access to. See Workplace Search roles and group assignments.

All users who match the role mapping will have access to these groups. The level of access is determined by their Workplace Search role.

Choose one or more of the enumerated values, or choose the special value All to grant access to all current and future groups.

Evaluating mappings:

Each time a user makes a request to Workplace Search, the Workplace Search role mappings are evaluated. If the user matches a role mapping, based on their external user attributes, the user is granted the Workplace Search role and group assignments from the role mapping.

When a user matches multiple mappings, the most permissive mapping applies.

When using the standalone Enterprise Search management interface, role mappings are evaluated each time a user logs in rather than each time a user makes a request.

Types of mappings:

There are two types of Workplace Search role mappings: default and custom.

Default Workplace Search role mappings

edit

Default Workplace Search role mappings map users to Workplace Search roles and groups according to their Elastic Stack roles. All users with the given Elastic Stack role match the mapping and receive the Workplace Search role and groups specified in the mapping.

Therefore, to manage access using default role mappings, you manage users' Elastic Stack roles. See Manage Elastic Stack roles.

Some Workplace Search mappings are always active, while others are active only when Enterprise Search role-based access control (RBAC) is enabled or disabled. See Enterprise Search role-based access control (RBAC) in the Enterprise Search documentation.

When RBAC is disabled (default), the default mappings are permissive, allowing most users full access to Workplace Search.
When RBAC is enabled, the default mappings are restrictive, allowing access to only those users with specific Elastic Stack roles.

Default Workplace Search role mappings reference:

Elastic Stack role	Workplace Search role	Workplace Search groups	Active when
`superuser`	`admin`	Default	Always active
`enterprise-search-workplace-search-admin`	`admin`	Default	RBAC enabled
`enterprise-search-workplace-search-user`	`user`	Default	RBAC enabled
`*` (1)	`admin`	Default	RBAC disabled
`editor`	`admin`	Default	RBAC disabled
`viewer`	`user`	Default	RBAC disabled

(1) * matches all built-in Elastic Stack roles and user-defined Elastic Stack roles not otherwise shown.

Manage Elastic Stack roles

edit

If you are using default Workplace Search mappings to manage access to Workplace Search, you don’t manage Workplace Search mappings directly. Instead, you manage Elastic Stack roles. These roles are then mapped to Workplace Search roles and group assignments automatically.

Manage Elastic Stack roles outside of Workplace Search, through any of the user management interfaces provided by the Elastic Stack. See Manage users using the Elastic Stack within the Enterprise Search documentation.

Custom Workplace Search role mappings

edit

Custom Workplace Search role mappings map users to Workplace Search roles and groups based on any external user attribute of your choice. External user attributes vary by identity provider, and may include username, email, role, and group.

Remember, you manage user attributes separately from a user’s access to Workplace Search. Do not confuse external user attributes with Workplace Search roles.

See the following sections to manage custom Workplace Search role mappings:

Create a custom Workplace Search role mapping

edit

Create a custom Workplace Search role mapping to map any user attribute value to an Workplace Search role and group assignments.

Create a custom role mapping:

Navigate to Enterprise Search > Workplace Search > Users and roles.
Choose Create a new role mapping.
Choose an external attribute. See Workplace Search role mappings.
Enter an attribute value pattern. See Workplace Search role mappings.
Choose an Workplace Search role and group assignments for the new user. See Workplace Search roles and group assignments.
Save your changes.

The new role mapping:

List, modify, and remove custom Workplace Search role mappings

edit

After creating custom role mappings, you can modify and remove them from the same user interface.

Manage custom role mappings:

Navigate to Enterprise Search > Workplace Search > Users and roles.
Locate the Role mappings section.
Use the controls within each role mapping row to modify the external attribute, attribute value, role or group assignments, or remove the role mapping.

Role mappings UI:

The following sections have moved:

Default Workplace Search mappings for Elastic Stack roles has moved to Default Workplace Search role mappings.

Standard auth mode was removed in Enterprise Search 7.14.0.
See Manage users for your Elastic deployment and Upgrade from Enterprise Search 7.13 and earlier in the Enterprise Search documentation.

Native auth mode was deprecated in Enterprise Search 7.14.0.
See Manage users for your Elastic deployment and Upgrade from Enterprise Search 7.13 and earlier in the Enterprise Search documentation.

SAML auth mode was deprecated in Enterprise Search 7.14.0.
See Manage users for your Elastic deployment and Upgrade from Enterprise Search 7.13 and earlier in the Enterprise Search documentation.

« Administration and management Create and manage groups »