75 lines
4.1 KiB
Plaintext
75 lines
4.1 KiB
Plaintext
[[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.
|