mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-22 12:56:53 +00:00
[DOCS] Adds PKI delegation.enabled example (#53030)
This commit is contained in:
Lisa Cawley
lcawl
parent
302980e0c4
commit
859c6441b3
@ -6,26 +6,15 @@ the desired network layers (transport or http), and map the Distinguished Names
|
||||
(DNs) from the Subject field in the user certificates to roles. You create the
|
||||
mappings in a role mapping file or use the role mappings API.
|
||||
|
||||
If you want the same users to also be authenticated using certificates when they
|
||||
connect to {kib}, you must configure the {es} PKI realm to
|
||||
<<pki-realm-for-proxied-clients,allow delegation>> and to
|
||||
{kibana-ref}/kibana-authentication.html#pki-authentication[enable PKI authentication in {kib}].
|
||||
|
||||
You can also use a combination of PKI and username/password authentication. For
|
||||
TIP: You can 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 with client authentication to use PKI when
|
||||
clients connect directly to {es}.
|
||||
authenticating HTTP traffic using username and password credentials.
|
||||
|
||||
. Add a realm configuration for a `pki` realm to `elasticsearch.yml` under the
|
||||
`xpack.security.authc.realms.pki` namespace.
|
||||
If you are configuring multiple realms, you should
|
||||
explicitly set the `order` attribute. See <<ref-pki-settings>> for all of the
|
||||
options you can set for a `pki` realm.
|
||||
`xpack.security.authc.realms.pki` namespace. If you are configuring multiple
|
||||
realms, you should 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:
|
||||
@ -44,15 +33,21 @@ xpack:
|
||||
With this configuration, any certificate trusted by the {es} SSL/TLS layer is
|
||||
accepted for authentication. The username is the common name (CN) extracted
|
||||
from the DN in the Subject field of the end-entity certificate. This
|
||||
configuration does not permit PKI authentication to {kib}.
|
||||
configuration is not sufficient to permit PKI authentication to {kib};
|
||||
additional steps are required.
|
||||
|
||||
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 Subject DN as the
|
||||
username, you can specify a regex to extract the desired username. The regex is
|
||||
applied on the Subject DN. For example, the regex in the following
|
||||
--
|
||||
|
||||
. Optional: If you want to use something other than the CN of the Subject DN as
|
||||
the username, you can specify a regex to extract the desired username. The regex
|
||||
is applied on the Subject DN.
|
||||
+
|
||||
--
|
||||
For example, the regex in the following
|
||||
configuration extracts the email address from the Subject DN:
|
||||
|
||||
[source, yaml]
|
||||
@ -71,6 +66,10 @@ client's certificate, then the realm does not authenticate the certificate.
|
||||
|
||||
--
|
||||
|
||||
. Optional: If you want the same users to also be authenticated using
|
||||
certificates when they connect to {kib}, you must configure the {es} PKI realm
|
||||
to allow delegation. See <<pki-realm-for-proxied-clients>>.
|
||||
|
||||
. Restart {es} because realm configuration is not reloaded automatically. If
|
||||
you're following through with the next steps, you might wish to hold the
|
||||
restart for last.
|
||||
@ -80,6 +79,11 @@ restart for last.
|
||||
. Enable client authentication on the desired network layers (transport or http).
|
||||
+
|
||||
--
|
||||
IMPORTANT: To use PKI when clients connect directly to {es}, you must enable
|
||||
SSL/TLS with client authentication. That is to say, you must set `xpack.security.transport.ssl.client_authentication` and
|
||||
`xpack.security.http.ssl.client_authentication` to `optional` or `required`. If
|
||||
the setting value is `optional`, clients without certificates can authenticate
|
||||
with other credentials.
|
||||
|
||||
When clients connect directly to {es} and are not proxy-authenticated, the PKI
|
||||
realm relies on the TLS settings of the node's network interface. The realm can
|
||||
@ -95,22 +99,22 @@ In particular this means:
|
||||
`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,`ssl.verification_mode`>> for an explanation of this
|
||||
setting.
|
||||
or by setting `verification_mode` to `none`.
|
||||
* The _protocols_ supported by the interface must be compatible with those
|
||||
used by the client.
|
||||
|
||||
For an explanation of these settings, see <<ssl-tls-settings>>.
|
||||
|
||||
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 is possible to
|
||||
configure the PKI realm to trust only a _subset_ of the certificates accepted
|
||||
any certificate that is to be used within the PKI realm. However, it is 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. The path must be located within the Elasticsearch
|
||||
configuration directory (ES_PATH_CONF). For example:
|
||||
configuration directory (`ES_PATH_CONF`). For example:
|
||||
|
||||
[source, yaml]
|
||||
------------------------------------------------------------
|
||||
@ -135,25 +139,23 @@ xpack.security.authc.realms.pki.pki1.truststore.secure_password
|
||||
------------------------------------------------------------
|
||||
|
||||
The `certificate_authorities` option can be used as an alternative to the
|
||||
`truststore.path` setting, when the certificate files are PEM formatted
|
||||
. The setting accepts a list. The two options are exclusive, they cannot be both used
|
||||
`truststore.path` setting, when the certificate files are PEM formatted. The
|
||||
setting accepts a list. The two options are exclusive, they cannot be both used
|
||||
simultaneously.
|
||||
--
|
||||
|
||||
. Map roles for PKI users.
|
||||
+
|
||||
--
|
||||
You map roles for PKI users through the <<security-role-mapping-apis,role
|
||||
mapping APIs>> or by using a file stored on each node. Both configuration
|
||||
options are merged together. 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 map roles for PKI users through the
|
||||
<<security-role-mapping-apis,role mapping APIs>> or by using a file stored on
|
||||
each node. Both configuration options are merged together. 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:
|
||||
`user` role using the role mapping API:
|
||||
|
||||
[source,console]
|
||||
--------------------------------------------------
|
||||
@ -169,10 +171,7 @@ PUT /_security/role_mapping/users
|
||||
|
||||
<1> The distinguished name (DN) of a PKI user.
|
||||
|
||||
Or, alternatively, configured inside a role-mapping file. The file's path
|
||||
defaults to `ES_PATH_CONF/role_mapping.yml`. You can specify a different path (which must be within
|
||||
ES_PATH_CONF) by using the `files.role_mapping` realm setting (e.g.
|
||||
`xpack.security.authc.realms.pki.pki1.files.role_mapping`):
|
||||
Alternatively, use a role-mapping file. For example:
|
||||
|
||||
[source, yaml]
|
||||
------------------------------------------------------------
|
||||
@ -182,9 +181,14 @@ user: <1>
|
||||
<1> The name of a role.
|
||||
<2> The distinguished name (DN) of a PKI user.
|
||||
|
||||
The file's path defaults to `ES_PATH_CONF/role_mapping.yml`. You can specify a
|
||||
different path (which must be within `ES_PATH_CONF`) by using the
|
||||
`files.role_mapping` realm setting (e.g.
|
||||
`xpack.security.authc.realms.pki.pki1.files.role_mapping`).
|
||||
|
||||
The distinguished 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.
|
||||
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.
|
||||
|
||||
@ -206,47 +210,60 @@ alternative to role mapping.
|
||||
|
||||
By default, the PKI realm relies on the node's network interface to perform the
|
||||
SSL/TLS handshake and extract the client certificate. This behaviour requires
|
||||
that that clients connect directly to {es} so that their SSL connection is
|
||||
terminated by the {es} node. If SSL/TLS authenticatication is to be performed
|
||||
by {kib}, the PKI realm must be configured to permit delegation.
|
||||
that clients connect directly to {es} so that their SSL connection is terminated
|
||||
by the {es} node. If SSL/TLS authentication is to be performed by {kib}, the
|
||||
PKI realm must be configured to permit delegation.
|
||||
|
||||
Specifically, when clients presenting X.509 certificates connect to {kib},
|
||||
{kib} performs the SSL/TLS authentication. {kib} then forwards the client's
|
||||
certificate chain, by calling an {es} API, to have them further validated by
|
||||
certificate chain (by calling an {es} API) to have them further validated by
|
||||
the PKI realms that have been configured for delegation.
|
||||
|
||||
To permit authentication delegation for a specific {es} PKI realm, start by
|
||||
configuring the realm for the usual case, as detailed in the
|
||||
<<pki-realm-for-direct-clients>>
|
||||
section. Note that you must explicitly configure a `truststore` (or,
|
||||
equivalently `certificate_authorities`) even though it is the same trust
|
||||
configuration that you have configured on the network layer. Afterwards,
|
||||
simply toggle the `delegation.enabled` realm setting to `true`. This realm is
|
||||
now allowed to validate delegated PKI authentication (after restarting {es}).
|
||||
<<pki-realm-for-direct-clients>> section. In this scenario, when you enable TLS,
|
||||
it is mandatory that you <<tls-http,encrypt HTTP client communications>>.
|
||||
|
||||
NOTE: PKI authentication delegation requires that the
|
||||
`xpack.security.authc.token.enabled` setting be `true` and that SSL/TLS be
|
||||
configured (without SSL/TLS client authentication).
|
||||
You must also explicitly configure a `truststore` (or, equivalently
|
||||
`certificate_authorities`) even though it is the same trust configuration that
|
||||
you have configured on the network layer. The
|
||||
`xpack.security.authc.token.enabled` and `delegation.enabled` settings must also
|
||||
be `true`. For example:
|
||||
|
||||
NOTE: {kib} also needs to be
|
||||
{kibana-ref}/kibana-authentication.html#pki-authentication[configured to allow
|
||||
PKI certificate authentication].
|
||||
[source, yaml]
|
||||
------------------------------------------------------------
|
||||
xpack:
|
||||
security:
|
||||
authc:
|
||||
token.enabled: true
|
||||
realms:
|
||||
pki:
|
||||
pki1:
|
||||
order: 1
|
||||
delegation.enabled: true
|
||||
truststore:
|
||||
path: "pki1_truststore.jks"
|
||||
------------------------------------------------------------
|
||||
|
||||
After you restart {es}, this realm can validate delegated PKI authentication.
|
||||
You must then
|
||||
{kibana-ref}/kibana-authentication.html#pki-authentication[configure {kib} to allow PKI certificate authentication].
|
||||
|
||||
A PKI realm with `delegation.enabled` still works unchanged for clients
|
||||
connecting directly to {es}. Directly authenticated users, and users that are PKI
|
||||
connecting directly to {es}. Directly authenticated users and users that are PKI
|
||||
authenticated by delegation to {kib} both follow the same
|
||||
<<mapping-roles,role mapping rules>> or
|
||||
<<authorization_realms,authorization realms configurations>>.
|
||||
|
||||
However, if you use the <<security-role-mapping-apis,role mapping APIs>>,
|
||||
you can distinguish between users that are authenticated by delegation and
|
||||
users that are authenticated directly. The former have the
|
||||
extra fields `pki_delegated_by_user` and `pki_delegated_by_realm` in the user's
|
||||
metadata. In the common setup, where authentication is delegated to {kib}, the
|
||||
values of these fields are `kibana` and `reserved`, respectively. For example,
|
||||
the following role mapping rule will assign the `role_for_pki1_direct` role to
|
||||
all users that have been authenticated directly by the `pki1` realm, by
|
||||
connecting to {es} instead of going through {kib}:
|
||||
If you use the <<security-role-mapping-apis,role mapping APIs>>, however, you
|
||||
can distinguish between users that are authenticated by delegation and users
|
||||
that are authenticated directly. The former have the extra fields
|
||||
`pki_delegated_by_user` and `pki_delegated_by_realm` in the user's metadata. In
|
||||
the common setup, where authentication is delegated to {kib}, the values of
|
||||
these fields are `kibana` and `reserved`, respectively. For example, the
|
||||
following role mapping rule assigns the `role_for_pki1_direct` role to all users
|
||||
that have been authenticated directly by the `pki1` realm, by connecting to {es}
|
||||
instead of going through {kib}:
|
||||
|
||||
[source,console]
|
||||
--------------------------------------------------
|
||||
@ -269,5 +286,5 @@ PUT /_security/role_mapping/direct_pki_only
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
<1> only when this metadata field is set (it is *not* `null`) the user has been
|
||||
authenticated in the delegation scenario.
|
||||
<1> If this metadata field is set (that is to say, it is *not* `null`), the user
|
||||
has been authenticated in the delegation scenario.
|
||||
|
||||
@ -3,9 +3,9 @@
|
||||
=== PKI user authentication
|
||||
|
||||
You can configure {es} to use Public Key Infrastructure (PKI) certificates to
|
||||
authenticate users. This requires clients connecting directly to {es} to
|
||||
present X.509 certificates. The certificates must first be accepted for
|
||||
authentication on the SSL/TLS layer on {es}. Only then they are optionally
|
||||
authenticate users. In this scenario, clients connecting directly to {es} must
|
||||
present X.509 certificates. First, the certificates must be accepted for
|
||||
authentication on the SSL/TLS layer on {es}. Then they are optionally
|
||||
further validated by a PKI realm. See <<pki-realm-for-direct-clients>>.
|
||||
|
||||
You can also use PKI certificates to authenticate to {kib}, however this
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user