From 875341c6024d2f68d8ab6c8148f0675601a6e539 Mon Sep 17 00:00:00 2001 From: Sokratis Papadopoulos Date: Tue, 30 Jul 2024 18:08:33 +0200 Subject: [PATCH] Add documentation on Kerberos configuration (#7844) * Add documentation on Kerberos configuration. Signed-off-by: Sokratis Papadopoulos * Add krb doc Signed-off-by: Sokratis Papadopoulos * Reorder kerberos in backend list Signed-off-by: Sokratis Papadopoulos * Reformat Signed-off-by: Sokratis Papadopoulos * Typo on acceptor_principal Signed-off-by: Sokratis Papadopoulos * Fix style Signed-off-by: Sokratis Papadopoulos * Fix style Signed-off-by: Sokratis Papadopoulos * Typo on acceptor_principal Signed-off-by: Sokratis Papadopoulos * Add default value for boolean params Signed-off-by: Sokratis Papadopoulos * Update kerberos.md --------- Signed-off-by: Sokratis Papadopoulos Co-authored-by: Sokratis Papadopoulos Co-authored-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- _security/authentication-backends/kerberos.md | 62 ++++++++++++++++++ _security/configuration/configuration.md | 64 +------------------ 2 files changed, 64 insertions(+), 62 deletions(-) create mode 100644 _security/authentication-backends/kerberos.md diff --git a/_security/authentication-backends/kerberos.md b/_security/authentication-backends/kerberos.md new file mode 100644 index 00000000000..40b041abcb6 --- /dev/null +++ b/_security/authentication-backends/kerberos.md @@ -0,0 +1,62 @@ +--- +layout: default +title: Kerberos +parent: Authentication backends +nav_order: 75 +--- + +# Kerberos + +Kerberos is a robust and secure method for user authentication that prevents passwords from being sent over the internet by issuing "tickets" for secure identity verification. + +In order to use Kerberos authentication, you must set the following settings in `opensearch.yml` and `config.yml`. + +## OpenSearch node configuration + +In `opensearch.yml`, define the following settings: + +```yml +plugins.security.kerberos.krb5_filepath: '/etc/krb5.conf' +plugins.security.kerberos.acceptor_keytab_filepath: 'opensearch_keytab.tab' +plugins.security.kerberos.acceptor_principal: 'HTTP/localhost' +``` + +Name | Description +:--- | :--- +`krb5_filepath` | The path to your Kerberos configuration file. This file contains various settings regarding your Kerberos installation, for example, the `realm` names, `hostnames`, and ports of the Kerberos key distribution center (KDC). +`acceptor_keytab_filepath` | The path to the `keytab` file, which contains the principal that the Security plugin uses to issue requests through Kerberos. +`acceptor_principal` | The principal that the Security plugin uses to issue requests through Kerberos. This value must be present in the `keytab` file. + +Due to security restrictions, the `keytab` file must be placed in `config` or a subdirectory, and the path in `opensearch.yml` must be relative, not absolute. +{: .note } + +## Cluster security configuration + +The following example shows a typical Kerberos authentication domain in `config.yml`: + +```yml +kerberos_auth_domain: + enabled: true + order: 1 + http_authenticator: + type: kerberos + challenge: true + config: + krb_debug: false + strip_realm_from_principal: true + authentication_backend: + type: noop +``` + +Authentication through Kerberos when using a browser on an HTTP level is achieved using SPNEGO. Kerberos/SPNEGO implementations vary, depending on your browser and operating system. This is important when deciding if you need to set the `challenge` flag to `true` or `false`. + +As with [HTTP Basic Authentication]({{site.url}}{{site.baseurl}}/security/authentication-backends/basic-authc/), this flag determines how the Security plugin should react when no `Authorization` header is found in the HTTP request or if this header does not equal `negotiate`. + +If set to `true`, the Security plugin sends a response with status code 401 and a `WWW-Authenticate` header set to `negotiate`. This tells the client (browser) to resend the request with the `Authorization` header set. If set to `false`, the Security plugin cannot extract the credentials from the request, and authentication fails. Setting `challenge` to `false` thus makes sense only if the Kerberos credentials are sent in the initial request. + +Name | Description +:--- | :--- +`krb_debug` | As the name implies, setting it to `true` outputs Kerberos-specific debugging messages to `stdout`. Use this setting if you encounter problems with your Kerberos integration. Default is `false`. +`strip_realm_from_principal` | When set it to `true`, the Security plugin strips the realm from the user name. Default: `true`. + +Because Kerberos/SPNEGO authenticates users on an HTTP level, no additional `authentication_backend` is needed. Set this value to `noop`. diff --git a/_security/configuration/configuration.md b/_security/configuration/configuration.md index 2a038b7fb9d..57008a41586 100755 --- a/_security/configuration/configuration.md +++ b/_security/configuration/configuration.md @@ -97,6 +97,7 @@ The `type` setting for `http_authenticator` accepts the following values. For mo | Value | Description | | :--- | :--- | | `basic` | HTTP basic authentication. For more information about using basic authentication, see the HTTP basic authentication documentation. | +| `kerberos` | Kerberos authentication. See the Kerberos documentation for additional configuration information. | | `jwt` | JSON Web Token (JWT) authentication. See the JSON Web Token documentation for additional configuration information. | | `openid` | OpenID Connect authentication. See the OpenID Connect documentation for additional configuration information. | | `saml` | SAML authentication. See the SAML documentation for additional configuration information. | @@ -162,65 +163,4 @@ To learn about configuring the authentication backends, see the [Authentication * [Active Directory and LDAP]({{site.url}}{{site.baseurl}}/security/authentication-backends/ldap/) * [Proxy-based authentication]({{site.url}}{{site.baseurl}}/security/authentication-backends/proxy/) * [Client certificate authentication]({{site.url}}{{site.baseurl}}/security/authentication-backends/client-auth/) - - - - +* [Kerberos authentication]({{site.url}}{{site.baseurl}}/security/authentication-backends/kerberos/)