Manage users and access to Enterprise Search

edit

Manage users and access to Enterprise Search

edit

To quickly get started managing users and access to App Search or Workplace Search, see the following guides within the product-specific documentation:

You can manage users and their access to Enteprise Search entirely within App Search and Workplace Search. Or you can manage access to Enterprise Search separately from where you manage your users.

When managing access, you separately manage access to App Search, Workplace Search, and Enterprise Search management APIs. However, App Search and Workplace Search are both affected by an Enterprise Search setting called role-based access control (RBAC). You can also reset access to Enterprise Search.

When managing users, you manage them within App Search, Workplace Search, the Elastic Stack, or external identity providers. In addition to managed users, you can access Enterprise Search using several default users. You can recover users if you lose access, but the process varies by type of user or deployment.

Since 7.14.0, Enterprise Search shares users with the Elastic Stack and will automatically migrate standard users when upgrading from earlier versions.

Use the following sections to learn more about these topics:

Manage users' access to Enterprise Search

edit

Users of your Elastic deployment may need access to App Search, Workplace Search, and the Enterprise Search management APIs. You grant access to each of these interfaces separately.

Manage users' access to App Search

edit

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

You can manage users and their access together within App Search. Or you can manage users outside of App Search and control access through App Search role mappings. App Search provides default mappings, and you can define your own custom mappings.

See Manage users and access to App Search in the App Search documentation.

Manage users' access to Workplace Search

edit

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

You can manage users and their access together within Workplace Search. Or you can manage users outside of Workplace Search and control access through Workplace Search role mappings. Workplace Search provides default mappings, and you can define your own custom mappings.

See Manage users and access to Workplace Search in the Workplace Search documentation.

Manage users' access to Enterprise Search management APIs

edit

Enterprise Search has management APIs for health, status, and other functions useful to operators.

You manage access to these APIs differently than access to App Search or Workplace Search. Refer to the API reference for each API operation.

See Management APIs.

Enterprise Search role-based access control (RBAC)

edit

Access to App Search and Workplace Search is affected by an Enterprise Search setting called role-based access control (RBAC).

When Enterprise Search RBAC is disabled, most users of your deployment have full access to App Search and Workplace Search. This is the default setting for new deployments.

To restrict users' access, you must enable RBAC. You can enable RBAC from either App Search or Workplace Search, but once enabled, the setting applies to both products.

To enable and disable Enterprise Search RBAC, see the following sections:

Enabling RBAC changes the default mappings for both App Search and Workplace Search. The default mappings change from permissive to restrictive. For details, see the following sections in the product-specific documentation:

To use custom mappings within App Search or Workplace Search, you must enable RBAC. Activating RBAC from either product enables custom mappings for both products. For details, see the following sections in the product-specific documentation:

Enable Enterprise Search RBAC

edit

You can enable RBAC from either App Search or Workplace Search, but once enabled, the setting applies to both products.

  1. Open the management interface for App Search or Workplace Search.
  2. Select Users and roles.
  3. Select Enable role-based access.

If this button is not present, RBAC is already enabled.

Enable RBAC in App Search:

enable rbac app search

Enable RBAC in Workplace Search:

enable rbac workplace search

Disable Enterprise Search RBAC

edit

There are two ways to disable Enterprise Search RBAC:

Reset access to Enterprise Search

edit

You can reset access to Enterprise Search.

This is a destructive process. Carefully review the following effects before performing this action.

Resetting access to Enterprise Search performs the following operations:

Reset access to Enterprise Search using the command line interface:

bin/enterprise-search --reset-auth

Manage users for your Elastic deployment

edit

You can manage users for your Elastic deployment within App Search or Workplace Search, or within a variety of other interfaces.

The application or service that provides the user management interface is called an identity provider. You can use your Elastic deployment or Elastic Cloud as identity providers, and you can set up any number of external identity providers.

A user or user account is composed of an identifier and other attributes. These may include username, email, role, and any number of other attributes defined by the identity provider.

Each user management interface permits different management operations, such as listing, creating, inviting, modifying, and deleting users and their attributes.

Manage users for your Elastic deployment within any of the following interfaces:

Manage users using App Search

edit

You can create, invite, list, and modify users directly within App Search. Within App Search, you create users and give them access to App Search at the same time.

See Manage users within App Search in the App Search documentation.

To manage users within App Search, you must enable Enterprise Search role-based access control (RBAC). Enabling this setting also affects the default mappings for App Search and Workplace Search. See Enterprise Search role-based access control (RBAC).

The users you create within App Search are native Elastic users and can be granted access to Elastic features outside of App Search. See Native user authentication in the Elasticsearch documentation.

Manage users using Workplace Search

edit

You can create, invite, list, and modify users directly within Workplace Search. Within Workplace Search, you create users and give them access to Workplace Search at the same time.

See Manage users within Wrokplace Search in the Workplace Search documentation.

To manage users within Workplace Search, you must enable Enterprise Search role-based access control (RBAC). Enabling this setting also affects the default mappings for Workplace Search and Workplace Search. See Enterprise Search role-based access control (RBAC).

The users you create within Workplace Search are native Elastic users and can be granted access to Elastic features outside of Workplace Search. See Native user authentication in the Elasticsearch documentation.

Manage users using the Elastic Stack

edit

You may want to manage users outside of App Search and Workplace Search, particularly if you want to permit broad access to Elastic features. This may include access to other Elastic solutions, apps, and features.

Elasticsearch and Kibana provide UI, API, CLI, and file interfaces to manage users for your Elastic deployment. To manage users within these interfaces, refer to the following information in the Elasticsearch documentation:

To give these users access to App Search and Enterprise Search, you must map their Elastic Stack roles or other user attributes to App Search or Workplace Search roles. See the following guides in the App Search and Workplace Search documentation:

Manage users using external identity provider services (IdPs)

edit

You may want to manage users within an external identify provider, particularly if you want to re-use the same users across Elastic deployments or other web applications.

You can configure your Elastic deployment to use any SAML 2.0 Identity Provider service (IdP). The following are examples of these services:

For each SAML identity provider you’d like to use, you must complete a one-time setup process. Refer to the following documentation:

After completing the one-time setup, manage these users within the interfaces provided by the IdP.

To give these users access to App Search and Enterprise Search, you must map their Elastic Stack roles or other user attributes to App Search or Workplace Search roles. See the following guides in the App Search and Workplace Search documentation:

Manage users using Elastic Cloud

edit

Elastic Cloud is a SAML 2.0 IdP managed by Elastic. However, presently, you can have only one Elastic Cloud user per deployment.

See Elastic Cloud user.

In future releases, you will be able to grant access to multiple Elastic Cloud users on each deployment.

Default users

edit

In addition to managing your own users, you can access Enterprise Search using several default users that are created for you.

Elastic Cloud user

edit

The Elastic Cloud user is the user who created your Elastic deployment through the Elastic Cloud service.

This user has the Elastic Stack superuser role and therefore has full access to Enterprise Search. See superuser in the Elasticsearch documentation.

To recover this user, see Recover the Elastic Cloud user.

elastic user

edit

The elastic user is one of the built-in users for the Elastic Stack. See Built-in users in the Elasticsearch documentation.

This user has the Elastic Stack superuser role and therefore has full access to Enterprise Search. See superuser in the Elasticsearch documentation.

To recover this user, see Recover the elastic user.

enterprise_search user

edit

The enterprise_search user is created when Enterprise Search starts for the first time.

This user is a native Elastic Stack user that you can manage like any other native user. For example, you can delete this user if you prefer to use one of the other default users. See Native user authentication in the Elasticsearch documentation.

The enterprise_search user has the Elastic Stack roles enterprise-search-app-search-owner and enterprise-search-workplace-search-admin. The user therefore has full access to Enterprise Search due to the default role mappings in each product.

The first time Enterprise Search starts, it generates and prints to the screen a random password for this user. Alternatively, you can set the environment variable ENT_SEARCH_DEFAULT_PASSWORD to set an explicit password for this user. You must do this the first time you start Enterprise Search.

For example, to set the password to u7f#o#FY&l4vv?-M^86+8GY?, start Enterprise Search for the first time with this command:

ENT_SEARCH_DEFAULT_PASSWORD='u7f#o#FY&l4vv?-M^86+8GY?' bin/enterprise-search

To recover this user, see Recover the enterprise_search user.

Recover users for your Elastic deployment

edit

If you or another user of your deployment can no longer log in, you can recover that user. Refer to the appropriate section:

Recover your own user account

edit

To recover your own user account, use the help text and links provided with the login form. You may need to contact an administrator or operator for your deployment.

Recover users as a superuser

edit

As a superuser, you can change the passwords of other users.

Within Kibana, choose Stack Management, then Users. Select a user to change their password.

You can also use the change passwords API endpoint. See Change passwords API in the Elasticsearch documentation.

You must access this API as a superuser or other user with the necessary privileges.

If necessary, create a new superuser using the file-based user realm. See File-based user authentication in the Elasticsearch documentation.

Recover the Elastic Cloud user

edit

As the Elastic Cloud user, you can recover your own user account. Use the help text and links provided with the Elastic Cloud login form.

Recover the elastic user

edit

The process to recover the elastic user varies by deployment type.

For Elastic Cloud deployments, see Reset the elastic user password in the Elastic Cloud documentation.

For self-managed deployments, recover the user as a superuser.

Recover the enterprise_search user

edit

The process to recover the enterprise_search user varies by deployment type.

For production deployments, recover the user as a superuser.

Within local development environments, you can also reset access to Enterprise Search. See Reset access to Enterprise Search.

Configure users and access

edit

Operators can configure some aspects of user and access management for Enterprise Search:

Set up a SAML 2.0 identity provider service (SAML IdP) for Enterprise Search

edit

You can manage Enterprise Search users using external identity provider services (IdPs), as long as they implement the SAML 2.0 standard for authentication.

For each SAML identity provider you’d like to use, you must complete a one-time setup process. To complete this process, see Set up Enterprise Search with SAML.

Set a preferred authentication provider for Enterprise Search in Kibana

edit

When using Kibana as your primary management interface for Enterprise Search, Enterprise Search redirects users to Kibana to log in. See User interfaces for an explanation of management interfaces for Enterprise Search.

Enterprise Search considers Kibana to be the primary management interface when the following configuration is present in enterprise-search.yml:

  • kibana.external_url is set.
  • No settings matching ent_search.auth.* are set.

Kibana may be configured with multiple authentication providers. In this case, you can set a preferred provider for Enterprise Search within the Enterprise Search configuration. Kibana will then prefer this provider when redirecting users to Kibana. Kibana will present the preferred login option rather than ask users to choose from all available providers when logging in.

Configure the preferred provider within enterprise-search.yml by setting kibana.preferred_auth_provider to the name of the authentication provider of your choice from your Kibana configuration.

For example, given the following kibana.yml:

xpack.security.authc.providers:
  basic.basic1:
    order: 0
    icon: "logoElasticsearch"
    hint: "Typically for administrators"
  saml.saml1:
    order: 1
    realm: saml1
    description: "Log in with SSO"
    icon: "https://my-company.xyz/saml-logo.svg"

Set the preferred auth provider to saml1 within enterprise-search.yml:

kibana.preferred_auth_provider: saml1

Upgrade from Enterprise Search 7.13 and earlier

edit

When upgrading from Enterprise Search 7.13 and earlier, do not change any user/auth configuration settings before upgrading to 7.14.0 or later.

Prior to 7.14.0, Enterprise Search had three auth modes: standard, native, and SAML. Auth modes are deprecated in Enterprise Search 7.14.0 and will be removed in 8.0.0.

Since 7.14.0, users created by Enterprise Search are native Elastic Stack users, and those users can be granted access to Elastic features outside of Enterprise Search.

Enterprise Search will use your current configuration to migrate your existing user data. When you upgrade from 7.13.0 and earlier, Enterprise Search performs the following operations:

If the currently configured auth mode is standard (or blank):

  • Migrate standard Enterprise Search users to native Elastic Stack users.
  • For each migrated user, create a role mapping, based on username, to map the user to the same roles and groups or engines they could previously access.
  • Delete all users that were created specifically for Enterprise Search native authentication.
  • Delete Workplace Search private content sources belonging to the deleted users.

For example, if the following list represents your users before upgrading:

  • shay.banon (standard)
  • steven.schuurman (standard)
  • shay.banon (native)
  • uri.boness (native)

Then the following represents your users after upgrading:

  • shay.banon (native, migrated from standard)
  • steven.schuurman (native, migrated from standard)
  • shay.banon (deleted native user)
  • uri.boness (deleted native user)

If the currently configured auth mode is any other value (not standard):

  • Delete all users that were created specifically for Enterprise Search standard authentication.
  • Delete Workplace Search private content sources belonging to the deleted users.

For example, if the following list represents your users before upgrading:

  • shay.banon (standard)
  • steven.schuurman (standard)
  • shay.banon (native)
  • uri.boness (native)

Then the following represents your users after upgrading:

  • shay.banon (deleted standard user)
  • steven.schuurman (deleted standard user)
  • shay.banon (native, unchanged)
  • uri.boness (native, unchanged)

After upgrading, review the other sections in this document to determine how you’d like to manage users and access, since new options are available.