You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
You can configure the {{stack}} {{security-features}} to support Kerberos V5 authentication, an industry standard protocol to authenticate users in {{es}}.
39
+
40
+
::::{note}
41
+
You can't use the Kerberos realm to authenticate on the transport network layer.
42
+
::::
43
+
44
+
45
+
To authenticate users with Kerberos, you need to configure a Kerberos realm and map users to roles. For more information on realm settings, see [Kerberos realm settings](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/configuration-reference/security-settings.md#ref-kerberos-settings).
46
+
47
+
## Key concepts [kerberos-terms]
48
+
49
+
There are a few terms and concepts that you’ll encounter when you’re setting up Kerberos realms:
50
+
51
+
kdc
52
+
: Key Distribution Center. A service that issues Kerberos tickets.
53
+
54
+
principal
55
+
: A Kerberos principal is a unique identity to which Kerberos can assign tickets. It can be used to identify a user or a service provided by a server.
56
+
57
+
Kerberos V5 principal names are of format `primary/instance@REALM`, where `primary` is a user name.
58
+
59
+
`instance` is an optional string that qualifies the primary and is separated by a slash(`/`) from the primary. For a user, usually it is not used; for service hosts, it is the fully qualified domain name of the host.
60
+
61
+
`REALM` is the Kerberos realm. Usually it is the domain name in upper case. An example of a typical user principal is `[email protected]`. An example of a typical service principal is `HTTP/[email protected]`.
62
+
63
+
64
+
realm
65
+
: Realms define the administrative boundary within which the authentication server has authority to authenticate users and services.
66
+
67
+
keytab
68
+
: A file that stores pairs of principals and encryption keys.
69
+
70
+
::::{important}
71
+
Anyone with read permissions to this file can use the credentials in the network to access other services so it is important to protect it with proper file permissions.
72
+
::::
73
+
74
+
75
+
krb5.conf
76
+
: A file that contains Kerberos configuration information such as the default realm name, the location of Key distribution centers (KDC), realms information, mappings from domain names to Kerberos realms, and default configurations for realm session key encryption types.
77
+
78
+
ticket granting ticket (TGT)
79
+
: A TGT is an authentication ticket generated by the Kerberos authentication server. It contains an encrypted authenticator.
80
+
81
+
82
+
## Configuring a Kerberos realm [kerberos-realm-configuration]
83
+
84
+
Kerberos is used to protect services and uses a ticket-based authentication protocol to authenticate users. You can configure {{es}} to use the Kerberos V5 authentication protocol, which is an industry standard protocol, to authenticate users. In this scenario, clients must present Kerberos tickets for authentication.
85
+
86
+
In Kerberos, users authenticate with an authentication service and later with a ticket granting service to generate a TGT (ticket-granting ticket). This ticket is then presented to the service for authentication. Refer to your Kerberos installation documentation for more information about obtaining TGT. {{es}} clients must first obtain a TGT then initiate the process of authenticating with {{es}}.
87
+
88
+
### Before you begin [kerberos-realm-prereq]
89
+
90
+
1. Deploy Kerberos.
91
+
92
+
You must have the Kerberos infrastructure set up in your environment.
93
+
94
+
::::{note}
95
+
Kerberos requires a lot of external services to function properly, such as time synchronization between all machines and working forward and reverse DNS mappings in your domain. Refer to your Kerberos documentation for more details.
96
+
::::
97
+
98
+
99
+
These instructions do not cover setting up and configuring your Kerberos deployment. Where examples are provided, they pertain to an MIT Kerberos V5 deployment. For more information, see [MIT Kerberos documentation](http://web.mit.edu/kerberos/www/index.md)
100
+
101
+
If you're using a self-managed cluster, then perform the following additional steps:
102
+
103
+
1. Configure Java GSS.
104
+
105
+
{{es}} uses Java GSS framework support for Kerberos authentication. To support Kerberos authentication, {{es}} needs the following files:
106
+
107
+
*`krb5.conf`, a Kerberos configuration file
108
+
* A `keytab` file that contains credentials for the {{es}} service principal
109
+
110
+
The configuration requirements depend on your Kerberos setup. Refer to your Kerberos documentation to configure the `krb5.conf` file.
111
+
112
+
For more information on Java GSS, see [Java GSS Kerberos requirements](https://docs.oracle.com/javase/10/security/kerberos-requirements1.htm)
113
+
114
+
2. Enable TLS for HTTP.
115
+
116
+
If your {{es}} cluster is operating in production mode, you must configure the HTTP interface to use SSL/TLS before you can enable Kerberos authentication. For more information, see [Encrypt HTTP client communications for {{es}}](../../../deploy-manage/security/set-up-basic-security-plus-https.md#encrypt-http-communication).
117
+
118
+
This step is necessary to support Kerberos authentication through {{kib}}. It is not required for Kerberos authentication directly against the {{es}} Rest API.
119
+
120
+
If you started {{es}} [with security enabled](/deploy-manage/deploy/self-managed/installing-elasticsearch.md), then TLS is already enabled for HTTP.
121
+
122
+
{{ech}}, {{ece}}, and {{eck}} have TLS enabled by default.
123
+
124
+
3. Enable the token service.
125
+
126
+
The {{es}} Kerberos implementation makes use of the {{es}} token service. If you configure TLS on the HTTP interface, this service is automatically enabled. It can be explicitly configured by adding the following setting in your `elasticsearch.yml` file:
127
+
128
+
```yaml
129
+
xpack.security.authc.token.enabled: true
130
+
```
131
+
This step is necessary to support Kerberos authentication through {{kib}}. It is not required for Kerberos authentication directly against the {{es}} Rest API.
132
+
133
+
{{ech}}, {{ece}}, and {{eck}} have TLS enabled by default.
134
+
135
+
136
+
137
+
### Create a Kerberos realm [kerberos-realm-create]
138
+
139
+
To configure a Kerberos realm in {{es}}:
140
+
141
+
#### Prepare Kerberos config files
142
+
143
+
Prepare the following resources:
144
+
145
+
* `krb5.conf`: The Kerberos configuration file (`krb5.conf`) provides information such as the default realm, the Key Distribution Center (KDC), and other configuration details required for Kerberos authentication. For more information, see [krb5.conf](https://web.mit.edu/kerberos/krb5-latest/doc/admin/conf_files/krb5_conf.html).
146
+
* **A keytab**: A keytab is a file that stores pairs of principals and encryption keys. {{es}} uses the keys from the keytab to decrypt the tickets presented by the user. You must create a keytab for {{es}} by using the tools provided by your Kerberos implementation. For example, some tools that create keytabs are `ktpass.exe` on Windows and `kadmin` for MIT Kerberos.
147
+
148
+
#### Configure {{es}}
149
+
150
+
The way that you provide Kerberos config files to {{es}} depends on your deployment method.
151
+
152
+
For detailed information of available realm settings, see [Kerberos realm settings](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/configuration-reference/security-settings.md#ref-kerberos-settings).
153
+
154
+
:::::{tab-set}
155
+
156
+
::::{tab-item} Self-managed
157
+
158
+
1. Configure the JVM to find the Kerberos configuration file.
159
+
160
+
{{es}} uses Java GSS and JAAS Krb5LoginModule to support Kerberos authentication using a Simple and Protected GSSAPI Negotiation (SPNEGO) mechanism. When the JVM needs some configuration properties, it tries to find those values by locating and loading the `krb5.conf` file. The JVM system property to configure the file path is `java.security.krb5.conf`. To configure JVM system properties see [Set JVM options](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/jvm-settings.md#set-jvm-options). If this system property is not specified, Java tries to locate the file based on the conventions.
161
+
162
+
:::{tip}
163
+
It is recommended that this system property be configured for {{es}}. The method for setting this property depends on your Kerberos infrastructure. Refer to your Kerberos documentation for more details.
164
+
:::
165
+
166
+
For more information, see [krb5.conf](https://web.mit.edu/kerberos/krb5-latest/doc/admin/conf_files/krb5_conf.html).
167
+
168
+
2. Put the keytab file in the {{es}} configuration directory.
169
+
170
+
Make sure that this keytab file has read permissions. This file contains credentials, therefore you must take appropriate measures to protect it.
171
+
172
+
:::{important}
173
+
{{es}} uses Kerberos on the HTTP network layer, therefore there must be a keytab file for the HTTP service principal on every {{es}} node. The service principal name must have the format `HTTP/[email protected]`. The keytab files are unique for each node since they include the hostname. An {{es}} node can act as any principal a client requests as long as that principal and its credentials are found in the configured keytab.
174
+
:::
175
+
176
+
3. Create a Kerberos realm.
177
+
178
+
To enable Kerberos authentication in {{es}}, you must add a Kerberos realm in the realm chain.
179
+
180
+
:::{note}
181
+
You can configure only one Kerberos realm on {{es}} nodes.
182
+
:::
183
+
184
+
To configure a Kerberos realm, there are a few mandatory realm settings and other optional settings that you need to configure in the `elasticsearch.yml` configuration file. Add a realm configuration under the `xpack.security.authc.realms.kerberos` namespace.
185
+
186
+
The most common configuration for a Kerberos realm is as follows:
187
+
188
+
```yaml
189
+
xpack.security.authc.realms.kerberos.kerb1:
190
+
order: 3
191
+
keytab.path: es.keytab
192
+
remove_realm_name: false
193
+
```
194
+
4. Restart {{es}}.
195
+
::::
196
+
197
+
::::{tab-item} ECH and ECE
198
+
199
+
1. Create a [custom bundle](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch-plugins/cloud-enterprise/ece-add-plugins.md) that contains your `krb5.conf` and `keytab` files, and add it to your cluster.
200
+
201
+
:::{tip}
202
+
You should use these exact filenames for {{ecloud}} to recognize the file in the bundle.
203
+
::::
204
+
205
+
2. Edit your cluster configuration, sometimes also referred to as the deployment plan, to define Kerberos settings as described in [Elasticsearch documentation](/deploy-manage/users-roles/cluster-or-deployment-auth/kerberos.md).
206
+
207
+
```sh
208
+
xpack.security.authc.realms.kerberos.cloud-krb:
209
+
order: 2
210
+
keytab.path: es.keytab
211
+
remove_realm_name: false
212
+
```
213
+
::::
214
+
215
+
::::{tab-item} ECK
216
+
217
+
1. Install your `krb5.conf` and `keytab` files as a [custom configuration file](/deploy-manage/deploy/cloud-on-k8s/custom-configuration-files-plugins.md).
218
+
219
+
2. Edit your cluster configuration, sometimes also referred to as the deployment plan, to define Kerberos settings as described in [Elasticsearch documentation](/deploy-manage/users-roles/cluster-or-deployment-auth/kerberos.md).
220
+
221
+
```sh
222
+
xpack.security.authc.realms.kerberos.cloud-krb:
223
+
order: 2
224
+
keytab.path: es.keytab
225
+
remove_realm_name: false
226
+
```
227
+
::::
228
+
229
+
:::::
230
+
231
+
The `username` is extracted from the ticket presented by the user and usually has the format `username@REALM`. This `username` is used for mapping roles to the user. If realm setting `remove_realm_name` is set to `true`, the realm part (`@REALM`) is removed.
232
+
233
+
## Map Kerberos users to roles
234
+
235
+
236
+
The `kerberos` realm enables you to map Kerberos users to roles.
237
+
238
+
You can map these users to roles in multiple ways:
239
+
240
+
* Using the role mappings page in {{kib}}.
241
+
* Using the [role mapping API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-role-mapping).
242
+
243
+
You identify users by their `username` field.
244
+
245
+
The following example uses the role mapping API to map `user@REALM` to the roles `monitoring` and `user`:
246
+
247
+
```console
248
+
POST /_security/role_mapping/kerbrolemapping
249
+
{
250
+
"roles" : [ "monitoring_user" ],
251
+
"enabled": true,
252
+
"rules" : {
253
+
"field" : { "username" : "user@REALM" }
254
+
}
255
+
}
256
+
```
257
+
258
+
In case you want to support Kerberos cross realm authentication, you may need to map roles based on the Kerberos realm name. For such scenarios, the following additional user metadata can be used for role mapping:
259
+
260
+
- `kerberos_realm`: The Kerberos realm name.
261
+
- `kerberos_user_principal_name`The user principal name from the Kerberos ticket.
262
+
263
+
For more information, see [Mapping users and groups to roles](/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md).
264
+
265
+
::::{note}
266
+
The Kerberos realm supports [authorization realms](/deploy-manage/users-roles/cluster-or-deployment-auth/realm-chains.md#authorization_realms) as an alternative to role mapping.
267
+
::::
268
+
269
+
### Configure Kibana for Kerberos [kerberos-realm-kibana]
270
+
271
+
If you want to use Kerberos to authenticate using your browser and {{kib}}, you need to enable the relevant authentication provider in {{kib}} configuration. See [kerberos single sign-on](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-authentication.md#kerberos)
0 commit comments