OpenSearch/shield/docs/public/setting-up-authentication/configuring-esusers-realm.asciidoc

[[esusers]]
=== 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 
<<managing-users, 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:

. 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-settings, 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:
+
[source, yaml]
------------------------------------------------------------
shield:
  authc:
    realms:
      esusers1:
        type: esusers
        order: 0
------------------------------------------------------------

. Restart Elasticsearch.

[[esusers-settings]]
===== 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 <<ref-shield-files-location,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 <<ref-shield-files-location,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 
                                          	   {ref}/common-options.html#time-units[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-algo, 
                                           	   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.