Using esusers to Authenticate Users

You can manage and authenticate users with Shield’s built-in system, esusers. An esusers realm is created by default when you install Shield. You use the esusers command line tool to add and remove users, assign user roles, and manage user passwords.

Configuring an esusers Realm

Like other realms, you can configure options for an esusers realm in the shield.authc.realms namespace in elasticsearch.yml.

To configure an esusers realm:

  1. Add a realm configuration of type esusers to elasticsearch.yml in the shield.authc.realms namespace. At a minimum, you must set the realm type to esusers. If you are configuring multiple realms, you should also explicitly set the order attribute. See esusers Realm Settings for all of the options you can set for an esusers realm.

    For example, the following snippet shows an esusers realm configuration that sets the order to zero so the realm is checked first:

    shield:
      authc:
        realms:
          esusers1:
            type: esusers
            order: 0
  2. Restart Elasticsearch.

esusers Realm Settings

Setting

Required

Description

type

yes

Indicates the realm type. Must be set to esusers.

order

no

Indicates the priority of this realm within the realm chain. Realms with a lower order are consulted first. Although not required, we recommend explicitly setting this value when you configure multiple realms. Defaults to Integer.MAX_VALUE.

enabled

no

Indicates whether this realm is enabled or disabled. Enables you to disable a realm without removing its configuration. Defaults to true.

files.users

no

Points to the location of the users file where the users and their passwords are stored. By default, it is CONFIG_DIR/shield/users.

files.users_roles

no

Points to the location of the users_roles file where the users and their roles are stored. Defaults to CONFIG_DIR/shield/users_roles.

cache.ttl

no

Specifies the time-to-live for cached user entries. A user’s credentials are cached for this period of time. Specify the time period using the standard Elasticsearch time units. Defaults to 20m.

cache.max_users

no

Specifies the maximum number of user entries that can be stored in the cache at one time. Defaults to 100,000.

cache.hash_algo

no

Specifies the hashing algorithm that is used for the cached user credentials. See Cache hash algorithms for the possible values. (Expert Setting)

Note

When no realms are explicitly configured in elasticsearch.yml, a default realm chain is created that holds a single esusers realm. If you wish to only work with esusers realm and you’re satisfied with the default files paths, there is no real need to add the above configuration.