Add documentation on Kerberos configuration (opensearch-project#7844)

* Add documentation on Kerberos configuration. Signed-off-by: Sokratis Papadopoulos <[email protected]> * Add krb doc Signed-off-by: Sokratis Papadopoulos <[email protected]> * Reorder kerberos in backend list Signed-off-by: Sokratis Papadopoulos <[email protected]> * Reformat Signed-off-by: Sokratis Papadopoulos <[email protected]> * Typo on acceptor_principal Signed-off-by: Sokratis Papadopoulos <[email protected]> * Fix style Signed-off-by: Sokratis Papadopoulos <[email protected]> * Fix style Signed-off-by: Sokratis Papadopoulos <[email protected]> * Typo on acceptor_principal Signed-off-by: Sokratis Papadopoulos <[email protected]> * Add default value for boolean params Signed-off-by: Sokratis Papadopoulos <[email protected]> * Update kerberos.md --------- Signed-off-by: Sokratis Papadopoulos <[email protected]> Co-authored-by: Sokratis Papadopoulos <[email protected]> Co-authored-by: Naarcha-AWS <[email protected]>
mingshl · Aug 2, 2024 · 875341c · 875341c
1 parent 1870ceb
commit 875341c
Show file tree

Hide file tree

Showing 2 changed files with 64 additions and 62 deletions.
diff --git a/_security/authentication-backends/kerberos.md 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
@@ -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/)
-
-
-<!--- Remvoving Kerberos documentation until issue #907 is resolved.
-### Kerberos
-
-Kerberos authentication does not work with OpenSearch Dashboards. To track OpenSearch's progress in adding support for Kerberos in OpenSearch Dashboards, see [issue #907](https://github.com/opensearch-project/security-dashboards-plugin/issues/907) in the Dashboard's Security plugin repository. 
-{: .warning }
-
-Due to the nature of Kerberos, you must define some settings in `opensearch.yml` and some in `config.yml`.
-
-In `opensearch.yml`, define the following:
-
-```yml
-plugins.security.kerberos.krb5_filepath: '/etc/krb5.conf'
-plugins.security.kerberos.acceptor_keytab_filepath: 'eskeytab.tab'
-```
-
-- `plugins.security.kerberos.krb5_filepath` defines 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).
-
-- `plugins.security.kerberos.acceptor_keytab_filepath` defines the path to the keytab file, which contains the principal that the Security plugin uses to issue requests against Kerberos.
-
-- `plugins.security.kerberos.acceptor_principal: 'HTTP/localhost'` defines the principal that the Security plugin uses to issue requests against 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 }
-
-
-#### Dynamic configuration
-
-A typical Kerberos authentication domain in `config.yml` looks like this:
-
-```yml
-    authc:
-      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 against Kerberos through 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](#http-basic), 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.
-
-As the name implies, setting `krb_debug` to `true` will output Kerberos-specific debugging messages to `stdout`. Use this setting if you encounter problems with your Kerberos integration.
-
-If you set `strip_realm_from_principal` to `true`, the Security plugin strips the realm from the user name.
-
-
-#### Authentication backend
-
-Because Kerberos/SPNEGO authenticates users on an HTTP level, no additional `authentication_backend` is needed. Set this value to `noop`.
---->
-
+* [Kerberos authentication]({{site.url}}{{site.baseurl}}/security/authentication-backends/kerberos/)