From 186ce830a0343fae2e3f784fe3efd49214eee27c Mon Sep 17 00:00:00 2001 From: Janne Valkealahti Date: Thu, 26 Mar 2015 09:44:41 +0000 Subject: [PATCH] Ref doc updates --- docs/src/reference/asciidoc/appendix.adoc | 125 ++++++++++++++++++++++ docs/src/reference/asciidoc/samples.adoc | 7 ++ 2 files changed, 132 insertions(+) diff --git a/docs/src/reference/asciidoc/appendix.adoc b/docs/src/reference/asciidoc/appendix.adoc index 7dd6455..9e9b24c 100644 --- a/docs/src/reference/asciidoc/appendix.adoc +++ b/docs/src/reference/asciidoc/appendix.adoc @@ -259,6 +259,7 @@ or typos. Kerberos setup is generally very brittle and it is not always very easy to debug where the problem lies. ==== +.Cannot find key of appropriate type to decrypt [source,text] ---- @@ -284,6 +285,130 @@ simply don't have a required encryption key which then may be caused by a misconfiguration in your kerberos server or a simply typo in your principal. +.Using wrong kerberos configuration + +{zwsp} + + +In most system all commands and libraries will search kerberos +configuration either from a default locations or special locations +like JDKs. It's easy to get mixed up especially if working from unix +systems, which already may have default settings to work with MIT +kerberos, towards Windows domains. + +This is a specific example what happens with `ldapsearch` trying to +query Windows AD using kerberos authentication. + +[source,text] +---- +$ ldapsearch -H ldap://WIN-EKBO0EQ7TS7.example.org -b "dc=example,dc=org" +SASL/GSSAPI authentication started +ldap_sasl_interactive_bind_s: Local error (-2) + additional info: SASL(-1): generic failure: GSSAPI Error: + Unspecified GSS failure. Minor code may provide more information + (No Kerberos credentials available) +---- + +Well that doesn't look good and is a simple indication that I don't +have a valid kerberos tickets as shown below. + +[source,text] +---- +$ klist +klist: Credentials cache file '/tmp/krb5cc_1000' not found +---- + +We already have a keytab file we exported from Windows AD to be used +with tomcat running on Linux. Lets try to use that to authenticate +with Windows AD. + +You can have a dedicated config file which usually can be used with +native Linux commands and JVMs via system propertys. + +[source,text] +---- +$ cat krb5.ini +[libdefaults] +default_realm = EXAMPLE.ORG +default_keytab_name = /tmp/tomcat.keytab +forwardable=true + +[realms] +EXAMPLE.ORG = { + kdc = WIN-EKBO0EQ7TS7.example.org:88 +} + +[domain_realm] +example.org=EXAMPLE.ORG +.example.org=EXAMPLE.ORG +---- + +Lets use that config and a keytab to get initial credentials. + +[source,text] +---- +$ env KRB5_CONFIG=/path/to/krb5.ini kinit -kt tomcat.keytab HTTP/neo.example.org@EXAMPLE.ORG + +$ klist +Ticket cache: FILE:/tmp/krb5cc_1000 +Default principal: HTTP/neo.example.org@EXAMPLE.ORG + +Valid starting Expires Service principal +26/03/15 09:04:37 26/03/15 19:04:37 krbtgt/EXAMPLE.ORG@EXAMPLE.ORG + renew until 27/03/15 09:04:37 +---- + +Lets see what happens if we now try to do a simple query against +Windows AD. + +[source,text] +---- +$ ldapsearch -H ldap://WIN-EKBO0EQ7TS7.example.org -b "dc=example,dc=org" +SASL/GSSAPI authentication started +ldap_sasl_interactive_bind_s: Local error (-2) + additional info: SASL(-1): generic failure: GSSAPI Error: + Unspecified GSS failure. Minor code may provide more information + (KDC returned error string: PROCESS_TGS) +---- + +This may be simply because `ldapsearch` is getting confused and simply +using wrong configuration. You can tell `ldapsearch` to use a +different configuration via `KRB5_CONFIG` env variable just like we +did with `kinit`. You can also use `KRB5_TRACE=/dev/stderr` to get +more verbose output of what native libraries are doing. + +[source,text] +---- +$ env KRB5_CONFIG=/path/to/krb5.ini ldapsearch -H ldap://WIN-EKBO0EQ7TS7.example.org -b "dc=example,dc=org" + +$ klist +Ticket cache: FILE:/tmp/krb5cc_1000 +Default principal: HTTP/neo.example.org@EXAMPLE.ORG + +Valid starting Expires Service principal +26/03/15 09:11:03 26/03/15 19:11:03 krbtgt/EXAMPLE.ORG@EXAMPLE.ORG + renew until 27/03/15 09:11:03 + 26/03/15 09:11:44 26/03/15 19:11:03 + ldap/win-ekbo0eq7ts7.example.org@EXAMPLE.ORG + renew until 27/03/15 09:11:03 +---- + +Above you can see what happened if query was successful by looking +kerberos tickets. Now you can experiment with further query commands +i.e. if you working with `KerberosLdapContextSource`. + +[source,text] +---- +$ ldapsearch -H ldap://WIN-EKBO0EQ7TS7.example.org \ +-b "dc=example,dc=org" \ +"(| (userPrincipalName=user2@EXAMPLE.ORG) +(sAMAccountName=user2@EXAMPLE.ORG))" \ +dn + +... +# test user, example.org +dn: CN=test user,DC=example,DC=org +---- + [appendix] [[browserspnegoconfig]] == Configure Browsers for Spnego Negotiation diff --git a/docs/src/reference/asciidoc/samples.adoc b/docs/src/reference/asciidoc/samples.adoc index 57cecdd..0797f6c 100644 --- a/docs/src/reference/asciidoc/samples.adoc +++ b/docs/src/reference/asciidoc/samples.adoc @@ -57,6 +57,13 @@ Run a server. $ java -jar sec-server-win-auth-{revnumber}.jar ---- +[IMPORTANT] +==== +You may need to use custom kerberos config with Linux either by using +`-Djava.security.krb5.conf=/path/to/krb5.ini` or +`GlobalSunJaasKerberosConfig` bean. +==== + [NOTE] ==== See <> for more instructions how to work with