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

[DOCS] Reorganizes authentication details in Stack Overview (#30280)

This commit is contained in:
Lisa Cawley 2018-05-02 12:08:02 -07:00 committed by GitHub
parent fb0aa562a5
commit 3e9fe3c9cd
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
14 changed files with 383 additions and 447 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

350
x-pack/docs/en/security/authentication.asciidoc
View File

@ -1,350 +0,0 @@
[[setting-up-authentication]]
== Setting Up User Authentication
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).
You can use the native support for managing and authenticating users, or
integrate with external user management systems such as LDAP and Active
Directory. For information about managing native users,
see <<managing-native-users, Managing Native Users>>.
[float]
[[built-in-users]]
=== Built-in Users
{security} provides built-in user credentials to help you get up and running.
These users have a fixed set of privileges and cannot be authenticated until their
passwords have been set. The `elastic` user can be used to
<<set-built-in-user-passwords,set all of the built-in user passwords>>.
`elastic`:: A built-in _superuser_. See <<built-in-roles>>.
`kibana`:: The user Kibana uses to connect and communicate with Elasticsearch.
`logstash_system`:: The user Logstash uses when storing monitoring information in Elasticsearch.
`beats_system`:: The user the Beats use when storing monitoring information in Elasticsearch.
[float]
[[built-in-user-explanation]]
==== How the Built-in Users Work
These built-in users are stored within a special `.security` index managed by
{security}.
This means that, if the password is changed, or a user is disabled, then that
change is automatically reflected on each node in the cluster. It also means
that if your `.security` index is deleted, or restored from a snapshot, then
any changes you have applied will be lost.
Although they share the same API, the built-in users are separate and distinct
from users managed by the <<native-realm, native realm>>. Disabling the native
realm will not have any effect on the built-in users. The built-in users can
be disabled individually, using the
{ref}/security-api-users.html[user management API].
[float]
[[bootstrap-elastic-passwords]]
==== The Elastic Bootstrap Password
When you install {es}, if the `elastic` user does not already have a password,
it uses a default bootstrap password. The bootstrap password is a transient
password that enables you to run the tools that set all the built-in user passwords.
By default, the bootstrap password is derived from a randomized `keystore.seed`
setting, which is added to the keystore during installation. You do not need
to know or change this bootstrap password. If you have defined a
`bootstrap.password` setting in the keystore, however, that value is used instead.
For more information about interacting with the keystore, see
{ref}/secure-settings.html[Secure Settings].
NOTE: After you <<set-built-in-user-passwords,set passwords for the built-in users>>,
in particular for the `elastic` user, there is no further use for the bootstrap
password.
[float]
[[set-built-in-user-passwords]]
==== Setting Built-in User Passwords
You must set the passwords for all built-in users.
The +elasticsearch-setup-passwords+ tool is the simplest method to set the
built-in users' passwords for the first time. It uses the `elastic` user's
bootstrap password to run user management API requests. For example, you can run
the command in an "interactive" mode, which prompts you to enter new passwords
for the `elastic`, `kibana`, `logstash_system`, and `beats_system` users:
[source,shell]
--------------------------------------------------
bin/elasticsearch-setup-passwords interactive
--------------------------------------------------
For more information about the command options, see
{ref}/setup-passwords.html[elasticsearch-setup-passwords].
IMPORTANT: After you set a password for the `elastic` user, the bootstrap
password is no longer valid; you cannot run the `elasticsearch-setup-passwords`
command a second time.
Alternatively, you can set the initial passwords for the built-in users by using
the *Management > Users* page in {kib} or the
{ref}/security-api-change-password.html[Change Password API]. These methods are
more complex. You must supply the `elastic` user and its bootstrap password to
log into {kib} or run the API. This requirement means that you cannot use the
default bootstrap password that is derived from the `keystore.seed` setting.
Instead, you must explicitly set a `bootstrap.password` setting in the keystore
before you start {es}. For example, the following command prompts you to enter a
new bootstrap password:
[source,shell]
----------------------------------------------------
bin/elasticsearch-keystore add "bootstrap.password"
----------------------------------------------------
You can then start {es} and {kib} and use the `elastic` user and bootstrap
password to log into {kib} and change the passwords. Alternatively, you can
submit Change Password API requests for each built-in user. These methods are
better suited for changing your passwords after the initial setup is complete,
since at that point the bootstrap password is no longer required.
[float]
[[add-built-in-user-passwords]]
==== Adding Built-in User Passwords To {kib}, Logstash, and Beats
After the `kibana` user password is set, you need to update the {kib} server
with the new password by setting `elasticsearch.password` in the `kibana.yml`
configuration file:
[source,yaml]
-----------------------------------------------
elasticsearch.password: kibanapassword
-----------------------------------------------
The `logstash_system` user is used internally within Logstash when
monitoring is enabled for Logstash.
To enable this feature in Logstash, you need to update the Logstash
configuration with the new password by setting `xpack.monitoring.elasticsearch.password` in
the `logstash.yml` configuration file:
[source,yaml]
----------------------------------------------------------
xpack.monitoring.elasticsearch.password: logstashpassword
----------------------------------------------------------
If you have upgraded from an older version of elasticsearch/x-pack,
the `logstash_system` user may have defaulted to _disabled_ for security reasons.
Once the password has been changed, you can enable the user via the following API call:
[source,js]
---------------------------------------------------------------------
PUT _xpack/security/user/logstash_system/_enable
---------------------------------------------------------------------
// CONSOLE
The `beats_system` user is used internally within Beats when monitoring is
enabled for Beats.
To enable this feature in Beats, you need to update the configuration for each
of your beats to reference the correct username and password. For example:
[source,yaml]
----------------------------------------------------------
xpack.monitoring.elasticsearch.username: beats_system
xpack.monitoring.elasticsearch.password: beatspassword
----------------------------------------------------------
If you have upgraded from an older version of {es}, then you may not have set a
password for the `beats_system` user. If this is the case, then you should use
the *Management > Users* page in {kib} or the
{ref}/security-api-change-password.html[Change Password API] to set a password
for this user.
[float]
[[disabling-default-password]]
==== Disabling Default Password Functionality
[IMPORTANT]
=============================================================================
This setting is deprecated. The elastic user no longer has a default password.
The password must be set before the user can be used.
See <<bootstrap-elastic-passwords>>.
=============================================================================
[float]
[[internal-users]]
=== Internal Users
{security} has three _internal_ users (`_system`, `_xpack`, and `_xpack_security`)
that are responsible for the operations that take place inside an {es} cluster.
These users are only used by requests that originate from within the cluster.
For this reason, they cannot be used to authenticate against the API and there
is no password to manage or reset.
From time-to-time you may find a reference to one of these users inside your
logs, including <<auditing, audit logs>>.
[[how-authc-works]]
=== How Authentication Works
Authentication in {security} is handled by one or more authentication services
called _realms_. A _realm_ is used to resolve and authenticate users based on
authentication tokens. {security} provides the following built-in realms:
_native_::
An internal realm where users are stored in a dedicated Elasticsearch index.
This realm supports an authentication token in the form of username and password,
and is available by default when no realms are explicitly configured. See
<<native-realm>>.
_ldap_::
A realm that uses an external LDAP server to authenticate the
users. This realm supports an authentication token in the form of username and
password, and requires explicit configuration in order to be used. See
<<ldap-realm>>.
_active_directory_::
A realm that uses an external Active Directory Server to authenticate the
users. With this realm, users are authenticated by usernames and passwords.
See <<active-directory-realm>>.
_pki_::
A realm that authenticates users using Public Key Infrastructure (PKI). This
realm works in conjunction with SSL/TLS and identifies the users through the
Distinguished Name (DN) of the client's X.509 certificates. See <<pki-realm>>.
_file_::
An internal realm where users are defined in files stored on each node in the
Elasticsearch cluster. This realm supports an authentication token in the form
of username and password, and is always available. See <<file-realm>>.
_saml_::
A realm that facilitates authentication using the SAML 2.0 Web SSO protocol.
This realm is designed to support authentication through {kib}, and is non
intended for use in the REST API. See <<saml-realm>>.
{security} also supports custom realms. If you need to integrate with another
authentication system, you can build a custom realm plugin. For more information,
see <<custom-realms, Integrating with Other Authentication Systems>>.
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. You should make sure each
configured realm has a distinct `order` setting. In the event that two or more
realms have the same `order`, they will be processed in `name` order.
During the authentication process, {security} 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: 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>>.
The default realm chain contains the `native` and `file` realms. To explicitly,
configure a realm chain, you specify the chain in `elasticsearch.yml`. When you
configure a realm chain, only the realms you specify are used for authentication.
To use the `native` and `file` realms, you must include them in the chain.
The following snippet configures a realm chain that includes the `file` and
`native` realms, as well as two LDAP realms and an Active Directory realm.
[source,yaml]
----------------------------------------
xpack.security.authc:
realms:
file:
type: file
order: 0
native:
type: native
order: 1
ldap1:
type: ldap
order: 2
enabled: false
url: 'url_to_ldap1'
...
ldap2:
type: ldap
order: 3
url: 'url_to_ldap2'
...
ad1:
type: active_directory
order: 4
url: 'url_to_ad'
----------------------------------------
As can be seen above, each realm has a unique name that identifies it and each
realm type dictates its own set of required and optional settings. That said,
there are three settings that are common to all realms:
[cols=",^,",options="header"]
|=========
| Setting | Required | Description
| `type` | true | Identifies the type of the realm. The realm type
determines what other settings the realms should be
configured with. The type can be one of: `native`,
`ldap`, `active_directory`, `pki`, `file`, or in case
of a custom realm, the type name that identifies it.
| `order` | false | A numeric value representing the priority/index of
the realm within the realm chain. This will determine
the order by which the realms will be consulted
during authentication, with lower order being consulted
first.
| `enabled` | false | When set to `false` the realm will be disabled and
will not be added to the realm chain. This is useful
for debugging purposes as it enables you to remove
a realm from the chain without deleting and losing
its configuration.
|=========
Realm types can roughly be classified in two categories:
Internal:: Realms that are internal to Elasticsearch and don't require any
communication with external parties. They are fully managed by
{security}. There can only be a maximum of one configured realm
per internal realm type. {security} provides two internal realm
types: `native` and `file`.
External:: Realms that require interaction with parties/components external to
Elasticsearch, typically, with enterprise grade identity management
systems. Unlike internal realms, there can be as many external realms
as one would like - each with its own unique name and configuration.
{security} provides three external realm types: `ldap`,
`active_directory` and `pki`.
include::authentication/anonymous-access.asciidoc[]
include::authentication/native-realm.asciidoc[]
include::authentication/ldap-realm.asciidoc[]
include::authentication/active-directory-realm.asciidoc[]
include::authentication/pki-realm.asciidoc[]
include::authentication/file-realm.asciidoc[]
include::authentication/saml-realm.asciidoc[]
include::authentication/custom-realm.asciidoc[]
include::authentication/user-cache.asciidoc[]
include::authentication/saml-guide.asciidoc[]

15
x-pack/docs/en/security/authentication/active-directory-realm.asciidoc
View File

@ -1,5 +1,5 @@
[[active-directory-realm]]
=== Active Directory User Authentication
=== Active Directory user authentication
You can configure {security} to communicate with Active Directory to authenticate
users. To integrate with Active Directory, you configure an `active_directory`
@ -33,7 +33,7 @@ retrieves the user's group memberships from the `tokenGroups` attribute on the
user's entry in Active Directory.
[[ad-load-balancing]]
==== Load Balancing and Failover
==== Load balancing and failover
The `load_balance.type` setting can be used at the realm level to configure how
{security} should interact with multiple Active Directory servers. Two modes of
operation are supported: failover and load balancing.
@ -41,18 +41,17 @@ operation are supported: failover and load balancing.
See {ref}/security-settings.html#load-balancing[Load Balancing and Failover Settings].
[[ad-settings]]
==== Active Directory Realm Settings
==== Active Directory realm settings
See {ref}/security-settings.html#ref-ad-settings[Active Directory Realm Settings].
[[mapping-roles-ad]]
==== Mapping Active Directory Users and Groups to Roles
==== Mapping Active Directory users and groups to roles
See {ref}/configuring-ad-realm.html[Configuring an Active Directory realm].
[[ad-user-metadata]]
==== User Metadata in Active Directory Realms
==== User metadata in Active Directory realms
When a user is authenticated via an Active Directory realm, the following
properties are populated in the user's _metadata_:
@ -72,7 +71,7 @@ Additional metadata can be extracted from the Active Directory server by configu
the `metadata` setting on the Active Directory realm.
[[active-directory-ssl]]
==== Setting up SSL Between Elasticsearch and Active Directory
==== Setting up SSL between Elasticsearch and Active Directory
See
{ref}/configuring-tls.html#tls-active-directory[Encrypting communications between {es} and Active Directory].
{ref}/configuring-tls.html#tls-active-directory[Encrypting communications between {es} and Active Directory].

156
x-pack/docs/en/security/authentication/built-in-users.asciidoc Normal file
View File

@ -0,0 +1,156 @@
[[built-in-users]]
=== Built-in users
{security} provides built-in user credentials to help you get up and running.
These users have a fixed set of privileges and cannot be authenticated until their
passwords have been set. The `elastic` user can be used to
<<set-built-in-user-passwords,set all of the built-in user passwords>>.
`elastic`:: A built-in _superuser_. See <<built-in-roles>>.
`kibana`:: The user Kibana uses to connect and communicate with Elasticsearch.
`logstash_system`:: The user Logstash uses when storing monitoring information in Elasticsearch.
`beats_system`:: The user the Beats use when storing monitoring information in Elasticsearch.
[float]
[[built-in-user-explanation]]
==== How the built-in users work
These built-in users are stored within a special `.security` index managed by
{security}.
This means that, if the password is changed, or a user is disabled, then that
change is automatically reflected on each node in the cluster. It also means
that if your `.security` index is deleted, or restored from a snapshot, then
any changes you have applied will be lost.
Although they share the same API, the built-in users are separate and distinct
from users managed by the <<native-realm, native realm>>. Disabling the native
realm will not have any effect on the built-in users. The built-in users can
be disabled individually, using the
{ref}/security-api-users.html[user management API].
[float]
[[bootstrap-elastic-passwords]]
==== The Elastic bootstrap password
When you install {es}, if the `elastic` user does not already have a password,
it uses a default bootstrap password. The bootstrap password is a transient
password that enables you to run the tools that set all the built-in user passwords.
By default, the bootstrap password is derived from a randomized `keystore.seed`
setting, which is added to the keystore during installation. You do not need
to know or change this bootstrap password. If you have defined a
`bootstrap.password` setting in the keystore, however, that value is used instead.
For more information about interacting with the keystore, see
{ref}/secure-settings.html[Secure Settings].
NOTE: After you <<set-built-in-user-passwords,set passwords for the built-in users>>,
in particular for the `elastic` user, there is no further use for the bootstrap
password.
[float]
[[set-built-in-user-passwords]]
==== Setting built-in user passwords
You must set the passwords for all built-in users.
The +elasticsearch-setup-passwords+ tool is the simplest method to set the
built-in users' passwords for the first time. It uses the `elastic` user's
bootstrap password to run user management API requests. For example, you can run
the command in an "interactive" mode, which prompts you to enter new passwords
for the `elastic`, `kibana`, `logstash_system`, and `beats_system` users:
[source,shell]
--------------------------------------------------
bin/elasticsearch-setup-passwords interactive
--------------------------------------------------
For more information about the command options, see
{ref}/setup-passwords.html[elasticsearch-setup-passwords].
IMPORTANT: After you set a password for the `elastic` user, the bootstrap
password is no longer valid; you cannot run the `elasticsearch-setup-passwords`
command a second time.
Alternatively, you can set the initial passwords for the built-in users by using
the *Management > Users* page in {kib} or the
{ref}/security-api-change-password.html[Change Password API]. These methods are
more complex. You must supply the `elastic` user and its bootstrap password to
log into {kib} or run the API. This requirement means that you cannot use the
default bootstrap password that is derived from the `keystore.seed` setting.
Instead, you must explicitly set a `bootstrap.password` setting in the keystore
before you start {es}. For example, the following command prompts you to enter a
new bootstrap password:
[source,shell]
----------------------------------------------------
bin/elasticsearch-keystore add "bootstrap.password"
----------------------------------------------------
You can then start {es} and {kib} and use the `elastic` user and bootstrap
password to log into {kib} and change the passwords. Alternatively, you can
submit Change Password API requests for each built-in user. These methods are
better suited for changing your passwords after the initial setup is complete,
since at that point the bootstrap password is no longer required.
[float]
[[add-built-in-user-passwords]]
==== Adding Built-in User Passwords To {kib}, Logstash, and Beats
After the `kibana` user password is set, you need to update the {kib} server
with the new password by setting `elasticsearch.password` in the `kibana.yml`
configuration file:
[source,yaml]
-----------------------------------------------
elasticsearch.password: kibanapassword
-----------------------------------------------
The `logstash_system` user is used internally within Logstash when
monitoring is enabled for Logstash.
To enable this feature in Logstash, you need to update the Logstash
configuration with the new password by setting `xpack.monitoring.elasticsearch.password` in
the `logstash.yml` configuration file:
[source,yaml]
----------------------------------------------------------
xpack.monitoring.elasticsearch.password: logstashpassword
----------------------------------------------------------
If you have upgraded from an older version of elasticsearch/x-pack,
the `logstash_system` user may have defaulted to _disabled_ for security reasons.
Once the password has been changed, you can enable the user via the following API call:
[source,js]
---------------------------------------------------------------------
PUT _xpack/security/user/logstash_system/_enable
---------------------------------------------------------------------
// CONSOLE
The `beats_system` user is used internally within Beats when monitoring is
enabled for Beats.
To enable this feature in Beats, you need to update the configuration for each
of your beats to reference the correct username and password. For example:
[source,yaml]
----------------------------------------------------------
xpack.monitoring.elasticsearch.username: beats_system
xpack.monitoring.elasticsearch.password: beatspassword
----------------------------------------------------------
If you have upgraded from an older version of {es}, then you may not have set a
password for the `beats_system` user. If this is the case, then you should use
the *Management > Users* page in {kib} or the
{ref}/security-api-change-password.html[Change Password API] to set a password
for this user.
[float]
[[disabling-default-password]]
==== Disabling default password functionality
[IMPORTANT]
=============================================================================
This setting is deprecated. The elastic user no longer has a default password.
The password must be set before the user can be used.
See <<bootstrap-elastic-passwords>>.
=============================================================================

2
x-pack/docs/en/security/authentication/configuring-native-realm.asciidoc
View File

@ -1,6 +1,6 @@
[role="xpack"]
[[configuring-native-realm]]
=== Configuring a Native Realm
=== Configuring a native realm
The easiest way to manage and authenticate users is with the internal `native`
realm.

4
x-pack/docs/en/security/authentication/file-realm.asciidoc
View File

@ -1,5 +1,5 @@
[[file-realm]]
=== File-based User Authentication
=== File-based user authentication
You can manage and authenticate users with the built-in `file` realm.
With the `file` realm, users are defined in local files on each node in the cluster.
@ -23,4 +23,4 @@ command-line tool. This tool enables you to add and remove users, assign user
roles, and manage user passwords.
For more information, see
{ref}/configuring-file-realm.html[Configuring a file realm].
{ref}/configuring-file-realm.html[Configuring a file realm].

12
x-pack/docs/en/security/authentication/internal-users.asciidoc Normal file
View File

@ -0,0 +1,12 @@
[[internal-users]]
=== Internal users
{security} has three _internal_ users (`_system`, `_xpack`, and `_xpack_security`)
that are responsible for the operations that take place inside an {es} cluster.
These users are only used by requests that originate from within the cluster.
For this reason, they cannot be used to authenticate against the API and there
is no password to manage or reset.
From time-to-time you may find a reference to one of these users inside your
logs, including <<auditing, audit logs>>.

8
x-pack/docs/en/security/authentication/ldap-realm.asciidoc
View File

@ -20,12 +20,12 @@ The `ldap` realm supports two modes of operation, a user search mode
and a mode with specific templates for user DNs.
[[ldap-user-search]]
===== User search mode and user DN templates mode
==== User search mode and user DN templates mode
See {ref}/configuring-ldap-realm.html[Configuring an LDAP Realm].
[[ldap-load-balancing]]
===== Load balancing and failover
==== Load balancing and failover
The `load_balance.type` setting can be used at the realm level to configure how
{security} should interact with multiple LDAP servers. {security} supports both
failover and load balancing modes of operation.
@ -33,7 +33,7 @@ failover and load balancing modes of operation.
See {ref}/security-settings.html#load-balancing[Load Balancing and Failover Settings].
[[ldap-settings]]
===== LDAP realm settings
==== LDAP realm settings
See {ref}/security-settings.html#ref-ldap-settings[LDAP Realm Settings].
@ -82,4 +82,4 @@ with the <<mapping-roles-api, role mapping API>> or in
[[ldap-ssl]]
==== Setting up SSL Between Elasticsearch and LDAP
See {ref}/tls-ldap.html[Encrypting Communications Between {es} and LDAP].
See {ref}/tls-ldap.html[Encrypting Communications Between {es} and LDAP].

50
x-pack/docs/en/security/authentication/overview.asciidoc Normal file
View File

@ -0,0 +1,50 @@
[[setting-up-authentication]]
== User authentication
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).
The {stack} authenticates users by identifying the users behind the requests
that hit the cluster and verifying that they are who they claim to be. The
authentication process is handled by one or more authentication services called
<<realms,_realms_>>.
You can use the native support for managing and authenticating users, or
integrate with external user management systems such as LDAP and Active
Directory.
{security} provides built-in realms such as `native`,`ldap`, `active_directory`,
`pki`, `file`, and `saml`. If none of the built-in realms meet your needs, you
can also build your own custom realm and plug it into the {stack}.
When {security} is enabled, depending on the realms you've configured, you must
attach your user credentials to the requests sent to {es}. For example, when
using realms that support usernames and passwords you can simply attach
{wikipedia}/Basic_access_authentication[basic auth] header to the requests.
include::built-in-users.asciidoc[]
include::internal-users.asciidoc[]
include::realms.asciidoc[]
include::active-directory-realm.asciidoc[]
include::file-realm.asciidoc[]
include::ldap-realm.asciidoc[]
include::native-realm.asciidoc[]
include::pki-realm.asciidoc[]
include::saml-realm.asciidoc[]
include::custom-realm.asciidoc[]
include::anonymous-access.asciidoc[]
include::user-cache.asciidoc[]
include::saml-guide.asciidoc[]

2
x-pack/docs/en/security/authentication/pki-realm.asciidoc
View File

@ -15,6 +15,6 @@ the desired network layers (transport or http), and map the Distinguished Names
See {ref}/configuring-pki-realm.html[Configuring a PKI realm].
[[pki-settings]]
==== PKI Realm Settings
==== PKI realm settings
See {ref}/security-settings.html#ref-pki-settings[PKI realm settings].

123
x-pack/docs/en/security/authentication/realms.asciidoc Normal file
View File

@ -0,0 +1,123 @@
[[realms]]
=== Realms
Authentication in {security} is handled by one or more authentication services
called _realms_. A _realm_ is used to resolve and authenticate users based on
authentication tokens. {security} provides the following built-in realms:
_native_::
An internal realm where users are stored in a dedicated {es} index.
This realm supports an authentication token in the form of username and password,
and is available by default when no realms are explicitly configured. The users
are managed via the {ref}/security-api-users.html[User Management API]. See
<<native-realm>>.
_ldap_::
A realm that uses an external LDAP server to authenticate the
users. This realm supports an authentication token in the form of username and
password, and requires explicit configuration in order to be used. See
<<ldap-realm>>.
_active_directory_::
A realm that uses an external Active Directory Server to authenticate the
users. With this realm, users are authenticated by usernames and passwords.
See <<active-directory-realm>>.
_pki_::
A realm that authenticates users using Public Key Infrastructure (PKI). This
realm works in conjunction with SSL/TLS and identifies the users through the
Distinguished Name (DN) of the client's X.509 certificates. See <<pki-realm>>.
_file_::
An internal realm where users are defined in files stored on each node in the
{es} cluster. This realm supports an authentication token in the form
of username and password and is always available. See <<file-realm>>.
_saml_::
A realm that facilitates authentication using the SAML 2.0 Web SSO protocol.
This realm is designed to support authentication through {kib} and is not
intended for use in the REST API. See <<saml-realm>>.
{security} also supports custom realms. If you need to integrate with another
authentication system, you can build a custom realm plugin. For more information,
see <<custom-realms, Integrating with Other Authentication Systems>>.
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. You should make sure each
configured realm has a distinct `order` setting. In the event that two or more
realms have the same `order`, they will be processed in `name` order.
During the authentication process, {security} 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: 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>>.
The default realm chain contains the `native` and `file` realms. To explicitly,
configure a realm chain, you specify the chain in `elasticsearch.yml`. When you
configure a realm chain, only the realms you specify are used for authentication.
To use the `native` and `file` realms, you must include them in the chain.
The following snippet configures a realm chain that includes the `file` and
`native` realms, as well as two LDAP realms and an Active Directory realm.
[source,yaml]
----------------------------------------
xpack.security.authc:
realms:
file:
type: file
order: 0
native:
type: native
order: 1
ldap1:
type: ldap
order: 2
enabled: false
url: 'url_to_ldap1'
...
ldap2:
type: ldap
order: 3
url: 'url_to_ldap2'
...
ad1:
type: active_directory
order: 4
url: 'url_to_ad'
----------------------------------------
As can be seen above, each realm has a unique name that identifies it and each
realm type dictates its own set of required and optional settings. That said,
there are
{ref}/security-settings.html#ref-realm-settings[settings that are common to all realms].
Realm types can roughly be classified in two categories:
Internal:: Realms that are internal to Elasticsearch and don't require any
communication with external parties. They are fully managed by
{security}. There can only be a maximum of one configured realm
per internal realm type. {security} provides two internal realm
types: `native` and `file`.
External:: Realms that require interaction with parties/components external to
{es}, typically, with enterprise grade identity management
systems. Unlike internal realms, there can be as many external realms
as one would like - each with its own unique name and configuration.
{security} provides the following external realm types: `ldap`,
`active_directory`, `saml`, and `pki`.

40
x-pack/docs/en/security/authentication/saml-guide.asciidoc
View File

@ -1,6 +1,6 @@
[[saml-guide]]
== Configuring SAML Single-Sign-On on the Elastic Stack
== Configuring SAML single-sign-on on the Elastic Stack
The Elastic Stack supports SAML single-sign-on (SSO) into {kib}, using {es} as
a backend service. In SAML terminology, the Elastic Stack is operating as a
@ -21,7 +21,7 @@ the primary (or sole) authentication method for users of that {kib} instance.
Once you enable SAML authentication in {kib} it will affect all users who try
to login. The <<saml-kibana>> section provides more detail about how this works.
=== The Identity Provider
=== The identity provider
The Elastic Stack supports the SAML 2.0 _Web Browser SSO_ and the SAML
2.0 _Single Logout_ profiles and can integrate with any Identity Provider (IdP)
@ -69,7 +69,7 @@ For `<LogoutRequest>` messages, the message itself must be signed, and the
signature should be provided as a URL parameter, as required by the HTTP-Redirect
binding.
=== Configure {es} for SAML Authentication
=== Configure {es} for SAML authentication
There are five configuration steps to enable SAML authentication in {es}:
@ -88,7 +88,7 @@ authentication.
For more information, see
{ref}/configuring-tls.html#tls-http[Encrypting HTTP Client Communications].
==== Enable the Token Service
==== Enable the token service
The {es} SAML implementation makes use of the {es} Token Service. This service
is automatically enabled if you configure TLS on the HTTP interface, and can be
@ -100,7 +100,7 @@ xpack.security.authc.token.enabled: true
------------------------------------------------------------
[[saml-create-realm]]
==== Create a SAML Realm
==== Create a SAML realm
SAML authentication is enabled by configuring a SAML realm within the
authentication chain for {es}.
@ -137,7 +137,7 @@ The configuration values used in the example above are:
xpack.security.authc.realms.saml::
This defines a new authentication realm named "saml1".
See <<how-authc-works>> for more explanation of realms.
See <<realms>> for more explanation of realms.
type:: The `type` must be `saml`
order::
@ -184,7 +184,7 @@ attribute.principal:: See <<saml-attribute-mapping>>.
attribute.groups:: See <<saml-attribute-mapping>>.
[[saml-attribute-mapping]]
==== Attribute Mapping
==== Attribute mapping
When a user connects to {kib} through your Identity Provider, the Identity
Provider will supply a SAML Assertion about the user. The assertion will contain
@ -237,7 +237,7 @@ The recommended steps for configuring these SAML attributes are as follows:
in your IdP. In the example above, we have configured the `principal` and
`groups` attributes.
===== Special Attribute Names
===== Special attribute names
In general, {es} expects that the configured value for an attribute will be a
URI such as `urn:oid:0.9.2342.19200300.100.1.1`, however there are some
@ -288,7 +288,7 @@ xpack.security.authc.realms.saml1:
------------------------------------------------------------
[[saml-user-properties]]
===== {es} User Properties
===== {es} user properties
The {es} SAML realm can be configured to map SAML `attributes` to the
following properties on the authenticated user:
@ -308,7 +308,7 @@ name:: _(Optional)_ The user's full name.
mail:: _(Optional)_ The user's email address.
dn:: _(Optional)_ The user's X.500 _Distinguished Name_.
===== Extracting partial values from SAML Attributes
===== Extracting partial values from SAML attributes
There are some occasions where the IdP's attribute may contain more information
than you wish to use within {es}. A common example of this is one where the
@ -354,7 +354,7 @@ you make sure your regular expressions are as precise as possible so that
you do not inadvertently open an avenue for user impersonation attacks.
[[saml-logout]]
==== SAML Logout
==== SAML logout
The SAML protocol supports the concept of Single Logout (SLO).
The level of support for SLO varies between Identity Providers.
@ -367,7 +367,7 @@ By default the Elastic Stack will support SAML SLO if the following are true:
- You configure `sp.logout`
- The setting `idp.use_single_logout` is not `false`
===== IdP SLO Service
===== IdP SLO service
One of the values that {es} reads from the IdP's SAML metadata is the
`<SingleLogoutService>`. In order for Single Logout to work with the Elastic
@ -401,7 +401,7 @@ will ignore the SLO service that your IdP provides. In this case, when a user
logs out of {kib} it will invalidate their {es} session (security token), but
will not perform any logout at the IdP.
===== Using {kib} without Single Logout
===== Using {kib} without single logout
If your IdP does not support Single Logout, or you choose not to use it, then
{kib} will perform a "local logout" only.
@ -428,7 +428,7 @@ The possible solutions to this problem are:
[[saml-enc-sign]]
==== Encryption and Signing
==== Encryption and signing
The Elastic Stack supports generating signed SAML messages (for authentication
and/or logout), verifying signed SAML messages from the IdP (for both
@ -453,7 +453,7 @@ configured for the Elastic Stack Service Provider.
Encryption certificates are rarely needed, but the Elastic Stack supports them
for cases where IdPs or local policies mandate their use.
===== Generating certificates and keys.
===== Generating certificates and keys
{es} supports certificates and keys in either PEM, PKCS#12 or JKS format.
Some Identity Providers are more restrictive in the formats they support, and
@ -486,7 +486,7 @@ The generated zip archive will contain 3 files:
Encryption certificates can be generated with the same process.
===== Configuring {es} for Signing
===== Configuring {es} for signing
By default, {security} will sign _all_ outgoing SAML messages if a signing
key has been configured.
@ -527,7 +527,7 @@ A list of message types to sign. A message type is identified by the
_local name_ of the XML element used for the message. Supported values
are: `AuthnRequest`, `LogoutRequest` and `LogoutResponse`.
===== Configuring {es} for Encrypted Messages
===== Configuring {es} for encrypted messages
{security} supports a single key for message decryption. If a key is
configured, then {security} will attempt to use it to decrypt
@ -583,7 +583,7 @@ The {ref}/saml-metadata.html[documentation for the elasticsearch-saml-metadata u
describes how to run it, and the available command line options.
[[saml-role-mapping]]
=== Configuring Role Mappings
=== Configuring role mappings
When a user authenticates using SAML, they are identified to the Elastic Stack,
but this does not automatically grant them access to perform any actions or
@ -649,7 +649,7 @@ PUT /_xpack/security/role_mapping/saml-finance
// TEST
[[saml-user-metadata]]
=== User Metadata
=== User metadata
By default users who authenticate via SAML will have some additional metadata
fields.
@ -737,7 +737,7 @@ for `http` or `443` for `https`).
These values must be aligned with the URLs used in the {es} configuration for
`sp.acs` and `sp.logout`.
==== Supporting SAML and Basic authentication in {kib}
==== Supporting SAML and basic authentication in {kib}
The SAML support in {kib} is designed on the expectation that it will be the
primary (or sole) authentication method for users of that {kib} instance.

13
x-pack/docs/en/security/authentication/saml-realm.asciidoc
View File

@ -1,5 +1,5 @@
[[saml-realm]]
=== SAML Authentication
=== SAML authentication
{security} supports user authentication using SAML Single Sign On.
{security} provides this support using the Web Browser SSO profile of the SAML
2.0 protocol.
@ -21,23 +21,20 @@ Elastic Stack, there is a step-by-step guide to
The remainder of this document will describe {es} specific configuration options
for SAML realms.
[[saml-settings]]
==== SAML Realm Settings
==== SAML realm settings
See {ref}/security-settings.html#ref-saml-settings[SAML Realm Settings].
===== SAML Realm Signing Settings
==== SAML realm signing settings
See {ref}/security-settings.html#ref-saml-signing-settings[SAML Realm Signing Settings].
===== SAML Realm Encryption Settings
==== SAML realm encryption settings
See {ref}/security-settings.html#ref-saml-encryption-settings[SAML Realm Encryption Settings].
===== SAML Realm SSL Settings
==== SAML realm SSL settings
See {ref}/security-settings.html#ref-saml-ssl-settings[SAML Realm SSL Settings].

53
x-pack/docs/en/security/how-security-works.asciidoc
View File

@ -9,62 +9,11 @@ layers.
{security} provides the means to secure the Elastic cluster on several levels:
* User authentication
* <<setting-up-authentication>>
* Authorization and Role Based Access Control (a.k.a RBAC)
* Node/Client Authentication and Channel Encryption
* Auditing
[float]
=== User Authentication
User authentication is the process of identifying the users behind the requests
that hit the cluster and verifying that indeed they are who they claim to be. The
authentication process is handled by one or more authentication services called
_realms_. {security} provides the following built-in realms:
|======
| `native` | | | An internal realm where users are stored in a dedicated
Elasticsearch index. With this realm, users are
authenticated by usernames and passwords. The users
are managed via the
{ref}/security-api-users.html[User Management API].
| `ldap` | | | A realm that uses an external LDAP server to authenticate
the users. With this realm, users are authenticated by
usernames and passwords.
| `active_directory` | | | A realm that uses an external Active Directory Server
to authenticate the users. With this realm, users
are authenticated by usernames and passwords.
| `pki` | | | A realm that authenticates users using Public Key
Infrastructure (PKI). This realm works in conjunction
with SSL/TLS and identifies the users through the
Distinguished Name (DN) of the client's X.509
certificates.
| `file` | | | An internal realm where users are defined in files
stored on each node in the Elasticsearch cluster.
With this realm, users are authenticated by usernames
and passwords. The users are managed via dedicated
tools that are provided by {xpack} on installation.
| `saml` | | | A realm that uses SAML 2.0 Web SSO. This realm is
designed to be used with {kib}.
|======
If none of the built-in realms meets your needs, you can also build your own
custom realm and plug it into {xpack}.
When {security} is enabled, depending on the realms you've configured, you will
need to attach your user credentials to the requests sent to Elasticsearch. For
example, when using realms that support usernames and passwords you can simply
attach {wikipedia}/Basic_access_authentication[basic auth] header to the requests.
For more information on user authentication see <<setting-up-authentication>>
[float]
=== Authorization

2
x-pack/docs/en/security/index.asciidoc
View File

@ -98,7 +98,7 @@ include::getting-started.asciidoc[]
include::how-security-works.asciidoc[]
include::authentication.asciidoc[]
include::authentication/overview.asciidoc[]
include::authorization.asciidoc[]