[DOCS] Adds PKI realm configuration details (#30225)
This commit is contained in:
Lisa Cawley
GitHub
parent
6506edfd9c
commit
86addc0c8b
|
|
@ -0,0 +1,176 @@
|
||||||
|
[role="xpack"]
|
||||||
|
[[configuring-pki-realm]]
|
||||||
|
=== Configuring a PKI realm
|
||||||
|
|
||||||
|
You can configure {security} to use Public Key Infrastructure (PKI) certificates
|
||||||
|
to authenticate users in {es}. This requires clients to present X.509
|
||||||
|
certificates.
|
||||||
|
|
||||||
|
NOTE: You cannot use PKI certificates to authenticate users in {kib}.
|
||||||
|
|
||||||
|
To use PKI in {es}, you configure a PKI realm, enable client authentication on
|
||||||
|
the desired network layers (transport or http), and map the Distinguished Names
|
||||||
|
(DNs) from the user certificates to {security} roles in the role mapping file.
|
||||||
|
|
||||||
|
You can also use a combination of PKI and username/password authentication. For
|
||||||
|
example, you can enable SSL/TLS on the transport layer and define a PKI realm to
|
||||||
|
require transport clients to authenticate with X.509 certificates, while still
|
||||||
|
authenticating HTTP traffic using username and password credentials. You can
|
||||||
|
also set `xpack.security.transport.ssl.client_authentication` to `optional` to
|
||||||
|
allow clients without certificates to authenticate with other credentials.
|
||||||
|
|
||||||
|
IMPORTANT: You must enable SSL/TLS and enable client authentication to use PKI.
|
||||||
|
|
||||||
|
For more information, see {xpack-ref}/pki-realm.html[PKI User Authentication].
|
||||||
|
|
||||||
|
. Add a realm configuration of type `pki` to `elasticsearch.yml` under the
|
||||||
|
`xpack.security.authc.realms` namespace. At a minimum, you must set the realm
|
||||||
|
`type` to `pki`. If you are configuring multiple realms, you should also
|
||||||
|
explicitly set the `order` attribute. See <<ref-pki-settings>> for all of the
|
||||||
|
options you can set for a `pki` realm.
|
||||||
|
+
|
||||||
|
--
|
||||||
|
For example, the following snippet shows the most basic `pki` realm configuration:
|
||||||
|
|
||||||
|
[source, yaml]
|
||||||
|
------------------------------------------------------------
|
||||||
|
xpack:
|
||||||
|
security:
|
||||||
|
authc:
|
||||||
|
realms:
|
||||||
|
pki1:
|
||||||
|
type: pki
|
||||||
|
------------------------------------------------------------
|
||||||
|
|
||||||
|
With this configuration, any certificate trusted by the SSL/TLS layer is accepted
|
||||||
|
for authentication. The username is the common name (CN) extracted from the DN
|
||||||
|
of the certificate.
|
||||||
|
|
||||||
|
IMPORTANT: When you configure realms in `elasticsearch.yml`, only the
|
||||||
|
realms you specify are used for authentication. If you also want to use the
|
||||||
|
`native` or `file` realms, you must include them in the realm chain.
|
||||||
|
|
||||||
|
If you want to use something other than the CN of the DN as the username, you
|
||||||
|
can specify a regex to extract the desired username. For example, the regex in
|
||||||
|
the following configuration extracts the email address from the DN:
|
||||||
|
|
||||||
|
[source, yaml]
|
||||||
|
------------------------------------------------------------
|
||||||
|
xpack:
|
||||||
|
security:
|
||||||
|
authc:
|
||||||
|
realms:
|
||||||
|
pki1:
|
||||||
|
type: pki
|
||||||
|
username_pattern: "EMAILADDRESS=(.*?)(?:,|$)"
|
||||||
|
------------------------------------------------------------
|
||||||
|
--
|
||||||
|
|
||||||
|
. Restart {es}.
|
||||||
|
|
||||||
|
. <<configuring-tls,Enable SSL/TLS>>.
|
||||||
|
|
||||||
|
. Enable client authentication on the desired network layers (transport or http).
|
||||||
|
+
|
||||||
|
--
|
||||||
|
//TBD: This step might need to be split into a separate topic with additional details
|
||||||
|
//about setting up client authentication.
|
||||||
|
The PKI realm relies on the TLS settings of the node's network interface. The
|
||||||
|
realm can be configured to be more restrictive than the underlying network
|
||||||
|
connection - that is, it is possible to configure the node such that some
|
||||||
|
connections are accepted by the network interface but then fail to be
|
||||||
|
authenticated by the PKI realm. However, the reverse is not possible. The PKI
|
||||||
|
realm cannot authenticate a connection that has been refused by the network
|
||||||
|
interface.
|
||||||
|
|
||||||
|
In particular this means:
|
||||||
|
|
||||||
|
* The transport or http interface must request client certificates by setting
|
||||||
|
`client_authentication` to `optional` or `required`.
|
||||||
|
* The interface must _trust_ the certificate that is presented by the client
|
||||||
|
by configuring either the `truststore` or `certificate_authorities` paths,
|
||||||
|
or by setting `verification_mode` to `none`. See
|
||||||
|
<<ssl-tls-settings,`xpack.ssl.verification_mode`>> for an explanation of this
|
||||||
|
setting.
|
||||||
|
* The _protocols_ supported by the interface must be compatible with those
|
||||||
|
used by the client.
|
||||||
|
|
||||||
|
The relevant network interface (transport or http) must be configured to trust
|
||||||
|
any certificate that is to be used within the PKI realm. However, it possible to
|
||||||
|
configure the PKI realm to trust only a _subset_ of the certificates accepted
|
||||||
|
by the network interface. This is useful when the SSL/TLS layer trusts clients
|
||||||
|
with certificates that are signed by a different CA than the one that signs your
|
||||||
|
users' certificates.
|
||||||
|
|
||||||
|
To configure the PKI realm with its own truststore, specify the `truststore.path`
|
||||||
|
option. For example:
|
||||||
|
|
||||||
|
[source, yaml]
|
||||||
|
------------------------------------------------------------
|
||||||
|
xpack:
|
||||||
|
security:
|
||||||
|
authc:
|
||||||
|
realms:
|
||||||
|
pki1:
|
||||||
|
type: pki
|
||||||
|
truststore:
|
||||||
|
path: "/path/to/pki_truststore.jks"
|
||||||
|
password: "x-pack-test-password"
|
||||||
|
------------------------------------------------------------
|
||||||
|
|
||||||
|
The `certificate_authorities` option can be used as an alternative to the
|
||||||
|
`truststore.path` setting.
|
||||||
|
--
|
||||||
|
|
||||||
|
. Map roles for PKI users.
|
||||||
|
+
|
||||||
|
--
|
||||||
|
You map roles for PKI users through the
|
||||||
|
<<security-api-role-mapping,role-mapping API>> or by using a file stored on
|
||||||
|
each node. When a user authenticates against a PKI realm, the privileges for
|
||||||
|
that user are the union of all privileges defined by the roles to which the
|
||||||
|
user is mapped.
|
||||||
|
|
||||||
|
You identify a user by the distinguished name in their certificate.
|
||||||
|
For example, the following mapping configuration maps `John Doe` to the
|
||||||
|
`user` role:
|
||||||
|
|
||||||
|
Using the role-mapping API:
|
||||||
|
[source,js]
|
||||||
|
--------------------------------------------------
|
||||||
|
PUT _xpack/security/role_mapping/users
|
||||||
|
{
|
||||||
|
"roles" : [ "user" ],
|
||||||
|
"rules" : { "field" : {
|
||||||
|
"dn" : "cn=John Doe,ou=example,o=com" <1>
|
||||||
|
} },
|
||||||
|
"enabled": true
|
||||||
|
}
|
||||||
|
--------------------------------------------------
|
||||||
|
// CONSOLE
|
||||||
|
<1> The distinguished name (DN) of a PKI user.
|
||||||
|
|
||||||
|
Or, alternatively, configured in a role-mapping file:
|
||||||
|
[source, yaml]
|
||||||
|
------------------------------------------------------------
|
||||||
|
user: <1>
|
||||||
|
- "cn=John Doe,ou=example,o=com" <2>
|
||||||
|
------------------------------------------------------------
|
||||||
|
<1> The name of a role.
|
||||||
|
<2> The distinguished name (DN) of a PKI user.
|
||||||
|
|
||||||
|
The disinguished name for a PKI user follows X.500 naming conventions which
|
||||||
|
place the most specific fields (like `cn` or `uid`) at the beginning of the
|
||||||
|
name, and the most general fields (like `o` or `dc`) at the end of the name.
|
||||||
|
Some tools, such as _openssl_, may print out the subject name in a different
|
||||||
|
format.
|
||||||
|
|
||||||
|
One way that you can determine the correct DN for a certificate is to use the
|
||||||
|
<<security-api-authenticate,authenticate API>> (use the relevant PKI
|
||||||
|
certificate as the means of authentication) and inspect the metadata field in
|
||||||
|
the result. The user's distinguished name will be populated under the `pki_dn`
|
||||||
|
key. You can also use the authenticate API to validate your role mapping.
|
||||||
|
|
||||||
|
For more information, see
|
||||||
|
{xpack-ref}/mapping-roles.html[Mapping Users and Groups to Roles].
|
||||||
|
--
|
||||||
|
|
@ -1,5 +1,5 @@
|
||||||
[[pki-realm]]
|
[[pki-realm]]
|
||||||
=== PKI User Authentication
|
=== PKI user authentication
|
||||||
|
|
||||||
You can configure {security} to use Public Key Infrastructure (PKI) certificates
|
You can configure {security} to use Public Key Infrastructure (PKI) certificates
|
||||||
to authenticate users in {es}. This requires clients to present X.509
|
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
|
||||||
(DNs) from the user certificates to {security} roles in the
|
(DNs) from the user certificates to {security} roles in the
|
||||||
<<mapping-roles, role mapping file>>.
|
<<mapping-roles, role mapping file>>.
|
||||||
|
|
||||||
You can also use a combination of PKI and username/password authentication. For
|
See {ref}/configuring-pki-realm.html[Configuring a PKI realm].
|
||||||
example, you can enable SSL/TLS on the transport layer and define a PKI realm to
|
|
||||||
require transport clients to authenticate with X.509 certificates, while still
|
|
||||||
authenticating HTTP traffic using username and password credentials. You can also set
|
|
||||||
`xpack.security.transport.ssl.client_authentication` to `optional` to allow clients without
|
|
||||||
certificates to authenticate with other credentials.
|
|
||||||
|
|
||||||
IMPORTANT: You must enable SSL/TLS and enabled client authentication to use PKI.
|
|
||||||
For more information, see <<ssl-tls, Setting Up SSL/TLS on a Cluster>>.
|
|
||||||
|
|
||||||
==== PKI Realm Configuration
|
|
||||||
|
|
||||||
Like other realms, you configure options for a `pki` realm under the
|
|
||||||
`xpack.security.authc.realms` namespace in `elasticsearch.yml`.
|
|
||||||
|
|
||||||
To configure a `pki` realm:
|
|
||||||
|
|
||||||
. Add a realm configuration of type `pki` to `elasticsearch.yml` under the
|
|
||||||
`xpack.security.authc.realms` namespace. At a minimum, you must set the realm `type` to
|
|
||||||
`pki`. If you are configuring multiple realms, you should also explicitly set
|
|
||||||
the `order` attribute. See <<pki-settings>> for all of the options you can set
|
|
||||||
for a `pki` realm.
|
|
||||||
+
|
|
||||||
For example, the following snippet shows the most basic `pki` realm configuration:
|
|
||||||
+
|
|
||||||
[source, yaml]
|
|
||||||
------------------------------------------------------------
|
|
||||||
xpack:
|
|
||||||
security:
|
|
||||||
authc:
|
|
||||||
realms:
|
|
||||||
pki1:
|
|
||||||
type: pki
|
|
||||||
------------------------------------------------------------
|
|
||||||
+
|
|
||||||
With this configuration, any certificate trusted by the SSL/TLS layer is accepted
|
|
||||||
for authentication. The username is the common name (CN) extracted from the DN
|
|
||||||
of the certificate.
|
|
||||||
+
|
|
||||||
IMPORTANT: When you configure realms in `elasticsearch.yml`, only the
|
|
||||||
realms you specify are used for authentication. If you also want to use the
|
|
||||||
`native` or `file` realms, you must include them in the realm chain.
|
|
||||||
+
|
|
||||||
If you want to use something other than the CN of the DN as the username, you
|
|
||||||
can specify a regex to extract the desired username. For example, the regex in
|
|
||||||
the following configuration extracts the email address from the DN:
|
|
||||||
+
|
|
||||||
[source, yaml]
|
|
||||||
------------------------------------------------------------
|
|
||||||
xpack:
|
|
||||||
security:
|
|
||||||
authc:
|
|
||||||
realms:
|
|
||||||
pki1:
|
|
||||||
type: pki
|
|
||||||
username_pattern: "EMAILADDRESS=(.*?)(?:,|$)"
|
|
||||||
------------------------------------------------------------
|
|
||||||
+
|
|
||||||
. Restart Elasticsearch.
|
|
||||||
|
|
||||||
[[pki-ssl-config]]
|
|
||||||
==== PKI and SSL Settings
|
|
||||||
|
|
||||||
The PKI realm relies on the SSL settings of the node's network interface
|
|
||||||
(transport or http). The realm can be configured to be more restrictive than
|
|
||||||
the underlying network connection - that is, it is possible to configure the
|
|
||||||
node such that some connections are accepted by the network interface but then
|
|
||||||
fail to be authenticated by the PKI realm. However the reverse is not possible
|
|
||||||
- the PKI realm cannot authenticate a connection that has been refused by the
|
|
||||||
network interface.
|
|
||||||
|
|
||||||
In particular this means:
|
|
||||||
|
|
||||||
* The transport or http interface must request client certificates by setting
|
|
||||||
`client_authentication` to `optional` or `required`.
|
|
||||||
* The interface must _trust_ the certificate that is presented by the client
|
|
||||||
by configuring either the `truststore` or `certificate_authorities` paths,
|
|
||||||
or by setting `verification_mode` to `none`.
|
|
||||||
+
|
|
||||||
See {ref}/security-settings.html#ssl-tls-settings[`xpack.ssl.verification_mode`]
|
|
||||||
for an explanation of this setting.
|
|
||||||
|
|
||||||
* The _protocols_ supported by the interface must be compatible with those
|
|
||||||
used by the client.
|
|
||||||
|
|
||||||
|
|
||||||
The relevant network interface (transport or http) must be configured to trust
|
|
||||||
any certificate that is to be used within the PKI realm. However it possible to
|
|
||||||
configure the PKI realm to trust only a _subset_ of the certificates accepted
|
|
||||||
by the network interface.
|
|
||||||
This is useful when the SSL/TLS layer trusts clients with certificates that are
|
|
||||||
signed by a different CA than the one that signs your users' certificates.
|
|
||||||
|
|
||||||
To configure the PKI realm with its own truststore, specify the
|
|
||||||
`truststore.path` option as below:
|
|
||||||
|
|
||||||
[source, yaml]
|
|
||||||
------------------------------------------------------------
|
|
||||||
xpack:
|
|
||||||
security:
|
|
||||||
authc:
|
|
||||||
realms:
|
|
||||||
pki1:
|
|
||||||
type: pki
|
|
||||||
truststore:
|
|
||||||
path: "/path/to/pki_truststore.jks"
|
|
||||||
password: "x-pack-test-password"
|
|
||||||
------------------------------------------------------------
|
|
||||||
|
|
||||||
The `certificate_authorities` option may be used as an alternative to the
|
|
||||||
`truststore.path` setting.
|
|
||||||
|
|
||||||
|
|
||||||
[[pki-settings]]
|
[[pki-settings]]
|
||||||
===== PKI Realm Settings
|
==== PKI Realm Settings
|
||||||
|
|
||||||
See {ref}/security-settings.html#ref-pki-settings[PKI Realm Settings].
|
See {ref}/security-settings.html#ref-pki-settings[PKI realm settings].
|
||||||
|
|
||||||
[[assigning-roles-pki]]
|
|
||||||
==== Mapping Roles for PKI Users
|
|
||||||
|
|
||||||
You map roles for PKI users through the
|
|
||||||
{ref}/security-api-role-mapping.html[role-mapping API], or by using a file stored on
|
|
||||||
each node. When a user authenticates against a PKI realm, the privileges for
|
|
||||||
that user are the union of all privileges defined by the roles to which the
|
|
||||||
user is mapped.
|
|
||||||
|
|
||||||
You identify a user by the distinguished name in their certificate.
|
|
||||||
For example, the following mapping configuration maps `John Doe` to the
|
|
||||||
`user` role:
|
|
||||||
|
|
||||||
Using the role-mapping API:
|
|
||||||
[source,js]
|
|
||||||
--------------------------------------------------
|
|
||||||
PUT _xpack/security/role_mapping/users
|
|
||||||
{
|
|
||||||
"roles" : [ "user" ],
|
|
||||||
"rules" : { "field" : {
|
|
||||||
"dn" : "cn=John Doe,ou=example,o=com" <1>
|
|
||||||
} },
|
|
||||||
"enabled": true
|
|
||||||
}
|
|
||||||
--------------------------------------------------
|
|
||||||
// CONSOLE
|
|
||||||
<1> The distinguished name (DN) of a PKI user.
|
|
||||||
|
|
||||||
Or, alternatively, configured in a role-mapping file:
|
|
||||||
[source, yaml]
|
|
||||||
------------------------------------------------------------
|
|
||||||
user: <1>
|
|
||||||
- "cn=John Doe,ou=example,o=com" <2>
|
|
||||||
------------------------------------------------------------
|
|
||||||
<1> The name of a role.
|
|
||||||
<2> The distinguished name (DN) of a PKI user.
|
|
||||||
|
|
||||||
The disinguished name for a PKI user follows X.500 naming conventions which
|
|
||||||
place the most specific fields (like `cn` or `uid`) at the beginning of the
|
|
||||||
name, and the most general fields (like `o` or `dc`) at the end of the name.
|
|
||||||
Some tools, such as _openssl_, may print out the subject name in a different
|
|
||||||
format.
|
|
||||||
|
|
||||||
One way that you can determine the correct DN for a certificate is to use the
|
|
||||||
{ref}/security-api-authenticate.html[authenticate API] (use the relevant PKI
|
|
||||||
certificate as the means of authentication) and inspect the metadata field in
|
|
||||||
the result. The user's distinguished name will be populated under the `pki_dn`
|
|
||||||
key. You can also use the authenticate API to validate your role mapping.
|
|
||||||
|
|
||||||
For more information, see <<mapping-roles, Mapping Users and Groups to Roles>>.
|
|
||||||
|
|
|
||||||
|
|
@ -72,6 +72,7 @@ user API.
|
||||||
|
|
||||||
. Choose which types of realms you want to use to authenticate users.
|
. Choose which types of realms you want to use to authenticate users.
|
||||||
** <<configuring-ad-realm,Configure an Active Directory realm>>.
|
** <<configuring-ad-realm,Configure an Active Directory realm>>.
|
||||||
|
** <<configuring-pki-realm,Configure a PKI realm>>.
|
||||||
|
|
||||||
. Set up roles and users to control access to {es}.
|
. Set up roles and users to control access to {es}.
|
||||||
For example, to grant _John Doe_ full access to all indices that match
|
For example, to grant _John Doe_ full access to all indices that match
|
||||||
|
|
@ -132,5 +133,6 @@ include::securing-communications/configuring-tls-docker.asciidoc[]
|
||||||
include::securing-communications/enabling-cipher-suites.asciidoc[]
|
include::securing-communications/enabling-cipher-suites.asciidoc[]
|
||||||
include::securing-communications/separating-node-client-traffic.asciidoc[]
|
include::securing-communications/separating-node-client-traffic.asciidoc[]
|
||||||
include::authentication/configuring-active-directory-realm.asciidoc[]
|
include::authentication/configuring-active-directory-realm.asciidoc[]
|
||||||
|
include::authentication/configuring-pki-realm.asciidoc[]
|
||||||
include::{xes-repo-dir}/settings/security-settings.asciidoc[]
|
include::{xes-repo-dir}/settings/security-settings.asciidoc[]
|
||||||
include::{xes-repo-dir}/settings/audit-settings.asciidoc[]
|
include::{xes-repo-dir}/settings/audit-settings.asciidoc[]
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue