honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Cleaned up realm topics, split off cache management. Closes elastic/elasticsearch#523, elastic/elasticsearch#451. 

Original commit: elastic/x-pack-elasticsearch@99534117de
This commit is contained in:
debadair 2015-08-14 14:51:21 -07:00
parent 28f629da29
commit ee6ac98565
9 changed files with 662 additions and 336 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
shield/docs/public/managing-users.asciidoc
View File

@ -1,3 +1,4 @@
[[managing-users]]
== Managing Users in an esusers Realm
The `esusers` command line tool is located in `ES_HOME/bin/shield` and enables several

12
shield/docs/public/mapping-roles.asciidoc
View File

@ -11,14 +11,14 @@ the name and location of the mapping file by configuring the appropriate `role_m
`shield.authc.pki.files.role_mapping` :: The location of the role mapping file for PKI realms.
Within the role mapping file, Elasticsearch roles are keys and groups
and users are values. The mapping can have a many-to-many relationship.
and users are values. The mapping can have a many-to-many relationship.
When you map roles to groups, the roles of a user in that group are the combination of the
roles assigned to that group and the roles assigned to that user.
To map users and groups to a role, you create a mapping file and copy it to each node in the cluster. Tools like Puppet or Chef can help with this.
[[ldap-role-mapping]]
.Example LDAP Role Mapping File
.Mapping LDAP Users and Groups to Roles
[source, yaml]
------------------------------------------------------------
# Example LDAP group mapping configuration:
@ -39,7 +39,7 @@ user:
[[ad-role-mapping]]
.Example Active Directory Role Mapping File
.Mapping Active Directory Users and Groups to Roles
[source, yaml]
------------------------------------------------------------
# Example Active Directory group mapping configuration:
@ -59,7 +59,7 @@ user:
<3> Example specifying the distinguished name of a Active Directory user
[[pki-role-mapping]]
.Example PKI Role Mapping File
.Mapping PKI Users to Roles
[source, yaml]
------------------------------------------------------------
# Example user mapping configuration:
@ -71,7 +71,7 @@ user:
- "cn=John Doe,ou=example,o=com"
------------------------------------------------------------
<1> The name of a Shield role defined in the <<defining-roles, roles file>>
<2> Example specifying the distinguished name of a PKI user
<2> The distinguished name of a PKI user
NOTE: For PKI realms, only the DN of a user can be mapped as there is no concept of a group in PKI
NOTE: For PKI realms, only the DN of a user can be mapped as there is no concept of a group in PKI.

2
shield/docs/public/reference.asciidoc
View File

@ -259,7 +259,7 @@ shield.authc.realms:
| `cache.max_users` | no | 100000 | Specified the maximum number of user entries that can live in the cache at a given time.
| `cache.hash_algo` | no | `ssha256` |(Expert Setting) Specifies the hashing algorithm that will be used for the in-memory cached user credentials (see <<ref-cache-hash-algo,Cache hash algorithms>> table for all possible values).
|======
NOTE: `user_dn_templates` is required to operate in user template mode and `user_search.base_dn` is required to operated in user search mode. Only one is required for a given realm configuration. For more information on the different modes, see <<ldap-realms, ldap realms>>.
NOTE: `user_dn_templates` is required to operate in user template mode and `user_search.base_dn` is required to operated in user search mode. Only one is required for a given realm configuration. For more information on the different modes, see <<ldap, ldap realms>>.
[[ref-ad-settings]]

3
shield/docs/public/setting-up-authentication.asciidoc
View File

@ -103,3 +103,6 @@ include::setting-up-authentication/configuring-ldap-realm.asciidoc[]
include::setting-up-authentication/configuring-active-directory-realm.asciidoc[]
include::setting-up-authentication/configuring-pki-realm.asciidoc[]
include::setting-up-authentication/controlling-user-cache.asciidoc[]

329
shield/docs/public/setting-up-authentication/configuring-active-directory-realm.asciidoc
View File

@ -1,40 +1,48 @@
[[active-directory]]
=== Configuring an Active Directory Realm
=== Using Active Directory to Authenticate Users
A secure Elasticsearch cluster can authenticate users from a Active Directory using the LDAP protocol.
With the Active Directory Realm Authentication, you can assign roles to Active Directory groups. When a user
authenticates with Active Directory, the privileges for that user are the union of all privileges defined by the roles
assigned to the set of groups that the user belongs to.
You can configure Shield to communicate with Active Directory to authenticate users. To integrate
with Active Directory, you configure an Active Directory realm and assign Active Directory users
and groups to Shield roles in the <<mapping-roles, role mapping file>>.
==== Active Directory and LDAP
To protect passwords, communications between Shield and the LDAP server should be encrypted
using SSL/TLS. Clients and nodes that connect via SSL/TLS to the LDAP server need to have the
LDAP server's certificate or the server's root CA certificate installed in their keystore or
truststore. For more information about installing certificates, see <<active-directory-ssl,
Encrypting Communications Between Shield and Active Directory with SSL/TLS>>.
The Active Directory Realm uses LDAP to communicate with Active Directory. The Active Directory Realm is similar to the
LDAP realm but takes advantage of extra features and streamlines configuration.
==== Configuring an Active Directory Realm
A general overview of LDAP will help with the configuration. LDAP databases, like Active Directory, store users and
groups hierarchically, similar to the way folders are grouped in a file system. The path to any
entry is a _Distinguished Name_, or DN. A DN uniquely identifies a user or group. User and group names typically use
attributes such as _common name_ (`cn`) or _unique ID_ (`uid`). An LDAP directory's hierarchy is built from containers
such as the _organizational unit_ (`ou`), _organization_ (`o`), or _domain controller_ (`dc`).
Shield uses LDAP to communicate with Active Directory, so Active Directory realms are similar
to <<ldap, LDAP realms>>. Like LDAP directories, Active Directory stores users and groups
hierarchically. The directory's hierarchy is built from containers such as the _organizational
unit_ (`ou`), _organization_ (`o`), and _domain controller_ (`dc`).
LDAP ignores white space in a DN definition. The following two DNs are equivalent:
The path to a entry is a _Distinguished Name_ (DN) that uniquely identifies a user or group. User
and group names typically have attributes such as a _common name_ (`cn`) or _unique ID_ (`uid`).
A DN is specified as a string, for example `"cn=admin,dc=example,dc=com"`. White space is ignored.
[source,shell]
---------------------------------
"cn=admin,dc=example,dc=com"
"cn =admin ,dc= example , dc = com"
---------------------------------
NOTE: When you use Active Directory for authentication, the username entered by the user is expected
to match the `sAMAccountName` or `userPrincipalName`, not the common name.
Although optional, connections to the Active Directory server should use the Secure Sockets Layer (SSL/TLS) protocol to protect
passwords. Clients and nodes that connect via SSL/TLS to the LDAP server require the certificate or the root CA for the
server. These certificates should be put into each node's keystore/truststore.
To configure an Active Directory realm:
==== Active Directory Realm Configuration
Like all realms, the `active_directory` 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 Active Directory Configuration
. Add a realm configuration of type `active_directory` to `elasticsearch.yml` in the
`shield.authc.realms` namespace. At a minimum, you must set the realm
`type` to `active_directory` and specify the Active Directory `domain_name`. To use SSL/TLS to
encrypt communications with the Active Directory server, you must also set the `url` attribute and
specify the LDAPS protocol and secure port number. If you are configuring multiple realms, you
should also explicitly set the `order` attribute to control the order in which the realms are
consulted during authentication. See <<ad-settings, Active Directory Realm Settings>>
for all of the options you can set for an Active Directory realm.
+
NOTE: Binding to Active Directory fails if the domain name is not mapped in DNS. If DNS is not
being provided by a Windows DNS server, add a mapping for the domain in the local
`/etc/hosts` file.
+
For example, the following realm configuration configures Shield to connect to
`ldaps://example.com:636` to authenticate users through Active Directory.
+
[source, yaml]
------------------------------------------------------------
shield:
@ -42,128 +50,193 @@ shield:
realms:
active_directory:
type: active_directory
order: 0
domain_name: example.com
unmapped_groups_as_roles: true
order: 0 <1>
domain_name: ad.example.com
url: ldaps://ad.example.com:636 <2>
unmapped_groups_as_roles: true <3>
...
------------------------------------------------------------
<1> The realm order controls the order in which the configured realms are checked when
authenticating a user.
<2> If you don't specify the URL, it defaults to `ldap:<domain_name>:389`.
<3> When this option is enabled, Shield automatically maps Active Directory groups to
roles of the same name defined in `roles.yml`.
. Restart Elasticsearch.
[[ad-settings]]
===== Active Directory Realm Settings
.Active Directory Realm Settings
|=======================
| Setting | Required | Description
| `type` | yes | Indicates the realm type and must be set to `active_directory`
| `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`.
| `domain_name` | yes | Specifies the domain name of the Active Directory. The cluster can derive the LDAP URL and `user_search_dn` fields from values in this element if those fields are not otherwise specified.
| `url` | no | Specifies a LDAP URL in the form of `ldap[s]://<server>:<port>`. Shield attempts to authenticate against this URL. If not specified, the URL will be derived from the `domain_name`, assuming clear-text `ldap` and port `389` (e.g. `ldap://<domain_name>:389`).
| `user_search.base_dn` | no | Specifies the context to search for the user. The default value for this element is the root of the Active Directory domain.
| `user_search.scope` | no | Specifies whether the user search should be `sub_tree` (default), `one_level` or `base`. `one_level` only searches users directly contained within the `base_dn`. `sub_tree` searches all objects contained under `base_dn`. `base` specifies that the `base_dn` is a user object, and that it is the only user considered.
| `user_search.filter` | no | Specifies a filter to use to lookup a user given a username. The default filter looks up `user` objects with either `sAMAccountName` or `userPrincipalName`
| `group_search.base_dn` | no | Specifies the context to search for groups in which the user has membership. The default value for this element is the root of the Active Directory domain.
| `group_search.scope` | no | Specifies whether the group search should be `sub_tree` (default), `one_level` or `base`. `one_level` searches for groups directly contained within the `base_dn`. `sub_tree` searches all objects contained under `base_dn`. `base` specifies that the `base_dn` is a group object, and that it is the only group considered.
| `unmapped_groups_as_roles` | no | When set to `true`, the names of any unmapped LDAP groups are used as role names and assigned to the user. The default value is `false`.
| `files.role_mapping` | no | Specifies the <<ref-shield-files-location,location>> for the <<ad-role-mapping, YAML role mapping configuration file>>. By default it is `CONFIG_DIR/shield/users/role_mapping.yml`.
| `follow_referrals` | no | Boolean value that specifies whether Shield should follow referrals returned by the LDAP server. Referrals are URLs returned by the server that are to be used to continue the LDAP operation (e.g. search). Default is `true`.
| `hostname_verification` | no | When set to `true`, hostname verification will be performed when connecting to a LDAP server. The hostname or IP address used in the `url` must match one of the names in the certificate or the connection will not be allowed. Defaults to `true`.
| `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 <<ad-cache-hash-algo,here>> for possible values).
| `type` | yes | Indicates the realm type. Must be set to
`active_directory`.
| `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`.
| `domain_name` | yes | Specifies the domain name of the Active Directory. Shield
uses the domain name to derive the LDAP URL and
`user_search_dn` if those fields are not specified.
| `url` | no | Specifies an LDAP URL of the form
`ldap[s]://<server>:<port>`. Shield attempts to
authenticate against this URL. If the URL is not
specified, Shield derives it from the `domain_name`,
assuming an unencrypted connection to port 389. For
example, `ldap://<domain_name>:389`. You must specify the
URL to connect using SSL/TLS or connect to a custom port.
| `user_search.base_dn` | no | Specifies the context to search for the user. Defaults to
the root of the Active Directory domain.
| `user_search.scope` | no | Specifies whether the user search should be `sub_tree`
(default), `one_level`, or `base`. `sub_tree` searches
all objects contained under `base_dn`. `one_level` only
searches users directly contained within the `base_dn`.
`base` specifies that the `base_dn` is a user object and
that it is the only user considered.
| `user_search.filter` | no | Specifies a filter to use to lookup a user given a
username. The default filter looks up `user` objects
with either `sAMAccountName` or `userPrincipalName`. If
specified, this must be a proper LDAP user search filter,
for example `(&(objectClass=user)(sAMAccountName={0}))`.
For more information, see https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx[Search Filter Syntax].
| `group_search.base_dn` | no | Specifies the context to search for groups in which the
user has membership. Defaults to the root of the Active
Directory domain.
| `group_search.scope` | no | Specifies whether the group search should be `sub_tree`
(default), `one_level` or `base`. `sub_tree` searches
all objects contained under `base_dn`. `one_level`
searches for groups directly contained within the
`base_dn`. `base` specifies that the `base_dn` is a
group object and that it is the only group considered.
| `unmapped_groups_as_roles` | no | Specifies whether the names of any unmapped LDAP groups
should be used as role names and assigned to the user.
Defaults to `false`.
| `files.role_mapping` | no | Specifies the path and file name of the
<<ad-role-mapping, YAML role mapping configuration file>>.
Defaults to `CONF_DIR/shield/users/role_mapping.yml`,
where `CONF_DIR` is `ES_HOME/config` (zip/tar installations)
or `/etc/elasticsearch` (package installations).
| `follow_referrals` | no | Specifies whether Shield should follow referrals returned
by the LDAP server. Referrals are URLs returned by the
server that are to be used to continue the LDAP operation
(such as `search`). Defaults to `true`.
| `hostname_verification` | no | Specifies whether hostname verification is performed when
connecting to an LDAP server. When `true`, the hostname
or IP address used in the `url` must match one of the
names in the certificate or the connection will not be
allowed. Due to its potential security impact,
`hostname_verification` is not exposed via the
{ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API].
Defaults to `true`.
| `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: `hostname_verification` is considered to be a senstivie setting and therefore is not exposed via
{ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API].
[[assigning-roles-ad]]
==== Assigning Active Directory Users and Groups to Roles
To configure privileges for Active Directory users and groups, you assign them to roles in
the role mapping file stored on each node. You specify users and groups using their distinguished
names. For example, the following mapping configuration assigns the Active Directory `admins`
group both the `monitoring` and `user` roles, and assigns the `user` role to the `users`
group and `John Doe`.
Active Directory authentication expects the username entered to be the same name as the `sAMAccountName` or `userPrincipalName` and not the
`CommonName` (CN). The URL is optional, but allows the use of custom ports.
[source, yaml]
------------------------------------------------------------
monitoring: <1>
- "cn=admins,dc=example,dc=com" <2>
user:
- "cn=users,dc=example,dc=com" <3>
- "cn=admins,dc=example,dc=com"
- "cn=John Doe,cn=contractors,dc=example,dc=com" <4>
------------------------------------------------------------
<1> The name of a role defined in <<defining-roles, `roles.yml`>>.
<2> The distinguished name of the `admins` group.
<3> The distinguished name of the `users` group.
<4> The distinguished name of the user `John Doe`.
NOTE: Binding to Active Directory fails when the domain name is not mapped in DNS. If DNS is not being provided
by a Windows DNS server, add a mapping for the domain in the local `/etc/hosts` file.
For more information, see <<mapping-roles, Mapping Users and Groups to Roles>>.
[[active-directory-ssl]]
==== Encrypting Communications Between Shield and Active Directory with SSL/TLS
==== Adding a Server Certificate
You should encrypt communications between Shield and Active Directory to protect the user
credentials that are sent to Active Directory for authentication. Connecting via SSL/TLS
ensures that the identity of the Active Directory server is authenticated before Shield
transmits the user credentials, and the user names and passwords are encrypted in transit.
To use SSL/TLS to access your Active Directory server over an URL with the `ldaps` protocol, make sure the client
used by Shield can access the certificate of the CA that signed the LDAP server's certificate. This will enable
Shield's client to authenticate the Active Directory server before sending any passwords to it.
To encrypt communications between Shield and Active Directory:
To do this, first obtain a certificate for the Active Directory servers or a CA certificate that has signed the certificate.
You can use the `openssl` command to fetch the certificate and add the certificate to the `ldap.crt` file, as in
the following Unix example:
. Configure each node to trust certificates signed by the CA that signed your Active Directory server
certificates. For example, the following command imports `cacert.pem`
into node01's keystore. (For information about using truststores, see <<create-truststore,
Configuring a Separate Truststore>>.)
+
[source,shell]
--------------------------------------------------
cd CONFIG_DIR/shield
keytool -importcert -keystore node01.jks -file cacert.pem -alias ad_ca
--------------------------------------------------
+
The CA cert must be a PEM encoded certificate.
+
[NOTE]
===============================
You can also import the individual server certificates rather than the CA certificate, but
this is only recommended if you have a single Active Directory server.
You can fetch the Active Directory server certificate with `openssl`.
For example, the following command gets the certificate for `ad.example.com` and stores it locally
in `ldap.crt`.
[source, shell]
----------------------------------------------------------------------------------------------
echo | openssl s_client -connect ldap.example.com:636 2>/dev/null | openssl x509 > ldap.crt
echo | openssl s_client -connect ad.example.com:636 2>/dev/null | openssl x509 > ldap.crt
----------------------------------------------------------------------------------------------
This certificate needs to be stored in the node keystore/truststore. Import the certificate into the truststore with the
following command, providing the password for the keystore when prompted.
If you are using an older version of openssl you might need to use use the `-host` and
`-port` options rather than the `-connect` option.
===============================
[source,shell]
----------------------------------------------------------------------------------------------------
keytool -import -keystore node01.jks -file ldap.crt
----------------------------------------------------------------------------------------------------
. If you haven't already configured the path to the node's keystore or truststore in
`elasticsearch.yml`, set the `shield.ssl.keystore.path` or `shield.ssl.truststore.path`
attributes. For example:
+
[source, yaml]
--------------------------------------------------
shield.ssl.keystore.path: /home/es/config/shield/node01.jks <1>
shield.ssl.keystore.password: myPass <2>
shield.ssl.keystore.key_password: myKeyPass <3>
--------------------------------------------------
<1> The full path to the node keystore file. This must be a location within the Elasticsearch
configuration directory.
<2> The password used to access the keystore.
<3> The password used to access the certificate. This is only required if you specified a separate
certificate password when generating the certificate.
+
For more information, see <<ssl-tls, Enabling SSL/TLS in the Node Configuration>>.
If not already configured, add the path of the keystore/truststore to `elasticsearch.yml` as described in <<securing-communications, Securing Communications with Encryption and IP Filtering>>.
By default, Shield will attempt to verify the hostname or IP address used in the `url` with the values in the
certificate. If the values in the certificate do not match, Shield will not allow a connection to the Active Directory server.
This behavior can be disabled by setting the `hostname_verification` property.
. Set the `url` attribute in the realm configuration to specify the LDAPS protocol and
the secure port number. For example, `url: ldaps://ad.example.com:636`.
Finally, restart Elasticsearch to pick up the changes to `elasticsearch.yml`.
. Restart Elasticsearch to pick up the changes to `elasticsearch.yml`.
==== User Cache
To avoid connecting to the Active Directory server for every incoming request, the users and their credentials
are cached locally on each node. This is a common practice when authenticating against remote servers and as
can be seen in the table <<ad-settings, above>>, the characteristics of this cache are configurable.
The cached user credentials are hashed in memory, and there are several hash algorithms to choose from:
[[ad-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.
| `sha2` | Uses `SHA2` algorithm.
| `apr1` | Uses `apr1` algorithm (md5 crypt).
| `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 `ad1`
realm:
[source, java]
------------------------------------------------------------
$ curl -XPOST 'http://localhost:9200/_shield/realm/ad1/_cache/clear'
------------------------------------------------------------
It is also possible to evict specific users:
[source, java]
------------------------------------------------------------
$ curl -XPOST 'http://localhost:9200/_shield/realm/ad1/_cache/clear?usernames=rdeniro,alpacino'
------------------------------------------------------------
Multiple realms can also be specified using comma-delimited list:
[source, java]
------------------------------------------------------------
$ curl -XPOST 'http://localhost:9200/_shield/realm/ad1,ad2/_cache/clear'
------------------------------------------------------------
NOTE: By default, when you configure Shield to connect to Active Directory using SSL/TLS,
Shield attempts to verify the hostname or IP address specified with the `url` attribute in
the realm configuration with the values in the certificate. If the values in the certificate
and realm configuration do not match, Shield does not allow a connection to the Active
Directory server. This is done to protect against man in the middle attacks. If necessary,
you can disable this behavior by setting the <<ref-ssl-tls-settings, `hostname_verification`>>
property to `false`.

77
shield/docs/public/setting-up-authentication/configuring-esusers-realm.asciidoc
View File

@ -1,41 +1,74 @@
[[esusers]]
=== Configuring an esusers Realm
=== Using esusers to Authenticate Users
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.
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.
==== `esusers` Realm Settings
==== Configuring an esusers Realm
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:
Like other realms, you can configure options for an `esusers` realm in the
`shield.authc.realms` namespace in `elasticsearch.yml`.
.Example `esusers` Realm Configuration
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:
default:
esusers1:
type: esusers
order: 0
------------------------------------------------------------
[[esusers-settings]]
. Restart Elasticsearch.
[[esusers-settings]]
===== esusers Realm 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 <<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. By default, it is `CONFIG_DIR/shield/users_roles`.
| `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).
| `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 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.
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.

396
shield/docs/public/setting-up-authentication/configuring-ldap-realm.asciidoc
View File

@ -1,44 +1,47 @@
[[ldap]]
=== Configuring an LDAP Realm
=== Using LDAP to Authenticate Users
A secure Elasticsearch cluster can authenticate users from a Lightweight Directory Access Protocol (LDAP) directory.
With LDAP Authentication, you can assign roles to LDAP groups. When a user authenticates with LDAP, the privileges for
that user are the union of all privileges defined by the roles assigned to the set of groups that the user belongs to.
You can configure Shield to communicate with a Lightweight Directory Access Protocol
(LDAP) directory to authenticate users. To integrate with LDAP, you configure an LDAP realm and
assign LDAP groups to Shield roles in the <<mapping-roles, role mapping file>>.
This section discusses configuration for an LDAP Realm.
To protect passwords, communications between Shield and the LDAP server should be encrypted
using SSL/TLS. Clients and nodes that connect via SSL/TLS to the LDAP server need to have the
LDAP server's certificate or the server's root CA certificate installed in their keystore or
truststore. For more information about installing certificates, see <<ssl-tls, Setting Up SSL>>.
==== LDAP Overview
==== Configuring an LDAP Realm
LDAP stores users and groups hierarchically, similar to the way folders are grouped in a file system. The path to any
entry is a _Distinguished Name_, or DN. A DN uniquely identifies a user or group. User and group names typically use
attributes such as _common name_ (`cn`) or _unique ID_ (`uid`). An LDAP directory's hierarchy is built from containers
such as the _organizational unit_ (`ou`), _organization_ (`o`), or _domain controller_ (`dc`).
LDAP stores users and groups hierarchically, similar to the way folders are grouped in a file
system. An LDAP directory's hierarchy is built from containers such as the
_organizational unit_ (`ou`), _organization_ (`o`), and _domain controller_ (`dc`).
LDAP ignores white space in a DN definition. The following two DNs are equivalent:
The path to a entry is a _Distinguished Name_ (DN) that uniquely identifies a user or group.
User and group names typically have attributes such as a _common name_ (`cn`) or _unique ID_ (`uid`).
A DN is specified as a string, for example `"cn=admin,dc=example,dc=com"`. White space is ignored.
[source,shell]
---------------------------------
"cn=admin,dc=example,dc=com"
"cn =admin ,dc= example , dc = com"
---------------------------------
Although optional, connections to the LDAP server should use the Secure Sockets Layer (SSL/TLS) protocol to protect
passwords. Clients and nodes that connect via SSL/TLS to the LDAP server require the certificate or the root CA for the
server. These certificates should be put into each node's keystore/truststore.
[[ldap-realms]]
==== LDAP Realm Settings
Like all realms, the `ldap` realm is configured under the `shield.authc.realms` settings namespace in the
`elasticsearch.yml` file. The LDAP realm supports two modes of operation, a user search mode and a mode with specific
templates for user DNs.
The LDAP realm supports two modes of operation, a user search mode
and a mode with specific templates for user DNs. See <<ldap-settings, LDAP Realm Settings>>
for all of the options you can set for an LDAP realm.
[[ldap-user-search]]
===== LDAP Realm with User Search added[1.1.0]
A LDAP user search is the most common mode of operation. In this mode, a specific user with permission to search the LDAP
is used to seach for the user DN based on the username and a LDAP attribute. The following snippet shows an example of
such configuration:
===== Configuring an LDAP Realm with User Search added[1.1.0]
LDAP user search is the most common mode of operation. In this mode, a specific user with
permission to search the LDAP directory is used to search for the user DN based on the username
and an LDAP attribute.
.Example LDAP Realm Configuration with User Search
To configure an LDAP Realm with User Search:
. Add a realm configuration of type `ldap` to `elasticsearch.yml` in the
`shield.authc.realms` namespace. At a minimum, you must set the realm
`type` to `ldap`, specify the `url` of the LDAP server, and specify the container DN to search for
users with the `user_search.base_dn` option. If you are configuring multiple realms, you
should also explicitly set the `order` attribute to control the order in which the realms are
consulted during authentication. See <<ldap-settings, LDAP Realm Settings>>
for all of the options you can set for an LDAP realm.
+
For example, the following snippet shows an LDAP realm configured with a user search:
+
[source, yaml]
------------------------------------------------------------
shield:
@ -60,12 +63,26 @@ shield:
unmapped_groups_as_roles: false
------------------------------------------------------------
===== LDAP Realm with User DN Templates
User DN templates can be specified if your LDAP environment uses a few specific standard naming conditions for users. The
advantage of this method is that a search is not needed to find the user DN; conversely the disadvantage is multiple bind
operations may be needed to find the right user DN. The following snippet shows an example of such configuration:
. Restart Elasticsearch
.Example LDAP Realm Configuration with User DN Templates
===== Configuring an LDAP Realm with User DN Templates
If your LDAP environment uses a few specific standard naming conditions for users, you can use
User DN templates to configure the realm. The advantage of this method is that a search does not
have to be performed to find the user DN. However, multiple bind operations might be needed to find
the correct user DN.
To configure an LDAP Realm with User Search:
. Add a realm configuration of type `ldap` to `elasticsearch.yml` in the
`shield.authc.realms` namespace. At a minimum, you must set the realm
`type` to `ldap`, specify the `url` of the LDAP server, and specify at least one template with
the `user_dn_templates` option. If you are configuring multiple realms, you
should also explicitly set the `order` attribute to control the order in which the realms are
consulted during authentication. See <<ldap-settings, LDAP Realm Settings>>
for all of the options you can set for an LDAP realm.
+
For example, the following snippet shows an LDAP realm configured with User DN templates:
+
[source, yaml]
------------------------------------------------------------
shield:
@ -86,142 +103,235 @@ shield:
------------------------------------------------------------
[[ldap-settings]]
===== LDAP Realm Settings
.Common LDAP Realm Settings
|=======================
| Setting | Required | Description
| `type` | yes | Indicates the realm type and must be set to `ldap`.
| `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`.
| `url` | yes | Specifies the LDAP URL in the form of `ldap[s]://<server>:<port>`. Shield attempts to authenticate against this URL.
| `group_search.base_dn` | no | Specifies a container DN to search for groups in which the user has membership. When this element is absent, Shield searches for a `memberOf` attribute set on the user in order to determine group membership.
| `group_search.scope` | no | Specifies whether the group search should be `sub_tree`, `one_level` or `base`. `one_level` only searches objects directly contained within the `base_dn`. The default `sub_tree` searches all objects contained under `base_dn`. `base` specifies that the `base_dn` is a group object, and that it is the only group considered.
| `group_search.filter` | no | When not set, the realm will search for `group`, `groupOfNames`, or `groupOfUniqueNames`, with the attributes `member` or `memberOf`. Any instance of `{0}` in the filter will be replaced by the user attribute defined in `group_search.user_attribute`
| `group_search.user_attribute` | no | Specifies the user attribute that will be fetched and provided as a parameter to the filter. If not set, the user DN is passed into the filter.
| `unmapped_groups_as_roles` | no | When set to `true`, the names of any unmapped LDAP groups are used as role names and assigned to the user. The default value is `false`.
| `connect_timeout` | no | The timeout period for establishing an LDAP connection. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to "5s" - for 5 seconds
| `read_timeout` | no | The timeout period for an LDAP operation. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to "5s" - for 5 seconds
| `files.role_mapping` | no | Specifies the <<ref-shield-files-location,location>> for the <<ldap-role-mapping, YAML role mapping configuration file>>. By default, it is `CONFIG_DIR/shield/role_mapping.yml`.
| `follow_referrals` | no | Boolean value that specifies whether Shield should follow referrals returned by the LDAP server. Referrals are URLs returned by the server that are to be used to continue the LDAP operation (e.g. search). Default is `true`.
| `hostname_verification` | no | When set to `true`, hostname verification will be performed when connecting to a LDAP server. The hostname or IP address used in the `url` must match one of the names in the certificate or the connection will not be allowed. Defaults to `true`.
| `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 <<ldap-cache-hash-algo,here>> for possible values).
| `type` | yes | Indicates the realm type. Must be set to `ldap`.
| `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`.
| `url` | yes | Specifies an LDAP URL of the form of
`ldap[s]://<server>:<port>`. Shield attempts to
authenticate against this URL.
| `group_search.base_dn` | no | Specifies a container DN to search for groups in which
the user has membership. When this element is absent,
Shield searches for a `memberOf` attribute set on the
user to determine group membership.
| `group_search.scope` | no | Specifies whether the group search should be
`sub_tree`, `one_level` or `base`. `one_level` only
searches objects directly contained within the
`base_dn`. The default `sub_tree` searches all objects
contained under `base_dn`. `base` specifies that the
`base_dn` is a group object, and that it is the only
group considered.
| `group_search.filter` | no | Specifies a filter to use to lookup a group. If not
set, the realm searches for `group`,
`groupOfNames`, or `groupOfUniqueNames`, with the
attributes `member` or `memberOf`. Any instance of
`{0}` in the filter is replaced by the user
attribute defined in `group_search.user_attribute`
| `group_search.user_attribute` | no | Specifies the user attribute that is fetched and
provided as a parameter to the filter. If not set,
the user DN is passed to the filter.
| `unmapped_groups_as_roles` | no | Specifies whether the names of any unmapped LDAP groups
should be used as role names and assigned to the user.
Defaults to `false`.
| `connect_timeout` | no | Specifies the timeout period for establishing an
LDAP connection. An `s` at the end indicates seconds,
`ms` indicates milliseconds. Defaults to `5s` (5 seconds).
| `read_timeout` | no | The timeout period for an LDAP operation. An `s` at
the end indicates seconds, `ms` indicates
milliseconds. Defaults to `5s` (5 seconds).
| `files.role_mapping` | no | Specifies the path and file name for the
<<ldap-role-mapping, YAML role mapping configuration
file>>. Defaults to
`ES_HOME/config/shield/role_mapping.yml`.
| `follow_referrals` | no | Specifies whether Shield should
follow referrals returned by the LDAP server. Referrals
are URLs returned by the server that are to be used to
continue the LDAP operation (e.g. search). Defaults to
`true`.
| `hostname_verification` | no | Specifies whether hostname verification is performed when
connecting to an LDAP server. When `true`, the hostname
or IP address used in the `url` must match one of the
names in the certificate or the connection will not be
allowed. Due to its potential security impact,
`hostname_verification` is not exposed via the
{ref}/cluster-nodes-info.html#cluster-nodes-info[nodes
info API]. Defaults to `true`.
| `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)
|=======================
.User Template LDAP Realm Settings
|=======================
| Setting | Required | Description
| `user_dn_templates` | yes | Specifies the DN template that replaces the user name with the string `{0}`. This element is multivalued, allowing for multiple user contexts.
| `user_dn_templates` | yes | Specifies the DN template that replaces the user name
with the string `{0}`. This element is multivalued,
allowing for multiple user contexts.
|=======================
.User Search LDAP Realm Settings added[1.1.0]
|=======================
| Setting | Required | Description
| `bind_dn` | no | The DN of the user that will be used to bind to the LDAP and perform searches. If this is not specified, an anonymous bind will be attempted.
| `bind_password` | no | The password for the user that will be used to bind to the LDAP.
| `bind_dn` | no | The DN of the user that is used to
bind to the LDAP and perform searches. If
not specified, an anonymous bind
is attempted. Due to its potential security
impact, `hostname_verification` is not
exposed via the
{ref}/cluster-nodes-info.html#cluster-nodes-info[
nodes info API].
| `bind_password` | no | The password for the user that is used
to bind to the LDAP. Due to its potential
security impact, `hostname_verification` is
not exposed via the
{ref}/cluster-nodes-info.html#cluster-nodes-info[
nodes info API].
| `user_search.base_dn` | yes | Specifies a container DN to search for users.
| `user_search.scope` | no | The scope of the user search. Valid values are `sub_tree`, `one_level` or `base`. `one_level` only searches objects directly contained within the `base_dn`. The default `sub_tree` searches all objects contained under `base_dn`. `base` specifies that the `base_dn` is the user object, and that it is the only user considered.
| `user_search.attribute` | no | The attribute to match with the username presented to Shield. The default attribute is `uid`
| `user_search.pool.size` | no | The maximum number of connections to the LDAP server to allow in the connection pool. Default is `20`.
| `user_search.pool.initial_size` | no | The initial number of connections to create to the LDAP server on startup. Default is `5`.
| `user_search.pool.health_check.enabled` | no | Flag to enable or disable a health check on LDAP connections in the connection pool. Connections will be checked in the background at the specified interval. Default is `true`
| `user_search.pool.health_check.dn` | no | The distinguished name to be retrieved as part of the health check. Default is the value of `bind_dn`. If `bind_dn` is not specified, a value must be specified.
| `user_search.pool.health_check.interval` | no | The interval to perform background checks of connections in the pool. Default is `60s`.
| `user_search.scope` | no | The scope of the user search. Valid values
are `sub_tree`, `one_level` or `base`.
`one_level` only searches objects directly
contained within the `base_dn`.
`sub_tree` searches all objects contained
under `base_dn`. `base` specifies that the
`base_dn` is the user object, and that it is
the only user considered. Defaults to
`sub_tree`.
| `user_search.attribute` | no | Specifies the attribute to match with the
username presented to Shield. Defaults to
`uid`.
| `user_search.pool.size` | no | Specifies the maximum number of connections
to the LDAP server to allow in the connection
pool. Defaults to `20`.
| `user_search.pool.initial_size` | no | The initial number of connections to create
to the LDAP server on startup. Defaults to `5`.
| `user_search.pool.health_check.enabled` | no | Enables or disables a health check on
LDAP connections in the connection pool.
Connections are checked in the background at
the specified interval. Defaults to `true`.
| `user_search.pool.health_check.dn` | no | Specifies the distinguished name to retrieve
as part of the health check. Defaults to the
value of `bind_dn`. If `bind_dn` is not
configured, you must specify a value.
| `user_search.pool.health_check.interval` | no | How often to perform background checks
of connections in the pool. Defaults to
`60s`.
|=======================
NOTE: If any settings starting with `user_search` are specified the `user_dn_templates` setting is ignored.
NOTE: If any settings starting with `user_search` are specified, the `user_dn_templates`
the settings are ignored.
NOTE: `bind_dn`, `bind_password` and `hostname_verification` are considered to be senstivie settings and therefore are not exposed via
{ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API].
[[assigning-roles-ldap]]
==== Assigning LDAP Groups to Roles
==== Adding an LDAP server certificate
To configure privileges for LDAP users, you assign LDAP groups to roles in
the role mapping file stored on each node. When a user authenticates with LDAP,
the privileges for that user are the union of all privileges defined by
the roles assigned to the set of groups that the user belongs to.
To use SSL/TLS to access your LDAP server over an URL with the `ldaps` protocol, make sure the LDAP client used by
Shield can access the certificate of the CA that signed the LDAP server's certificate. This enables Shield's LDAP
client to authenticate the LDAP server before sending any passwords to it.
You specify groups using their distinguished names. For example, the following mapping
configuration assigns the LDAP `admins` group both the `monitoring` and `user` roles, and
assigns the `user` role to the `users` group.
To do this, first obtain a certificate for the LDAP servers or a CA certificate that has signed the LDAP certificate.
You can use the `openssl` command to fetch the certificate and add the certificate to the `ldap.crt` file, as in
the following Unix example:
[source, yaml]
------------------------------------------------------------
monitoring: <1>
- "cn=admins,dc=example,dc=com" <2>
user:
- "cn=users,dc=example,dc=com" <3>
- "cn=admins,dc=example,dc=com"
------------------------------------------------------------
<1> The name of a role defined in <<defining-roles, `roles.yml`>>.
<2> The distinguished name of the `admins` group.
<3> The distinguished name of the `users` group.
For more information, see <<mapping-roles, Mapping Users and Groups to Roles>>.
==== Encrypting Communications Between Shield and LDAP with SSL/TLS
You should encrypt communications between Shield and your LDAP server to protect the user
credentials that are sent to for authentication. Connecting via SSL/TLS
ensures that the identity of the LDAP server is authenticated before Shield
transmits the user credentials, and the user names and passwords are encrypted in transit.
To encrypt communications between Shield and your LDAP server:
. Configure each node to trust certificates signed by the CA that signed your LDAP server
certificates. For example, the following command imports `cacert.pem`
into node01's keystore. (For information about using truststores, see <<create-truststore,
Configuring a Separate Truststore>>.)
+
[source,shell]
--------------------------------------------------
cd CONFIG_DIR/shield
keytool -importcert -keystore node01.jks -file cacert.pem -alias ldap_ca
--------------------------------------------------
+
The CA cert must be a PEM encoded certificate.
+
[NOTE]
===============================
You can also import the individual server certificates rather than the CA certificate, but
this is only recommended if you have a single LDAP server.
You can fetch the LDAP server certificate with `openssl`.
For example, the following command gets the certificate for `ldap.example.com` and stores it locally
in `ldap.crt`.
[source, shell]
----------------------------------------------------------------------------------------------
echo | openssl s_client -connect ldap.example.com:636 2>/dev/null | openssl x509 > ldap.crt
----------------------------------------------------------------------------------------------
NOTE: Older versions of openssl might not have the `-connect` option. Instead use the `-host` and `-port` options.
If you are using an older version of openssl you might need to use use the `-host` and
`-port` options rather than the `-connect` option.
===============================
[[keytool]]
This certificate needs to be stored in the node keystore/truststore. Import the certificate into the truststore with the
following command, providing the password for the keystore when prompted.
. If you haven't already configured the path to the node's keystore or truststore in
`elasticsearch.yml`, set the `shield.ssl.keystore.path` or `shield.ssl.truststore.path`
attributes. For example:
+
[source, yaml]
--------------------------------------------------
shield.ssl.keystore.path: /home/es/config/shield/node01.jks <1>
shield.ssl.keystore.password: myPass <2>
shield.ssl.keystore.key_password: myKeyPass <3>
--------------------------------------------------
<1> The full path to the node keystore file. This must be a location within the Elasticsearch
configuration directory.
<2> The password used to access the keystore.
<3> The password used to access the certificate. This is only required if you specified a separate
certificate password when generating the certificate.
+
For more information, see <<ssl-tls, Enabling SSL/TLS in the Node Configuration>>.
[source,shell]
----------------------------------------------------------------------------------------------------
keytool -import -keystore node01.jks -file ldap.crt
----------------------------------------------------------------------------------------------------
. Set the `url` attribute in the realm configuration to specify the LDAPS protocol and
the secure port number. For example, `url: ldaps://ldap.example.com:636`.
If not already configured, add the path of the keystore/truststore to `elasticsearch.yml` as described in <<securing-communications, Securing Communications with Encryption and IP Filtering>>.
By default, Shield will attempt to verify the hostname or IP address used in the `url` with the values in the
certificate. If the values in the certificate do not match, Shield will not allow a connection to the LDAP server. This
behavior can be disabled by setting the `hostname_verification` property.
. Restart Elasticsearch to pick up the changes to `elasticsearch.yml`.
Restart Elasticsearch to pick up the changes to `elasticsearch.yml`.
NOTE: `hostname_verification` is considered to be a senstivie setting and therefore is not exposed via
{ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API].
[[ldap-user-cache]]
==== User Cache
To avoid connecting to the LDAP server for every incoming request, the users and their credentials are cached
locally on each node. This is a common practice when authenticating against remote servers and as can be seen
in the table <<ldap-settings,above>>, the characteristics of this cache are configurable.
The cached user credentials are hashed in memory, and there are several hash algorithms to choose from:
[[ldap-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.
| `sha2` | Uses `SHA2` algorithm.
| `apr1` | Uses `apr1` algorithm (md5 crypt).
| `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/ldap1/_cache/clear'
------------------------------------------------------------
It is also possible to evict specific users:
[source, java]
------------------------------------------------------------
$ curl -XPOST 'http://localhost:9200/_shield/realm/ldap1/_cache/clear?usernames=rdeniro,alpacino'
------------------------------------------------------------
Multiple realms can also be specified using comma-delimited list:
[source, java]
------------------------------------------------------------
$ curl -XPOST 'http://localhost:9200/_shield/realm/ldap1,ldap2/_cache/clear'
------------------------------------------------------------
NOTE: By default, when you configure Shield to connect to an LDAP server using SSL/TLS,
Shield attempts to verify the hostname or IP address specified with the `url` attribute in
the realm configuration with the values in the certificate. If the values in the certificate
and realm configuration do not match, Shield does not allow a connection to the LDAP server.
This is done to protect against man in the middle attacks. If necessary,
you can disable this behavior by setting the <<ref-ssl-tls-settings, `hostname_verification`>>
property to `false`. `hostname_verification` is considered to be a sensitive setting and
is not exposed via {ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API].

117
shield/docs/public/setting-up-authentication/configuring-pki-realm.asciidoc
View File

@ -1,26 +1,35 @@
[[pki]]
=== Configuring a PKI Realm
=== Using PKI to Authenticate Users added[1.3.0]
added[1.3.0] Shield allows for authentication through the use of Public Key Infrastructure (PKI). This works by requiring
clients to present X.509 certificates that are used for authentication and authorization will be performed by mapping the
distinguished name (DN) from the certificate to roles.
You can configure Shield to use Public Key Infrastructure (PKI) certificates to authenticate users.
This requires clients to present X.509 certificates. To use PKI, you configure a PKI realm,
enable client authentication on the desired network layers (transport or http),
and map the DNs from the user certificates to Shield roles in the <<mapping-roles, role mapping file>>.
==== SSL/TLS setup
You can use a combination of PKI encryption and username and password authentication. For example,
you can enable SSL/TLS on the transport layer and define a PKI realm to require transport clients to
authenticate with X.509 certificates, while still authenticating HTTP traffic using usernames and
passwords. You can also set `shield.transport.ssl.client.auth` to `optional`
to allow clients without certificates to authenticate with other credentials.
The PKI realm requires that SSL/TLS be enabled and client authentication also be enabled on the desired network layers
(http and/or transport). It is possible to enable SSL/TLS and client authentication on only one network layer and use PKI
authentication for that layer; for example, enabling SSL/TLS and client authentication on the transport layer with a PKI
realm defined would allow for transport clients to authenticate with X.509 certificates while HTTP traffic would still
authenticate using username and password authentication. The PKI realm supports a client authentication setting of either
`required` or `optional`; `required` forces all clients to present a certificate, while `optional` enables clients
without certificates to authenticate with other credentials. For SSL/TLS configuration details, please see
<<ref-ssl-tls-settings, SSL/TLS settings>>.
IMPORTANT: You must enable SSL/TLS to use PKI. For more information, see
<<ssl-tls, Setting Up SSL/TLS on a Cluster>>.
==== PKI Realm Configuration
Like all realms, the `pki` realm is configured under the `shield.authc.realms` settings namespace in the
`elasticsearch.yml` file. The following snippet shows an example of the most basic configuration:
Like realms, you configure options for a `pki` realm in the `shield.authc.realms` namespace in
`elasticsearch.yml`.
To configure PKI realm:
. Add a realm configuration of type `pki` to `elasticsearch.yml` in the
`shield.authc.realms` namespace. At a minimum, you must set the realm
`type` to `pki`. If you are configuring multiple realms, you
should also explicitly set the `order` attribute. See <<pki-settings, PKI Realm Settings>>
for all of the options you can set for an `pki` realm.
+
For example, the following snippet shows the most basic PKI realm configuration:
+
[source, yaml]
------------------------------------------------------------
shield:
@ -29,12 +38,14 @@ shield:
pki1:
type: pki
------------------------------------------------------------
In the above configuration, any certificate trusted by the SSL/TLS layer will be accepted for authentication. The username
will be the common name (CN) extracted from the DN of the certificate. If the username that should be used is something
other than the CN of the DN, a regex can be provided to extract the value desired for the username. The following example
will extract the email address from the DN:
+
With this configuration, any certificate trusted by the SSL/TLS layer is accepted for
authentication. The username is the common name (CN) extracted from the DN of the certificate.
+
If you want to use something other than the CN of the DN as the username, you can specify
a regex to extract the desired username. For example, the regex in the following configuration
extracts the email address from the DN:
+
[source, yaml]
------------------------------------------------------------
shield:
@ -44,11 +55,12 @@ shield:
type: pki
username_pattern: "EMAILADDRESS=(.*?)(?:,|$)"
------------------------------------------------------------
The PKI realm also provides configuration options to specify a specific truststore for authentication, which is useful
when the SSL/TLS layer trusts clients with certificates that are signed by a different CA than the one that signs the
certificates for client authentication. The following example shows such a configuration:
+
You can also specify which truststore to use for authentication. This is useful
when the SSL/TLS layer trusts clients with certificates that are signed by a different
CA than the one that signs your users' certificates. To specify the location of the truststore,
specify the `truststore.path` option:
+
[source, yaml]
------------------------------------------------------------
shield:
@ -61,18 +73,51 @@ shield:
password: "changeme"
------------------------------------------------------------
[[pki-settings]]
. Restart Elasticsearch.
[[pki-settings]]
===== PKI Realm Settings
.PKI Realm Settings
|=======================
| Setting | Required | Description
| `type` | yes | Indicates the realm type and must be set to `pki`
| `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`.
| `username_pattern` | no | The regular expression pattern used to extract the username from the certificate DN. The first match group is used as the username. Default is `CN=(.*?)(?:,\|$)`
| `truststore.path` | no | The path of a truststore to use. The default truststore is the one defined by <<ref-ssl-tls-settings,SSL/TLS settings>>
| `truststore.password` | no | The password to the truststore. Must be provided if `truststore.path` is set.
| `truststore.algorithm` | no | Algorithm for the trustsore. Default is `SunX509`
| `files.role_mapping` | no | Specifies the <<ref-shield-files-location,location>> for the <<pki-role-mapping, YAML role mapping configuration file>>. By default, it is `CONFIG_DIR/shield/role_mapping.yml`.
| `type` | yes | Indicates the realm type. Must be set to `pki`
| `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`.
| `username_pattern` | no | Specifies the regular expression pattern used to extract
the username from the certificate DN. The first match
group is used as the username. Defaults to
`CN=(.*?)(?:,\|$)`.
| `truststore.path` | no | The path to the truststore. Defaults to the path
defined by <<ref-ssl-tls-settings,SSL/TLS settings>>.
| `truststore.password` | no | Specifies the password for the truststore. Must be
provided if `truststore.path` is set.
| `truststore.algorithm` | no | Specifies the algorithm used for the trustsore. Defaults to
`SunX509`.
| `files.role_mapping` | no | Specifies the <<ref-shield-files-location,location>>
for the <<pki-role-mapping, YAML role mapping
configuration file>>. Defaults to
`CONFIG_DIR/shield/role_mapping.yml`.
|=======================
[[assigning-roles-pki]]
==== Assigning Roles for PKI Users
You assign roles for PKI users in the role mapping file stored on each node. You identify a user
by the distinguished name in their certificate. For example, the following mapping
configuration assigns `John Doe` the `user` role:
[source, yaml]
------------------------------------------------------------
user: <1>
- "cn=John Doe,ou=example,o=com" <2>
------------------------------------------------------------
<1> The name of a Shield role defined in the <<defining-roles, roles file>>
<2> The distinguished name of a PKI user.
For more information, see <<mapping-roles, Mapping Users and Groups to Roles>>.

61
shield/docs/public/setting-up-authentication/controlling-user-cache.asciidoc Normal file
View File

@ -0,0 +1,61 @@
[[controlling-user-cache]]
=== Controlling the User Cache
User credentials are cached in memory on each node to avoid connecting to a remote authentication
server or hitting the disk for every incoming request. You can configure characteristics of the
user cache with the `cache.ttl`, `cache.max_users`, and ``cache.hash_algo` realm settings.
NOTE: PKI realms do not use the user cache.
The cached user credentials are hashed in memory. By default, Shield uses a salted `sha-256`
hash algorigthm. You can use a different algorithm by setting the `cache-hash_algo` setting
to any of the supported <<cache-hash-algo, Cache hash algorithms>>.
[[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.
| `sha2` | Uses `SHA2` algorithm.
| `apr1` | Uses `apr1` algorithm (md5 crypt).
| `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 (for example through
memory dumps and using `ptrace`).
|=======================
[float]
==== Evicting Users from the Cache
Shield exposes an API to force the eviction of cached users. For example, the following request
evicts all users from the `ad1` realm:
[source, java]
------------------------------------------------------------
$ curl -XPOST 'http://localhost:9200/_shield/realm/ad1/_cache/clear'
------------------------------------------------------------
To clear the cache for multiple realms, specify the realms as a comma-separated list:
[source, java]
------------------------------------------------------------
$ curl -XPOST 'http://localhost:9200/_shield/realm/ad1,ad2/_cache/clear'
------------------------------------------------------------
You can also evict specific users:
[source, java]
------------------------------------------------------------
$ curl -XPOST 'http://localhost:9200/_shield/realm/ad1/_cache/clear?usernames=rdeniro,alpacino'
------------------------------------------------------------