|
| 1 | +[role="xpack"] |
| 2 | +[[configuring-kerberos-realm]] |
| 3 | +=== Configuring a Kerberos realm |
| 4 | + |
| 5 | +Kerberos is used to protect services and uses a ticket-based authentication |
| 6 | +protocol to authenticate users. |
| 7 | +You can configure {es} to use the Kerberos V5 authentication protocol, which is |
| 8 | +an industry standard protocol, to authenticate users. |
| 9 | +In this scenario, clients must present Kerberos tickets for authentication. |
| 10 | + |
| 11 | +In Kerberos, users authenticate with an authentication service and later |
| 12 | +with a ticket granting service to generate a TGT (ticket-granting ticket). |
| 13 | +This ticket is then presented to the service for authentication. |
| 14 | +Refer to your Kerberos installation documentation for more information about |
| 15 | +obtaining TGT. {es} clients must first obtain a TGT then initiate the process of |
| 16 | +authenticating with {es}. |
| 17 | + |
| 18 | +For a summary of Kerberos terminology, see {stack-ov}/kerberos-realm.html[Kerberos authentication]. |
| 19 | + |
| 20 | +==== Before you begin |
| 21 | + |
| 22 | +. Deploy Kerberos. |
| 23 | ++ |
| 24 | +-- |
| 25 | +You must have the Kerberos infrastructure set up in your environment. |
| 26 | + |
| 27 | +NOTE: Kerberos requires a lot of external services to function properly, such as |
| 28 | +time synchronization between all machines and working forward and reverse DNS |
| 29 | +mappings in your domain. Refer to your Kerberos documentation for more details. |
| 30 | + |
| 31 | +These instructions do not cover setting up and configuring your Kerberos |
| 32 | +deployment. Where examples are provided, they pertain to an MIT Kerberos V5 |
| 33 | +deployment. For more information, see |
| 34 | +http://web.mit.edu/kerberos/www/index.html[MIT Kerberos documentation] |
| 35 | +-- |
| 36 | + |
| 37 | +. Configure Java GSS. |
| 38 | ++ |
| 39 | +-- |
| 40 | + |
| 41 | +{es} uses Java GSS framework support for Kerberos authentication. |
| 42 | +To support Kerberos authentication, {es} needs the following files: |
| 43 | + |
| 44 | +* `krb5.conf`, a Kerberos configuration file |
| 45 | +* A `keytab` file that contains credentials for the {es} service principal |
| 46 | + |
| 47 | +The configuration requirements depend on your Kerberos setup. Refer to your |
| 48 | +Kerberos documentation to configure the `krb5.conf` file. |
| 49 | + |
| 50 | +For more information on Java GSS, see |
| 51 | +https://docs.oracle.com/javase/10/security/kerberos-requirements1.htm[Java GSS Kerberos requirements] |
| 52 | +-- |
| 53 | + |
| 54 | +==== Create a Kerberos realm |
| 55 | + |
| 56 | +To configure a Kerberos realm in {es}: |
| 57 | + |
| 58 | +. Configure the JVM to find the Kerberos configuration file. |
| 59 | ++ |
| 60 | +-- |
| 61 | +{es} uses Java GSS and JAAS Krb5LoginModule to support Kerberos authentication |
| 62 | +using a Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO) mechanism. |
| 63 | +The Kerberos configuration file (`krb5.conf`) provides information such as the |
| 64 | +default realm, the Key Distribution Center (KDC), and other configuration details |
| 65 | +required for Kerberos authentication. When the JVM needs some configuration |
| 66 | +properties, it tries to find those values by locating and loading this file. The |
| 67 | +JVM system property to configure the file path is `java.security.krb5.conf`. To |
| 68 | +configure JVM system properties see {ref}/jvm-options.html[configuring jvm options]. |
| 69 | +If this system property is not specified, Java tries to locate the file based on |
| 70 | +the conventions. |
| 71 | + |
| 72 | +TIP: It is recommended that this system property be configured for {es}. |
| 73 | +The method for setting this property depends on your Kerberos infrastructure. |
| 74 | +Refer to your Kerberos documentation for more details. |
| 75 | + |
| 76 | +For more information, see http://web.mit.edu/kerberos/krb5-latest/doc/admin/conf_files/krb5_conf.html[krb5.conf] |
| 77 | + |
| 78 | +-- |
| 79 | + |
| 80 | +. Create a keytab for the {es} node. |
| 81 | ++ |
| 82 | +-- |
| 83 | +A keytab is a file that stores pairs of principals and encryption keys. {es} |
| 84 | +uses the keys from the keytab to decrypt the tickets presented by the user. You |
| 85 | +must create a keytab for {es} by using the tools provided by your Kerberos |
| 86 | +implementation. For example, some tools that create keytabs are `ktpass.exe` on |
| 87 | +Windows and `kadmin` for MIT Kerberos. |
| 88 | +-- |
| 89 | + |
| 90 | +. Put the keytab file in the {es} configuration directory. |
| 91 | ++ |
| 92 | +-- |
| 93 | +Make sure that this keytab file has read permissions. This file contains |
| 94 | +credentials, therefore you must take appropriate measures to protect it. |
| 95 | + |
| 96 | +IMPORTANT: {es} uses Kerberos on the HTTP network layer, therefore there must be |
| 97 | +a keytab file for the HTTP service principal on every {es} node. The service |
| 98 | +principal name must have the format `HTTP/ [email protected]`. |
| 99 | +The keytab files are unique for each node since they include the hostname. |
| 100 | +An {es} node can act as any principal a client requests as long as that |
| 101 | +principal and its credentials are found in the configured keytab. |
| 102 | + |
| 103 | +-- |
| 104 | + |
| 105 | +. Create a Kerberos realm. |
| 106 | ++ |
| 107 | +-- |
| 108 | + |
| 109 | +To enable Kerberos authentication in {es}, you must add a Kerberos realm in the |
| 110 | +realm chain. |
| 111 | + |
| 112 | +NOTE: You can configure only one Kerberos realm on {es} nodes. |
| 113 | + |
| 114 | +To configure a Kerberos realm, there are a few mandatory realm settings and |
| 115 | +other optional settings that you need to configure in the `elasticsearch.yml` |
| 116 | +configuration file. Add a realm of type `kerberos` under the |
| 117 | +`xpack.security.authc.realms` namespace. |
| 118 | + |
| 119 | +The most common configuration for a Kerberos realm is as follows: |
| 120 | + |
| 121 | +[source, yaml] |
| 122 | +------------------------------------------------------------ |
| 123 | +xpack.security.authc.realms.kerb1: |
| 124 | + type: kerberos |
| 125 | + order: 3 |
| 126 | + keytab.path: es.keytab |
| 127 | + remove_realm_name: false |
| 128 | +------------------------------------------------------------ |
| 129 | + |
| 130 | +The `username` is extracted from the ticket presented by user and usually has |
| 131 | +the format `username@REALM`. This `username` is used for mapping |
| 132 | +roles to the user. If realm setting `remove_realm_name` is |
| 133 | +set to `true`, the realm part (`@REALM`) is removed. The resulting `username` |
| 134 | +is used for role mapping. |
| 135 | + |
| 136 | +For detailed information of available realm settings, |
| 137 | +see {ref}/security-settings.html#ref-kerberos-settings[Kerberos realm settings]. |
| 138 | + |
| 139 | +-- |
| 140 | + |
| 141 | +. Restart {es} |
| 142 | + |
| 143 | +. Map Kerberos users to roles. |
| 144 | ++ |
| 145 | +-- |
| 146 | + |
| 147 | +The `kerberos` realm enables you to map Kerberos users to roles. You can |
| 148 | +configure these role mappings by using the |
| 149 | +{ref}/security-api-role-mapping.html[role-mapping API]. You identify |
| 150 | +users by their `username` field. |
| 151 | + |
| 152 | +The following example uses the role mapping API to map `user@REALM` to the roles |
| 153 | +`monitoring` and `user`: |
| 154 | + |
| 155 | +[source,js] |
| 156 | +-------------------------------------------------- |
| 157 | +POST _xpack/security/role_mapping/kerbrolemapping |
| 158 | +{ |
| 159 | + "roles" : [ "monitoring_user" ], |
| 160 | + "enabled": true, |
| 161 | + "rules" : { |
| 162 | + "field" : { "username" : "user@REALM" } |
| 163 | + } |
| 164 | +} |
| 165 | +-------------------------------------------------- |
| 166 | +// CONSOLE |
| 167 | + |
| 168 | +For more information, see {stack-ov}/mapping-roles.html[Mapping users and groups to roles]. |
| 169 | +-- |
| 170 | + |
0 commit comments