[Kerberos] Add documentation for Kerberos realm (#32662)
This commit adds documentation for configuring Kerberos realm. Configuring Kerberos realm documentation highlights important terminology and requirements before creating Kerberos realm. Most of the documentation is centered around configuration from Elasticsearch rather than go deep into Kerberos implementation. Kerberos realm settings are mentioned in the security settings for Kerberos realm.
This commit is contained in:
parent
3fa36807f8
commit
e143cce865
|
@ -1056,6 +1056,33 @@ Specifies the supported protocols for TLS/SSL.
|
|||
Specifies the
|
||||
cipher suites that should be supported.
|
||||
|
||||
[float]
|
||||
[[ref-kerberos-settings]]
|
||||
===== Kerberos realm settings
|
||||
|
||||
For a Kerberos realm, the `type` must be set to `kerberos`. In addition to the
|
||||
<<ref-realm-settings,settings that are valid for all realms>>, you can specify
|
||||
the following settings:
|
||||
|
||||
`keytab.path`:: Specifies the path to the Kerberos keytab file that contains the
|
||||
service principal used by this {es} node. This must be a location within the
|
||||
{es} configuration directory and the file must have read permissions. Required.
|
||||
|
||||
`remove_realm_name`:: Set to `true` to remove the realm part of principal names.
|
||||
Principal names in Kerberos have the form `user/instance@REALM`. If this option
|
||||
is `true`, the realm part (`@REALM`) will not be included in the username.
|
||||
Defaults to `false`.
|
||||
|
||||
`krb.debug`:: Set to `true` to enable debug logs for the Java login module that
|
||||
provides support for Kerberos authentication. Defaults to `false`.
|
||||
|
||||
`cache.ttl`:: The time-to-live for cached user entries. A user is cached for
|
||||
this period of time. Specify the time period using the standard {es}
|
||||
<<time-units,time units>>. Defaults to `20m`.
|
||||
|
||||
`cache.max_users`:: The maximum number of user entries that can live in the
|
||||
cache at any given time. Defaults to 100,000.
|
||||
|
||||
[float]
|
||||
[[load-balancing]]
|
||||
===== Load balancing and failover
|
||||
|
|
|
@ -0,0 +1,170 @@
|
|||
[role="xpack"]
|
||||
[[configuring-kerberos-realm]]
|
||||
=== Configuring a Kerberos realm
|
||||
|
||||
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.
|
||||
|
||||
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}.
|
||||
|
||||
For a summary of Kerberos terminology, see {stack-ov}/kerberos-realm.html[Kerberos authentication].
|
||||
|
||||
==== Before you begin
|
||||
|
||||
. Deploy Kerberos.
|
||||
+
|
||||
--
|
||||
You must have the Kerberos infrastructure set up in your environment.
|
||||
|
||||
NOTE: 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.
|
||||
|
||||
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
|
||||
http://web.mit.edu/kerberos/www/index.html[MIT Kerberos documentation]
|
||||
--
|
||||
|
||||
. Configure Java GSS.
|
||||
+
|
||||
--
|
||||
|
||||
{es} uses Java GSS framework support for Kerberos authentication.
|
||||
To support Kerberos authentication, {es} needs the following files:
|
||||
|
||||
* `krb5.conf`, a Kerberos configuration file
|
||||
* A `keytab` file that contains credentials for the {es} service principal
|
||||
|
||||
The configuration requirements depend on your Kerberos setup. Refer to your
|
||||
Kerberos documentation to configure the `krb5.conf` file.
|
||||
|
||||
For more information on Java GSS, see
|
||||
https://docs.oracle.com/javase/10/security/kerberos-requirements1.htm[Java GSS Kerberos requirements]
|
||||
--
|
||||
|
||||
==== Create a Kerberos realm
|
||||
|
||||
To configure a Kerberos realm in {es}:
|
||||
|
||||
. Configure the JVM to find the Kerberos configuration file.
|
||||
+
|
||||
--
|
||||
{es} uses Java GSS and JAAS Krb5LoginModule to support Kerberos authentication
|
||||
using a Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO) mechanism.
|
||||
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. When the JVM needs some configuration
|
||||
properties, it tries to find those values by locating and loading this file. The
|
||||
JVM system property to configure the file path is `java.security.krb5.conf`. To
|
||||
configure JVM system properties see {ref}/jvm-options.html[configuring jvm options].
|
||||
If this system property is not specified, Java tries to locate the file based on
|
||||
the conventions.
|
||||
|
||||
TIP: 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.
|
||||
|
||||
For more information, see http://web.mit.edu/kerberos/krb5-latest/doc/admin/conf_files/krb5_conf.html[krb5.conf]
|
||||
|
||||
--
|
||||
|
||||
. Create a keytab for the {es} node.
|
||||
+
|
||||
--
|
||||
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.
|
||||
--
|
||||
|
||||
. Put the keytab file in the {es} configuration directory.
|
||||
+
|
||||
--
|
||||
Make sure that this keytab file has read permissions. This file contains
|
||||
credentials, therefore you must take appropriate measures to protect it.
|
||||
|
||||
IMPORTANT: {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/es.domain.local@ES.DOMAIN.LOCAL`.
|
||||
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.
|
||||
|
||||
--
|
||||
|
||||
. Create a Kerberos realm.
|
||||
+
|
||||
--
|
||||
|
||||
To enable Kerberos authentication in {es}, you must add a Kerberos realm in the
|
||||
realm chain.
|
||||
|
||||
NOTE: You can configure only one Kerberos realm on {es} nodes.
|
||||
|
||||
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 of type `kerberos` under the
|
||||
`xpack.security.authc.realms` namespace.
|
||||
|
||||
The most common configuration for a Kerberos realm is as follows:
|
||||
|
||||
[source, yaml]
|
||||
------------------------------------------------------------
|
||||
xpack.security.authc.realms.kerb1:
|
||||
type: kerberos
|
||||
order: 3
|
||||
keytab.path: es.keytab
|
||||
remove_realm_name: false
|
||||
------------------------------------------------------------
|
||||
|
||||
The `username` is extracted from the ticket presented by 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. The resulting `username`
|
||||
is used for role mapping.
|
||||
|
||||
For detailed information of available realm settings,
|
||||
see {ref}/security-settings.html#ref-kerberos-settings[Kerberos realm settings].
|
||||
|
||||
--
|
||||
|
||||
. Restart {es}
|
||||
|
||||
. Map Kerberos users to roles.
|
||||
+
|
||||
--
|
||||
|
||||
The `kerberos` realm enables you to map Kerberos users to roles. You can
|
||||
configure these role mappings by using the
|
||||
{ref}/security-api-role-mapping.html[role-mapping API]. You identify
|
||||
users by their `username` field.
|
||||
|
||||
The following example uses the role mapping API to map `user@REALM` to the roles
|
||||
`monitoring` and `user`:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
POST _xpack/security/role_mapping/kerbrolemapping
|
||||
{
|
||||
"roles" : [ "monitoring_user" ],
|
||||
"enabled": true,
|
||||
"rules" : {
|
||||
"field" : { "username" : "user@REALM" }
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
|
||||
For more information, see {stack-ov}/mapping-roles.html[Mapping users and groups to roles].
|
||||
--
|
||||
|
|
@ -77,6 +77,7 @@ user API.
|
|||
** <<configuring-native-realm,Configure a native realm>>.
|
||||
** <<configuring-pki-realm,Configure a PKI realm>>.
|
||||
** <<configuring-saml-realm,Configure a SAML realm>>.
|
||||
** <<configuring-kerberos-realm,Configure a Kerberos realm>>.
|
||||
|
||||
. Set up roles and users to control access to {es}.
|
||||
For example, to grant _John Doe_ full access to all indices that match
|
||||
|
@ -142,5 +143,7 @@ include::authentication/configuring-ldap-realm.asciidoc[]
|
|||
include::authentication/configuring-native-realm.asciidoc[]
|
||||
include::authentication/configuring-pki-realm.asciidoc[]
|
||||
include::authentication/configuring-saml-realm.asciidoc[]
|
||||
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/authentication/configuring-kerberos-realm.asciidoc
|
||||
include::authentication/configuring-kerberos-realm.asciidoc[]
|
||||
include::{es-repo-dir}/settings/security-settings.asciidoc[]
|
||||
include::{es-repo-dir}/settings/audit-settings.asciidoc[]
|
||||
|
|
Loading…
Reference in New Issue