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

edit

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:

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
```
Restart Elasticsearch.

esusers Realm Settings

edit

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)

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.

« Enabling Anonymous Access [1.1.0] Added in 1.1.0. Using LDAP to Authenticate Users »