291 lines
13 KiB
Plaintext
291 lines
13 KiB
Plaintext
[[esusers]]
|
|
=== esusers - Internal File Based Authentication
|
|
|
|
The _esusers_ realm is the default Shield realm. The _esusers_ realm enables the registration of users, passwords for
|
|
those users, and associates those users with roles. The `esusers` command-line tool assists with the registration and
|
|
administration of users.
|
|
|
|
==== `esusers` Realm Settings
|
|
|
|
Like all other realms, the `esusers` realm is configured under the `shield.authc.realms` settings namespace in the
|
|
`elasticsearch.yml` file. The following snippet shows an example of such configuration:
|
|
|
|
.Example `esusers` Realm Configuration
|
|
[source, yaml]
|
|
------------------------------------------------------------
|
|
shield:
|
|
authc:
|
|
realms:
|
|
default:
|
|
type: esusers
|
|
order: 0
|
|
------------------------------------------------------------
|
|
|
|
[[esusers-settings]]
|
|
|
|
.`esusers` Realm Settings
|
|
|=======================
|
|
| Setting | Required | Description
|
|
| `type` | yes | Indicates the realm type and must be set to `esusers`.
|
|
| `order` | no | Indicates the priority of this realm within the realm chain. Realms with lower order will be consulted first. Although not required, it is highly recommended to explicitly set this value when multiple realms are configured. Defaults to `Integer.MAX_VALUE`.
|
|
| `enabled` | no | Indicates whether this realm is enabled/disabled. Provides an easy way to disable realms in the chain without removing their configuration. Defaults to `true`.
|
|
| `files.users` | no | Points to the location of the `users` file where the users and their passwords are stored. Defaults to `users` file under shield's <<shield-config, config directory>>.
|
|
| `files.users_roles` | no | Points to the location of the `users_roles` file where the users and their roles are stored. Defaults to `users_roles` file under shield's <<shield-config, config directory>>.
|
|
| `cache.ttl` | no | Specified the time-to-live for cached user entries (a user and its credentials will be cached for this configured period of time). Defaults to `20m` (use the standard elasticsearch {ref}/common-options.html#time-units[time units]).
|
|
| `cache.max_users` | no | Specified the maximum number of user entries that can live in the cache at a given time. Defaults to 100,000.
|
|
| `cache.hash_algo` | no | (Expert Setting) Specifies the hashing algorithm that will be used for the in-memory cached user credentials (see <<esusers-cache-hash-algo,here>> for possible values).
|
|
|=======================
|
|
|
|
NOTE: When no realms are explicitly configured in `elasticsearch.yml`, a default realm chain will be 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.
|
|
|
|
==== The `esusers` Command Line Tool
|
|
|
|
The `esusers` command line tool is located under Shield's <<shield-bin, bin>> directory and enables several
|
|
administrative tasks for managing users:
|
|
|
|
* <<esusers-add,Adding users>>
|
|
* <<esusers-list,Listing users and roles>>
|
|
* <<esusers-pass,Managing user passwords>>
|
|
* <<esusers-roles,Managing users' roles>>
|
|
* <<esusers-del,Removing users>>
|
|
|
|
[[esusers-add]]
|
|
===== Adding Users
|
|
|
|
The `esusers useradd` command adds a user to your cluster.
|
|
|
|
NOTE: To ensure that Elasticsearch can read the user and role information at startup, run `esusers useradd` as the
|
|
same user you use to run Elasticsearch. Running the command as root or some other user will update the permissions
|
|
for the `users` and `users_roles` files and prevent Elasticsearch from accessing them.
|
|
|
|
[source,shell]
|
|
----------------------------------------
|
|
esusers useradd <username>
|
|
----------------------------------------
|
|
|
|
A username must be at least 1 character and no longer than 30 characters. The first character must be a letter
|
|
(`a-z` or `A-Z`) or an underscore (`_`). Subsequent characters can be letters, underscores (`_`), digits (`0-9`), or any
|
|
of the following symbols `@`, `-`, `.` or `$`
|
|
|
|
You can specify the user's password at the command line with the `-p` option. When this option is absent, the
|
|
`esusers` command prompts you for the password. Omit the `-p` option to keep plaintext passwords out of the terminal
|
|
session's command history.
|
|
|
|
[source,shell]
|
|
----------------------------------------------------
|
|
esusers useradd <username> -p <secret>
|
|
----------------------------------------------------
|
|
|
|
Passwords must be at least 6 characters long.
|
|
|
|
You can define a user's roles with the `-r` parameter. This parameter accepts a comma-separated list of role names to
|
|
associate with the user.
|
|
|
|
[source,shell]
|
|
-------------------------------------------------------------------
|
|
esusers useradd <username> -r <comma-separated list of role names>
|
|
-------------------------------------------------------------------
|
|
|
|
The following example adds a new user named `jacknich` to the _esusers_ realm. The password for this user is
|
|
`theshining`, and this user is associated with the `logstash` and `marvel` roles.
|
|
|
|
[source,shell]
|
|
---------------------------------------------------------
|
|
esusers useradd jacknich -p theshining -r logstash,marvel
|
|
---------------------------------------------------------
|
|
|
|
For valid role names please see <<valid-role-name, Role Definitions>>.
|
|
|
|
[[esusers-list]]
|
|
===== Listing Users
|
|
|
|
The `esusers list` command lists the users registered in the _esusers_ realm, as in the following example:
|
|
|
|
[source, shell]
|
|
----------------------------------
|
|
esusers list
|
|
rdeniro : admin
|
|
alpacino : power_user
|
|
jacknich : marvel,logstash
|
|
----------------------------------
|
|
|
|
Users are in the left-hand column and their corresponding roles are listed in the right-hand column.
|
|
|
|
===== Listing Specific Users
|
|
|
|
The `esusers list <username>` command lists a specific user. Use this command to verify that a user has been
|
|
successfully added to the cluster.
|
|
|
|
[source,shell]
|
|
-----------------------------------
|
|
esusers list jacknich
|
|
jacknich : marvel,logstash
|
|
-----------------------------------
|
|
|
|
[[esusers-pass]]
|
|
===== Changing Users' Passwords
|
|
|
|
The `esusers passwd` command enables you to reset a user's password. You can specify the new password directly with the
|
|
`-p` option. When `-p` option is omitted, the tool will prompt you to enter and confirm a password in interactive mode.
|
|
|
|
[source,shell]
|
|
--------------------------------------------------
|
|
esusers passwd <username>
|
|
--------------------------------------------------
|
|
|
|
[source,shell]
|
|
--------------------------------------------------
|
|
esusers passwd <username> -p <password>
|
|
--------------------------------------------------
|
|
|
|
[[esusers-roles]]
|
|
===== Changing Users' Roles
|
|
|
|
The `esusers roles` command manages the roles associated to a particular user. The `-a` option adds a comma-separated
|
|
list of roles to a user. The `-r` option removes a comma-separated list of roles from a user. You can combine adding and
|
|
removing roles within the same command to change a user's roles.
|
|
|
|
[source,shell]
|
|
------------------------------------------------------------------------------------------------------------
|
|
esusers roles <username> -a <commma-separate list of roles> -r <commma-separate list of roles>
|
|
------------------------------------------------------------------------------------------------------------
|
|
|
|
The following command removes the `logstash` and `marvel` roles from user `jacknich`, as well as adding the `user` role:
|
|
|
|
[source,shell]
|
|
---------------------------------------------------------------
|
|
esusers roles jacknich -r logstash,marvel -a user
|
|
---------------------------------------------------------------
|
|
|
|
Listing the user displays the new role assignment:
|
|
|
|
[source,shell]
|
|
---------------------------------
|
|
esusers list jacknich
|
|
jacknich : user
|
|
---------------------------------
|
|
|
|
[[esusers-del]]
|
|
===== Deleting Users
|
|
|
|
The `esusers userdel` command deletes a user.
|
|
|
|
[source,shell]
|
|
--------------------------------------------------
|
|
userdel <username>
|
|
--------------------------------------------------
|
|
|
|
==== How `esusers` Works
|
|
|
|
The `esusers` tool manipulates two files, `users` and `users_roles`, in Shield's
|
|
<<shield-config,config>> directory. These two files store all user data for the _esusers_ realm and are read by Shield
|
|
on startup.
|
|
|
|
By default, Shield checks these files for changes every 5 seconds. You can change this default behavior by changing the
|
|
value of the `resource.reload.interval.high` setting in the `elasticsearch.yml` file.
|
|
|
|
[IMPORTANT]
|
|
==============================
|
|
|
|
These files are managed locally by the node and are **not** managed
|
|
globally by the cluster. This means that with a typical multi-node cluster,
|
|
the exact same changes need to be applied on each and every node in the
|
|
cluster.
|
|
|
|
A safer approach would be to apply the change on one of the nodes and have the
|
|
`users` and `users_roles` files distributed/copied to all other nodes in the
|
|
cluster (either manually or using a configuration management system such as
|
|
Puppet or Chef).
|
|
|
|
==============================
|
|
|
|
While it is possible to modify these files directly using any standard text
|
|
editor, we strongly recommend using the `esusers` command-line tool to apply
|
|
the required changes.
|
|
|
|
[[users-file]]
|
|
===== The `users` File
|
|
|
|
The `users` file stores all the users and their passwords. Each line in the `users` file represents a single user entry
|
|
consisting of the username and **hashed** password.
|
|
|
|
[source,bash]
|
|
----------------------------------------------------------------------
|
|
rdeniro:$2a$10$BBJ/ILiyJ1eBTYoRKxkqbuDEdYECplvxnqQ47uiowE7yGqvCEgj9W
|
|
alpacino:$2a$10$cNwHnElYiMYZ/T3K4PvzGeJ1KbpXZp2PfoQD.gfaVdImnHOwIuBKS
|
|
jacknich:$2a$10$GYUNWyABV/Ols/.bcwxuBuuaQzV6WIauW6RdboojxcixBq3LtI3ni
|
|
----------------------------------------------------------------------
|
|
|
|
NOTE: The `esusers` command-line tool uses `bcrypt` to hash the password by default.
|
|
|
|
[[users_roles-file]]
|
|
===== The `users_roles` File
|
|
|
|
The `users_roles` file stores the roles associated with the users, as in the following example:
|
|
|
|
[source,shell]
|
|
--------------------------------------------------
|
|
admin:rdeniro
|
|
power_user:alpacino,jacknich
|
|
user:jacknich
|
|
--------------------------------------------------
|
|
|
|
Each row maps a role to a comma-separated list of all the users that are associated with that role.
|
|
|
|
==== User Cache
|
|
|
|
The user credentials are not stored on disk in clear text. The esusers creates a `bcrypt` hashes of the passwords and
|
|
stores those. `bcrypt` is considered to be highly secured hash and by default it uses 10 rounds to generate the salts
|
|
it hashes with. While highly secured, it is also relatively slow. For this reason, Shield also introduce an in-memory
|
|
cache over the `esusers` store. This cache can use a different hashing algorithm for storing the passwords in memeory.
|
|
The default hashing algorithm that is used is `ssha256` - a salted SHA-256 algorithm.
|
|
|
|
We've seen in the table <<esusers-settings,above>> that the cache characteristics can be configured. The following table
|
|
describes the different hash algorithm that can be set:
|
|
|
|
[[esusers-cache-hash-algo]]
|
|
|
|
.Cache hash algorithms
|
|
|=======================
|
|
| Algorithm | Description
|
|
| `ssha256` | Uses a salted `SHA-256` algorithm (default).
|
|
| `md5` | Uses `MD5` algorithm.
|
|
| `sha1` | Uses `SHA1` algorithm.
|
|
| `bcrypt` | Uses `bcrypt` algorithm with salt generated in 10 rounds.
|
|
| `bcrypt4` | Uses `bcrypt` algorithm with salt generated in 4 rounds.
|
|
| `bcrypt5` | Uses `bcrypt` algorithm with salt generated in 5 rounds.
|
|
| `bcrypt6` | Uses `bcrypt` algorithm with salt generated in 6 rounds.
|
|
| `bcrypt7` | Uses `bcrypt` algorithm with salt generated in 7 rounds.
|
|
| `bcrypt8` | Uses `bcrypt` algorithm with salt generated in 8 rounds.
|
|
| `bcrypt9` | Uses `bcrypt` algorithm with salt generated in 9 rounds.
|
|
| `noop`,`clear_text` | Doesn't hash the credentials and keeps it in clear text in memory. CAUTION:
|
|
keeping clear text is considered insecure and can be compromised at the OS
|
|
level (e.g. memory dumps and `ptrace`).
|
|
|=======================
|
|
|
|
===== Cache Eviction API
|
|
|
|
Shield exposes an API to force cached user eviction. The following example, evicts all users from the `ldap1`
|
|
realm:
|
|
|
|
[source, java]
|
|
------------------------------------------------------------
|
|
$ curl -XPOST 'http://localhost:9200/_shield/realm/esusers/_cache/clear'
|
|
------------------------------------------------------------
|
|
|
|
It is also possible to evict specific users:
|
|
|
|
[source, java]
|
|
------------------------------------------------------------
|
|
$ curl -XPOST 'http://localhost:9200/_shield/realm/esusers/_cache/clear?usernames=rdeniro,alpacino'
|
|
------------------------------------------------------------
|
|
|
|
Multiple realms can also be specified using comma-delimited list:
|
|
|
|
[source, java]
|
|
------------------------------------------------------------
|
|
$ curl -XPOST 'http://localhost:9200/_shield/realm/esusers,ldap1/_cache/clear'
|
|
------------------------------------------------------------
|