Before Version 5.0, manage users and roles in Shieldedit

Shield is always installed, but you must save your Shield configuration to enable the security features. If you don’t enable Shield, anyone who knows the ID of your deployment can connect to it.

Enable Shieldedit

You should enable Shield on all Elasticsearch clusters that you create. If your cluster does not have Shield enabled, anyone who knows the ID of your cluster can access it. By default, when you create a new deployment, the Shield plugin is installed on your clusters, but it is not enabled.

To enable Shield:

  1. Log in to the Elasticsearch Add-On for Heroku console.
  2. On the deployments page, select your deployment.

    Narrow your deployments by name, ID, or choose from several other filters. To customize your view, use a combination of filters, or change the format from a grid to a list.

  3. From your deployment menu, go to Elasticsearch and then Security.
  4. In the Security editor, review the users and roles that will be created and copy down the passwords. Keep the passwords in a secure location.

    By default, three users are always created: The admin user, the readwrite user, and the readonly user. If you are new to Shield, you can accept these default users for now and manage your own users later.

  5. Click Save to hash the passwords, save the configuration, and enable Shield.

    When you save the configuration, the passwords are hashed and you will not be able to recover them afterwards. If you ever need to reset a password, replace the corresponding hash with your new password and then save the configuration again.

After Shield is enabled, users and applications can connect to your deployment only if they can authenticate successfully.

If you are not sure how enabling Shield will affect your deployment, you can also clone an unsecured cluster, enable Shield on the new deployment, and test there before updating or completely replacing your existing deployment.

Edit users and rolesedit

You can configure users, assign their roles, and define the privileges of those roles in the Security editor. It is accessible from the Elasticsearch cluster. The Security editor works based on YAML files, so you can add comments where necessary.

A valid role or user name must be at least 1 character and no longer than 30 characters. It must begin with a letter (a-z) or an underscore (_). Subsequent characters can be letters, underscores (_), digits (0-9) or any of the following symbols @, -, . or $


The Users editor defines the users in your deployment. A user has a username and a password hash. You define a new user by adding a new line with the username mapping to a clear text password. When you save, the password is hashed in your browser before being saved to our servers.

You can click on New User to have a new user added to the file with a randomly generated password. Copy this password before saving, as there is no way to access the password after it has been hashed. If you lose the password, just change it to a new one.

If you run Shield in a deployment running on your own servers, you can simply copy the config/shield/users file and paste it in this editor.

This is an example of a valid users file:

# Lines starting with # are comments.
# This file expects usernames to map passwords or hashes, like the following:
admin: $2a$12$uRopB3Jz3slQQVMUTlNuPeHRhbfbFWDBrXhRk8vzK7xr0mavw2vAq
readwrite: $2a$12$Y/tCEs7RSzWrlWsjyyuB2.ARhuMis5PXj47IXvrDED/jJ8Cx1dKza
readonly: $2a$12$DQ8jiYAHiCvHWkmNM2fOgOsXgwZxsl/4PxY6zr5g5BOYRcG8dV9IW

# This password has not been hashed yet, but will be when you save.
my_user: bc3rqc0q1xwr4irq3o

To delete a user, simply remove it from this file.

Users per roleedit

A user can have more than one role, and a role can be assigned to multiple users.

The Users per Role editor lets you customize these. The format is one line per role, with the role name followed by a comma-delimited list of users.

# The users per role file maps roles and users like this:
# role_name: user1, user2

readonly: user1, user2
my_custom_role: user2, user3

# In this case, user2 will have the roles readonly and my_custom_role


The Roles editor lets you customize exactly which actions users with the role can do, both on a deployment and an index level.

Full documentation on configuring role-based access control is available in the Shield documentation.

You can use the default roles or adapt them. Here are two examples of roles with comments that indicate what privileges these roles grant:

# Admins can do everything
  # If you use a generic group of actions, such as "all", "read", "monitor", etc.
  # you can simply specify the group without listing every action.
  cluster: all
    # The same is true for indices. You can also list aliases here.
    # Note that the index name '*' is quoted. This is because this is actually
    # a YAML file, and the * character can have a special meaning. It is a good
    # practice to quote all the index names.
    '*': all

# This is an example of a role with more granular access. We explicitly list
# every action possible, both on the cluster and the indicies.
# A user with this role will be able to use Kibana 4 and read the indices
# logs-* and even-more-logs-*. Dashboards/Visualizations can be modified
# but the indices being analyzed can only be read.
      - cluster:monitor/nodes/info
      - cluster:monitor/health
      # Note that we use a list here. Every action is indented and
      # starts with `- `.
      - indices:admin/mappings/fields/get
      - indices:admin/validate/query
      - indices:data/read/search
      - indices:data/read/msearch
      - indices:admin/get
      - indices:admin/exists
      - indices:admin/mapping/put
      - indices:admin/mappings/fields/get
      - indices:admin/refresh
      - indices:admin/validate/query
      - indices:data/read/get
      - indices:data/read/mget
      - indices:data/read/search
      - indices:data/write/delete
      - indices:data/write/index
      - indices:data/write/update
      - indices:admin/create