Reference doc updates

build.gradle

@@ -207,6 +207,7 @@ configure(rootProject) {
 			doctype: 'book',
 			numbered: '',
 			'spring-version' : springVersion,
+			'spring-security-version' : springSecurityVersion,
 			revnumber : project.version
 	}
 

docs/src/reference/asciidoc/appendix.adoc

@@ -3,6 +3,16 @@
 
 :numbered!:
 
+[appendix]
+== Material Used in this Document
+Dummy UserDetailsService used in samples because we don't have a real
+user source.
+
+[source,java,indent=0]
+----
+include::samples/DummyUserDetailsService.java[tags=snippetA]
+----
+
 [appendix]
 == Crash Course to Kerberos
 In any authentication process there are usually a three parties
@@ -21,7 +31,7 @@ one which really brings everything together and thus is the most
 critical component in your environment. Because of this it is also
 considered as a single point of failure.
 
-Initially when `Kerberos` environment is setup and domain users
+Initially when `Kerberos` environment is setup and domain user
 principals created into to a database, encryption keys are also
 created. These encryption keys are based on shared secrets(i.e. user
 password) and actual passwords are never kept in a clear text.
@@ -32,15 +42,15 @@ Interestingly there is no communication between a `resource` and a
 
 image:images/drawio-kerb-cc2.png[]
 
-When client wants to authenticate itself with a resource it first
+When client wants to authenticate itself with a `resource` it first
 needs to communicate with a `KDC`. `Client` will craft a special package
 which contains encrypted and unencrypted parts. Unencrypted part
 contains i.e. information about a user and encrypted part other
 information which is part of a protocol. `Client` will encrypt package
 data with its own key.
 
 When `KDC` receives this authentication package from a client it
-checks who this client claims to be from an unencrypted part and based
+checks who this `client` claims to be from an unencrypted part and based
 on that information it uses `client` decryption key it already have in
 its database. If this decryption is succesfull `KDC` knows that this
 `client` is the one it claims to be.
@@ -66,15 +76,16 @@ received service ticket to a service which then thinks that I don't
 know anything about this guy but he have me an authentication ticket.
 What `service` can do next is try to decrypt that ticket and if that
 operation is succesfull it knows that only other party who knows my
-credentials is the `KDC` and because I trust him I can also trust this
-client claiming to be who he is.
+credentials is the `KDC` and because I trust him I can also trust that
+this client is a one he claims to be.
 
 [appendix]
 == Setup Kerberos Environments
 Doing a production setup of Kerberos environment is out of scope of
 this document but this appendix provides some help to get you
 started for setting up needed components for development.
 
+[[setupmitkerberos]]
 === Setup MIT Kerberos
 First action is to setup a new realm and a database.
 
@@ -144,7 +155,17 @@ policy
 Enter password for principal "[email protected]": 
 Re-enter password for principal "[email protected]": 
 Principal "[email protected]" created.
+----
+
+If you like you can create a keytab file for this user.
 
+[source,text,indent=0]
+----
+kadmin:  ktadd -k /tmp/user1.keytab [email protected]
+Entry for principal [email protected] with kvno 2, encryption type aes256-cts-hmac-sha1-96 added to keytab WRFILE:/tmp/user1.keytab.
+Entry for principal [email protected] with kvno 2, encryption type arcfour-hmac added to keytab WRFILE:/tmp/user1.keytab.
+Entry for principal [email protected] with kvno 2, encryption type des3-cbc-sha1 added to keytab WRFILE:/tmp/user1.keytab.
+Entry for principal [email protected] with kvno 2, encryption type des-cbc-crc added to keytab WRFILE:/tmp/user1.keytab.
 ----
 
 Lets create a service ticket for tomcat and export credentials to a
@@ -164,7 +185,7 @@ Entry for principal HTTP/[email protected] with kvno 2, encryption typ
 Entry for principal HTTP/[email protected] with kvno 2, encryption type des-cbc-crc added to keytab WRFILE:/tmp/tomcat2.keytab.
 ----
 
-
+[[setupwinkerberos]]
 === Setup Windows Domain Controller
 
 This was tested using `Windows Server 2012 R2`
@@ -214,5 +235,88 @@ PS C:\> ktpass /out c:\tomcat.keytab /mapuser [email protected] /princ HTTP/neo
 This appendix provides generic information about troubleshooting
 errors and problems.
 
+[IMPORTANT]
+====
+If you think environment and configuration is correctly setup, do
+double check and ask other person to check possible obvious mistakes
+or typos. Kerberos setup is generally very brittle and it is not
+always very easy to debug where the problem lies.
+====
+
+
+[source,text]
+----
+GSSException: Failure unspecified at GSS-API level (Mechanism level:
+Invalid argument (400) - Cannot find key of appropriate type to
+decrypt AP REP - RC4 with HMAC)
+----
+
+If you see abore error indicating missing key type, this will happen
+with two different use cases. Firstly your JVM may not support
+appropriate encryption type or it is disabled in your `krb5.conf`
+file.
+
+[source,text]
+----
+default_tkt_enctypes = rc4-hmac
+default_tgs_enctypes = rc4-hmac
+----
+
+Second case is less obvious and hard to track because it will lead
+into same error. This specific `GSSException` is throws also if you
+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.
+
+[appendix]
+[[browserspnegoconfig]]
+== Configure Browsers for Spnego Negotiation
+
+=== Firefox
+Complete following steps to ensure that your Firefox browser is
+enabled to perform Spnego authentication.
+
+- Open Firefox.
+- At address field, type *about:config*.
+- In filter/search, type *negotiate*.
+- Parameter *network.negotiate-auth.trusted-uris* may be set to
+  default *https://* which doesn't work for you. Replace this with
+  your server address.
+
+=== Chrome
+
+With Google Chrome you generally need to set command-line parameters
+order to white list servers with Chrome will negotiate. 
+
+[source,text]
+----
+--auth-server-whitelist="*.example.com"
+--auth-negotiate-delegate-whitelist="*.example.com"
+----
+
+You can see which policies are enable by typing *chrome://policy/*
+into Chrome's address bar.
+
+With Linux Chrome will also read policy files from
+`/etc/opt/chrome/policies/managed` directory.
+
+.mypolicy.json
+[source,json]
+----
+{
+  "AuthServerWhitelist" : "*.example.org",
+  "AuthNegotiateDelegateWhitelist" : "*.example.org",
+  "DisableAuthNegotiateCnameLookup" : true,
+  "EnableAuthNegotiatePort" : true
+}
+----
+
+=== Internet Explorer
+Complete following steps to ensure that your Internet Explorer browser
+is enabled to perform Spnego authentication.
 
+- Open Internet Explorer.
+- Click *Tools > Intenet Options > Security* tab.
+- In *Local intranet* section make sure your server is trusted by i.e.
+  adding it into a list.
 

docs/src/reference/asciidoc/index.adoc

@@ -17,5 +17,5 @@ include::introduction.adoc[]
 
 [[springandssk]]
 include::ssk.adoc[]
-
+include::samples.adoc[]
 include::appendix.adoc[]

docs/src/reference/asciidoc/introduction.adoc

@@ -6,5 +6,6 @@ application developers to Kerberos concepts with Spring.
 
 == Requirements
 
-Spring Security Kerberos {revnumber} is built and tested with JDK 7, Spring
-Framework {spring-version}.
+Spring Security Kerberos {revnumber} is built and tested with JDK 7,
+Spring Security {spring-security-version} and Spring Framework {spring-version}.
+

docs/src/reference/asciidoc/preface.adoc

@@ -8,3 +8,8 @@ This reference documentations contains following parts.
 <<springsecuritykerberos>> describes the usage of Spring Security
 Kerberos
 
+<<springsecuritykerberossamples>> describes the usage of Spring
+Security Kerberos Samples
+
+<<appendices>> generic support material
+

docs/src/reference/asciidoc/samples.adoc

@@ -0,0 +1,169 @@
+[[springsecuritykerberossamples]]
+= Spring Security Kerberos Samples
+
+This part of the reference documentation is introducing samples
+projects. Generally samples can be either compiled manually by
+building main distribution from
+https://github.com/spring-projects/spring-security-kerberos or using
+nightly snapshots or actual release builds.
+
+- http://repo.spring.io/libs-snapshot/org/springframework/security/kerberos/
+- http://repo.spring.io/libs-release/org/springframework/security/kerberos/
+
+[IMPORTANT]
+====
+If you download and run sample from a maven repo it will not work
+until a correct configuration is applied. See notes below for specific
+samples.
+====
+
+<<samples-sec-server-win-auth>> sample for Windows environment
+
+<<samples-sec-server-client-auth>> sample using server side authenticator
+
+<<samples-sec-server-spnego-form-auth>> sample using ticket validation
+with spnego and form
+
+<<samples-sec-server-spnego-form-auth-xml>> sample using ticket
+validation with spnego and form (xml config)
+
+[[samples-sec-server-win-auth]]
+== Security Server Windows Auth Sample
+Goals of this sample:
+
+- In windows environment, User will be able to logon to application
+  with Windows Active directory Credential which has been entered
+  during log on to windows. There should not be any ask for
+  userid/password credentials.
+- In non-windows environment, User will be presented with a screen
+  to provide Active directory credentials.
+
+[source,yaml,indent=0]
+----
+server:
+    port: 8080
+    app:
+        ad-domain: EXAMPLE.ORG
+        ad-server: ldap://WIN-EKBO0EQ7TS7.example.org/
+        service-principal: HTTP/[email protected]
+        keytab-location: /tmp/tomcat.keytab
+----
+In above you can see the default configuration for this sample. You
+can override these settings using a normal Spring Boot tricks like
+using command-line options or custom `application.yml` file.
+
+Run a server.
+[source,text,subs="attributes"]
+----
+$ java -jar sec-server-win-auth-{revnumber}.jar
+----
+
+[NOTE]
+====
+See <<setupwinkerberos>> for more instructions how to work with
+windows kerberos environment.
+====
+
+Login to `Windows 8.1` using domain credentials and access sample
+
+image:images/ie1.png[]
+image:images/ie2.png[]
+
+Access sample application from a non windows vm and use domain
+credentials manually.
+
+image:images/ff1.png[]
+image:images/ff2.png[]
+image:images/ff3.png[]
+
+
+[[samples-sec-server-client-auth]]
+== Security Server Side Auth Sample
+This sample demonstrates how server is able to authenticate user
+against kerberos environment using his credentials passed in via a
+form login.
+
+Run a server.
+[source,text,subs="attributes"]
+----
+$ java -jar sec-server-client-auth-{revnumber}.jar
+----
+
+[source,yaml,indent=0]
+----
+server:
+    port: 8080
+----
+
+[[samples-sec-server-spnego-form-auth]]
+== Security Server Spnego and Form Auth Sample
+This sample demonstrates how a server can be configured to accept a
+Spnego based negotiation from a browser while still being able to fall
+back to a form based authentication.
+
+Using a `user1` principal <<setupmitkerberos>>, do a kerberos login
+either using credentials.
+[source,text]
+----
+$ kinit user1
+Password for [email protected]: 
+
+$ klist
+Ticket cache: FILE:/tmp/krb5cc_1000
+Default principal: [email protected]
+
+Valid starting     Expires            Service principal
+10/03/15 17:18:45  11/03/15 03:18:45  krbtgt/[email protected]
+  renew until 11/03/15 17:18:40
+----
+
+or using a keytab file.
+
+[source,text]
+----
+$ kinit -kt user1.keytab user1
+
+$ klist
+Ticket cache: FILE:/tmp/krb5cc_1000
+Default principal: [email protected]
+
+Valid starting     Expires            Service principal
+10/03/15 17:25:03  11/03/15 03:25:03  krbtgt/[email protected]
+  renew until 11/03/15 17:25:03
+----
+
+Run a server.
+[source,text,subs="attributes"]
+----
+$ java -jar sec-server-spnego-form-auth-{revnumber}.jar
+----
+
+Now you should be able to open your browser and let it do Spnego
+authentication with existing ticket.
+
+[NOTE]
+====
+See <<browserspnegoconfig>> for more instructions for configuring
+browsers to use Spnego.
+====
+
+[source,yaml,indent=0]
+----
+server:
+    port: 8080
+app:
+    service-principal: HTTP/[email protected]
+    keytab-location: /tmp/tomcat.keytab
+----
+
+[[samples-sec-server-spnego-form-auth-xml]]
+== Security Server Spnego and Form Auth Xml Sample
+This is a same sample than <<samples-sec-server-spnego-form-auth>> but
+using xml based configuration instead of JavaConfig.
+
+Run a server.
+[source,text,subs="attributes"]
+----
+$ java -jar sec-server-spnego-form-auth-xml-{revnumber}.jar
+----
+

docs/src/reference/asciidoc/samples/AuthProviderConfig.xml

@@ -9,9 +9,10 @@
     http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.2.xsd
     http://www.springframework.org/schema/security http://www.springframework.org/schema/security/spring-security-3.1.xsd">
 
-  <sec:http>
-    <sec:intercept-url pattern="/secure/**" access="IS_AUTHENTICATED_FULLY" />
-    <sec:form-login login-page="/login.html" default-target-url="/secure/index.jsp"/>
+  <sec:http use-expressions="true" >
+    <sec:intercept-url pattern="/" access="permitAll" />
+    <sec:intercept-url pattern="/home" access="permitAll" />
+    <sec:intercept-url pattern="/**" access="authenticated"/>
   </sec:http>
 
   <sec:authentication-manager alias="authenticationManager">