Skip to content

Commit e03f90a

Browse files
lcawllcawl
authored
[6.3][DOCS] Copies security source files from stack-docs (#48103)
1 parent cffd9dd commit e03f90a

37 files changed

+2749
-0
lines changed

‎x-pack/docs/en/security/authentication/active-directory-realm.asciidoc‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
[role="xpack"]
2+
[[active-directory-realm]]
3+
=== Active Directory user authentication
4+
5+
You can configure {security} to communicate with Active Directory to authenticate
6+
users. To integrate with Active Directory, you configure an `active_directory`
7+
realm and map Active Directory users and groups to {security} roles in the
8+
<<mapping-roles, role mapping file>>.
9+
10+
See {ref}/configuring-ad-realm.html[Configuring an Active Directory Realm].
11+
12+
{security} uses LDAP to communicate with Active Directory, so `active_directory`
13+
realms are similar to <<ldap-realm, `ldap` realms>>. Like LDAP directories,
14+
Active Directory stores users and groups hierarchically. The directory's
15+
hierarchy is built from containers such as the _organizational unit_ (`ou`),
16+
_organization_ (`o`), and _domain controller_ (`dc`).
17+
18+
The path to an entry is a _Distinguished Name_ (DN) that uniquely identifies a
19+
user or group. User and group names typically have attributes such as a
20+
_common name_ (`cn`) or _unique ID_ (`uid`). A DN is specified as a string, for
21+
example `"cn=admin,dc=example,dc=com"` (white spaces are ignored).
22+
23+
{security} only supports Active Directory security groups. You cannot map
24+
distribution groups to roles.
25+
26+
NOTE: When you use Active Directory for authentication, the username entered by
27+
the user is expected to match the `sAMAccountName` or `userPrincipalName`,
28+
not the common name.
29+
30+
The Active Directory realm authenticates users using an LDAP bind request. After
31+
authenticating the user, the realm then searches to find the user's entry in
32+
Active Directory. Once the user has been found, the Active Directory realm then
33+
retrieves the user's group memberships from the `tokenGroups` attribute on the
34+
user's entry in Active Directory.
35+
36+
[[ad-load-balancing]]
37+
==== Load balancing and failover
38+
The `load_balance.type` setting can be used at the realm level to configure how
39+
{security} should interact with multiple Active Directory servers. Two modes of
40+
operation are supported: failover and load balancing.
41+
42+
See {ref}/security-settings.html#load-balancing[Load Balancing and Failover Settings].
43+
44+
[[ad-settings]]
45+
==== Active Directory realm settings
46+
47+
See {ref}/security-settings.html#ref-ad-settings[Active Directory Realm Settings].
48+
49+
[[mapping-roles-ad]]
50+
==== Mapping Active Directory users and groups to roles
51+
52+
See {ref}/configuring-ad-realm.html[Configuring an Active Directory realm].
53+
54+
[[ad-user-metadata]]
55+
==== User metadata in Active Directory realms
56+
When a user is authenticated via an Active Directory realm, the following
57+
properties are populated in the user's _metadata_:
58+
59+
|=======================
60+
| Field | Description
61+
| `ldap_dn` | The distinguished name of the user.
62+
| `ldap_groups` | The distinguished name of each of the groups that were
63+
resolved for the user (regardless of whether those
64+
groups were mapped to a role).
65+
|=======================
66+
67+
This metadata is returned in the
68+
{ref}/security-api-authenticate.html[authenticate API] and can be used with
69+
<<templating-role-query, templated queries>> in roles.
70+
71+
Additional metadata can be extracted from the Active Directory server by configuring
72+
the `metadata` setting on the Active Directory realm.
73+
74+
[[active-directory-ssl]]
75+
==== Setting up SSL between Elasticsearch and Active Directory
76+
77+
See
78+
{ref}/configuring-tls.html#tls-active-directory[Encrypting communications between {es} and Active Directory].

‎x-pack/docs/en/security/authentication/built-in-users.asciidoc‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
[role="xpack"]
2+
[[built-in-users]]
3+
=== Built-in users
4+
5+
{security} provides built-in user credentials to help you get up and running.
6+
These users have a fixed set of privileges and cannot be authenticated until their
7+
passwords have been set. The `elastic` user can be used to
8+
<<set-built-in-user-passwords,set all of the built-in user passwords>>.
9+
10+
`elastic`:: A built-in _superuser_. See <<built-in-roles>>.
11+
`kibana`:: The user Kibana uses to connect and communicate with Elasticsearch.
12+
`logstash_system`:: The user Logstash uses when storing monitoring information in Elasticsearch.
13+
`beats_system`:: The user the Beats use when storing monitoring information in Elasticsearch.
14+
15+
16+
[float]
17+
[[built-in-user-explanation]]
18+
==== How the built-in users work
19+
These built-in users are stored within a special `.security` index managed by
20+
{security}.
21+
This means that, if the password is changed, or a user is disabled, then that
22+
change is automatically reflected on each node in the cluster. It also means
23+
that if your `.security` index is deleted, or restored from a snapshot, then
24+
any changes you have applied will be lost.
25+
26+
Although they share the same API, the built-in users are separate and distinct
27+
from users managed by the <<native-realm, native realm>>. Disabling the native
28+
realm will not have any effect on the built-in users. The built-in users can
29+
be disabled individually, using the
30+
{ref}/security-api-disable-user.html[disable users API].
31+
32+
[float]
33+
[[bootstrap-elastic-passwords]]
34+
==== The Elastic bootstrap password
35+
36+
When you install {es}, if the `elastic` user does not already have a password,
37+
it uses a default bootstrap password. The bootstrap password is a transient
38+
password that enables you to run the tools that set all the built-in user passwords.
39+
40+
By default, the bootstrap password is derived from a randomized `keystore.seed`
41+
setting, which is added to the keystore during installation. You do not need
42+
to know or change this bootstrap password. If you have defined a
43+
`bootstrap.password` setting in the keystore, however, that value is used instead.
44+
For more information about interacting with the keystore, see
45+
{ref}/secure-settings.html[Secure Settings].
46+
47+
NOTE: After you <<set-built-in-user-passwords,set passwords for the built-in users>>,
48+
in particular for the `elastic` user, there is no further use for the bootstrap
49+
password.
50+
51+
[float]
52+
[[set-built-in-user-passwords]]
53+
==== Setting built-in user passwords
54+
55+
You must set the passwords for all built-in users.
56+
57+
The +elasticsearch-setup-passwords+ tool is the simplest method to set the
58+
built-in users' passwords for the first time. It uses the `elastic` user's
59+
bootstrap password to run user management API requests. For example, you can run
60+
the command in an "interactive" mode, which prompts you to enter new passwords
61+
for the `elastic`, `kibana`, `logstash_system`, and `beats_system` users:
62+
63+
[source,shell]
64+
--------------------------------------------------
65+
bin/elasticsearch-setup-passwords interactive
66+
--------------------------------------------------
67+
68+
For more information about the command options, see
69+
{ref}/setup-passwords.html[elasticsearch-setup-passwords].
70+
71+
IMPORTANT: After you set a password for the `elastic` user, the bootstrap
72+
password is no longer valid; you cannot run the `elasticsearch-setup-passwords`
73+
command a second time.
74+
75+
Alternatively, you can set the initial passwords for the built-in users by using
76+
the *Management > Users* page in {kib} or the
77+
{ref}/security-api-change-password.html[Change Password API]. These methods are
78+
more complex. You must supply the `elastic` user and its bootstrap password to
79+
log into {kib} or run the API. This requirement means that you cannot use the
80+
default bootstrap password that is derived from the `keystore.seed` setting.
81+
Instead, you must explicitly set a `bootstrap.password` setting in the keystore
82+
before you start {es}. For example, the following command prompts you to enter a
83+
new bootstrap password:
84+
85+
[source,shell]
86+
----------------------------------------------------
87+
bin/elasticsearch-keystore add "bootstrap.password"
88+
----------------------------------------------------
89+
90+
You can then start {es} and {kib} and use the `elastic` user and bootstrap
91+
password to log into {kib} and change the passwords. Alternatively, you can
92+
submit Change Password API requests for each built-in user. These methods are
93+
better suited for changing your passwords after the initial setup is complete,
94+
since at that point the bootstrap password is no longer required.
95+
96+
[float]
97+
[[add-built-in-user-passwords]]
98+
==== Adding Built-in User Passwords To {kib}, Logstash, and Beats
99+
100+
After the `kibana` user password is set, you need to update the {kib} server
101+
with the new password by setting `elasticsearch.password` in the `kibana.yml`
102+
configuration file:
103+
104+
[source,yaml]
105+
-----------------------------------------------
106+
elasticsearch.password: kibanapassword
107+
-----------------------------------------------
108+
109+
The `logstash_system` user is used internally within Logstash when
110+
monitoring is enabled for Logstash.
111+
112+
To enable this feature in Logstash, you need to update the Logstash
113+
configuration with the new password by setting `xpack.monitoring.elasticsearch.password` in
114+
the `logstash.yml` configuration file:
115+
116+
[source,yaml]
117+
----------------------------------------------------------
118+
xpack.monitoring.elasticsearch.password: logstashpassword
119+
----------------------------------------------------------
120+
121+
If you have upgraded from an older version of {es},
122+
the `logstash_system` user may have defaulted to _disabled_ for security reasons.
123+
Once the password has been changed, you can enable the user via the following API call:
124+
125+
[source,js]
126+
---------------------------------------------------------------------
127+
PUT _xpack/security/user/logstash_system/_enable
128+
---------------------------------------------------------------------
129+
// CONSOLE
130+
131+
The `beats_system` user is used internally within Beats when monitoring is
132+
enabled for Beats.
133+
134+
To enable this feature in Beats, you need to update the configuration for each
135+
of your beats to reference the correct username and password. For example:
136+
137+
[source,yaml]
138+
----------------------------------------------------------
139+
xpack.monitoring.elasticsearch.username: beats_system
140+
xpack.monitoring.elasticsearch.password: beatspassword
141+
----------------------------------------------------------
142+
143+
If you have upgraded from an older version of {es}, then you may not have set a
144+
password for the `beats_system` user. If this is the case, then you should use
145+
the *Management > Users* page in {kib} or the
146+
{ref}/security-api-change-password.html[Change Password API] to set a password
147+
for this user.
148+
149+
[float]
150+
[[disabling-default-password]]
151+
==== Disabling default password functionality
152+
[IMPORTANT]
153+
=============================================================================
154+
This setting is deprecated. The elastic user no longer has a default password.
155+
The password must be set before the user can be used.
156+
See <<bootstrap-elastic-passwords>>.
157+
=============================================================================

‎x-pack/docs/en/security/authentication/file-realm.asciidoc‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
[role="xpack"]
2+
[[file-realm]]
3+
=== File-based user authentication
4+
5+
You can manage and authenticate users with the built-in `file` realm.
6+
With the `file` realm, users are defined in local files on each node in the cluster.
7+
8+
IMPORTANT: As the administrator of the cluster, it is your responsibility to
9+
ensure the same users are defined on every node in the cluster.
10+
{security} does not deliver any mechanism to guarantee this.
11+
12+
The `file` realm is primarily supported to serve as a fallback/recovery realm. It
13+
is mostly useful in situations where all users locked themselves out of the system
14+
(no one remembers their username/password). In this type of scenarios, the `file`
15+
realm is your only way out - you can define a new `admin` user in the `file` realm
16+
and use it to log in and reset the credentials of all other users.
17+
18+
IMPORTANT: When you configure realms in `elasticsearch.yml`, only the
19+
realms you specify are used for authentication. To use the
20+
`file` realm as a fallback, you must include it in the realm chain.
21+
22+
To define users, {security} provides the {ref}/users-command.html[users]
23+
command-line tool. This tool enables you to add and remove users, assign user
24+
roles, and manage user passwords.
25+
26+
For more information, see
27+
{ref}/configuring-file-realm.html[Configuring a file realm].

‎x-pack/docs/en/security/authentication/index.asciidoc‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
2+
include::overview.asciidoc[]
3+
include::built-in-users.asciidoc[]
4+
include::internal-users.asciidoc[]
5+
include::realms.asciidoc[]
6+
include::active-directory-realm.asciidoc[]
7+
include::file-realm.asciidoc[]
8+
include::ldap-realm.asciidoc[]
9+
include::native-realm.asciidoc[]
10+
include::pki-realm.asciidoc[]
11+
include::saml-realm.asciidoc[]
12+
13+
include::{xes-repo-dir}/security/authentication/custom-realm.asciidoc[]
14+
15+
include::{xes-repo-dir}/security/authentication/anonymous-access.asciidoc[]
16+
17+
include::{xes-repo-dir}/security/authentication/user-cache.asciidoc[]
18+
19+
include::{xes-repo-dir}/security/authentication/saml-guide.asciidoc[]

‎x-pack/docs/en/security/authentication/internal-users.asciidoc‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
[role="xpack"]
2+
[[internal-users]]
3+
=== Internal users
4+
5+
{security} has three _internal_ users (`_system`, `_xpack`, and `_xpack_security`)
6+
that are responsible for the operations that take place inside an {es} cluster.
7+
8+
These users are only used by requests that originate from within the cluster.
9+
For this reason, they cannot be used to authenticate against the API and there
10+
is no password to manage or reset.
11+
12+
From time-to-time you may find a reference to one of these users inside your
13+
logs, including <<auditing, audit logs>>.

‎x-pack/docs/en/security/authentication/ldap-realm.asciidoc‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
[role="xpack"]
2+
[[ldap-realm]]
3+
=== LDAP user authentication
4+
5+
You can configure {security} to communicate with a Lightweight Directory Access
6+
Protocol (LDAP) server to authenticate users. To integrate with LDAP, you
7+
configure an `ldap` realm and map LDAP groups to user roles in the
8+
<<mapping-roles, role mapping file>>.
9+
10+
LDAP stores users and groups hierarchically, similar to the way folders are
11+
grouped in a file system. An LDAP directory's hierarchy is built from containers
12+
such as the _organizational unit_ (`ou`), _organization_ (`o`), and
13+
_domain controller_ (`dc`).
14+
15+
The path to an entry is a _Distinguished Name_ (DN) that uniquely identifies a
16+
user or group. User and group names typically have attributes such as a
17+
_common name_ (`cn`) or _unique ID_ (`uid`). A DN is specified as a string,
18+
for example `"cn=admin,dc=example,dc=com"` (white spaces are ignored).
19+
20+
The `ldap` realm supports two modes of operation, a user search mode
21+
and a mode with specific templates for user DNs.
22+
23+
[[ldap-user-search]]
24+
==== User search mode and user DN templates mode
25+
26+
See {ref}/configuring-ldap-realm.html[Configuring an LDAP Realm].
27+
28+
[[ldap-load-balancing]]
29+
==== Load balancing and failover
30+
The `load_balance.type` setting can be used at the realm level to configure how
31+
{security} should interact with multiple LDAP servers. {security} supports both
32+
failover and load balancing modes of operation.
33+
34+
See {ref}/security-settings.html#load-balancing[Load Balancing and Failover Settings].
35+
36+
[[ldap-settings]]
37+
==== LDAP realm settings
38+
39+
See {ref}/security-settings.html#ref-ldap-settings[LDAP Realm Settings].
40+
41+
[[mapping-roles-ldap]]
42+
==== Mapping LDAP groups to roles
43+
44+
An integral part of a realm authentication process is to resolve the roles
45+
associated with the authenticated user. Roles define the privileges a user has
46+
in the cluster.
47+
48+
Since with the `ldap` realm the users are managed externally in the LDAP server,
49+
the expectation is that their roles are managed there as well. If fact, LDAP
50+
supports the notion of groups, which often represent user roles for different
51+
systems in the organization.
52+
53+
The `ldap` realm enables you to map LDAP users to to roles via their LDAP
54+
groups, or other metadata. This role mapping can be configured via the
55+
{ref}/security-api-put-role-mapping.html[add role mapping API] or by using a file stored
56+
on each node. When a user authenticates with LDAP, the privileges
57+
for that user are the union of all privileges defined by the roles to which
58+
the user is mapped. For more information, see
59+
{ref}/configuring-ldap-realm.html[Configuring an LDAP Realm].
60+
61+
[[ldap-user-metadata]]
62+
==== User metadata in LDAP realms
63+
When a user is authenticated via an LDAP realm, the following properties are
64+
populated in the user's _metadata_:
65+
66+
|=======================
67+
| Field | Description
68+
| `ldap_dn` | The distinguished name of the user.
69+
| `ldap_groups` | The distinguished name of each of the groups that were
70+
resolved for the user (regardless of whether those
71+
groups were mapped to a role).
72+
|=======================
73+
74+
This metadata is returned in the
75+
{ref}/security-api-authenticate.html[authenticate API], and can be used with
76+
<<templating-role-query, templated queries>> in roles.
77+
78+
Additional fields can be included in the user's metadata by configuring
79+
the `metadata` setting on the LDAP realm. This metadata is available for use
80+
with the <<mapping-roles-api, role mapping API>> or in
81+
<<templating-role-query, templated role queries>>.
82+
83+
[[ldap-ssl]]
84+
==== Setting up SSL Between Elasticsearch and LDAP
85+
86+
See {ref}/configuring-tls.html#tls-ldap[Encrypting Communications Between {es} and LDAP].

0 commit comments

Comments
 (0)