123 lines
5.8 KiB
Plaintext
123 lines
5.8 KiB
Plaintext
[[pki]]
|
|
=== Using PKI to Authenticate Users added[1.3.0]
|
|
|
|
You can configure Shield 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 DNs from the user certificates to Shield roles in the <<mapping-roles, role mapping file>>.
|
|
|
|
You can use a combination of PKI encryption and username and 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 usernames and
|
|
passwords. You can also set `shield.transport.ssl.client.auth` to `optional`
|
|
to allow clients without certificates to authenticate with other credentials.
|
|
|
|
IMPORTANT: You must enable SSL/TLS to use PKI. For more information, see
|
|
<<ssl-tls, Setting Up SSL/TLS on a Cluster>>.
|
|
|
|
==== PKI Realm Configuration
|
|
|
|
Like realms, you configure options for a `pki` realm in the `shield.authc.realms` namespace in
|
|
`elasticsearch.yml`.
|
|
|
|
To configure PKI realm:
|
|
|
|
. Add a realm configuration of type `pki` to `elasticsearch.yml` in the
|
|
`shield.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, PKI Realm Settings>>
|
|
for all of the options you can set for an `pki` realm.
|
|
+
|
|
For example, the following snippet shows the most basic PKI realm configuration:
|
|
+
|
|
[source, yaml]
|
|
------------------------------------------------------------
|
|
shield:
|
|
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.
|
|
+
|
|
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]
|
|
------------------------------------------------------------
|
|
shield:
|
|
authc:
|
|
realms:
|
|
pki1:
|
|
type: pki
|
|
username_pattern: "EMAILADDRESS=(.*?)(?:,|$)"
|
|
------------------------------------------------------------
|
|
+
|
|
You can also specify which truststore to use for authentication. 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 specify the location of the truststore,
|
|
specify the `truststore.path` option:
|
|
+
|
|
[source, yaml]
|
|
------------------------------------------------------------
|
|
shield:
|
|
authc:
|
|
realms:
|
|
pki1:
|
|
type: pki
|
|
truststore:
|
|
path: "/path/to/pki_truststore.jks"
|
|
password: "changeme"
|
|
------------------------------------------------------------
|
|
|
|
. Restart Elasticsearch.
|
|
|
|
[[pki-settings]]
|
|
===== PKI Realm Settings
|
|
|
|
|=======================
|
|
| 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=(.*?)(?:,\|$)`.
|
|
| `truststore.path` | no | The path to the truststore. Defaults to the path
|
|
defined by <<ref-ssl-tls-settings,SSL/TLS settings>>.
|
|
| `truststore.password` | no | Specifies the password for the truststore. Must be
|
|
provided if `truststore.path` is set.
|
|
| `truststore.algorithm` | no | Specifies the algorithm used for the trustsore. Defaults to
|
|
`SunX509`.
|
|
| `files.role_mapping` | no | Specifies the <<ref-shield-files-location,location>>
|
|
for the <<pki-role-mapping, YAML role mapping
|
|
configuration file>>. Defaults to
|
|
`CONFIG_DIR/shield/role_mapping.yml`.
|
|
|=======================
|
|
|
|
[[assigning-roles-pki]]
|
|
==== Assigning Roles for PKI Users
|
|
|
|
You assign roles for PKI users in the role mapping file stored on each node. You identify a user
|
|
by the distinguished name in their certificate. For example, the following mapping
|
|
configuration assigns `John Doe` the `user` role:
|
|
|
|
[source, yaml]
|
|
------------------------------------------------------------
|
|
user: <1>
|
|
- "cn=John Doe,ou=example,o=com" <2>
|
|
------------------------------------------------------------
|
|
<1> The name of a Shield role defined in the <<defining-roles, roles file>>
|
|
<2> The distinguished name of a PKI user.
|
|
|
|
For more information, see <<mapping-roles, Mapping Users and Groups to Roles>>. |