search mobile facets autocomplete spellcheck crawler rankings weights synonyms analytics engage api customize documentation install setup technology content domains user history info home business cart chart contact email activate analyticsalt analytics autocomplete cart contact content crawling custom documentation domains email engage faceted history info install mobile person querybuilder search setup spellcheck synonyms weights engage_search_term engage_related_content engage_next_results engage_personalized_results engage_recent_results success add arrow-down arrow-left arrow-right arrow-up caret-down caret-left caret-right caret-up check close content conversions-small conversions details edit grid help small-info error live magento minus move photo pin plus preview refresh search settings small-home stat subtract text trash unpin wordpress x alert case_deflection advanced-permissions keyword-detection predictive-ai sso

Security and User Management

"How do I setup and manage self managed Enterprise Search security, users, and access roles?"

Enterprise Search and Elasticsearch security is a requirement.

Luckily, Enterprise Search offers three robust security modes that can tie into Elasticsearch's identity management features.

Choose from one of three security modes to securely manage access to Enterprise Search:

  1. Standard: The default method: Users are managed by Enterprise Search. Use this to keep user management coupled to Enterprise Search. Users are invited and administrated by an Enterprise Search account owner.
  2. Elasticsearch Native Realm: Users are managed by the Elasticsearch native realm. If your Elasticsearch cluster is already managing users and their roles, then you can prevent duplication of effort. Whether you're using Kibana or automating user creation via Elasticsearch APIs, you can set Enterprise Search to inherit that configuration and then use Role Mapping to tie those existing roles to Enterprise Search users and their own permissions.
  3. Elasticsearch SAML: Allow a third-party authentication provider like Auth0 or Okta to manage users within Elasticsearch. Inherits SAML settings from Elasticsearch. Role Mapping associates third-party governed roles with Enterprise Search users and their own permissions.

Standard

Standard security requires configuration of both Elasticsearch and Enterprise Search.

It is the default security method when Elasticsearch security is enabled.

Within Elasticsearch

Within the Elasticsearch directory, open up the config/elasticsearch.yml file and add:

xpack.security.enabled: true

Next, you'll need to setup a password so that Enterprise Search can reach Elasticsearch.

Elasticsearch comes with a password setup utility.

It takes two different options:

  1. auto to have Elasticsearch generate passwords.
  2. interactive to manually set your own secure passwords.

Either mode will result in a set of passwords for Elasticsearch users.

You'll need the password for the elastic user -- it's the default user.

bin/elasticsearch-setup-passwords auto

The output will look like so:

Changed password for user apm_system
PASSWORD apm_system = xxxxxxxxxxxxxx

Changed password for user kibana
PASSWORD kibana = xxxxxxxxxxxxxx

Changed password for user logstash_system
PASSWORD logstash_system = xxxxxxxxxxxxxx

Changed password for user beats_system
PASSWORD beats_system = xxxxxxxxxxxxxx

Changed password for user remote_monitoring_user
PASSWORD remote_monitoring_user = xxxxxxxxxxxxxx

Changed password for user elastic <<<
PASSWORD elastic = [ELASTIC_PW]

Retrieve and store the elastic user credential using care and best practices!

To recap, we:

  1. Enabled security settings within Elasticsearch.
  2. Generated and securely stored credentials.

The rest happens within Enterprise Search's configuration files.

Within Enterprise Search

Within Enterprise Search directory, edit config/enterprise-search.yml and add your credentials:

ent_search.auth.source: standard
elasticsearch.username: elastic
elasticsearch.password: [ELASTIC_PW]

That's it!

Now user settings are managed by Enterprise Search.

The default user is: elastic

The default password is generated for you upon start-up. Look into your console log to retrieve it.

You can also pass in your own default password via an environment variable on first start-up:

ENT_SEARCH_DEFAULT_PASSWORD=password bin/enterprise-search

Follow the Role Based Access Control guide for more information on how roles work.

Elasticsearch Native Realm

Elasticsearch can manage users through the Elasticsearch native realm.

Enterprise Search can use the Elasticsearch native realm as its source of truth for identity management.

Within Elasticsearch

Within the Elasticsearch directory, open config/elasticsearch.yml and add if it is not present:

xpack.security.enabled: true
xpack:
  security:
    authc:
      realms:
        native:
          native1:
            order: 0

The internal native realm within Elasticsearch is on by default and its where users will be "stored" and managed.

Learn more within the Elasticsearch native realm documentation.

We've also set xpack.security.enabled to true.

Whenever security is enabled, additional steps are required to connect to Elasticsearch.

Follow the standard instructions to use Elasticsearch to create a password.

We'll set the new password within Enterprise Search and resume the Elasticsearch native realm configuration.

Within Enterprise Search

Within Enterprise Search, edit config/enterprise-search.yml and change the ent_search.auth.source to elasticsearch-native.

Your config/enterprise-search.yml will look as such after you add the new password:

elasticsearch.username: elastic
elasticsearch.password: [ELASTIC_PW]

ent_search.auth.source: elasticsearch-native

Restart Enterprise Search.

Upon restart, Enterprise Search will now be synchronized with the native realm.

That's the half-way point. Next, we'll introduce user management.

Native Realm User Management

User management is done through Elasticsearch.

Enterprise Search connects to Elasticsearch user management via Role Mapping.

A Role Mapping makes it so that roles - as Enterprise Search understands them - can map to roles as Elasticsearch defines them.

This allows you to inherit users instead of managing multiple sets of users.

And once inherited, you can map a role between the two to give the users you create scoped permissions.

In other words: Enterprise Search communicates with Elasticsearch to control and scope user access.

If you wanted to create a user named enterprise-search and provide a password, you'd do that in Elasticsearch like so:

curl -u elastic:[YOUR_KEY] -X POST "localhost:9200/_security/user/enterprise-search" \
-H 'Content-Type: application/json' \
-d '{
  "password" : "example-password",
  "roles" : [ "enterprise-search-user" ]
}'

A role is required -- we provided enterprise-search-user.

If you were creating users within Kibana instead of the Elasticsearch API, it looks like this.

Login to Enterprise Search using this new user: enterprise-search / example-password

Click Roles within the sidebar.

Select Add Mapping.

You'll see a screen which allows you to select various mapping configurations:

User Management - Create a mapping.
Creating a role mapping between Enterprise Search and Elasticsearch.

The goal here is to define a Attribute Value for a given External Attribute.

External - in this case - means Elasticsearch.

External AttributeAttribute Value
"email"Enterprise Search will look for an email within the native realm. Accepts wildcard characters, like *@example.com to add everyone within an organization, for example.
"metadata"Enterprise Search will look for metadata to create generic, flexible role mappings.
"username"Enterprise Search will match on username. Accepts wildcard characters, like: *_user.
"role"Elasticsearch users must contain at least one role. The value list contains a list of pre-populated Elasticsearch roles that are part of the cluster by default. See below on more information on how to add a role.

We created a user above using a role: enterprise-search-user.

If we select "role" as our External Attribute, enterprise-search-user will not be present in the default list.

Elasticsearch "created" the user role, but it isn't considered a "proper role" until the role definition has been added to Elasticsearch via the Role API.

An example API request to create an Elasticsearch role looks like so:

curl -u elastic:[YOUR_KEY] -X POST "localhost:9200/_security/role/enterprise-search-user" \
-H 'Content-Type: application/json' \
-d'{
  "cluster": ["all"],
  "indices": [
    {
      "names": [ ".ent-search-*"],
      "privileges": ["all"]
    }
  ],
  "applications": [
    {
      "application": "enterprise-search",
      "privileges": [ "admin", "read" ],
      "resources": [ "*" ]
    }
  ]
}'

In response, you'll receive:

{
  "role":{
    "created":true
  }
}

The "role" enterprise-search-user will now appear under the list of roles available to the role External Value:

User Management - The new role appears.
Creating a role mapping between Enterprise Search and Elasticsearch.

Read more within the Elasticsearch Role API documentation

Once you have selected an External Attribute and Attribute Value pair, you must then configure the Enterprise Search role.

You can provide a "role", Admin or User and then scope access:

User Management - The new role appears.
Creating a role mapping between Enterprise Search and Elasticsearch.

These roles provide access control parameters as Enterprise Search understands them.

The mapping is a link between two interpretations of a role:

  1. Enterprise Search and how users interact with it.
  2. Elasticsearch and how users are organized in the native realm.

Learn more about Enterprise Search roles and their permissions within the Role Based Access Control guide.

Click Save Mapping.

Now, any Elasticsearch user which matches the mapping will be able to access Enterprise Search and receive the new assignment.

A user needs to match at least one one mapping so that they can login!

Heads up! If a user matches two mappings, Enterprise Search will select the one which is more permissive. In other words, if role A provides read access to one Engine and role B provides write access to all Engines, if a user has both roles, they will inherit the permissions of role B.

Elasticsearch SAML

SAML support leverages the Elasticsearch SAML realm.

It requires a third party SAML provider, like Auth0 or Okta.

We'll demonstrate how to set-up with Auth0.

Auth0, SAML

Login to Auth0.

Create a new application:

SAML User Management
Creating a role mapping between Enterprise Search and Elasticsearch.

You'll want to give it a name - like My Saml App, then select Regular Web Applications:

SAML User Management
Creating a role mapping between Enterprise Search and Elasticsearch.

Next, click into your application and go into Settings:

SAML User Management
Creating a role mapping between Enterprise Search and Elasticsearch.

Scroll down until you see Allowed Callback URL.

Enter one that is relative to your ent_search.external_url, such as http://localhost:3002/users/saml_login, then save:

SAML User Management
Adding a callback URL

Keep scrolling down until you reach Advanced Settings:

SAML User Management
Advanced Settings text.

We need the SAML Metadate URL. Securely copy its contents.

That metadata URL contains XML which we need to position close to Elasticsearch. We'll do so in the Within Elasticsearch step.

The SAML Metadate URL is near the bottom:

SAML User Management
A bunch of menu options, of which SAML Metadata URL is one.

Back in your application menu, head to the Addons section.

From there, locate and activate SAML 2.0:

SAML User Management
Turning on SAML 2.0 in Auth0

Finally, create a user by selecting Users from the main menu and then clicking the + Create User button:

SAML User Management
Creating a user in Auth0

Fill out the email, a password, and leave connection to its default.

Within Elasticsearch

Within the Elasticsearch directory, open config/elasticsearch.yml and add:

(Note the comments!)

xpack.security.enabled: true
xpack.security.authc.token.enabled: true
xpack.security.transport.ssl.enabled: true

xpack.security.authc.realms.saml.saml_test: # saml_test is our "auth.name" -- we can name anything we'd like: auth0, enterprise_search, etc.
 order: 1
 idp.metadata.path: saml/idp-metadata.xml # We need to create this directory and place the file here.
 idp.entity_id: "urn:dev-abc-1234.auth0.com" # Taken from the SAML Metadata URL
 sp.entity_id: "http://localhost:3002/" # Match these with your external_url.
 sp.acs: "http://localhost:3002/users/saml_login"
 sp.logout: "http://localhost:3002/logout"
 attributes.principal: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
 attributes.mail: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"

Within the config directory, create a saml directory and a idp-metadata.xml file within it.

Paste the contents of the SAML Metadate URL file into the idp-metadata.xml file.

The URL has a prefix similar to the example: dev-abc-1234.auth0.com.

Be sure you have added that string as the idp.entity_id, prefixed with urn: as shown above.

Restart Elasticsearch.

Follow the standard instructions to use Elasticsearch to create a password.

We'll set that password and resume the SAML configuration within Enterprise Search.

Within Enterprise Search

Within Enterprise Search directory, edit config/enterprise-search.yml update the ent_search.auth.source:

elasticsearch.username: elastic
elasticsearch.password: [ELASTIC_PW]

ent_search.auth.source: elasticsearch-saml
ent_search.auth.name: saml_test

Note that the auth.name must match what is within Elasticsearch's SAML realm.

Visit your Enterprise Search URL and try to login.

You will be prompted to do so -- if you created an Auth0 user in the step above, use its credentials.

Within your SAML provider, you'll be able to create users to interact with the Elasticsearch native realm.

You can then use Enterprise Search's Role Mapping to coordinate with Elasticsearch.

Read the above section on the Elasticsearch native realm for more information on how to setup Role Mapping.

That's it! You've successfully connected SAML.

Reset Password

Run the binary with an attached --reset-auth command:

  • Standard Auth: Resets login and generates new random password.
  • elasticsearch-native and elasticsearch-saml: Removes the current role mappings. All users are granted the owner role.

Stuck? Looking for help? Contact support or check out the Enterprise Search community forum!