Skip to content

Commit f9e5be2

Browse files
lcawllcawl
authored
[DOCS] Copies security source files from stack-docs (#47707)
1 parent e5947f2 commit f9e5be2

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+3644
-1
lines changed

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

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
[role="xpack"]
2+
[[active-directory-realm]]
3+
=== Active Directory user authentication
4+
5+
You can configure {stack} {security-features} to communicate with Active
6+
Directory to authenticate users. To integrate with Active Directory, you
7+
configure an `active_directory` realm and map Active Directory users and groups
8+
to roles in the <<mapping-roles, role mapping file>>.
9+
10+
See {ref}/configuring-ad-realm.html[Configuring an active directory realm].
11+
12+
The {security-features} use LDAP to communicate with Active Directory, so
13+
`active_directory` realms are similar to <<ldap-realm, `ldap` realms>>. Like
14+
LDAP directories, Active Directory stores users and groups hierarchically. The
15+
directory's hierarchy is built from containers such as the _organizational unit_
16+
(`ou`), _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+
The {security-features} supports only Active Directory security groups. You
24+
cannot map 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+
the {security-features} should interact with multiple Active Directory servers.
40+
Two modes of operation are supported: failover and load balancing.
41+
42+
See
43+
{ref}/security-settings.html#load-balancing[Load balancing and failover settings].
44+
45+
[[ad-settings]]
46+
==== Active Directory realm settings
47+
48+
See
49+
{ref}/security-settings.html#ref-ad-settings[Active Directory realm settings].
50+
51+
[[mapping-roles-ad]]
52+
==== Mapping Active Directory users and groups to roles
53+
54+
See {ref}/configuring-ad-realm.html[Configuring an Active Directory realm].
55+
56+
[[ad-user-metadata]]
57+
==== User metadata in Active Directory realms
58+
When a user is authenticated via an Active Directory realm, the following
59+
properties are populated in the user's _metadata_:
60+
61+
|=======================
62+
| Field | Description
63+
| `ldap_dn` | The distinguished name of the user.
64+
| `ldap_groups` | The distinguished name of each of the groups that were
65+
resolved for the user (regardless of whether those
66+
groups were mapped to a role).
67+
|=======================
68+
69+
This metadata is returned in the
70+
{ref}/security-api-authenticate.html[authenticate API] and can be used with
71+
<<templating-role-query, templated queries>> in roles.
72+
73+
Additional metadata can be extracted from the Active Directory server by configuring
74+
the `metadata` setting on the Active Directory realm.
75+
76+
[[active-directory-ssl]]
77+
==== Setting up SSL between Elasticsearch and Active Directory
78+
79+
See
80+
{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: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
[role="xpack"]
2+
[[built-in-users]]
3+
=== Built-in users
4+
5+
The {stack-security-features} provide built-in user credentials to help you get
6+
up and running. These users have a fixed set of privileges and cannot be
7+
authenticated until their passwords have been set. The `elastic` user can be
8+
used to <<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+
`apm_system`:: The user the APM server uses when storing monitoring information in {es}.
15+
`remote_monitoring_user`:: The user {metricbeat} uses when collecting and
16+
storing monitoring information in {es}. It has the `remote_monitoring_agent` and
17+
`remote_monitoring_collector` built-in roles.
18+
19+
20+
[float]
21+
[[built-in-user-explanation]]
22+
==== How the built-in users work
23+
These built-in users are stored in a special `.security` index, which is managed
24+
by {es}. If a built-in user is disabled or its password
25+
changes, the change is automatically reflected on each node in the cluster. If
26+
your `.security` index is deleted or restored from a snapshot, however, any
27+
changes you have applied are lost.
28+
29+
Although they share the same API, the built-in users are separate and distinct
30+
from users managed by the <<native-realm, native realm>>. Disabling the native
31+
realm will not have any effect on the built-in users. The built-in users can
32+
be disabled individually, using the
33+
{ref}/security-api-disable-user.html[disable users API].
34+
35+
[float]
36+
[[bootstrap-elastic-passwords]]
37+
==== The Elastic bootstrap password
38+
39+
When you install {es}, if the `elastic` user does not already have a password,
40+
it uses a default bootstrap password. The bootstrap password is a transient
41+
password that enables you to run the tools that set all the built-in user passwords.
42+
43+
By default, the bootstrap password is derived from a randomized `keystore.seed`
44+
setting, which is added to the keystore during installation. You do not need
45+
to know or change this bootstrap password. If you have defined a
46+
`bootstrap.password` setting in the keystore, however, that value is used instead.
47+
For more information about interacting with the keystore, see
48+
{ref}/secure-settings.html[Secure Settings].
49+
50+
NOTE: After you <<set-built-in-user-passwords,set passwords for the built-in users>>,
51+
in particular for the `elastic` user, there is no further use for the bootstrap
52+
password.
53+
54+
[float]
55+
[[set-built-in-user-passwords]]
56+
==== Setting built-in user passwords
57+
58+
You must set the passwords for all built-in users.
59+
60+
The +elasticsearch-setup-passwords+ tool is the simplest method to set the
61+
built-in users' passwords for the first time. It uses the `elastic` user's
62+
bootstrap password to run user management API requests. For example, you can run
63+
the command in an "interactive" mode, which prompts you to enter new passwords
64+
for the `elastic`, `kibana`, `logstash_system`, `beats_system`, `apm_system`,
65+
and `remote_monitoring_user` users:
66+
67+
[source,shell]
68+
--------------------------------------------------
69+
bin/elasticsearch-setup-passwords interactive
70+
--------------------------------------------------
71+
72+
For more information about the command options, see
73+
{ref}/setup-passwords.html[elasticsearch-setup-passwords].
74+
75+
IMPORTANT: After you set a password for the `elastic` user, the bootstrap
76+
password is no longer valid; you cannot run the `elasticsearch-setup-passwords`
77+
command a second time.
78+
79+
Alternatively, you can set the initial passwords for the built-in users by using
80+
the *Management > Users* page in {kib} or the
81+
{ref}/security-api-change-password.html[Change Password API]. These methods are
82+
more complex. You must supply the `elastic` user and its bootstrap password to
83+
log into {kib} or run the API. This requirement means that you cannot use the
84+
default bootstrap password that is derived from the `keystore.seed` setting.
85+
Instead, you must explicitly set a `bootstrap.password` setting in the keystore
86+
before you start {es}. For example, the following command prompts you to enter a
87+
new bootstrap password:
88+
89+
[source,shell]
90+
----------------------------------------------------
91+
bin/elasticsearch-keystore add "bootstrap.password"
92+
----------------------------------------------------
93+
94+
You can then start {es} and {kib} and use the `elastic` user and bootstrap
95+
password to log into {kib} and change the passwords. Alternatively, you can
96+
submit Change Password API requests for each built-in user. These methods are
97+
better suited for changing your passwords after the initial setup is complete,
98+
since at that point the bootstrap password is no longer required.
99+
100+
[[add-built-in-user-passwords]]
101+
102+
[float]
103+
[[add-built-in-user-kibana]]
104+
==== Adding built-in user passwords to {kib}
105+
106+
After the `kibana` user password is set, you need to update the {kib} server
107+
with the new password by setting `elasticsearch.password` in the `kibana.yml`
108+
configuration file:
109+
110+
[source,yaml]
111+
-----------------------------------------------
112+
elasticsearch.password: kibanapassword
113+
-----------------------------------------------
114+
115+
See {kibana-ref}/using-kibana-with-security.html[Configuring security in {kib}].
116+
117+
[float]
118+
[[add-built-in-user-logstash]]
119+
==== Adding built-in user passwords to {ls}
120+
121+
The `logstash_system` user is used internally within Logstash when
122+
monitoring is enabled for Logstash.
123+
124+
To enable this feature in Logstash, you need to update the Logstash
125+
configuration with the new password by setting `xpack.monitoring.elasticsearch.password` in
126+
the `logstash.yml` configuration file:
127+
128+
[source,yaml]
129+
----------------------------------------------------------
130+
xpack.monitoring.elasticsearch.password: logstashpassword
131+
----------------------------------------------------------
132+
133+
If you have upgraded from an older version of Elasticsearch,
134+
the `logstash_system` user may have defaulted to _disabled_ for security reasons.
135+
Once the password has been changed, you can enable the user via the following API call:
136+
137+
[source,js]
138+
---------------------------------------------------------------------
139+
PUT _xpack/security/user/logstash_system/_enable
140+
---------------------------------------------------------------------
141+
// CONSOLE
142+
143+
See {logstash-ref}/ls-security.html#ls-monitoring-user[Configuring credentials for {ls} monitoring].
144+
145+
[float]
146+
[[add-built-in-user-beats]]
147+
==== Adding built-in user passwords to Beats
148+
149+
The `beats_system` user is used internally within Beats when monitoring is
150+
enabled for Beats.
151+
152+
To enable this feature in Beats, you need to update the configuration for each
153+
of your beats to reference the correct username and password. For example:
154+
155+
[source,yaml]
156+
----------------------------------------------------------
157+
xpack.monitoring.elasticsearch.username: beats_system
158+
xpack.monitoring.elasticsearch.password: beatspassword
159+
----------------------------------------------------------
160+
161+
For example, see {metricbeat-ref}/monitoring.html[Monitoring {metricbeat}].
162+
163+
The `remote_monitoring_user` is used when {metricbeat} collects and stores
164+
monitoring data for the {stack}. See <<monitoring-production>>.
165+
166+
If you have upgraded from an older version of {es}, then you may not have set a
167+
password for the `beats_system` or `remote_monitoring_user` users. If this is
168+
the case, then you should use the *Management > Users* page in {kib} or the
169+
{ref}/security-api-change-password.html[Change Password API] to set a password
170+
for these users.
171+
172+
[float]
173+
[[add-built-in-user-apm]]
174+
==== Adding built-in user passwords to APM
175+
176+
The `apm_system` user is used internally within APM when monitoring is enabled.
177+
178+
To enable this feature in APM, you need to update the APM configuration file to
179+
reference the correct username and password. For example:
180+
181+
[source,yaml]
182+
----------------------------------------------------------
183+
xpack.monitoring.elasticsearch.username: apm_system
184+
xpack.monitoring.elasticsearch.password: apmserverpassword
185+
----------------------------------------------------------
186+
187+
//See {apm-server-ref}/monitoring.html[Monitoring APM Server].
188+
189+
If you have upgraded from an older version of {es}, then you may not have set a
190+
password for the `apm_system` user. If this is the case,
191+
then you should use the *Management > Users* page in {kib} or the
192+
{ref}/security-api-change-password.html[Change Password API] to set a password
193+
for these users.
194+
195+
[float]
196+
[[disabling-default-password]]
197+
==== Disabling default password functionality
198+
[IMPORTANT]
199+
=============================================================================
200+
This setting is deprecated. The elastic user no longer has a default password.
201+
The password must be set before the user can be used.
202+
See <<bootstrap-elastic-passwords>>.
203+
=============================================================================

‎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. The {stack}
10+
{security-features} do 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 realms you
19+
specify are used for authentication. To use the `file` realm as a fallback, you
20+
must include it in the realm chain.
21+
22+
To define users, the {security-features} provide the
23+
{ref}/users-command.html[users] command-line tool. This tool enables you to add
24+
and remove users, assign user 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: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
2+
include::overview.asciidoc[]
3+
include::built-in-users.asciidoc[]
4+
include::internal-users.asciidoc[]
5+
include::token-authentication-services.asciidoc[]
6+
include::realms.asciidoc[]
7+
include::realm-chains.asciidoc[]
8+
include::active-directory-realm.asciidoc[]
9+
include::file-realm.asciidoc[]
10+
include::ldap-realm.asciidoc[]
11+
include::native-realm.asciidoc[]
12+
include::pki-realm.asciidoc[]
13+
include::saml-realm.asciidoc[]
14+
include::kerberos-realm.asciidoc[]
15+
16+
include::{xes-repo-dir}/security/authentication/custom-realm.asciidoc[]
17+
18+
include::{xes-repo-dir}/security/authentication/anonymous-access.asciidoc[]
19+
20+
include::{xes-repo-dir}/security/authentication/user-cache.asciidoc[]
21+
22+
include::{xes-repo-dir}/security/authentication/saml-guide.asciidoc[]

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

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

0 commit comments

Comments
 (0)