[Kerberos] Add troubleshooting documentation #32803

bizybot · 2018-08-13T07:59:02Z

This commit adds troubleshooting section for Kerberos.
Most of the times the problems seen are caused due to invalid
configurations like keytab missing principals or credentials
not up to date. Time synchronization is an important part for
Kerberos infrastructure and the time skew can cause problems.
To debug further documentation explains how to enable JAAS
Kerberos login module debugging and Kerberos/SPNEGO debugging
by setting JVM system properties.

This commit adds troubleshooting section for Kerberos. Most of the times the problems seen are caused due to invalid configurations like keytab missing principals or credentials not up to date. Time synchronization is important part for Kerberos infrastructure and the time skew can cause problems. To debug further documentation explains how to enable JAAS Kerberos login module debugging and Kerberos/SPNEGO debugging by setting JVM system propertoes.

elasticmachine · 2018-08-13T07:59:04Z

Pinging @elastic/es-security

elasticmachine · 2018-08-13T07:59:05Z

Pinging @elastic/es-docs

lcawl · 2018-08-15T23:01:20Z

x-pack/docs/en/security/troubleshooting.asciidoc

+
+* User authentication fails due to either GSS negotiation failure
+or a service login failure on the server side or in the {es} HTTP client. Some of
+the common exceptions are listed below with some tips to resolve them. 


If I'm understanding the first sentence correctly, I think it should be changed to something like this: "User authentication fails due to either a GSS negotiation failure or a service login failure (on the server or the {es} HTTP client)".

Yes, you are right. Thank you.

lcawl · 2018-08-15T23:03:53Z

x-pack/docs/en/security/troubleshooting.asciidoc

+
+*Resolution:*
+
+`Failure unspecified at GSS-API level (Mechanism level: Checksum failed)`::


Are these error messages in specific logs or on specific machines in the deployment?

I have updated with some more information as it can log message on the server side and an error message on the client. Thank you.

lcawl · 2018-08-15T23:05:10Z

x-pack/docs/en/security/troubleshooting.asciidoc

+--
+
+When this occurs on HTTP client side, it may be related to an incorrect password.
+


Are the subsequent paragraphs related to when this occurs on the server side?

I have separated this into client and server and yes the subsequent paragraphs are related to server-side except the last one which talks about hostname resolution which is common to both. Thank you.

jaymode · 2018-08-16T16:43:52Z

x-pack/docs/en/security/troubleshooting.asciidoc

+
+--
+
+To prevent replay attacks, Kerberos V5 sets maximum tolerance for computer clock


sets a maximum

Done, Thank you.

jaymode · 2018-08-16T16:44:23Z

x-pack/docs/en/security/troubleshooting.asciidoc

+--
+
+To prevent replay attacks, Kerberos V5 sets maximum tolerance for computer clock
+synchronization and it is usually set to 5 minutes. Check whether the time on 


it is typically 5 minutes

Done, Thank you.

jaymode · 2018-08-16T16:46:25Z

x-pack/docs/en/security/troubleshooting.asciidoc

+
+For detailed information, see {ref}/security-settings.html#ref-kerberos-settings[Kerberos realm settings].
+
+To enable Kerberos logging on JVM, add following JVM system properties:


I think this needs some context. Like when and why would you do this. How does it differ from the login module debug log

I added some context about what does this additional logging provide as in GSS context negotiation logs and Kerberos exchange messages. Thank you.

…roubleshooting-kerberos

tvernum · 2018-08-17T08:13:47Z

x-pack/docs/en/security/troubleshooting.asciidoc

+
+Kerberos depends on proper hostname resolution, so please check your DNS infrastructure.
+Incorrect DNS setup, DNS SRV records or configuration for KDC servers in `krb5.conf` 
+can cause problems with hostname resolution.


Is this + intended?

oops, Removed it. Thanks.

tvernum · 2018-08-17T08:15:03Z

x-pack/docs/en/security/troubleshooting.asciidoc

+
+As Kerberos logs are often cryptic in nature and many things can go wrong 
+as it depends on external services like DNS, time synchronization. You might 
+have to enable additional debug logs to root cause the issue.


I don't think "root cause" is a verb 😈

Maybe "... debug logs to determine the root cause of the issue."

Thank you, Tim. Addressed this.

tvernum

👍

jaymode

I left some feedback. After those are addressed, LGTM

jaymode · 2018-08-20T17:37:43Z

x-pack/docs/en/security/troubleshooting.asciidoc

+*Symptoms:*
+
+* User authentication fails due to either GSS negotiation failure 
+or a service login failure ( either on the server or in the {es} http client). 


nit remove space between ( and e

Thank you, addressed this.

jaymode · 2018-08-20T17:38:20Z

x-pack/docs/en/security/troubleshooting.asciidoc

+
+* User authentication fails due to either GSS negotiation failure 
+or a service login failure ( either on the server or in the {es} http client). 
+Some of the common exceptions are listed below with some tips to resolve them.


s/some tips to resolve/tips to help resolve

Changed, thank you.

jaymode · 2018-08-20T17:39:35Z

x-pack/docs/en/security/troubleshooting.asciidoc

+--
+
+As Kerberos logs are often cryptic in nature and many things can go wrong 
+as it depends on external services like DNS, time synchronization. You might 


s/DNS, time synchronization/DNS and NTP.

Modified this, Thank you.

jaymode · 2018-08-20T17:39:56Z

x-pack/docs/en/security/troubleshooting.asciidoc

+as it depends on external services like DNS, time synchronization. You might 
+have to enable additional debug logs to determine the root cause of the issue.
+
+{es} uses JAAS (Java Authentication and Authorization Service) Kerberos login 


s/uses JAAS/uses a JAAS

Modified this, Thank you

jaymode · 2018-08-20T17:40:28Z

x-pack/docs/en/security/troubleshooting.asciidoc

+For detailed information, see {ref}/security-settings.html#ref-kerberos-settings[Kerberos realm settings].
+
+Sometimes you may need to go deeper to understand the problem during SPNEGO 
+gss context negotiation or look at the Kerberos message exchange. To enable 


Modified this, Thank you

This commit adds troubleshooting section for Kerberos. Most of the times the problems seen are caused due to invalid configurations like keytab missing principals or credentials not up to date. Time synchronization is an important part for Kerberos infrastructure and the time skew can cause problems. To debug further documentation explains how to enable JAAS Kerberos login module debugging and Kerberos/SPNEGO debugging by setting JVM system properties.

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 13, 2018

bizybot requested review from jaymode, lcawl and tvernum August 13, 2018 07:59

bizybot changed the title ~~[Kerberos] Add troubleshooting documentation for Kerberos~~ [Kerberos] Add troubleshooting documentation Aug 13, 2018

[DOCS] Edits the Kerberos troubleshooting content

a559878

lcawl reviewed Aug 15, 2018

View reviewed changes

jaymode reviewed Aug 16, 2018

View reviewed changes

Yogesh Gaikwad added 3 commits August 17, 2018 13:26

Merge branch 'master' into troubleshooting-kerberos

2c94bb1

Merge remote-tracking branch 'origin/troubleshooting-kerberos' into t…

df46fa2

…roubleshooting-kerberos

[DOCS] Address review comments

9525bf8

tvernum reviewed Aug 17, 2018

View reviewed changes

Yogesh Gaikwad added 2 commits August 17, 2018 22:10

[DOCS] Address review comments

3b544ff

Merge branch 'master' into troubleshooting-kerberos

7ea4012

tvernum approved these changes Aug 20, 2018

View reviewed changes

Merge branch 'master' into troubleshooting-kerberos

0dbfd10

jaymode approved these changes Aug 20, 2018

View reviewed changes

Yogesh Gaikwad added 2 commits August 21, 2018 11:13

[DOCS] Address review comments

dd983fd

Merge branch 'master' into troubleshooting-kerberos

233b35a

bizybot merged commit 38886e8 into elastic:master Aug 21, 2018

bizybot deleted the troubleshooting-kerberos branch August 21, 2018 06:35

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

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


		Resolution:

		`Failure unspecified at GSS-API level (Mechanism level: Checksum failed)`::

		--

		When this occurs on HTTP client side, it may be related to an incorrect password.


		For detailed information, see {ref}/security-settings.html#ref-kerberos-settings[Kerberos realm settings].

		To enable Kerberos logging on JVM, add following JVM system properties:

[Kerberos] Add troubleshooting documentation #32803

[Kerberos] Add troubleshooting documentation #32803

Uh oh!

Conversation

bizybot commented Aug 13, 2018

Uh oh!

elasticmachine commented Aug 13, 2018

Uh oh!

elasticmachine commented Aug 13, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tvernum left a comment

Choose a reason for hiding this comment

Uh oh!

jaymode left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants