257 lines
10 KiB
Plaintext
257 lines
10 KiB
Plaintext
== Managing Users in an esusers Realm
|
|
|
|
The `esusers` command line tool is located in `ES_HOME/bin/shield` 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>>
|
|
|
|
[float]
|
|
[[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>>.
|
|
|
|
[float]
|
|
[[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.
|
|
|
|
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
|
|
-----------------------------------
|
|
|
|
[float]
|
|
[[esusers-pass]]
|
|
=== Managing User 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>
|
|
--------------------------------------------------
|
|
|
|
[float]
|
|
[[esusers-roles]]
|
|
=== Assigning Users to 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
|
|
---------------------------------
|
|
|
|
[float]
|
|
[[esusers-del]]
|
|
=== Deleting Users
|
|
|
|
The `esusers userdel` command deletes a user.
|
|
|
|
[source,shell]
|
|
--------------------------------------------------
|
|
userdel <username>
|
|
--------------------------------------------------
|
|
|
|
[float]
|
|
=== About `esusers`
|
|
|
|
The `esusers` tool manipulates two files, `users` and `users_roles`, in `CONFIG_DIR/shield/`. 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 `watcher.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.
|
|
|
|
[float]
|
|
[[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.
|
|
|
|
[float]
|
|
[[users_defining-roles]]
|
|
==== 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.
|
|
|
|
[float]
|
|
[[user-cache]]
|
|
==== 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`).
|
|
|=======================
|
|
|
|
[float]
|
|
[[cache-eviction-api]]
|
|
==== Cache Eviction API
|
|
Shield exposes an API to force cached user eviction. The following example, evicts all users from the `esusers`
|
|
realm:
|
|
|
|
[source, java]
|
|
------------------------------------------------------------
|
|
$ curl -XPOST 'http://localhost:9200/_shield/realm/esusers/_cache/clear'
|
|
------------------------------------------------------------
|
|
|
|
NOTE: if no realm is defined, the default realm name, `default_esusers` can be used to clear the cache
|
|
of the default esusers realm.
|
|
|
|
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'
|
|
------------------------------------------------------------
|