[Kerberos] Add documentation for Kerberos realm #32662

bizybot · 2018-08-07T02:33:58Z

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 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. TODO: - Troubleshooting documentation will be added in the next PR

elasticmachine · 2018-08-07T02:33:59Z

Pinging @elastic/es-docs

elasticmachine · 2018-08-07T02:34:00Z

Pinging @elastic/es-security

jbaiera · 2018-08-09T13:23:15Z

x-pack/docs/en/security/authentication/configuring-kerberos-realm.asciidoc

+Windows or `kadmin` for MIT Kerberos are some tools that can be used
+for creation of keytabs. Place this keytab file in the `ES_PATH_CONF`.
+Make sure that this keytab file has read permissions. As this file contains
+credentials appropriate measures must be taken to protect it.


Can we clarify further the principal names to use for Elasticsearch? I saw in the code that we allow logging in for principal *. If we're using unbound keytabs, it might make sense to mention that here

Sure, I will update this to add that information. Thank you.

lcawl · 2018-08-15T17:46:30Z

docs/reference/settings/security-settings.asciidoc

+
+`keytab.path`:: Specifies the path to the Kerberos keytab file that contains the 
+service principal used by this {es} node. It expects the keytab file to be present in `ES_PATH_CONF`
+and have read permissions. Required.


Does this mean that the keytab file must be in the ES_PATH_CONF, or is that just the default location?

Yes, it must be in the ES_PATH_CONF else elasticsearch will not have file permissions to access it unless we go. This is as per default installation. We can modify java security policy and give a different location but I am not sure if we mention that anywhere.

Do we say something similar for other files such as certificates? I think we should just be consistent with what we say

Yes, at places we say to put certificates in es configuration directory and have updated this to be consistent with what we say. Thank you.

lcawl · 2018-08-15T19:57:53Z

x-pack/docs/en/security/authentication/configuring-kerberos-realm.asciidoc

+
+--
+
+. Create a keytab for the service node. 


It is unclear what is meant by "the service node" here.

Changed it toElasticsearch node. Thank you.

lcawl · 2018-08-15T19:59:17Z

x-pack/docs/en/security/authentication/configuring-kerberos-realm.asciidoc

+Windows and `kadmin` for MIT Kerberos. 
+--
+
+. Put the keytab file in the `ES_PATH_CONF`.


Per earlier comment, can we put it in a different path if keytab.path is set appropriately?

No, we cannot put keytab in different path as we need permissions to access the file. Thank you.

lcawl · 2018-08-15T20:00:57Z

x-pack/docs/en/security/authentication/configuring-kerberos-realm.asciidoc

+credentials, therefore you must take appropriate measures to protect it.
+
+IMPORTANT: On every {es} node, there must be a keytab file for the HTTP
+principal. The keytab files are unique for each node since they include the


This is the first time we've referred to an "HTTP principal". Can this be clarified?

Clarified further, Thank you.

lcawl · 2018-08-15T20:02:10Z

docs/reference/settings/security-settings.asciidoc

+Principal names in Kerberos have the form `user/instance@REALM`. If this option 
+is `true`, the realm part (`@REALM`) is removed before setting the `username` 
+field in `User`. The shortened `username` value can then used during role mapping. 
+Defaults to `false`.


Does this mean you can't use role mappings unless that realm part is removed?

No, it is a option to decide whether to keep the @REALM part in the username. Changed the sentence as suggested by Jay. Thank you.

lcawl · 2018-08-15T20:03:42Z

x-pack/docs/en/security/authentication/configuring-kerberos-realm.asciidoc

+the format `username@REALM`. This `username` can then be used for mapping
+roles to the user. There is a realm setting `remove_realm_name` which when
+set to `true` removes the realm part (`@REALM`) and the resulting `username` can 
+then be used for role mapping.


Per previous comment, this seems to imply that you can't use role mappings successfully unless you set remove_realm_name to true. Is that right?

No, as explained above changed the wording as suggested by Jay. Thank you.

jaymode

I left some comments and suggestions

jaymode · 2018-08-15T19:50:00Z

docs/reference/settings/security-settings.asciidoc

+
+`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`) is removed before setting the `username` 


this goes into the code too much. I would just say the realm part (@realm) will not be included in the username

Removed the unwanted information. Thanks.

jaymode · 2018-08-15T19:53:18Z

x-pack/docs/en/security/authentication/configuring-kerberos-realm.asciidoc

+
+==== Create a Kerberos realm
+
+Following are the steps to enable Kerberos realm:


Maybe Perform the following steps to define a Kerberos realm

Lisa addressed this in her commit. Thank you.

jaymode · 2018-08-15T19:53:55Z

x-pack/docs/en/security/authentication/configuring-kerberos-realm.asciidoc

+
+Following are the steps to enable Kerberos realm:
+
+. Enable SSL/TLS for HTTP


is this really a requirement?

Not entirely as in it can function without enabling TLS. Some clients like Apache HTTP client do not complete the mutual authentication step to verify server. We can remove this if we do not want to have this as a hard requirement. We do not explicitly enforce this. Please suggest. Thank you.

If we do not enforce it, then we should remove it.

jaymode · 2018-08-15T19:54:24Z

x-pack/docs/en/security/authentication/configuring-kerberos-realm.asciidoc

+
+--
+
+`krb5.conf` is the Kerberos configuration file. {es} uses Java GSS and


s/is the/is the name of the

Lisa addressed this in her commit. Thank you.

jaymode · 2018-08-15T19:55:03Z

x-pack/docs/en/security/authentication/configuring-kerberos-realm.asciidoc

+--
+
+`krb5.conf` is the Kerberos configuration file. {es} uses Java GSS and
+JAAS Krb5LoginModule to support Kerberos authentication using Spnego


the JAAS Krb5LoginModule. s/Spnego/the SPNEGO

Lisa addressed this in her commit. Thank you.

jaymode · 2018-08-15T19:59:09Z

x-pack/docs/en/security/authentication/configuring-kerberos-realm.asciidoc

+Make sure that this keytab file has read permissions. As this file contains
+credentials appropriate measures must be taken to protect it.
+
+IMPORTANT: On every {es} node, there must be a keytab file for HTTP


s/HTTP/the HTTP

Done, Thank you.

jaymode · 2018-08-15T19:59:28Z

x-pack/docs/en/security/authentication/configuring-kerberos-realm.asciidoc

+IMPORTANT: On every {es} node, there must be a keytab file for HTTP
+principal. The keytab files are unique for each node as they include the
+hostname. Usually it will be of format `HTTP/[email protected]`
+{es} node can act as any principal a client requests as long as that


s/node/nodes

Done, thank you.

jaymode · 2018-08-15T20:00:15Z

x-pack/docs/en/security/authentication/configuring-kerberos-realm.asciidoc

+
+NOTE: You can only have one Kerberos realm configured on a {es} node.
+
+To configure Kerberos realm, there are few mandatory realm settings and


s/Kerberos/a Kerberos. s/there are/there are a

Addressed, Thank you.

jaymode · 2018-08-15T21:20:04Z

x-pack/docs/en/security/authentication/configuring-kerberos-realm.asciidoc

+configuration file. Add realm configuration of type `kerberos` under
+the `xpack.security.authc.realms` namespace.
+
+Most common configuration for Kerberos realm is as follows:


Done, Thank you.

jaymode · 2018-08-15T21:21:05Z

x-pack/docs/en/security/authentication/configuring-kerberos-realm.asciidoc

+The `kerberos` realm enables you to map Kerberos users to the roles.
+This role mapping can be configured via the
+{ref}/security-api-role-mapping.html[role-mapping API] or by using a file
+stored on each node. You identify user by its `username` field.


s/identify user/identify a user

Lisa addressed this in her commit, Thank you.

jaymode

LGTM pending making sure we're consistent about config files and ES_PATH_CONF

lcawl

I made a few edits in the "important" section of the configuration page. If those changes are satisfactory, this PR LGTM

…beros-documentation

jaymode · 2018-08-20T18:35:37Z

@bizybot please do not forget to backport this to 6.x and 6.4

* master: Generalize remote license checker (#32971) Trim translog when safe commit advanced (#32967) Fix an inaccuracy in the dynamic templates documentation. (#32890) Logging: Use settings when building daemon threads (#32751) All Translog inner closes should happen after tragedy exception is set (#32674) HLREST: AwaitsFix ML Test Pass DiscoveryNode to initiateChannel (#32958) Add mzn and dz to unsupported locales (#32957) Use settings from the context in BootstrapChecks (#32908) Update docs for node specifications (#30468) HLRC: Forbid all Elasticsearch logging infra (#32784) Only configure publishing if it's applied externally (#32351) Fixes libs:dissect when in eclipse Protect ScriptedMetricIT test cases against failures on 0-doc shards (#32959) (#32968) [Kerberos] Add documentation for Kerberos realm (#32662) Watcher: Properly find next valid date in cron expressions (#32734) Fix some small issues in the getting started docs (#30346) Set forbidden APIs target compatibility to compiler java version (#32935) Move connection listener to ConnectionManager (#32956)

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.

…e-types * elastic/master: (89 commits) Fix assertion in AbstractSimpleTransportTestCase (elastic#32991) [DOC] Splits role mapping APIs into separate pages (elastic#32797) HLRC: ML Close Job (elastic#32943) Generalize remote license checker (elastic#32971) Trim translog when safe commit advanced (elastic#32967) Fix an inaccuracy in the dynamic templates documentation. (elastic#32890) Logging: Use settings when building daemon threads (elastic#32751) All Translog inner closes should happen after tragedy exception is set (elastic#32674) HLREST: AwaitsFix ML Test Pass DiscoveryNode to initiateChannel (elastic#32958) Add mzn and dz to unsupported locales (elastic#32957) Use settings from the context in BootstrapChecks (elastic#32908) Update docs for node specifications (elastic#30468) HLRC: Forbid all Elasticsearch logging infra (elastic#32784) Only configure publishing if it's applied externally (elastic#32351) Fixes libs:dissect when in eclipse Protect ScriptedMetricIT test cases against failures on 0-doc shards (elastic#32959) (elastic#32968) [Kerberos] Add documentation for Kerberos realm (elastic#32662) Watcher: Properly find next valid date in cron expressions (elastic#32734) Fix some small issues in the getting started docs (elastic#30346) ...

bizybot added review v7.0.0 :Security/Authentication Logging in, Usernames/passwords, Realms (Native/LDAP/AD/SAML/PKI/etc) v6.4.0 v6.5.0 labels Aug 7, 2018

bizybot requested review from tvernum and lcawl August 7, 2018 02:33

Yogesh Gaikwad added 2 commits August 9, 2018 12:45

[Kerberos] Change role used in the role mapping API

b0c93a7

Merge branch 'master' into kerberos-documentation

98012d4

jbaiera reviewed Aug 9, 2018

View reviewed changes

Add information about unbound keytab usage

bfd23a1

bizybot requested a review from jaymode August 13, 2018 00:27

[DOCS] Small edits to the security settings

d257531

lcawl reviewed Aug 15, 2018

View reviewed changes

lcawl mentioned this pull request Aug 15, 2018

[Kerberos] Add stack documentation for Kerberos realm elastic/stack-docs#98

Merged

lcawl added 2 commits August 15, 2018 11:37

[DOCS] Moved Kerberos terminology

b40799a

[DOCS] Edits the Kerberos configuration page

447dde2

lcawl reviewed Aug 15, 2018

View reviewed changes

jaymode reviewed Aug 15, 2018

View reviewed changes

Address review comments

5417703

jaymode approved these changes Aug 16, 2018

View reviewed changes

Address review comments

8386a98

[DOCS] Small clarifications to important section

514d043

lcawl approved these changes Aug 16, 2018

View reviewed changes

Yogesh Gaikwad added 5 commits August 17, 2018 11:10

Merge branch 'master' into kerberos-documentation

3141d55

Merge remote-tracking branch 'origin/kerberos-documentation' into ker…

2625ac3

…beros-documentation

[DOCS] Kerberos supports only role mapping api

4d90102

Merge branch 'master' into kerberos-documentation

2c9df46

Merge branch 'master' into kerberos-documentation

3aa5f71

bizybot merged commit e143cce into elastic:master Aug 20, 2018

lcawl added the >docs General docs changes label Aug 20, 2018

jaymode added the backport pending label Aug 20, 2018

bizybot deleted the kerberos-documentation branch August 21, 2018 06:36

bizybot removed the backport pending label Oct 18, 2018

jimczi added v7.0.0-beta1 and removed v7.0.0 labels Feb 7, 2019


		==== Create a Kerberos realm

		Following are the steps to enable Kerberos realm:


		Following are the steps to enable Kerberos realm:

		. Enable SSL/TLS for HTTP


		NOTE: You can only have one Kerberos realm configured on a {es} node.

		To configure Kerberos realm, there are few mandatory realm settings and

[Kerberos] Add documentation for Kerberos realm #32662

[Kerberos] Add documentation for Kerberos realm #32662

Conversation

bizybot commented Aug 7, 2018 • edited Loading

elasticmachine commented Aug 7, 2018

elasticmachine commented Aug 7, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bizybot Aug 16, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jaymode left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jaymode left a comment

Choose a reason for hiding this comment

lcawl left a comment

Choose a reason for hiding this comment

jaymode commented Aug 20, 2018

bizybot commented Aug 7, 2018 •

edited

Loading

bizybot Aug 16, 2018 •

edited

Loading