2015-07-15 13:02:11 -04:00
|
|
|
[[setting-up-authentication]]
|
|
|
|
== Setting Up User Authentication
|
2015-07-13 06:31:34 -04:00
|
|
|
|
|
|
|
Authentication identifies an individual. To gain access to restricted resources, a user must prove their identity, via
|
|
|
|
passwords, credentials, or some other means (typically referred to as authentication tokens).
|
|
|
|
|
|
|
|
A _realm_ is an authentication mechanism, which Shield uses to resolve and authenticate users and their roles. Shield
|
|
|
|
currently provides four realm types:
|
|
|
|
|
|
|
|
[horizontal]
|
|
|
|
_esusers_:: A native authentication system built into Shield and available by default. See <<esusers>>.
|
|
|
|
_LDAP_:: Authentication via an external Lightweight Directory Protocol. See <<ldap>>.
|
2015-07-15 13:02:11 -04:00
|
|
|
_Active Directory_:: Authentication via an external Active Directory service. See <<active-directory>>.
|
2015-07-13 06:31:34 -04:00
|
|
|
_PKI_:: Authentication through the use of trusted X.509 certificates. See <<pki>>.
|
|
|
|
|
|
|
|
|
|
|
|
NOTE: _esusers_, _LDAP_, and _Active Directory_ realms authenticate using the username and password authentication tokens.
|
|
|
|
|
|
|
|
Realms live within a _realm chain_. It is essentially a prioritized list of configured realms (typically of various types).
|
|
|
|
The order of the list determines the order in which the realms will be consulted. During the authentication process,
|
|
|
|
Shield will consult and try to authenticate the request one realm at a time. Once one of the realms successfully
|
|
|
|
authenticates the request, the authentication is considered to be successful and the authenticated user will be associated
|
|
|
|
with the request (which will then proceed to the authorization phase). If a realm cannot authenticate the request, the
|
|
|
|
next in line realm in the chain will be consulted. If all realms in the chain could not authenticate the request, the
|
|
|
|
authentication is then considered to be unsuccessful and an authentication error will be returned (as HTTP status code `401`).
|
|
|
|
|
|
|
|
NOTE: Shield attempts to authenticate to each configured realm sequentially. Some systems (e.g. Active Directory) have a
|
|
|
|
temporary lock-out period after several successive failed login attempts. If the same username exists in multiple realms,
|
|
|
|
unintentional account lockouts are possible. For more information, please see <<trouble-shoot-active-directory, here>>.
|
|
|
|
|
|
|
|
For example, if `UserA` exists in both Active Directory and esusers, and the Active Directory realm is checked first and
|
|
|
|
esusers is checked second, an attempt to authenticate as `UserA` in the esusers realm would first attempt to authenticate
|
|
|
|
against Active Directory and fail, before successfully authenticating against the esusers realm. Because authentication is
|
|
|
|
verified on each request, the Active Directory realm would be checked - and fail - on each request for `UserA` in the esusers
|
|
|
|
realm. In this case, while the Shield request completed successfully, the account on Active Directory would have received
|
|
|
|
several failed login attempts, and that account may become temporarily locked out. Plan the order of your realms accordingly.
|
|
|
|
|
|
|
|
The realm chain can be configured in the `elasticsearch.yml` file. When not explicitly configured, a default chain will be
|
|
|
|
created that only holds the `esusers` realm in it. When explicitly configured, the created chain will be the exact reflection
|
|
|
|
of the configuration (e.g. the only realms in the chain will be those configured realms that are enabled)
|
|
|
|
|
|
|
|
The following snippet shows an example of realms configuration:
|
|
|
|
|
|
|
|
|
|
|
|
[source,yaml]
|
|
|
|
----------------------------------------
|
|
|
|
shield.authc:
|
|
|
|
|
|
|
|
realms:
|
|
|
|
|
|
|
|
esusers:
|
|
|
|
type: esusers
|
|
|
|
order: 0
|
|
|
|
|
|
|
|
ldap1:
|
|
|
|
type: ldap
|
|
|
|
order: 1
|
|
|
|
enabled: false
|
|
|
|
url: 'url_to_ldap1'
|
|
|
|
...
|
|
|
|
|
|
|
|
ldap2:
|
|
|
|
type: ldap
|
|
|
|
order: 2
|
|
|
|
url: 'url_to_ldap2'
|
|
|
|
...
|
|
|
|
|
|
|
|
ad1:
|
2015-07-17 19:07:52 -04:00
|
|
|
type: active_directory
|
2015-07-13 06:31:34 -04:00
|
|
|
order: 3
|
|
|
|
url: 'url_to_ad'
|
|
|
|
----------------------------------------
|
|
|
|
|
|
|
|
As can be seen above, each realm has a unique name that identifies it. There are three settings that are common to all
|
|
|
|
realms:
|
|
|
|
|
2015-07-17 19:07:52 -04:00
|
|
|
* `type` (required) - Identifies the type of the ream (currently can be `esusers`, `ldap` or `active_directory`). The realm
|
2015-07-13 06:31:34 -04:00
|
|
|
type determines what other settings the realms should be configured with.
|
|
|
|
* `order` (optional) - Defines the priority/index of the realm within the realm chain. This will determine when the realm
|
|
|
|
will be consulted during authentication.
|
|
|
|
* `enabled` (optional) - When set to `false` the realm will be disabled and will not be added to the realm chain. This is
|
|
|
|
useful for debugging purposes, where one can remove a realm from the chain without deleting and
|
|
|
|
losing its configuration.
|
|
|
|
|
|
|
|
The realm types can roughly be categorized to two categories:
|
|
|
|
|
2015-07-15 13:02:11 -04:00
|
|
|
* `internal` - Internal realm types are realms that are internal to Elasticsearch and don't require any communication with
|
2015-07-13 06:31:34 -04:00
|
|
|
external parties - they are fully managed by shield. There can only be a maximum of one configured realm
|
|
|
|
per internal realm type. (Currently, only one internal realm type exists - `esusers`).
|
|
|
|
|
2015-07-15 13:02:11 -04:00
|
|
|
* `external` - External realm types are realms that require interaction with parties/components external to Elasticsearch,
|
2015-07-13 06:31:34 -04:00
|
|
|
typically, with enterprise level identity management systems. Unlike the `internal` realms, there can be
|
|
|
|
as many `external` realms as one would like - each with a unique name and different settings. (Currently
|
2015-07-17 19:07:52 -04:00
|
|
|
the only `external` realm types that exist are `ldap`, `active_directory`, and `pki`).
|
2015-07-13 06:31:34 -04:00
|
|
|
|
|
|
|
|
2015-07-15 13:02:11 -04:00
|
|
|
include::setting-up-authentication/enabling-anonymous-access.asciidoc[]
|
2015-07-13 06:31:34 -04:00
|
|
|
|
2015-07-15 13:02:11 -04:00
|
|
|
include::setting-up-authentication/configuring-esusers-realm.asciidoc[]
|
2015-07-13 06:31:34 -04:00
|
|
|
|
2015-07-15 13:02:11 -04:00
|
|
|
include::setting-up-authentication/configuring-ldap-realm.asciidoc[]
|
2015-07-13 06:31:34 -04:00
|
|
|
|
2015-07-15 13:02:11 -04:00
|
|
|
include::setting-up-authentication/configuring-active-directory-realm.asciidoc[]
|
2015-07-13 06:31:34 -04:00
|
|
|
|
2015-07-15 13:02:11 -04:00
|
|
|
include::setting-up-authentication/configuring-pki-realm.asciidoc[]
|