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

« Limits Guides »

›

Manage users and access to App Search

edit

Manage users and access to App Search

edit

Users' access to App Search is determined by App Search roles and engine assignments.

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

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

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

App Search roles and engine assignments

edit

Each users' access to App Search is determined by their App Search role and engine assignments.

A role is a named set of permissions that rougly aligns with a job or team function. See App Search roles reference for a listing of all roles. Some roles allow access to all App Search engines, while other roles allow restricting users' access to specific engines.

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

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

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

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

App Search roles reference

edit

Role	Feature access	Engine access
Owner	Owners can do anything. There can be many owners, but there must be at least one owner at any time. Owners can manage other users and their access.	All engines.
Admin	Admins can do anything, except manage account settings. Admins can manage other users and their access.	All engines.
Dev (1)	Devs can manage all aspects of an engine.	Determined by engine assignments.
Editor (1)	Editors can manage search settings.	Determined by engine assignments.
Analyst (1)	Analysts can only view documents, query tester, and analytics.	Determined by engine assignments.

(1) The dev, editor, and analyst roles are not available at all subscription levels. Refer to the subscriptions pages for Elastic Cloud and Elastic Stack. To change your subscription level or start a trial, see Subscriptions and features.

Manage users within App Search

edit

You can manage users within App Search, along with their App Search roles and engine assignments. See App Search roles and engine assignments.

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

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

Create and invite a new Elastic user to App Search

edit

You can create a new Elastic user from within App Search and simultaneously set their App Search role and engine assignments. See App Search roles and engine 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 App 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 Search > Enterprise Search > App 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 App Search role and engine assignments for the new user. See App Search roles and engine assignments.
Save your changes.

App Search will display an invitation URL:

Share the invitation URL with the person who will log in as the new user. App 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 App Search.

Add an existing Elastic user to App Search

edit

If you have existing Elastic users, you can grant them access to App Search by choosing a role and engine assignments for each user. See App Search roles and engine 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 App Search role mappings.

Manage created and added users:

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

The added user:

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

edit

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

Manage created and added users:

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

Users UI:

Manage App Search role mappings

edit

While you can manage users directly within App 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 App Search, use App Search role mappings. These map users, based on their attributes, to App Search roles and engine assignments. See App Search roles and engine assignments.

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

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

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

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

App Search role mappings

edit

An App Search role mapping maps an external user attribute value to an App Search role and engine 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 App Search role that will be granted to users who match the role mapping. See App Search roles and engine assignments.

Engine assignments

A list of engine names to grant access to. See App Search roles and engine assignments.

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

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

Evaluating mappings:

Each time a user makes a request to App Search, the App Search role mappings are evaluated. If the user matches a role mapping, based on their external user attributes, the user is granted the App Search role and engine 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 App Search role mappings: default and custom.

Default App Search role mappings

edit

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

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

Some App 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 App Search.
When RBAC is enabled, the default mappings are restrictive, allowing access to only those users with specific Elastic Stack roles.

Default App Search role mappings reference:

Elastic Stack role	App Search role	App Search engines	Active when
`superuser`	`owner`	All	Always active
`enterprise-search-app-search-admin`	`admin`	All	RBAC enabled
`enterprise-search-app-search-developer`	`developer`	All	RBAC enabled
`enterprise-search-app-search-editor`	`editor` (1)	All	RBAC enabled
`enterprise-search-app-search-analyst`	`analyst` (1)	All	RBAC enabled
`*` (2)	`owner`	All	RBAC disabled
`editor`	`editor` (1)	All	RBAC disabled
`viewer`	`analyst` (1)	All	RBAC disabled

(1) The editor and analyst App Search roles are not available at all Elastic subscription levels. If these roles are not available to your deployment, App Search will instead map to the owner role.

(2) * 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 App Search mappings to manage access to App Search, you don’t manage App Search mappings directly. Instead, you manage Elastic Stack roles. These roles are then mapped to App Search roles and engine assignments automatically.

Manage Elastic Stack roles outside of App 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 App Search role mappings

edit

Custom App Search role mappings map users to App Search roles and engines 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 App Search. Do not confuse external user attributes with App Search roles.

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

Create a custom App Search role mapping

edit

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

Create a custom role mapping:

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

The new role mapping:

List, modify, and remove custom App 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 Search > Enterprise Search > App 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 engine assignments, or remove the role mapping.

Role mappings UI:

The following sections have moved:

Default App Search mappings for Elastic Stack roles has moved to Default App 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.

« Limits Guides »