Skip to content

Commit e86b2da

Browse files
lcawllcawl
authored
[7.4][DOCS] Copies security source files from stack-docs (#47613)
1 parent 97b86c0 commit e86b2da

Some content is hidden

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

48 files changed

+2244
-75
lines changed

‎docs/reference/monitoring/production.asciidoc

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ For example, the
7272
following request creates a `remote_monitor` user that has the
7373
`remote_monitoring_agent` role:
7474

75-
[source, sh]
75+
[source,console]
7676
---------------------------------------------------------------
7777
POST /_security/user/remote_monitor
7878
{
@@ -81,7 +81,6 @@ POST /_security/user/remote_monitor
8181
"full_name" : "Internal Agent For Remote Monitoring"
8282
}
8383
---------------------------------------------------------------
84-
// CONSOLE
8584
// TEST[skip:needs-gold+-license]
8685

8786
Alternatively, use the `remote_monitoring_user` {stack-ov}/built-in-users.html[built-in user].

‎x-pack/docs/en/security/auditing/output-logfile.asciidoc

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ Alternatively, use the
2323
{ref}/cluster-update-settings.html[cluster update settings API] to dynamically
2424
configure the logger:
2525

26-
[source,js]
26+
[source,console]
2727
--------------------------------------------------
2828
PUT /_cluster/settings
2929
{
@@ -32,7 +32,6 @@ PUT /_cluster/settings
3232
}
3333
}
3434
--------------------------------------------------
35-
// CONSOLE
3635

3736
NOTE: If you overwrite the `log4j2.properties` and do not specify appenders for
3837
any of the audit trails, audit events are forwarded to the root appender, which

‎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,console]
138+
---------------------------------------------------------------------
139+
PUT _security/user/logstash_system/_enable
140+
---------------------------------------------------------------------
141+
142+
See {logstash-ref}/ls-security.html#ls-monitoring-user[Configuring credentials for {ls} monitoring].
143+
144+
[float]
145+
[[add-built-in-user-beats]]
146+
==== Adding built-in user passwords to Beats
147+
148+
The `beats_system` user is used internally within Beats when monitoring is
149+
enabled for Beats.
150+
151+
To enable this feature in Beats, you need to update the configuration for each
152+
of your beats to reference the correct username and password. For example:
153+
154+
[source,yaml]
155+
----------------------------------------------------------
156+
xpack.monitoring.elasticsearch.username: beats_system
157+
xpack.monitoring.elasticsearch.password: beatspassword
158+
----------------------------------------------------------
159+
160+
For example, see {metricbeat-ref}/monitoring.html[Monitoring {metricbeat}].
161+
162+
The `remote_monitoring_user` is used when {metricbeat} collects and stores
163+
monitoring data for the {stack}. See <<monitoring-production>>.
164+
165+
If you have upgraded from an older version of {es}, then you may not have set a
166+
password for the `beats_system` or `remote_monitoring_user` users. If this is
167+
the case, then you should use the *Management > Users* page in {kib} or the
168+
{ref}/security-api-change-password.html[Change Password API] to set a password
169+
for these users.
170+
171+
[float]
172+
[[add-built-in-user-apm]]
173+
==== Adding built-in user passwords to APM
174+
175+
The `apm_system` user is used internally within APM when monitoring is enabled.
176+
177+
To enable this feature in APM, you need to update the
178+
{apm-server-ref-70}/configuring-howto-apm-server.html[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-70}/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/configuring-active-directory-realm.asciidoc

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -184,7 +184,8 @@ Directory `admins` group to both the `monitoring` and `user` roles, maps the
184184
role.
185185

186186
Configured via the role-mapping API:
187-
[source,js]
187+
188+
[source,console]
188189
--------------------------------------------------
189190
PUT /_security/role_mapping/admins
190191
{
@@ -195,10 +196,9 @@ PUT /_security/role_mapping/admins
195196
"enabled": true
196197
}
197198
--------------------------------------------------
198-
// CONSOLE
199199
<1> The Active Directory distinguished name (DN) of the `admins` group.
200200

201-
[source,js]
201+
[source,console]
202202
--------------------------------------------------
203203
PUT /_security/role_mapping/basic_users
204204
{
@@ -214,7 +214,6 @@ PUT /_security/role_mapping/basic_users
214214
"enabled": true
215215
}
216216
--------------------------------------------------
217-
// CONSOLE
218217
<1> The Active Directory distinguished name (DN) of the `users` group.
219218
<2> The Active Directory distinguished name (DN) of the user `John Doe`.
220219

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

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -151,7 +151,7 @@ users by their `username` field.
151151
The following example uses the role mapping API to map `user@REALM` to the roles
152152
`monitoring` and `user`:
153153

154-
[source,js]
154+
[source,console]
155155
--------------------------------------------------
156156
POST /_security/role_mapping/kerbrolemapping
157157
{
@@ -162,7 +162,6 @@ POST /_security/role_mapping/kerbrolemapping
162162
}
163163
}
164164
--------------------------------------------------
165-
// CONSOLE
166165

167166
In case you want to support Kerberos cross realm authentication you may
168167
need to map roles based on the Kerberos realm name. For such scenarios

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

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -145,7 +145,8 @@ names. For example, the following mapping configuration maps the LDAP
145145
`users` group to the `user` role.
146146

147147
Configured via the role-mapping API:
148-
[source,js]
148+
149+
[source,console]
149150
--------------------------------------------------
150151
PUT /_security/role_mapping/admins
151152
{
@@ -156,10 +157,9 @@ PUT /_security/role_mapping/admins
156157
"enabled": true
157158
}
158159
--------------------------------------------------
159-
// CONSOLE
160160
<1> The LDAP distinguished name (DN) of the `admins` group.
161161

162-
[source,js]
162+
[source,console]
163163
--------------------------------------------------
164164
PUT /_security/role_mapping/basic_users
165165
{
@@ -170,7 +170,6 @@ PUT /_security/role_mapping/basic_users
170170
"enabled": true
171171
}
172172
--------------------------------------------------
173-
// CONSOLE
174173
<1> The LDAP distinguished name (DN) of the `users` group.
175174

176175
Or, alternatively, configured via the role-mapping file:

0 commit comments

Comments
 (0)