honeymoose/OpenSearch
1
0
Fork 0
mirror of https://github.com/honeymoose/OpenSearch.git synced 2025-03-24 17:09:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

[DOCS] Clarify PKI realm support (elastic/x-pack-elasticsearch#3703)

Browse Source 
Original commit: elastic/x-pack-elasticsearch@55da7a07d1
This commit is contained in:
Lisa Cawley 2018-01-24 08:32:23 -08:00 committed by GitHub
parent e7c78e05f8
commit 9435ffe64b
2 changed files with 30 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
docs/en/security/authentication/pki-realm.asciidoc
View File

@ -2,10 +2,15 @@
=== PKI User Authentication
You can configure {security} to use Public Key Infrastructure (PKI) certificates
to authenticate users. This requires clients to present X.509 certificates. To
use PKI, 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 <<mapping-roles, role mapping file>>.
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
<<mapping-roles, 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
@ -22,7 +27,7 @@ IMPORTANT: You must enable SSL/TLS and enabled client authentication to use PKI
Like other realms, you configure options for a `pki` realm under the
`xpack.security.authc.realms` namespace in `elasticsearch.yml`.
To configure `pki` realm:
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
@ -119,35 +124,10 @@ The `certificate_authorities` option may be used as an alternative to the
[[pki-settings]]
===== PKI Realm Settings
[cols="4,^3,10"]
|=======================
| Setting | Required | Description
| `type` | yes | Indicates the realm type. Must be set to `pki`.
| `order` | no | Indicates the priority of this realm within the realm
chain. Realms with a lower order are consulted first.
Although not required, we recommend explicitly
setting this value when you configure multiple realms.
Defaults to `Integer.MAX_VALUE`.
| `enabled` | no | Indicates whether this realm is enabled or disabled.
Enables you to disable a realm without removing its
configuration. Defaults to `true`.
| `username_pattern` | no | Specifies the regular expression pattern used to extract
the username from the certificate DN. The first match
group is used as the username. Defaults to `CN=(.*?)(?:,\|$)`.
| `certificate_authorities` | no | List of paths to the PEM encoded certificate files
that should be trusted.
This setting may not be used with `truststore.path`.
| `truststore.path` | no | The path to the truststore. Defaults to the path
defined by {ref}/security-settings.html#ssl-tls-settings[SSL/TLS settings].
This setting may not be used with `certificate_authorities`.
| `truststore.password` | no/yes | Specifies the password for the truststore. Must be
provided if `truststore.path` is set.
| `truststore.algorithm` | no | Specifies the algorithm used for the truststore.
Defaults to `SunX509`.
| `files.role_mapping` | no | Specifies the <<security-files-location,location>>
for the <<pki-role-mapping, YAML role mapping configuration file>>.
Defaults to `CONFIG_DIR/x-pack/role_mapping.yml`.
|=======================
See
{ref}/security-settings.html#_settings_valid_for_all_realms[Security Settings for All Realms]
and
{ref}/security-settings.html#ref-pki-settings[PKI Realm Settings].
[[assigning-roles-pki]]
==== Mapping Roles for PKI Users

26
docs/en/settings/security-settings.asciidoc
View File

@ -131,10 +131,13 @@ information, see {xpack-ref}/setting-up-authentication.html[Setting Up Authentic
The type of the realm: `native, `ldap`, `active_directory`, `pki`, or `file`. Required.
`order`::
The priority of the realm within the realm chain. Defaults to `Integer.MAX_VALUE`.
The priority of the realm within the realm chain. Realms with a lower order are
consulted first. Although not required, use of this setting is strongly
recommended when you configure multiple realms. Defaults to `Integer.MAX_VALUE`.
`enabled`::
Enable/disable the realm. Defaults to `true`.
Indicates whether a realm is enabled. You can use this setting to disable a
realm without removing its configuration information. Defaults to `true`.
[[ref-users-settings]]
@ -589,13 +592,14 @@ the in-memory cached user credentials (see {xpack-ref}/controlling-user-cache.ht
`username_pattern`::
The regular expression pattern used to extract the username from the
certificate DN. The first match group is the used as the username.
Defaults to `CN=(.*?)(?:,\|$)`
Defaults to `CN=(.*?)(?:,\|$)`.
`certificate_authorities`::
List of PEM certificate files that should be used to authenticate a
user's certificate as trusted. Defaults to the trusted certificates configured for SSL.
See the {xpack-ref}/pki-realm.html#pki-ssl-config[SSL settings] section of the PKI realm documentation for more information.
This setting may not be used with `truststore.path`.
List of paths to the PEM certificate files that should be used to authenticate a
user's certificate as trusted. Defaults to the trusted certificates configured
for SSL. See the {xpack-ref}/pki-realm.html#pki-ssl-config[SSL settings]
section of the PKI realm documentation for more information.
This setting cannot be used with `truststore.path`.
`truststore.algorithm`::
Algorithm for the truststore. Defaults to `SunX509`.
@ -607,9 +611,11 @@ The password for the truststore. Must be provided if `truststore.path` is set.
The password for the truststore.
`truststore.path`::
The path of a truststore to use. Defaults to the trusted certificates configured for SSL.
See the {xpack-ref}/pki-realm.html#pki-ssl-config[SSL settings] section of the PKI realm documentation for more information.
This setting may not be used with `certificate_authorities`.
The path of a truststore to use. Defaults to the trusted certificates configured
for SSL. See the
{xpack-ref}/pki-realm.html#pki-ssl-config[SSL settings] section of the PKI realm
documentation for more information. This setting cannot be used with
`certificate_authorities`.
`files.role_mapping`::
Specifies the {xpack-ref}/security-files.html[location] of the