User Management and Security

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

Workplace Search offers three robust user management modes that are directly backed by the Elastic Stack Security features:

Standard mode requires configuration for both Elasticsearch and Workplace Search. It is the default user management and security mode.

Elasticsearch Configuration

Within the target Elasticsearch directory, open up the config/elasticsearch.yml file and enable security features:

xpack.security.enabled: true
xpack.security.authc.api_key.enabled: true

Next, we must set up a password so that Workplace Search can securely connect to Elasticsearch. Elasticsearch provides a password setup utility. Two options are available:

$ bin/elasticsearch-setup-passwords auto

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, and keep them handy for the following Workplace Search configuration steps.

Workplace Search Configuration

From the Workplace Search directory, locate the config/enterprise-search.yml configuration file and add your Elasticsearch credentials:

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

Our configuration is complete, with the exception of our default Workplace Search users' password. These are the credentials used to log in to the Workplace Search administrative dashboard:

You may alternatively choose to set the default user’s password via an environment variable on the first boot sequence:

$ ENT_SEARCH_DEFAULT_PASSWORD=some_secure_password bin/enterprise-search

You can now use the instructions for User invitations: SMTP setup and Group management to finish settings up Workplace Search for your team.

Elasticsearch offers user management via its Native Realm. Conveniently, Workplace Search can use the Elasticsearch user information as a source of truth for identity and access management.

Elasticsearch Configuration

From the Elasticsearch directory, locate config/elasticsearch.yml and povide the following configuration:

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

The Native Realm is now configured. As such, users are stored and managed via Elasticsearch directly.

We’ve also set xpack.security.enabled and xpack.security.authc.api_key.enabled to true. Additional steps are required to connect to Elasticsearch: follow the standard instructions to use Elasticsearch to create a password.

Workplace Search Configuration

From the Workplace Search directory, locate the config/enterprise-search.yml configuration file and update the ent_search.auth configuration:

elasticsearch.username: elastic
elasticsearch.password: [ELASTIC_PW]
ent_search.auth.native1.source: elasticsearch-native

Restart Workplace Search. Once back up, Workplace Search will now be synchronized with the Native Realm. That’s the half-way point. Next, we must introduce role mapping.

Workplace Search relies on Role Mapping to synchronize user information provided by Elasticsearch. In other words: you can use Elasticsearch to create a user and manage your users.

For example, if we create a user named example_mcuser and provide a password:

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

We can then login with example_mcuser and the example-password.

Any user you create in this way will have admin privileges until you setup a custom role mapping to define a user’s access level. The first step is to create a new role within Elasticsearch.

For example, we can create a new blank role called example_role:

curl -u elastic:[YOUR_KEY] -X POST "localhost:9200/_xpack/security/role/example_role" \
-H 'Content-Type: application/json' \
-d'{
  "cluster": [],
  "indices": [],
  "applications": [],
  "run_as": [],
  "metadata": {},
  "transient_metadata": {
    "enabled": true
  }
}'

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

This new role now requires a Role Mapping to assign permissions within Workplace Search.

Locate Roles in the main navigation.

Select Add Mapping:

Figure 1. User Management

We must define an Attribute Value for a given External Attribute.

External in this case means in Elasticsearch.

Our new example_role now appears as an Attribute Value under role:

Figure 2. User Management

Once you have selected an External Attribute and Attribute Value pair, you must then configure the Workplace Search role. You can provide an access level, Admin or User, and Group assignment:

Figure 3. User Management

It helps to create your admin group first so that you can login safely while configuring Workplace Search.

Click Save Role Mapping.

Now that we have created a role mapping, all new users need to match at least one mapping to successfully log in to Workplace Search. In our example, any user with example_role will be able to access Workplace Search as a User with All Groups access. The following will create such a user:

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

SAML support for Workplace Search is provided via Elasticsearch. For the sake of this guide, we’ll use Auth0 to demonstrate how to configure SAML for your orgnization.

Configuring SAML with Auth0

Step 1. Log in to Auth0 and create a new application:

Figure 4. SAML User Management

Step 2. You’ll want to give it a name - like My SAML App, then select Regular Web Applications:

Figure 5. SAML User Management

Step 3. Next, access the newly created application and locate Settings:

Figure 6. SAML User Management

Step 4. Find Allowed Callback URL. Enter one that is relative to your ent_search.external_url, such as http://localhost:3002/users/saml_login, and save:

Figure 7. SAML User Management

Step 5. Locate Advanced Settings and securely copy the contents of SAML Metadata URL. This Metadata URL contains XML which we must provide to our cluster. We’ll do so in the Elasticsearch Configuration step. :

Figure 8. SAML User Management

Figure 9. SAML User Management

Step 6. Back in your application menu, head to the Addons section. From there, locate and activate SAML 2.0:

Figure 10. SAML User Management

Step 7. Finally, create a user by selecting Users from the main menu and then clicking the + Create User button. Fill out the email, a password, and leave connection to its default.

Figure 11. SAML User Management

Elasticsearch Configuration

Step 1. Within the Elasticsearch directory, locate the config/elasticsearch.yml file and append:

xpack.security.enabled: true
xpack.security.authc.api_key.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"

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

Step 3. Paste the contents of the SAML Metadata URL file into the idp-metadata.xml file. The URL has a prefix similar to the example: dev-abc-1234.auth0.com.

Step 4. Restart Elasticsearch. Changes will take effect upon reboot.

Step 5. Follow the Standard Mode instructions to create a password for the elastic user for Elasticsearch. We’ll use these credentials and resume the SAML configuration within Workplace Search next.

Workplace Search Configuration

From the Workplace Search directory, locate the config/enterprise-search.yml configuration file and update the ent_search.auth configuration as well as the elastic password:

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

ent_search.auth.saml_test.source: elasticsearch-saml

Visit Workplace Search and log in with your SAML provider using the user previously created with Auth0.

Workplace Search is now aware of users managed within Auth0. However, for those users to access Workplace Search, you must map Workplace Search roles to those users based on their attributes stored in Auth0 (e.g. email, username, role).

Map Workplace Search roles from within Workplace Search. Although Elasticsearch and Kibana have interfaces for assigning and mapping roles, those settings don’t apply to Workplace Search.

Use Workplace Search’s Role Mapping feature to define all Workplace Search roles. Refer to the steps in Native Realm Role Mapping, but remember that in this instance you are mapping roles onto users managed in your SAML provider based on their attributes stored within that provider.