[[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>>.