Version: 7.x-36.0.0

Adding Search Guard users

This guide assumes that you have already installed Search Guard in your cluster using the demo installer.

The internal user database

Search Guard can use external authentication systems like LDAP, OpenID, SAML or Kerberos for authenticating users. As an alternative, you can also use the internal user database to manage your users.

The internal user database stores users and their credentials directly in Elasticsearch. To manage users in the internal user database you have three options:

  • Configure the users, their password hashes and backend roles in the sg_intern_users.yml file and use the sgadmin CLI to upload this configuration to your cluster (Community)
  • Use the internal users REST API (Enterprise)
  • Use the Kibana internal users configuration GUI (Enterprise)

In this guide we will take the first approach.

Adding users to sg_internal_users.yml

The sg_internal_users.yml file defines all Search Guard users. You can find an example in the folder:

<ES installation directory>/plugins/search-guard-7/sgconfig/sg_internal_users.yml

A user entry has the following basic format:

<username>:
  hash: <hashed password>
  backend_roles:
    - <rolename>
    - <rolename>

In this guide we want to add a user called jdoe which has read-only access to a fictitious index called humanresources.

We also want to add the user to a backend role called hr_department. For the moment, think about backend roles as a way of putting users in different groups, just like LDAP or Active Directory groups. We use them later to assign all users with the hr_department backend role to a Search Guard role.

So our basic entry in sg_internal_users.yml looks like:

jdoe:
  hash: <hashed password>
  backend_roles:
    - hr_department

Generating the password hash

Because we do not want to store any cleartext passsords anywhere, the password of the user must be hashed before we can add it to the configuration.

Search Guard uses a BCrypt hash for the passwords, so you can use any tool that is capable of producing a BCrypt hash{target:_blank}.

Search Guard ships with a hash.sh script which you can use as well to generate the password hash. The script is located in:

<ES installation directory>/plugins/search-guard-7/tools/hash.sh

We can generate the hash like:

<ES installation directory>/plugins/search-guard-7/tools/hash.sh -p <cleartext password>

Which will then output the hash on the command line. We can now simply copy the hash to our configuration:

jdoe:
  hash: $2y$12$AwwN1fn0HDEw/LBCwWU0y.Ys6PoKBL5pR.WTYAIV92ld7tA8kozqa
  backend_roles:
    - hr_department

Since we use the BCrypt algorithm, your actual hash values might vary from the ones in this guide.

Adding more users

In our example we will add another user that is also member of the hr_department group, and one more user that is member of the devops group. We will then create Search Guard roles for these users in the next step. Our configuration looks like:

jdoe:
  hash: $2y$12$AwwN1fn0HDEw/LBCwWU0y.Ys6PoKBL5pR.WTYAIV92ld7tA8kozqa
  backend_roles:
    - hr_department

psmith:
  hash: $2y$12$YOVZhJ.gbZOAoGyd9YGNMuw7rWYTfB73n8OGBLtsrihMkW5rg5D1G
  backend_roles:
    - hr_department

cmaddock:
  hash: $2y$12$3UFikPXIZLoHcsDGD0hyqOvxjytdXeRkefIF1M58jA5oueSDKthzu
  backend_roles:
    - devops

To keep things simple, the passwords we use here are the same as the username.

Uploading the changes to your cluster

In order to activate the changed configuration, we need to upload it to the Search Guard configuration index by using the sgadmin.sh command line tool.

If you used the demo installer to set up Search Guard, you will find a pre-configured sgadmin.sh script with all required parameters already set in the tools directory.

First cd into this directory:

cd <ES installation directory>/plugins/search-guard-7/tools/

And then execute:

./sgadmin_demo.sh

This will upload all configuration files located in

<ES installation directory>/plugins/search-guard-7/sgconfig/

to the cluster.

If everything works as expected, you should see an output like

Will update 'sg/config' with <ES installation directory>/plugins/search-guard-6/sgconfig/sg_config.yml 
   SUCC: Configuration for 'config' created or updated
Will update 'sg/roles' with <ES installation directory>/plugins/search-guard-6/sgconfig/sg_roles.yml 
   SUCC: Configuration for 'roles' created or updated
Will update 'sg/rolesmapping' with <ES installation directory>/plugins/search-guard-6/sgconfig/sg_roles_mapping.yml 
   SUCC: Configuration for 'rolesmapping' created or updated
Will update 'sg/internalusers' with <ES installation directory>/plugins/search-guard-6/sgconfig/sg_internal_users.yml 
   SUCC: Configuration for 'internalusers' created or updated
Will update 'sg/actiongroups' with <ES installation directory>plugins/search-guard-6/sgconfig/sg_action_groups.yml 
   SUCC: Configuration for 'actiongroups' created or updated
Done with success

The configuration changes are active immediately. There is no need to restart your cluster.


Not what you were looking for? Try the search.