5:26 a.m.
Author: thomas.heute(a)jboss.com
Date: 2010-04-15 06:26:29 -0400 (Thu, 15 Apr 2010)
New Revision: 2650
Modified:
portal/trunk/docs/reference-guide/en/modules/AuthenticationAndIdentity.xml
portal/trunk/docs/reference-guide/en/modules/AuthenticationAndIdentity/SSO.xml
Log:
Added SPNEGO section
Modified: portal/trunk/docs/reference-guide/en/modules/AuthenticationAndIdentity/SSO.xml
===================================================================
---
portal/trunk/docs/reference-guide/en/modules/AuthenticationAndIdentity/SSO.xml 2010-04-15
10:02:11 UTC (rev 2649)
+++
portal/trunk/docs/reference-guide/en/modules/AuthenticationAndIdentity/SSO.xml 2010-04-15
10:26:29 UTC (rev 2650)
@@ -3,7 +3,7 @@
<!ENTITY % BOOK_ENTITIES SYSTEM "../../Reference_Guide.ent">
%BOOK_ENTITIES;
]>
-<chapter id="chap-Reference_Guide-SSO_Single_Sign_On">
+<section id="chap-Reference_Guide-SSO_Single_Sign_On">
<title>SSO - Single Sign On</title>
<section id="sect-Reference_Guide-Single_Sign_On-Overview">
<title>Overview</title>
@@ -794,5 +794,233 @@
</section>
-</chapter>
+ <section id="sect-Reference_Guide-Single_Sign_On-SPNEGO">
+ <title>SPNEGO</title>
+ <para>SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) is
+ used to authenticate transparently through the web browser after the
+ user has been authenticated when logging-in his session.</para>
+ <para>A typical use case is the following:</para>
+ <procedure>
+ <step>
+ <para>Users logs into his desktop (Such as a Windows machine).</para>
+ </step>
+ <step>
+ <para>The desktop login is governed by Active Directory domain.</para>
+ </step>
+ <step>
+ <para>User then uses his browser (IE/Firefox) to access a web
+ application (that uses JBoss Negotiation) hosted on JBoss EPP.</para>
+ </step>
+ <step>
+ <para>The Browser transfers the desktop sign on information to the
+ web application.</para>
+ </step>
+ <step>
+ <para>JBoss EAP/AS uses background GSS messages with the Active
+ Directory (or any Kerberos Server) to validate the user.</para>
+ </step>
+ <step>
+ <para>The User has seamless SSO into the web application.</para>
+ </step>
+ </procedure>
+ <section>
+ <title>Configuration</title>
+ <para>GateIn uses JBoss Negotiation to enable SPNEGO based desktop
+ SSO for the Portal. Here are the steps to integrate SPNEGO with
+ GateIn.</para>
+ <procedure>
+ <step>
+ <para>
+ Activate the Host authentication
+
+ Under conf/login-config.xml, add the following host login module:
+ <programlisting><![CDATA[<!-- SPNEGO domain -->
+ <application-policy name="host">
+ <authentication>
+ <login-module code="com.sun.security.auth.module.Krb5LoginModule"
+ flag="required">
+ <module-option name="storeKey">true</module-option>
+ <module-option name="useKeyTab">true</module-option>
+ <module-option
name="principal">HTTP/server.local.network(a)LOCAL.NETWORK</module-option>
+ <module-option
name="keyTab">/home/user/krb5keytabs/jboss.keytab</module-option>
+ <module-option name="doNotPrompt">true</module-option>
+ <module-option name="debug">true</module-option>
+ </login-module>
+ </authentication>
+ </application-policy>
+]]></programlisting>
+ the 'keyTab' value should point to the keytab file that was
+ generated by the kadmin kerberos tool. See the Setting up your
+ Kerberos Development Environment guide for more details.
+ </para>
+ </step>
+ <step>
+ <para>
+ Extend the core authentication mechanisms to support
+ SPNEGO
+
+ Under
+ deployers/jbossweb.deployer/META-INF/war-deployers-jboss-beans.xml,
+ add 'SPNEGO' authenticators property
+
+ <programlisting><![CDATA[<property name="authenticators">
+ <map keyClass="java.lang.String"
valueClass="java.lang.String">
+ <entry>
+ <key>BASIC</key>
+
<value>org.apache.catalina.authenticator.BasicAuthenticator</value>
+ </entry>
+ <entry>
+ <key>CLIENT-CERT</key>
+
<value>org.apache.catalina.authenticator.SSLAuthenticator</value>
+ </entry>
+ <entry>
+ <key>DIGEST</key>
+
<value>org.apache.catalina.authenticator.DigestAuthenticator</value>
+ </entry>
+ <entry>
+ <key>FORM</key>
+
<value>org.apache.catalina.authenticator.FormAuthenticator</value>
+ </entry>
+ <entry>
+ <key>NONE</key>
+
<value>org.apache.catalina.authenticator.NonLoginAuthenticator</value>
+ </entry>
+
+ <!-- Add this entry -->
+ <entry>
+ <key>SPNEGO</key>
+
<value>org.jboss.security.negotiation.NegotiationAuthenticator</value>
+ </entry>
+ </map>
+ </property>]]></programlisting>
+
+ </para>
+ </step>
+ <step>
+ <para>Add the JBoss Negotiation binary
+
+ copy $GATEIN_SSO_HOME/spnego/jboss-negotiation-2.0.3.GA.jar to lib
+</para>
+ </step>
+ <step>
+ <para>Add the Gatein SSO module binaries
+
+ Add $GATEIN_SSO_HOME/spnego/gatein.ear/lib/sso-agent.jar, and
$GATEIN_SSO_HOME/spnego/gatein.ear/lib/sso-spnego.jar to deploy/gatein.ear/lib
+</para>
+ </step>
+ <step>
+ <para>
+ Activate SPNEGO LoginModule for GateIn
+
+ Modify deploy/gatein.ear/META-INF/gatein-jboss-beans.xml, so that it
+ looks like this:
+
+ <programlisting><![CDATA[<deployment
xmlns="urn:jboss:bean-deployer:2.0">
+ <application-policy xmlns="urn:jboss:security-beans:1.0"
name="gatein-domain">
+ <!-- Uncomment this for Kerberos based SSO integration -->
+ <authentication>
+ <login-module
+ code="org.gatein.sso.spnego.SPNEGOLoginModule"
+ flag="requisite">
+ <module-option
name="password-stacking">useFirstPass</module-option>
+ <module-option
name="serverSecurityDomain">host</module-option>
+ </login-module>
+ <login-module
+ code="org.gatein.sso.agent.login.SPNEGORolesModule"
+ flag="required">
+ <module-option
name="password-stacking">useFirstPass</module-option>
+ <module-option
name="portalContainerName">portal</module-option>
+ <module-option
name="realmName">gatein-domain</module-option>
+ </login-module>
+ </authentication>
+ </application-policy>
+</deployment>]]></programlisting>
+ </para>
+ </step>
+ <step>
+ <para>
+ Integrate SPNEGO support into the Portal web archive
+
+ Switch GateIn authentication mechanism from the default "FORM"
+ based to "SPNEGO" based authentication as follows:
+
+ Modify gatein.ear/02portal.war/WEB-INF/web.xml
+
+ <programlisting><![CDATA[ <!--
+ <login-config>
+ <auth-method>FORM</auth-method>
+ <realm-name>gatein-domain</realm-name>
+ <form-login-config>
+ <form-login-page>/initiatelogin</form-login-page>
+ <form-error-page>/errorlogin</form-error-page>
+ </form-login-config>
+ </login-config>
+ -->
+ <login-config>
+ <auth-method>SPNEGO</auth-method>
+ <realm-name>SPNEGO</realm-name>
+ </login-config>]]></programlisting>
+
+
+ Integrate request pre-processing needed for SPNEGO via filters.
+ Add the following filters to the web.xml at the top of the Filter
+ chain:
+
+ <programlisting><![CDATA[ <filter>
+ <filter-name>LoginRedirectFilter</filter-name>
+
<filter-class>org.gatein.sso.agent.filter.LoginRedirectFilter</filter-class>
+ <init-param>
+ <!-- This should point to your SSO authentication server -->
+ <param-name>LOGIN_URL</param-name>
+ <param-value>/portal/private/classic</param-value>
+ </init-param>
+ </filter>
+ <filter>
+ <filter-name>SPNEGOFilter</filter-name>
+
<filter-class>org.gatein.sso.agent.filter.SPNEGOFilter</filter-class>
+ </filter>
+
+ <filter-mapping>
+ <filter-name>LoginRedirectFilter</filter-name>
+ <url-pattern>/*</url-pattern>
+ </filter-mapping>
+ <filter-mapping>
+ <filter-name>SPNEGOFilter</filter-name>
+ <url-pattern>/*</url-pattern>
+ </filter-mapping>]]></programlisting>
+ </para>
+ </step>
+ <step>
+ <para>
+ Modify the Portal's 'Sign In' link to perform SPNEGO
+ authentication
+
+ Modify the 'Sign In' link on
+ gatein.war/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtmpl
+ as follows:
+
+ <programlisting><![CDATA[<!--
+<a
onclick="$signInAction"><%=_ctx.appRes("UILoginForm.label.Signin")%></a>
+-->
+<a
href="/portal/sso"><%=_ctx.appRes("UILoginForm.label.Signin")%></a>]]></programlisting>
+ </para>
+ </step>
+ <step>
+ <para>
+ Start the GateIn Portal
+ <programlisting>sudo ./run.sh -Djava.security.krb5.realm=LOCAL.NETWORK
-Djava.security.krb5.kdc=server.local.network -c spnego -b
server.local.network</programlisting>
+ </para>
+ </step>
+ <step>
+ <para>Login to Kerberos
+ <programlisting>kinit -A demo</programlisting>
+ You should be able to click the 'Sign In' link on the GateIn Portal
+ and the 'demo' user from the GateIn portal should be automatically
+ logged in</para>
+ </step>
+ </procedure>
+ </section>
+ </section>
+</section>
+
Modified: portal/trunk/docs/reference-guide/en/modules/AuthenticationAndIdentity.xml
===================================================================
--- portal/trunk/docs/reference-guide/en/modules/AuthenticationAndIdentity.xml 2010-04-15
10:02:11 UTC (rev 2649)
+++ portal/trunk/docs/reference-guide/en/modules/AuthenticationAndIdentity.xml 2010-04-15
10:26:29 UTC (rev 2650)
@@ -8,11 +8,9 @@
<xi:include
href="AuthenticationAndIdentity/PredefinedUserConfiguration.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include
href="AuthenticationAndIdentity/AuthenticationTokenConfiguration.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="AuthenticationAndIdentity/BackendConfiguration.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
- <!--
- <xi:include href="AuthenticationAndIdentity/SSO.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
- -->
<xi:include
href="AuthenticationAndIdentity/DataInjectorConfiguration.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="AuthenticationAndIdentity/OrganizationAPI.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="AuthenticationAndIdentity/AccessingUserProfile.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="AuthenticationAndIdentity/SSO.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
</chapter>