From 3e9fe3c9cd53bc74ad4d6e1abf34c917af6283ab Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Wed, 2 May 2018 12:08:02 -0700 Subject: [PATCH] [DOCS] Reorganizes authentication details in Stack Overview (#30280) --- .../docs/en/security/authentication.asciidoc | 350 ------------------ .../active-directory-realm.asciidoc | 15 +- .../authentication/built-in-users.asciidoc | 156 ++++++++ .../configuring-native-realm.asciidoc | 2 +- .../authentication/file-realm.asciidoc | 4 +- .../authentication/internal-users.asciidoc | 12 + .../authentication/ldap-realm.asciidoc | 8 +- .../security/authentication/overview.asciidoc | 50 +++ .../authentication/pki-realm.asciidoc | 2 +- .../security/authentication/realms.asciidoc | 123 ++++++ .../authentication/saml-guide.asciidoc | 40 +- .../authentication/saml-realm.asciidoc | 13 +- .../en/security/how-security-works.asciidoc | 53 +-- x-pack/docs/en/security/index.asciidoc | 2 +- 14 files changed, 383 insertions(+), 447 deletions(-) delete mode 100644 x-pack/docs/en/security/authentication.asciidoc create mode 100644 x-pack/docs/en/security/authentication/built-in-users.asciidoc create mode 100644 x-pack/docs/en/security/authentication/internal-users.asciidoc create mode 100644 x-pack/docs/en/security/authentication/overview.asciidoc create mode 100644 x-pack/docs/en/security/authentication/realms.asciidoc diff --git a/x-pack/docs/en/security/authentication.asciidoc b/x-pack/docs/en/security/authentication.asciidoc deleted file mode 100644 index 8838a0fefbf..00000000000 --- a/x-pack/docs/en/security/authentication.asciidoc +++ /dev/null @@ -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 <>. - -[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 -<>. - -`elastic`:: A built-in _superuser_. See <>. -`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 <>. 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 <>, -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 <>. -============================================================================= - -[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 <>. - -[[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 -<>. - -_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 -<>. - -_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 <>. - -_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 <>. - -_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 <>. - -_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 <>. - - - -{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 <>. - -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 <>. - -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[] diff --git a/x-pack/docs/en/security/authentication/active-directory-realm.asciidoc b/x-pack/docs/en/security/authentication/active-directory-realm.asciidoc index f0f209d3fa3..2069176172e 100644 --- a/x-pack/docs/en/security/authentication/active-directory-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/active-directory-realm.asciidoc @@ -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]. \ No newline at end of file +{ref}/configuring-tls.html#tls-active-directory[Encrypting communications between {es} and Active Directory]. diff --git a/x-pack/docs/en/security/authentication/built-in-users.asciidoc b/x-pack/docs/en/security/authentication/built-in-users.asciidoc new file mode 100644 index 00000000000..2400643755a --- /dev/null +++ b/x-pack/docs/en/security/authentication/built-in-users.asciidoc @@ -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 +<>. + +`elastic`:: A built-in _superuser_. See <>. +`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 <>. 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 <>, +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 <>. +============================================================================= diff --git a/x-pack/docs/en/security/authentication/configuring-native-realm.asciidoc b/x-pack/docs/en/security/authentication/configuring-native-realm.asciidoc index 3c4f44fdfc9..3cda29c2c71 100644 --- a/x-pack/docs/en/security/authentication/configuring-native-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/configuring-native-realm.asciidoc @@ -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. diff --git a/x-pack/docs/en/security/authentication/file-realm.asciidoc b/x-pack/docs/en/security/authentication/file-realm.asciidoc index 937537ac1a1..cf6f5cacd1c 100644 --- a/x-pack/docs/en/security/authentication/file-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/file-realm.asciidoc @@ -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]. \ No newline at end of file +{ref}/configuring-file-realm.html[Configuring a file realm]. diff --git a/x-pack/docs/en/security/authentication/internal-users.asciidoc b/x-pack/docs/en/security/authentication/internal-users.asciidoc new file mode 100644 index 00000000000..53468363dc8 --- /dev/null +++ b/x-pack/docs/en/security/authentication/internal-users.asciidoc @@ -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 <>. diff --git a/x-pack/docs/en/security/authentication/ldap-realm.asciidoc b/x-pack/docs/en/security/authentication/ldap-realm.asciidoc index 4e280c313d8..8180b109226 100644 --- a/x-pack/docs/en/security/authentication/ldap-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/ldap-realm.asciidoc @@ -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 <> or in [[ldap-ssl]] ==== Setting up SSL Between Elasticsearch and LDAP -See {ref}/tls-ldap.html[Encrypting Communications Between {es} and LDAP]. \ No newline at end of file +See {ref}/tls-ldap.html[Encrypting Communications Between {es} and LDAP]. diff --git a/x-pack/docs/en/security/authentication/overview.asciidoc b/x-pack/docs/en/security/authentication/overview.asciidoc new file mode 100644 index 00000000000..ada5453c7a7 --- /dev/null +++ b/x-pack/docs/en/security/authentication/overview.asciidoc @@ -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 +<>. + +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[] diff --git a/x-pack/docs/en/security/authentication/pki-realm.asciidoc b/x-pack/docs/en/security/authentication/pki-realm.asciidoc index 47f9670d840..4fc91717f93 100644 --- a/x-pack/docs/en/security/authentication/pki-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/pki-realm.asciidoc @@ -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]. diff --git a/x-pack/docs/en/security/authentication/realms.asciidoc b/x-pack/docs/en/security/authentication/realms.asciidoc new file mode 100644 index 00000000000..7bd48c5c8f0 --- /dev/null +++ b/x-pack/docs/en/security/authentication/realms.asciidoc @@ -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 +<>. + +_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 +<>. + +_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 <>. + +_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 <>. + +_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 <>. + +_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 <>. + +{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 <>. + +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 <>. + +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`. diff --git a/x-pack/docs/en/security/authentication/saml-guide.asciidoc b/x-pack/docs/en/security/authentication/saml-guide.asciidoc index 70d8180cedb..d1f7961fecb 100644 --- a/x-pack/docs/en/security/authentication/saml-guide.asciidoc +++ b/x-pack/docs/en/security/authentication/saml-guide.asciidoc @@ -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 <> 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 `` 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 <> for more explanation of realms. + See <> for more explanation of realms. type:: The `type` must be `saml` order:: @@ -184,7 +184,7 @@ attribute.principal:: See <>. attribute.groups:: See <>. [[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 ``. 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. diff --git a/x-pack/docs/en/security/authentication/saml-realm.asciidoc b/x-pack/docs/en/security/authentication/saml-realm.asciidoc index bbf7d597b30..c05f82d341b 100644 --- a/x-pack/docs/en/security/authentication/saml-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/saml-realm.asciidoc @@ -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]. diff --git a/x-pack/docs/en/security/how-security-works.asciidoc b/x-pack/docs/en/security/how-security-works.asciidoc index 8cd7befc642..ae402dfe05e 100644 --- a/x-pack/docs/en/security/how-security-works.asciidoc +++ b/x-pack/docs/en/security/how-security-works.asciidoc @@ -9,62 +9,11 @@ layers. {security} provides the means to secure the Elastic cluster on several levels: - * User 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 <> - - [float] === Authorization diff --git a/x-pack/docs/en/security/index.asciidoc b/x-pack/docs/en/security/index.asciidoc index 6804a5d3a98..188353d01a3 100644 --- a/x-pack/docs/en/security/index.asciidoc +++ b/x-pack/docs/en/security/index.asciidoc @@ -98,7 +98,7 @@ include::getting-started.asciidoc[] include::how-security-works.asciidoc[] -include::authentication.asciidoc[] +include::authentication/overview.asciidoc[] include::authorization.asciidoc[]