Skip to content

Commit 5d33aea

Browse files
lcawllcawl
committed
[DOCS] Adds PKI realm configuration details (#30225)
1 parent 734562f commit 5d33aea

File tree

3 files changed

+182
-166
lines changed

3 files changed

+182
-166
lines changed

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

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
[role="xpack"]
2+
[[configuring-pki-realm]]
3+
=== Configuring a PKI realm
4+
5+
You can configure {security} to use Public Key Infrastructure (PKI) certificates
6+
to authenticate users in {es}. This requires clients to present X.509
7+
certificates.
8+
9+
NOTE: You cannot use PKI certificates to authenticate users in {kib}.
10+
11+
To use PKI in {es}, you configure a PKI realm, enable client authentication on
12+
the desired network layers (transport or http), and map the Distinguished Names
13+
(DNs) from the user certificates to {security} roles in the role mapping file.
14+
15+
You can also use a combination of PKI and username/password authentication. For
16+
example, you can enable SSL/TLS on the transport layer and define a PKI realm to
17+
require transport clients to authenticate with X.509 certificates, while still
18+
authenticating HTTP traffic using username and password credentials. You can
19+
also set `xpack.security.transport.ssl.client_authentication` to `optional` to
20+
allow clients without certificates to authenticate with other credentials.
21+
22+
IMPORTANT: You must enable SSL/TLS and enable client authentication to use PKI.
23+
24+
For more information, see {xpack-ref}/pki-realm.html[PKI User Authentication].
25+
26+
. Add a realm configuration of type `pki` to `elasticsearch.yml` under the
27+
`xpack.security.authc.realms` namespace. At a minimum, you must set the realm
28+
`type` to `pki`. If you are configuring multiple realms, you should also
29+
explicitly set the `order` attribute. See <<ref-pki-settings>> for all of the
30+
options you can set for a `pki` realm.
31+
+
32+
--
33+
For example, the following snippet shows the most basic `pki` realm configuration:
34+
35+
[source, yaml]
36+
------------------------------------------------------------
37+
xpack:
38+
security:
39+
authc:
40+
realms:
41+
pki1:
42+
type: pki
43+
------------------------------------------------------------
44+
45+
With this configuration, any certificate trusted by the SSL/TLS layer is accepted
46+
for authentication. The username is the common name (CN) extracted from the DN
47+
of the certificate.
48+
49+
IMPORTANT: When you configure realms in `elasticsearch.yml`, only the
50+
realms you specify are used for authentication. If you also want to use the
51+
`native` or `file` realms, you must include them in the realm chain.
52+
53+
If you want to use something other than the CN of the DN as the username, you
54+
can specify a regex to extract the desired username. For example, the regex in
55+
the following configuration extracts the email address from the DN:
56+
57+
[source, yaml]
58+
------------------------------------------------------------
59+
xpack:
60+
security:
61+
authc:
62+
realms:
63+
pki1:
64+
type: pki
65+
username_pattern: "EMAILADDRESS=(.*?)(?:,|$)"
66+
------------------------------------------------------------
67+
--
68+
69+
. Restart {es}.
70+
71+
. <<configuring-tls,Enable SSL/TLS>>.
72+
73+
. Enable client authentication on the desired network layers (transport or http).
74+
+
75+
--
76+
//TBD: This step might need to be split into a separate topic with additional details
77+
//about setting up client authentication.
78+
The PKI realm relies on the TLS settings of the node's network interface. The
79+
realm can be configured to be more restrictive than the underlying network
80+
connection - that is, it is possible to configure the node such that some
81+
connections are accepted by the network interface but then fail to be
82+
authenticated by the PKI realm. However, the reverse is not possible. The PKI
83+
realm cannot authenticate a connection that has been refused by the network
84+
interface.
85+
86+
In particular this means:
87+
88+
* The transport or http interface must request client certificates by setting
89+
`client_authentication` to `optional` or `required`.
90+
* The interface must _trust_ the certificate that is presented by the client
91+
by configuring either the `truststore` or `certificate_authorities` paths,
92+
or by setting `verification_mode` to `none`. See
93+
<<ssl-tls-settings,`xpack.ssl.verification_mode`>> for an explanation of this
94+
setting.
95+
* The _protocols_ supported by the interface must be compatible with those
96+
used by the client.
97+
98+
The relevant network interface (transport or http) must be configured to trust
99+
any certificate that is to be used within the PKI realm. However, it possible to
100+
configure the PKI realm to trust only a _subset_ of the certificates accepted
101+
by the network interface. This is useful when the SSL/TLS layer trusts clients
102+
with certificates that are signed by a different CA than the one that signs your
103+
users' certificates.
104+
105+
To configure the PKI realm with its own truststore, specify the `truststore.path`
106+
option. For example:
107+
108+
[source, yaml]
109+
------------------------------------------------------------
110+
xpack:
111+
security:
112+
authc:
113+
realms:
114+
pki1:
115+
type: pki
116+
truststore:
117+
path: "/path/to/pki_truststore.jks"
118+
password: "x-pack-test-password"
119+
------------------------------------------------------------
120+
121+
The `certificate_authorities` option can be used as an alternative to the
122+
`truststore.path` setting.
123+
--
124+
125+
. Map roles for PKI users.
126+
+
127+
--
128+
You map roles for PKI users through the
129+
<<security-api-role-mapping,role-mapping API>> or by using a file stored on
130+
each node. When a user authenticates against a PKI realm, the privileges for
131+
that user are the union of all privileges defined by the roles to which the
132+
user is mapped.
133+
134+
You identify a user by the distinguished name in their certificate.
135+
For example, the following mapping configuration maps `John Doe` to the
136+
`user` role:
137+
138+
Using the role-mapping API:
139+
[source,js]
140+
--------------------------------------------------
141+
PUT _xpack/security/role_mapping/users
142+
{
143+
"roles" : [ "user" ],
144+
"rules" : { "field" : {
145+
"dn" : "cn=John Doe,ou=example,o=com" <1>
146+
} },
147+
"enabled": true
148+
}
149+
--------------------------------------------------
150+
// CONSOLE
151+
<1> The distinguished name (DN) of a PKI user.
152+
153+
Or, alternatively, configured in a role-mapping file:
154+
[source, yaml]
155+
------------------------------------------------------------
156+
user: <1>
157+
- "cn=John Doe,ou=example,o=com" <2>
158+
------------------------------------------------------------
159+
<1> The name of a role.
160+
<2> The distinguished name (DN) of a PKI user.
161+
162+
The disinguished name for a PKI user follows X.500 naming conventions which
163+
place the most specific fields (like `cn` or `uid`) at the beginning of the
164+
name, and the most general fields (like `o` or `dc`) at the end of the name.
165+
Some tools, such as _openssl_, may print out the subject name in a different
166+
format.
167+
168+
One way that you can determine the correct DN for a certificate is to use the
169+
<<security-api-authenticate,authenticate API>> (use the relevant PKI
170+
certificate as the means of authentication) and inspect the metadata field in
171+
the result. The user's distinguished name will be populated under the `pki_dn`
172+
key. You can also use the authenticate API to validate your role mapping.
173+
174+
For more information, see
175+
{xpack-ref}/mapping-roles.html[Mapping Users and Groups to Roles].
176+
--

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

Lines changed: 4 additions & 166 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
[[pki-realm]]
2-
=== PKI User Authentication
2+
=== PKI user authentication
33

44
You can configure {security} to use Public Key Infrastructure (PKI) certificates
55
to authenticate users in {es}. This requires clients to present X.509
@@ -12,171 +12,9 @@ the desired network layers (transport or http), and map the Distinguished Names
1212
(DNs) from the user certificates to {security} roles in the
1313
<<mapping-roles, role mapping file>>.
1414

15-
You can also use a combination of PKI and username/password authentication. For
16-
example, you can enable SSL/TLS on the transport layer and define a PKI realm to
17-
require transport clients to authenticate with X.509 certificates, while still
18-
authenticating HTTP traffic using username and password credentials. You can also set
19-
`xpack.security.transport.ssl.client_authentication` to `optional` to allow clients without
20-
certificates to authenticate with other credentials.
21-
22-
IMPORTANT: You must enable SSL/TLS and enabled client authentication to use PKI.
23-
For more information, see <<ssl-tls, Setting Up SSL/TLS on a Cluster>>.
24-
25-
==== PKI Realm Configuration
26-
27-
Like other realms, you configure options for a `pki` realm under the
28-
`xpack.security.authc.realms` namespace in `elasticsearch.yml`.
29-
30-
To configure a `pki` realm:
31-
32-
. Add a realm configuration of type `pki` to `elasticsearch.yml` under the
33-
`xpack.security.authc.realms` namespace. At a minimum, you must set the realm `type` to
34-
`pki`. If you are configuring multiple realms, you should also explicitly set
35-
the `order` attribute. See <<pki-settings>> for all of the options you can set
36-
for a `pki` realm.
37-
+
38-
For example, the following snippet shows the most basic `pki` realm configuration:
39-
+
40-
[source, yaml]
41-
------------------------------------------------------------
42-
xpack:
43-
security:
44-
authc:
45-
realms:
46-
pki1:
47-
type: pki
48-
------------------------------------------------------------
49-
+
50-
With this configuration, any certificate trusted by the SSL/TLS layer is accepted
51-
for authentication. The username is the common name (CN) extracted from the DN
52-
of the certificate.
53-
+
54-
IMPORTANT: When you configure realms in `elasticsearch.yml`, only the
55-
realms you specify are used for authentication. If you also want to use the
56-
`native` or `file` realms, you must include them in the realm chain.
57-
+
58-
If you want to use something other than the CN of the DN as the username, you
59-
can specify a regex to extract the desired username. For example, the regex in
60-
the following configuration extracts the email address from the DN:
61-
+
62-
[source, yaml]
63-
------------------------------------------------------------
64-
xpack:
65-
security:
66-
authc:
67-
realms:
68-
pki1:
69-
type: pki
70-
username_pattern: "EMAILADDRESS=(.*?)(?:,|$)"
71-
------------------------------------------------------------
72-
+
73-
. Restart Elasticsearch.
74-
75-
[[pki-ssl-config]]
76-
==== PKI and SSL Settings
77-
78-
The PKI realm relies on the SSL settings of the node's network interface
79-
(transport or http). The realm can be configured to be more restrictive than
80-
the underlying network connection - that is, it is possible to configure the
81-
node such that some connections are accepted by the network interface but then
82-
fail to be authenticated by the PKI realm. However the reverse is not possible
83-
- the PKI realm cannot authenticate a connection that has been refused by the
84-
network interface.
85-
86-
In particular this means:
87-
88-
* The transport or http interface must request client certificates by setting
89-
`client_authentication` to `optional` or `required`.
90-
* The interface must _trust_ the certificate that is presented by the client
91-
by configuring either the `truststore` or `certificate_authorities` paths,
92-
or by setting `verification_mode` to `none`.
93-
+
94-
See {ref}/security-settings.html#ssl-tls-settings[`xpack.ssl.verification_mode`]
95-
for an explanation of this setting.
96-
97-
* The _protocols_ supported by the interface must be compatible with those
98-
used by the client.
99-
100-
101-
The relevant network interface (transport or http) must be configured to trust
102-
any certificate that is to be used within the PKI realm. However it possible to
103-
configure the PKI realm to trust only a _subset_ of the certificates accepted
104-
by the network interface.
105-
This is useful when the SSL/TLS layer trusts clients with certificates that are
106-
signed by a different CA than the one that signs your users' certificates.
107-
108-
To configure the PKI realm with its own truststore, specify the
109-
`truststore.path` option as below:
110-
111-
[source, yaml]
112-
------------------------------------------------------------
113-
xpack:
114-
security:
115-
authc:
116-
realms:
117-
pki1:
118-
type: pki
119-
truststore:
120-
path: "/path/to/pki_truststore.jks"
121-
password: "x-pack-test-password"
122-
------------------------------------------------------------
123-
124-
The `certificate_authorities` option may be used as an alternative to the
125-
`truststore.path` setting.
126-
15+
See {ref}/configuring-pki-realm.html[Configuring a PKI realm].
12716

12817
[[pki-settings]]
129-
===== PKI Realm Settings
130-
131-
See {ref}/security-settings.html#ref-pki-settings[PKI Realm Settings].
132-
133-
[[assigning-roles-pki]]
134-
==== Mapping Roles for PKI Users
135-
136-
You map roles for PKI users through the
137-
{ref}/security-api-role-mapping.html[role-mapping API], or by using a file stored on
138-
each node. When a user authenticates against a PKI realm, the privileges for
139-
that user are the union of all privileges defined by the roles to which the
140-
user is mapped.
141-
142-
You identify a user by the distinguished name in their certificate.
143-
For example, the following mapping configuration maps `John Doe` to the
144-
`user` role:
145-
146-
Using the role-mapping API:
147-
[source,js]
148-
--------------------------------------------------
149-
PUT _xpack/security/role_mapping/users
150-
{
151-
"roles" : [ "user" ],
152-
"rules" : { "field" : {
153-
"dn" : "cn=John Doe,ou=example,o=com" <1>
154-
} },
155-
"enabled": true
156-
}
157-
--------------------------------------------------
158-
// CONSOLE
159-
<1> The distinguished name (DN) of a PKI user.
160-
161-
Or, alternatively, configured in a role-mapping file:
162-
[source, yaml]
163-
------------------------------------------------------------
164-
user: <1>
165-
- "cn=John Doe,ou=example,o=com" <2>
166-
------------------------------------------------------------
167-
<1> The name of a role.
168-
<2> The distinguished name (DN) of a PKI user.
169-
170-
The disinguished name for a PKI user follows X.500 naming conventions which
171-
place the most specific fields (like `cn` or `uid`) at the beginning of the
172-
name, and the most general fields (like `o` or `dc`) at the end of the name.
173-
Some tools, such as _openssl_, may print out the subject name in a different
174-
format.
175-
176-
One way that you can determine the correct DN for a certificate is to use the
177-
{ref}/security-api-authenticate.html[authenticate API] (use the relevant PKI
178-
certificate as the means of authentication) and inspect the metadata field in
179-
the result. The user's distinguished name will be populated under the `pki_dn`
180-
key. You can also use the authenticate API to validate your role mapping.
18+
==== PKI Realm Settings
18119

182-
For more information, see <<mapping-roles, Mapping Users and Groups to Roles>>.
20+
See {ref}/security-settings.html#ref-pki-settings[PKI realm settings].

‎x-pack/docs/en/security/configuring-es.asciidoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,7 @@ user API.
7272

7373
. Choose which types of realms you want to use to authenticate users.
7474
** <<configuring-ad-realm,Configure an Active Directory realm>>.
75+
** <<configuring-pki-realm,Configure a PKI realm>>.
7576

7677
. Set up roles and users to control access to {es}.
7778
For example, to grant _John Doe_ full access to all indices that match
@@ -132,5 +133,6 @@ include::securing-communications/configuring-tls-docker.asciidoc[]
132133
include::securing-communications/enabling-cipher-suites.asciidoc[]
133134
include::securing-communications/separating-node-client-traffic.asciidoc[]
134135
include::authentication/configuring-active-directory-realm.asciidoc[]
136+
include::authentication/configuring-pki-realm.asciidoc[]
135137
include::{xes-repo-dir}/settings/security-settings.asciidoc[]
136138
include::{xes-repo-dir}/settings/audit-settings.asciidoc[]

0 commit comments

Comments
 (0)