<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../../Reference_Guide.ent">
%BOOK_ENTITIES;
]>
<section id="chap-Reference_Guide-SSO_Single_Sign_On">
	<title>Single-Sign-On (SSO)</title>
    <highlights>
    <itemizedlist>
      <listitem>
        <para>
          <emphasis role="bold">
            <link linkend="sect-Reference_Guide-Single_Sign_On-CAS_Central_Authentication_Service">Central Authentication Service (CAS)
            </link></emphasis> </para>
            <para>Instructions on how to integrate between GateIn and the CAS Single-Sign-On Framework via 2 steps:
              installing/configuring a CAS server and setting up the portal to use the CAS server.</para>

      </listitem>
      <listitem>
        <para>
          <emphasis role="bold">
            <link linkend="sect-Reference_Guide-Single_Sign_On-JOSSO">JOSSO</link>
          </emphasis>
        </para>
         <para>Instructions on how to integrate between GateIn and the JOSSO Single-Sign-On Framework via 2 steps:
              installing/configuring a JOSSO server and setting up the portal to use the JOSSO server.</para>
      </listitem>
      <listitem>
        <para>
          <emphasis role="bold">
            <link linkend="sect-Reference_Guide-Single_Sign_On-OpenSSO_The_Open_Web_SSO_project">OpenSSO - The Open Web SSO project</link>
          </emphasis>
        </para>
         <para>Instructions on how to integrate between GateIn and the JOSSO Single-Sign-On Framework via 2 steps:
              installing/configuringg a JOSSO server and setting up the portal to use the JOSSO server.</para>
      </listitem>
      <listitem>
        <para>
          <emphasis role="bold">
            <link linkend="Single_Sign_On-SPNEGO">SPNEGO</link>
          </emphasis>
        </para>
         <para>Knowledge of SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) which is used to authenticate transparently
           throughout the web browser, and instructions on how to configure
         the SPNEGO Server on Linux and integrate SPNEGO with GateIn .</para>
      </listitem>
    </itemizedlist>
  </highlights>
	<para id="sect-Reference_Guide-Single_Sign_On-Overview">
				&PRODUCT; provides some forms of Single-Sign-On (<emphasis>SSO</emphasis>) as an integration and aggregation platform.
		</para>
		<para>
			When logging into the portal, users gain access to many systems throughout portlets using a single identity. In many cases, the portal infrastructure must be integrated with other SSO enabled systems. There are many different Identity Management solutions available. In most cases, each SSO framework provides a unique way to plug into a Java EE application.
		</para>

  <para xml:id="sect-Reference_Guide-Overview_of_SSO-Prerequisite">
    <citetitle>
      <emphasis role="bold">Prerequisites</emphasis>
    </citetitle>
  </para>

			<para>
				In this tutorial, the SSO server is installed in a Tomcat installation. Tomcat can be obtained from <ulink type="http" url="http://tomcat.apache.org">http://tomcat.apache.org</ulink>.
			</para>
			<para>
				All the packages required for setup can be found in a zip file located at <ulink type="http" url="https://repository.jboss.org/nexus/content/groups/public/org/gatein/sso/sso-packaging/1.1.0-GA/sso-packaging-1.1.0-GA.zip">here</ulink>. In this document, $GATEIN_SSO_HOME is called as the directory where the file is extracted.
			</para>
			<para>
				It is recommended that you should not run any portal extensions that could override the data when manipulating the <filename>gatein.ear</filename> file directly.
			</para>
			<para>
				Remove <filename>$PLATFORM_JBOSS_HOME/server/default/deploy/gatein-sample-extension.ear</filename> and <filename>$PLATFORM_JBOSS_HOME/server/default/deploy/gatein-sample-portal.ear</filename> which are packaged with &PRODUCT; by default.
			</para>
     <para>
	<prompt>
		<emphasis role="bold">See also</emphasis>
	</prompt>
</para>

		<itemizedlist>
           <listitem>
               <para><link linkend="sect-Reference_Guide-Password-encryption">Password Encryption</link></para>
           </listitem>
           <listitem>
               <para><link linkend="sect-Reference_Guide-Predefined_User_Configuration">Predefined User Configuration</link></para>
           </listitem>
           <listitem>
               <para><link linkend="sect-Reference_Guide-Authentication_Token_Configuration">Authentication Token Configuration</link></para>
           </listitem>
           <listitem>
               <para><link linkend="sect-Reference_Guide-PicketLink_IDM_integration">PicketLink IDM integration</link></para>
           </listitem>
           <listitem>
               <para><link linkend="sect-Reference_Guide-APIs-Organization_API">Organization API</link></para>
           </listitem>
           <listitem>
               <para><link linkend="sect-Reference_Guide-Accessing_User_Profile">Access User Profile</link></para>
           </listitem>
       </itemizedlist>

	<section id="sect-Reference_Guide-Single_Sign_On-CAS_Central_Authentication_Service" role="NotInToc">
		<title>Central Authentication Service (CAS)</title>
		<para>
			This Single-Sign-On plugin enables the seamless integration between &PRODUCT; and the CAS Single-Sign-On Framework. Details about CAS can be found <ulink url="http://www.jasig.org/cas">here</ulink>.
		</para>
		<para>
			The integration consists of 3 steps:
		</para>
		<procedure>
			<step>
				<para>
					Configure a CAS server to authenticate against the portal login module. In this example, the CAS server is installed on Tomcat.
				</para>
			</step>
			<step>
				<para>
					Set up the CAS client.
				</para>
			</step>
			<step>
				<para>
				Redirect to CAS.
				</para>
			</step>
		</procedure>
		<para xml:id="sect-Reference_Guide-CAS_server-Obtaining_CAS">
			Before doing the integration, you need to obtain CAS first:
		</para>
		<procedure>
			<step>
				<para>
				Download CAS from <ulink type="http" url="http://www.jasig.org/cas/download">http://www.jasig.org/cas/download</ulink>.
				</para>
			</step>
			<step>
				<para>
					Extract the downloaded file into a suitable location. This location will be referred to as <emphasis>$CAS_HOME</emphasis> in the following instructions.
				</para>
			</step>
		</procedure>
		<note>
			<para>
				The tested version, which should work with these instructions, is <emphasis role="bold">CAS 3.3.5</emphasis>; however, other versions can also work without problems.
			</para>
		</note>


			<section id="sect-Reference_Guide-CAS_server-Configuring_CAS_server">
				<title>Configure the CAS server</title>
				<para>
					To configure the web archive as desired, the simplest way is to make the necessary changes directly in the CAS code base.
				</para>
            <note>
               <para>
                  To complete these instructions, and perform the final build step, you will need the Apache Maven 2.
                  You can get it <ulink type="http" url="http://maven.apache.org/download.html">here</ulink>.
               </para>
            </note>
				<para>
					First, change the default authentication handler with the one provided by &PRODUCT;.
				</para>
				<para>
					The CAS Server Plugin makes secure authentication callbacks to a RESTful service installed on the remote &PRODUCT; server to authenticate a user.
				</para>
				<para>
					In order for the plugin to function correctly, it needs to be properly configured to connect to this service. This configuration is done via the <filename>cas.war/WEB-INF/deployerConfigContext.xml </filename> file.
				</para>
				<procedure>
					<step>
						<para>
							Open <filename>CAS_HOME/cas-server-webapp/src/main/webapp/WEB-INF/deployerConfigContext.xml</filename>
						</para>
					</step>
					<step>
						<para>
							Replace:
            </para>
<programlisting language="xml"> &#60;!--
  | Whereas CredentialsToPrincipalResolvers identify who it is some Credentials might authenticate,
  | AuthenticationHandlers actually authenticate credentials.  Here e declare the AuthenticationHandlers that
  | authenticate the Principals that the CredentialsToPrincipalResolvers identified.  CAS will try these handlers in turn
  | until it finds one that both supports the Credentials presented and succeeds in authenticating.
  +--&#62;
 &#60;property name=&#34;authenticationHandlers&#34;&#62;
   &#60;list&#62;
     &#60;!--
      | This is the authentication handler that authenticates services by means of callback via SSL, thereby validating
      | a server side SSL certificate.
      +--&#62;
     &#60;bean class=&#34;org.jasig.cas.authentication.handler.support.HttpBasedServiceCredentialsAuthenticationHandler&#34;
           p:httpClient-ref=&#34;httpClient&#34; /&#62;
     &#60;!--
      | This is the authentication handler declaration that every CAS deployer will need to change before deploying CAS
      | into production.  The default SimpleTestUsernamePasswordAuthenticationHandler authenticates UsernamePasswordCredentials
      | where the username equals the password.  You will need to replace this with an AuthenticationHandler that implements your
      | local authentication strategy.  You might accomplish this by coding a new such handler and declaring
      | edu.someschool.its.cas.MySpecialHandler here, or you might use one of the handlers provided in the adaptors modules.
      +--&#62;
     &#60;bean
        class=&#34;org.jasig.cas.authentication.handler.support.SimpleTestUsernamePasswordAuthenticationHandler&#34; /&#62;
   &#60;/list&#62;
 &#60;/property&#62;
</programlisting>

						<para>
							With the following (Make sure to set the host, port and context with the values corresponding to your portal). Also available in <filename>$GATEIN_SSO_HOME/cas/plugin/WEB-INF/deployerConfigContext.xml</filename>.
						</para>

<programlisting language="xml">&#60;!--
 | Whereas CredentialsToPrincipalResolvers identify who it is some Credentials might authenticate,
 | AuthenticationHandlers actually authenticate credentials.  Here we declare the AuthenticationHandlers that
 | authenticate the Principals that the CredentialsToPrincipalResolvers identified.  CAS will try these handlers in turn
 | until it finds one that both supports the Credentials presented and succeeds in authenticating.
 +--&#62;
 &#60;property name=&#34;authenticationHandlers&#34;&#62;
   &#60;list&#62;
     &#60;!--
      | This is the authentication handler that authenticates services by means of callback via SSL, thereby validating
      | a server side SSL certificate.
      +--&#62;
     &#60;bean class=&#34;org.jasig.cas.authentication.handler.support.HttpBasedServiceCredentialsAuthenticationHandler&#34;
           p:httpClient-ref=&#34;httpClient&#34; /&#62;
     &#60;!--
      | This is the authentication handler declaration that every CAS deployer will need to change before deploying CAS
      | into production.  The default SimpleTestUsernamePasswordAuthenticationHandler authenticates UsernamePasswordCredentials
      | where the username equals the password.  You will need to replace this with an AuthenticationHandler that implements your
      | local authentication strategy.  You might accomplish this by coding a new such handler and declaring
      | edu.someschool.its.cas.MySpecialHandler here, or you might use one of the handlers provided in the adaptors modules.
      +--&#62;
     &#60;!-- Integrates with the Gatein Authentication Service to perform authentication --&#62;
     &#60;!--
      | Note: Modify the Plugin Configuration based on the actual information of a GateIn instance.
      | The instance can be anywhere on the internet...Not necessarily on localhost where CAS is running
      +--&#62;
     &#60;bean class=&#34;org.gatein.sso.cas.plugin.AuthenticationPlugin&#34;&#62;
        &#60;property name=&#34;gateInHost&#34;&#62;&#60;value&#62;localhost&#60;/value&#62;&#60;/property&#62;
        &#60;property name=&#34;gateInPort&#34;&#62;&#60;value&#62;8080&#60;/value&#62;&#60;/property&#62;
        &#60;property name=&#34;gateInContext&#34;&#62;&#60;value&#62;portal&#60;/value&#62;&#60;/property&#62;
     &#60;/bean&#62;
   &#60;/list&#62;
 &#60;/property&#62;
</programlisting>

					</step>
					<step>
						<para>
							Copy <filename>$GATEIN_SSO_HOME/cas/plugin/WEB-INF/lib/sso-cas-plugin-&#60;VERSION&#62;.jar</filename> and <filename>$GATEIN_SSO_HOME/cas/plugin/WEB-INF/lib/commons-httpclient-&#60;VERSION&#62;.jar</filename> into the <filename>CAS_HOME/cas-server-webapp/src/main/webapp/WEB-INF/lib</filename> created directory.
						</para>
					</step>
					<step>
						<para>
							Get an installation of Tomcat and extract it into a suitable location (which will be called <emphasis>$PLATFORM_TOMCAT_HOME</emphasis> for these instructions).
						</para>
						<para>
							Change the default port to avoid a conflict with the default &PRODUCT; (for testing purposes). Edit <filename>$PLATFORM_TOMCAT_HOME/conf/server.xml</filename> and replace the 8080 port with 8888.
							<note>
								<para>
									If &PRODUCT; is running on the same machine as Tomcat, other ports need to be changed in addition to 8080 to avoid port conflicts.
                           They can be changed to any free port. For example, you can change admin port from 8005 to 8805, and AJP port from 8009 to 8809.
								</para>
							</note>
						</para>
					</step>
					<step>
						<para>
							Go to <emphasis>CAS_HOME/cas-server-webapp</emphasis> and execute the command:
              <command>mvn install
              </command>
						</para>
					</step>
					<step>
						<para>
							Copy <filename>CAS_HOME/cas-server-webapp/target/cas.war</filename> into <emphasis>$PLATFORM_TOMCAT_HOME/webapps</emphasis>.
						</para>
						<para>
							Tomcat should start and be accessible at <ulink type="http" url="http://localhost:8888/cas">http://localhost:8888/cas</ulink>. At this stage, the login will not be available.
						</para>
						<mediaobject>
							<imageobject role="html">
								<imagedata fileref="images/AuthenticationAndIdentity/SSO/cas.png" format="PNG" width="444" align="center" />
							</imageobject>
                            <imageobject role="fo">
								<imagedata fileref="images/AuthenticationAndIdentity/SSO/cas.png" format="PNG" scalefit="1" width="150mm" align="center" />
							</imageobject>
						</mediaobject>
					</step>
				</procedure>
			<note>
                <para>
                  By default on logout the CAS server will display the CAS logout page with a link to return to the portal. To make the CAS server redirect to the portal page after a logout, modify the
                                  <filename>cas.war/WEB-INF/cas-servlet.xml</filename> to include the follow line :
                </para>
<programlisting language="xml">&#60;bean id=&#34;logoutController&#34; class=&#34;org.jasig.cas.web.LogoutController&#34;
p:centralAuthenticationService-ref=&#34;centralAuthenticationService&#34;
p:logoutView=&#34;casLogoutView&#34;
p:warnCookieGenerator-ref=&#34;warnCookieGenerator&#34;
p:ticketGrantingTicketCookieGenerator-ref=&#34;ticketGrantingTicketCookieGenerator&#34;
p:followServiceRedirects=&#34;true&#34;/&#62;</programlisting>
            </note>
			</section>

		<section id="sect-Reference_Guide-CAS_Central_Authentication_Service-Setup_the_CAS_client">
			<title>Set up the CAS client</title>
			<procedure>
				<step>
					<para>
						Copy all libraries from <emphasis>$GATEIN_SSO_HOME/cas/gatein.ear/lib</emphasis> into <emphasis>$PLATFORM_JBOSS_HOME/server/default/deploy/gatein.ear/lib</emphasis> (Or in Tomcat, into $<emphasis>GATEIN_HOME/lib</emphasis>)
					</para>
				</step>
				<step>
					<itemizedlist>
						<listitem>
							<para>
							In JBoss AS, edit <filename>gatein.ear/META-INF/gatein-jboss-beans.xml</filename> and uncomment on this section:</para>

<programlisting language="xml"><![CDATA[<authentication>
  <login-module code="org.gatein.sso.agent.login.SSOLoginModule" flag="required">
    <module-option name="portalContainerName">portal</module-option>
    <module-option name="realmName">gatein-domain</module-option>
  </login-module>
  <login-module code="org.exoplatform.services.security.j2ee.JbossLoginModule" flag="required">
    <module-option name="portalContainerName">portal</module-option>
    <module-option name="realmName">gatein-domain</module-option>
  </login-module>
</authentication>]]></programlisting>
						</listitem>
						<listitem>
							<para>
							In Tomcat, edit <filename>GATEIN_HOME/conf/jaas.conf</filename>, uncomment on this section and comment other parts:
							</para>
<programlisting>org.gatein.sso.agent.login.SSOLoginModule required;
org.exoplatform.services.security.j2ee.TomcatLoginModule required
portalContainerName=portal
realmName=gatein-domain;
</programlisting>
						</listitem>
					</itemizedlist>
				</step>
				<step>
					<para>
						The installation can be tested at this point:
					</para>
					<procedure>
						<step>
							<para>
								Start (or restart) &PRODUCT;, and (assuming the CAS server on Tomcat is running) direct your browser to <ulink type="http" url="http://localhost:8888/cas">http://localhost:8888/cas</ulink>.
							</para>
						</step>
						<step>
							<para>
								Login with the username <emphasis>root</emphasis> and the password <emphasis>gtn</emphasis> (or any account created through the portal).
							</para>
						</step>
					</procedure>
				</step>
			</procedure>
		</section>

		<section id="sect-Reference_Guide-CAS_Central_Authentication_Service-Redirect_to_CAS">
			<title>Redirect to CAS</title>
			<para>
				To utilize the Central Authentication Service, &PRODUCT; needs to redirect all user authentication to the CAS server.
			</para>
			<para>
				Information about where the CAS is hosted must be properly configured within the &PRODUCT; instance. The required configuration is done by modifying three files:</para>
				<itemizedlist>
					<listitem>
						<para>
						In the <filename>gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file, modify the 'Sign In' link as follows:
<programlisting><![CDATA[<!--  <a class="Login" onclick="$signInAction"><%=_ctx.appRes("UILoginForm.label.Signin")%></a> -->
<a class="Login" href="/portal/sso"><%=_ctx.appRes("UILoginForm.label.Signin")%></a>]]></programlisting>
						</para>
					</listitem>
					<listitem>
						<para>
						In the <filename>gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file, modify the 'Sign In' link as follows:
            </para>
<programlisting><![CDATA[<!--
<a onclick="$signInAction"><%=_ctx.appRes("UILogoPortlet.action.signin")%></a>
-->
<a href="/portal/sso"><%=_ctx.appRes("UILogoPortlet.action.signin")%></a>]]></programlisting>

					</listitem>
					<listitem>
						<para>
							Replace the entire contents of <filename>gatein.ear/02portal.war/login/jsp/login.jsp</filename> with:</para>
<programlisting language="html">&#60;html&#62;
  &#60;head&#62;
    &#60;script type=&#34;text/javascript&#34;&#62;
     window.location = &#39;/portal/sso&#39;;
    &#60;/script&#62;
  &#60;/head&#62;
  &#60;body&#62;
  &#60;/body&#62;
&#60;/html&#62;</programlisting>
            </listitem>
         </itemizedlist>
         <itemizedlist>
            <listitem>
               <para>
                  Add the following filters at the top of the filter chain in <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename>:</para>

<programlisting language="xml"><![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>
      <!-- If casRenewTicket param value of InitiateLoginServlet is: not specified or false -->
      <param-value>http://localhost:8888/cas/login?service=http://localhost:8080/portal/initiatessologin</param-value>
      <!-- If casRenewTicket param value of InitiateLoginServlet is : true -->
      <!-- <param-value>http://localhost:8888/cas/login? service=http://localhost:8080/portal/initiatessologin&amp;renew=true</param-value> -->
   </init-param>
</filter>
<filter>
   <filter-name>CASLogoutFilter</filter-name>
   <filter-class>org.gatein.sso.agent.filter.CASLogoutFilter</filter-class>
   <init-param>
      <!-- This should point to your JOSSO authentication server -->
      <param-name>LOGOUT_URL</param-name>
      <param-value>http://localhost:8888/cas/logout</param-value>
   </init-param>
</filter>
<filter>
   <filter-name>InitiateLoginFilter</filter-name>
   <filter-class>org.gatein.sso.agent.filter.InitiateLoginFilter</filter-class>
   <init-param>
      <param-name>ssoServerUrl</param-name>
      <param-value>http://localhost:8888/cas</param-value>
   </init-param>
   <init-param>
      <param-name>casRenewTicket</param-name>
      <param-value>false</param-value>
   </init-param>
   <init-param>
      <param-name>casServiceUrl</param-name>
      <param-value>http://localhost:8080/portal/initiatessologin</param-value>
   </init-param>
   <init-param>
      <param-name>loginUrl</param-name>
      <param-value>http://localhost:8080/portal/dologin</param-value>
   </init-param>
</filter>

<!-- Mapping the filters at the very top of the filter chain -->
<filter-mapping>
   <filter-name>LoginRedirectFilter</filter-name>
   <url-pattern>/*</url-pattern>
</filter-mapping>
<filter-mapping>
   <filter-name>CASLogoutFilter</filter-name>
   <url-pattern>/*</url-pattern>
</filter-mapping>
<filter-mapping>
   <filter-name>InitiateLoginFilter</filter-name>
   <url-pattern>/initiatessologin</url-pattern>
</filter-mapping>]]></programlisting>
            </listitem>
         </itemizedlist>
         <para>
				Once these changes have been made, all links to the user authentication pages will redirect to the CAS centralized authentication form.
			</para>
		</section>
	</section>

	<section id="sect-Reference_Guide-Single_Sign_On-JOSSO" role="NotInToc">
		<title>JOSSO</title>
		<para>
			This Single-Sign-On plugin enables the seamless integration between &PRODUCT; and the JOSSO Single-Sign-On Framework. Details about JOSSO can be found <ulink url="http://www.josso.org">here</ulink>.
		</para>
		<para>
			Setting up this integration consists of 3 steps:
		</para>
		<procedure>
			<step>
				<para>
				Configure a JOSSO server to authenticate against the &PRODUCT; login module. In this section, the JOSSO server will be installed on Tomcat.
				</para>
			</step>
			<step>
				<para>
				Set up the JOSSO client.
				</para>
			</step>
			<step>
				<para>
				Set up the portal to redirect to JOSSO
				</para>
			</step>
		</procedure>
		<para xml:id="sect-Reference_Guide-JOSSO_server-Obtaining_JOSSO">To do this integration, you need to obtain JOSSO first:</para>
			<procedure>
				<step>
					<para>
					Download JOSSO from <ulink type="http" url="http://sourceforge.net/projects/josso/files/">http://sourceforge.net/projects/josso/files/</ulink>. Use the package that embeds Apache Tomcat.
				</para>
				</step>
				<step>
					<para>
					Extract the package into what will be called <emphasis>JOSSO_HOME</emphasis> in this example.
				</para>
				</step>
			</procedure>
        <warning>
          <para>The steps described later are only correct in case of JOSSO v.1.8.1.</para>
        </warning>


			<section id="sect-Reference_Guide-JOSSO_server-Configuring_JOSSO_server">
				<title>Configure a JOSSO server</title>
				<procedure>
					<step>
						<para>
							Copy the files from <emphasis>$GATEIN_SSO_HOME/josso/plugin</emphasis> into the Tomcat directory (<emphasis>$JOSSO_HOME</emphasis>).
						</para>
						<para>
							This action should replace or add the following files to the <emphasis>$JOSSO_HOME/webapps/josso/WEB-INF/lib</emphasis> directory:
						</para>
						<itemizedlist>
							<listitem>
								<para>
									<filename>$JOSSO_HOME/lib/josso-gateway-config.xml</filename>
								</para>
							</listitem>
							<listitem>
								<para>
									<filename>JOSSO_HOME/lib/josso-gateway-gatein-stores.xml</filename>
								</para>
							</listitem>
						</itemizedlist>
						<para>
							and
						</para>
						<itemizedlist>
							<listitem>
								<para>
									<filename>JOSSO_HOME/webapps/josso/WEB-INF/classes/gatein.properties</filename>
								</para>
							</listitem>
						</itemizedlist>
					</step>
					<step>
						<para>
							Edit <filename>$PLATFORM_TOMCAT_HOME/conf/server.xml</filename> and replace the 8080 port with 8888 to change the default Tomcat port and avoid a conflict with the default &PRODUCT; port (for testing purposes).
							<note>
								<title>Port Conflicts</title>
								<para>
                           If &PRODUCT; is running on the same machine as Tomcat, other ports need to be changed in addition to 8080 to avoid port conflicts.
                           They can be changed to any free port. For example, you can change the admin port from 8005 to 8805, and AJP port from 8009 to 8809.
								</para>
							</note>
						</para>
					</step>
					<step>
						<para>
							Tomcat should now start and allow access to <ulink type="http" url="http://localhost:8888/josso/signon/login.do">http://localhost:8888/josso/signon/login.do</ulink>; but at this stage, login will not be available.
						</para>
						<mediaobject>
							<imageobject role="html">
								<imagedata fileref="images/AuthenticationAndIdentity/SSO/opensso.png" format="PNG" width="444" align="center" />
							</imageobject>
                            <imageobject role="fo">
								<imagedata fileref="images/AuthenticationAndIdentity/SSO/opensso.png" format="PNG" scalefit="1" width="120mm" align="center" />
							</imageobject>
						</mediaobject>
					</step>
				</procedure>
			</section>

		<section id="sect-Reference_Guide-JOSSO-Setup_the_JOSSO_client">
			<title>Set up the JOSSO client</title>
			<procedure>
				<step>
					<para>
						Copy the library files from <emphasis>$GATEIN_SSO_HOME/josso/gatein.ear/lib</emphasis> into <emphasis>gatein.ear/lib</emphasis> (or into <emphasis>$GATEIN_HOME/lib</emphasis> if &PRODUCT; is  running in Tomcat)
					</para>
				</step>
            <step>
               <para>
                  Copy the file <filename>$GATEIN_SSO_HOME/josso/gatein.ear/portal.war/WEB-INF/classes/josso-agent-config.xml</filename> into <emphasis>gatein.ear/02portal.war/WEB-INF/classes</emphasis> (or into <emphasis>GATEIN_HOME/webapps/portal.war/WEB-INF/classes</emphasis>, or <emphasis>GATEIN_HOME/conf</emphasis> if &PRODUCT; is running in Tomcat)
               </para>
            </step>
				<step>
					<itemizedlist>
						<listitem>
							<para>
								In JBoss AS, edit <filename>gatein.ear/META-INF/gatein-jboss-beans.xml</filename> and uncomment on this section:</para>

<programlisting language="xml"><![CDATA[<authentication>
  <login-module code="org.gatein.sso.agent.login.SSOLoginModule" flag="required">
    <module-option name="portalContainerName">portal</module-option>
    <module-option name="realmName">gatein-domain</module-option>
  </login-module>
  <login-module code="org.exoplatform.services.security.j2ee.JbossLoginModule" flag="required">
    <module-option name="portalContainerName">portal</module-option>
    <module-option name="realmName">gatein-domain</module-option>
  </login-module>
</authentication>
]]></programlisting>
						</listitem>
						<listitem>
							<para>
								In Tomcat, edit <filename>GATEIN_HOME/conf/jaas.conf</filename>, uncomment on this section and comment other parts:
							</para>
<programlisting>org.gatein.sso.agent.login.SSOLoginModule required;
org.exoplatform.services.security.j2ee.TomcatLoginModule requiredtm
portalContainerName=portal
realmName=gatein-domain;
</programlisting>
						</listitem>
					</itemizedlist>
				</step>
				<step>
					<para>
						The installation can be tested at this point.
					</para>
					<procedure>
						<step>
							<para>
								Start (or restart) &PRODUCT;, and (assuming the JOSSO server on Tomcat is running) direct your browser to <ulink type="http" url="http://localhost:8888/josso/signon/login.do">http://localhost:8888/josso/signon/login.do</ulink>.
							</para>
						</step>
						<step>
							<para>
								Login with the username <emphasis>root</emphasis> and the password <emphasis>gtn</emphasis> or any account created through the portal.
							</para>
						</step>
					</procedure>
				</step>
			</procedure>
		</section>

		<section id="sect-Reference_Guide-JOSSO-Setup_the_portal_to_redirect_to_JOSSO">
			<title>Set up the portal to redirect to JOSSO</title>
			<para>
				The next part of the process redirects all user authentication to the JOSSO server.
			</para>
			<para>
				Information about where the JOSSO server is hosted must be properly configured within the &PRODUCT; instance. The required configuration is done by modifying four files:
      </para>

				<itemizedlist>
					<listitem>
						<para>
						In the <filename>gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file, modify the 'Sign In' link as follows:
<programlisting><![CDATA[<!--
<a class="Login" onclick="$signInAction"><%=_ctx.appRes("UILoginForm.label.Signin")%></a>
-->
<a class="Login" href="/portal/sso"><%=_ctx.appRes("UILoginForm.label.Signin")%></a>]]></programlisting>
						</para>
					</listitem>
					<listitem>
						<para>
						In the <filename>gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file, modify the 'Sign In' link as follows:
<programlisting><![CDATA[ <!--
<a onclick="$signInAction"><%=_ctx.appRes("UILogoPortlet.action.signin")%></a>
-->
<a href="/portal/sso"><%=_ctx.appRes("UILogoPortlet.action.signin")%></a>]]></programlisting>
						</para>
					</listitem>
        </itemizedlist>
        <itemizedlist>
          <listitem>
						<para>
							Replace the entire contents of <filename>gatein.ear/02portal.war/login/jsp/login.jsp</filename> with:</para>
<programlisting language="html">&#60;html&#62;
  &#60;head&#62;
    &#60;script type=&#34;text/javascript&#34;&#62;
     window.location = &#39;/portal/sso&#39;;
    &#60;/script&#62;
  &#60;/head&#62;
  &#60;body&#62;
  &#60;/body&#62;
&#60;/html&#62;</programlisting>
           </listitem>
        </itemizedlist>
        <itemizedlist>
					<listitem>
						<para>
							Add the following filters at the top of the filter chain in <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename>:</para>

<programlisting language="xml"><![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>http://localhost:8888/josso/signon/login.do?josso_back_to=http://localhost:8080/portal/initiatessologin</param-value>
   </init-param>
</filter>
<filter>
   <filter-name>JOSSOLogoutFilter</filter-name>
   <filter-class>org.gatein.sso.agent.filter.JOSSOLogoutFilter</filter-class>
   <init-param>
      <!-- This should point to your JOSSO authentication server -->
      <param-name>LOGOUT_URL</param-name>
      <param-value>http://localhost:8888/josso/signon/logout.do</param-value>
   </init-param>
</filter>
<filter>
   <filter-name>InitiateLoginFilter</filter-name>
   <filter-class>org.gatein.sso.agent.filter.InitiateLoginFilter</filter-class>
   <init-param>
      <param-name>ssoServerUrl</param-name>
      <param-value>http://localhost:8888/josso/signon/login.do</param-value>
   </init-param>
   <init-param>
      <param-name>loginUrl</param-name>
      <param-value>http://localhost:8080/portal/dologin</param-value>
   </init-param>
</filter>

<!-- Mapping the filters at the very top of the filter chain -->
<filter-mapping>
   <filter-name>LoginRedirectFilter</filter-name>
   <url-pattern>/*</url-pattern>
</filter-mapping>
<filter-mapping>
   <filter-name>JOSSOLogoutFilter</filter-name>
   <url-pattern>/*</url-pattern>
</filter-mapping>
<filter-mapping>
   <filter-name>InitiateLoginFilter</filter-name>
   <url-pattern>/initiatessologin</url-pattern>
</filter-mapping>]]></programlisting>
					</listitem>
        </itemizedlist>
			<para>
				From now on, all links redirecting to the user authentication pages will redirect to the JOSSO centralized authentication form.
			</para>
		</section>
	</section>

	<section id="sect-Reference_Guide-Single_Sign_On-OpenSSO_The_Open_Web_SSO_project" role="NotInToc">
		<title>OpenSSO - The Open Web SSO project</title>
		<para>
			This Single-Sign-On plugin enables the seamless integration between &PRODUCT; and the OpenSSO Single Sign On Framework. Details about OpenSSO can be found <ulink url="https://opensso.dev.java.net/">here</ulink>.
		</para>
		<para>
			Setting up this integration consists of 3 steps:
		</para>
		<procedure>
			<step>
				<para>
				Configure an OpenSSO server to authenticate against the &PRODUCT; login module. In this section, the OpenSSO server will be installed on Tomcat.
				</para>
			</step>
			<step>
				<para>
				Set up the OpenSSO client.
				</para>
			</step>
			<step>
				<para>
				Set up the portal to redirect to OpenSSO
				</para>
			</step>
		</procedure>
		<para xml:id="sect-Reference_Guide-OpenSSO_server-Obtaining_OpenSSO">To do this integration, you need to obtain OpenSSO first:</para>
		<procedure>
			<step>
				<para>
					Download OpenSSO from <ulink type="http" url="http://download.oracle.com/otn/nt/middleware/11g/oracle_opensso_80U2.zip">http://download.oracle.com/otn/nt/middleware/11g/oracle_opensso_80U2.zip</ulink>.
				</para>
			</step>
			<step>
				<para>
				   Extract the package into a suitable location. This location will be referred to as <emphasis>OPENSSO_HOME</emphasis> in this example.
				</para>
			</step>
		</procedure>
            <note>
               <para>
                  There is also possibility to use OpenAM instead of OpenSSO server. OpenAM is free and integration steps with &PRODUCT; and OpenAM are very similar as with OpenSSO. More info is
                  <ulink type="http" url="http://community.jboss.org/wiki/GateInAndOpenAMIntegration">here</ulink> .
               </para>
            </note>


			<section id="sect-Reference_Guide-OpenSSO_server-Configuring_OpenSSO_server">
				<title>Configure the OpenSSO server</title>
				<para>
					 To configure the web server as desired, it is simpler to directly modify the sources.
				</para>
				<para>
					The first step is to add the &PRODUCT; Authentication Plugin:
				</para>
				<para>
					The plugin makes secure authentication callbacks to a RESTful service installed on the remote &PRODUCT; server to authenticate a user.
				</para>
				<para>
					In order for the plugin to function correctly, it needs to be properly configured to connect to this service. This configuration is done via the <filename>opensso.war/config/auth/default/AuthenticationPlugin.xml</filename> file.
				</para>
				<procedure>
					<step>
						<para>
							Obtain a copy of Tomcat and extract it into a suitable location (this location will be referred to as <emphasis>$PLATFORM_TOMCAT_HOME</emphasis> in this example).
						</para>
					</step>
					<step>
						<para>
							Change the default port to avoid a conflict with the default &PRODUCT; port (for testing purposes) by editing <filename>$PLATFORM_TOMCAT_HOME/conf/server.xml</filename> and replacing the 8080 port with 8888.
							<note>
								<para>
                           If &PRODUCT; is running on the same machine as Tomcat, other ports need to be changed in addition to 8080 to avoid port conflicts.
                           They can be changed to any free port. For example, you can change the admin port from 8005 to 8805, and AJP port from 8009 to 8809.
								</para>
							</note>
						</para>
					</step>
					<step>
						<para>
							Ensure the <filename>$PLATFORM_TOMCAT_HOME/webapps/opensso/config/auth/default/AuthenticationPlugin.xml</filename> file looks like this:
            </para>

<programlisting language="xml">&#60;?xml version=&#39;1.0&#39; encoding=&#34;UTF-8&#34;?&#62;

&#60;!DOCTYPE ModuleProperties PUBLIC &#34;=//iPlanet//Authentication Module Properties XML Interface 1.0 DTD//EN&#34;
          &#34;jar://com/sun/identity/authentication/Auth_Module_Properties.dtd&#34;&#62;

&#60;ModuleProperties moduleName=&#34;AuthenticationPlugin&#34; version=&#34;1.0&#34; &#62;
  &#60;Callbacks length=&#34;2&#34; order=&#34;1&#34; timeout=&#34;60&#34;
             header=&#34;GateIn OpenSSO Login&#34; &#62;
    &#60;NameCallback&#62;
      &#60;Prompt&#62;
		Username
      &#60;/Prompt&#62;
    &#60;/NameCallback&#62;
    &#60;PasswordCallback echoPassword=&#34;false&#34; &#62;
      &#60;Prompt&#62;
		Password
      &#60;/Prompt&#62;
    &#60;/PasswordCallback&#62;
  &#60;/Callbacks&#62;
&#60;/ModuleProperties&#62;</programlisting>

					</step>
					<step>
						<para>
							Copy <filename>$GATEIN_SSO_HOME/opensso/plugin/WEB-INF/lib/sso-opensso-plugin-&#60;VERSION&#62;.jar</filename>, <filename>$GATEIN_SSO_HOME/opensso/plugin/WEB-INF/lib/commons-httpclient-&#60;VERSION&#62;.jar</filename>, and <filename>$GATEIN_SSO_HOME/opensso/plugin/WEB-INF/lib/commons-logging-&#60;VERSION&#62;.jar</filename> into the Tomcat directory at <emphasis>$PLATFORM_TOMCAT_HOME/webapps/opensso/WEB-INF/lib</emphasis>.
						</para>
					</step>
					<step>
						<para>
							Copy <filename>$GATEIN_SSO_HOME/opensso/plugin/WEB-INF/classes/gatein.properties</filename> into <filename>$PLATFORM_TOMCAT_HOME/webapps/opensso/WEB-INF/classes</filename>.
						</para>
					</step>

					<step>
						<para>
							Tomcat should start and be able to access <ulink type="http" url="http://localhost:8888/opensso/UI/Login?realm=gatein">http://localhost:8888/opensso/UI/Login?realm=gatein</ulink>. Login will not be available at this point.
						</para>
						<mediaobject>
							<imageobject role="html">
								<imagedata fileref="images/AuthenticationAndIdentity/SSO/opensso-shot.png" format="PNG" align="center" width="444" />
							</imageobject>
                            <imageobject role="fo">
								<imagedata fileref="images/AuthenticationAndIdentity/SSO/opensso-shot.png" format="PNG" scalefit="1" width="150mm" align="center"/>
							</imageobject>
						</mediaobject>
					</step>
            </procedure>

            <para>Configure the "gatein" realm:</para>
            <procedure>
               <step>
                     <para>Direct your browser to <ulink type="http" url="http://localhost:8888/opensso">http://localhost:8888/opensso</ulink>.</para>
               </step>
               <step>
                     <para>Create the default configuration.</para>
               </step>
               <step>
                     <para>Login as <emphasis>amadmin</emphasis> and then go to the <emphasis role="bold">Configuration</emphasis> tab -> <emphasis role="bold">Authentication</emphasis> -> <emphasis role="bold">Core</emphasis> link ->
                        add a new value and fill in the class name <emphasis role="bold">org.gatein.sso.opensso.plugin.AuthenticationPlugin</emphasis>.
                        This step is really important. If not, AuthenticationPlugin is not available among other the OpenSSO authentication modules.
                     </para>
               </step>
               <step>
                  <para>Go to the <emphasis role="bold">Access control</emphasis> tab and create the new realm called <emphasis role="bold">gatein</emphasis>.</para>
               </step>
               <step>
                  <para>Go to the "gatein" realm and click the <emphasis role="bold">Authentication</emphasis> tab. At the bottom of the <emphasis role="bold">Authentication chaining</emphasis> section, click <emphasis role="bold">ldapService</emphasis>.
                     Here, change the selection from "Datastore", which is the default module in the authentication chain, to <emphasis role="bold">AuthenticationPlugin</emphasis>.
                     This enables the authentication of "gatein" realm by using the GateIn REST service instead of the OpenSSO LDAP server.</para>
               </step>
               <step>
                  <para>
                     Go to <emphasis role="bold">Advanced properties</emphasis> and change UserProfile from <emphasis role="bold">Required</emphasis> to <emphasis role="bold">Dynamic</emphasis>. This step is needed
                     because &PRODUCT; users are not in the OpenSSO Datastore (LDAP server), so their profiles can not be obtained
                     if "Required" is active. By using "Dynamic", all new users are automatically
                     created in the OpenSSO datastore after successful authentication.
                  </para>
               </step>
               <step>
                  <para>
                     Increase the user privileges to allow the REST access. Go to <emphasis role="bold">Access control</emphasis> ->
                     <emphasis role="bold">Top level realm</emphasis> -> <emphasis role="bold">Privileges</emphasis> tab -> <emphasis role="bold">All authenticated users</emphasis>, and check the last two checkboxes:
                     <itemizedlist>
                        <listitem><para>Read and write access only for policy properties.</para></listitem>
                        <listitem><para>Read and write access to all realm and policy properties.</para></listitem>
                     </itemizedlist>
                  </para>
               </step>
               <step>
                  <para>Repeat previous step with increasing privileges for <emphasis role="bold">gatein</emphasis> realm as well.</para>
               </step>
            </procedure>
         </section>


		<section id="sect-Reference_Guide-OpenSSO_The_Open_Web_SSO_project-Setup_the_OpenSSO_client">
			<title>Set up the OpenSSO client</title>
			<procedure>
				<step>
					<para>
						Copy all libraries from <emphasis>$GATEIN_SSO_HOME/opensso/gatein.ear/lib</emphasis> into <emphasis>$PLATFORM_JBOSS_HOME/server/default/deploy/gatein.ear/lib</emphasis> (Or, in Tomcat, into <emphasis>GATEIN_HOME/lib</emphasis>)
					</para>
				</step>
				<step>
					<itemizedlist>
						<listitem>
							<para>
								In JBoss AS, edit <filename>gatein.ear/META-INF/gatein-jboss-beans.xml</filename> and uncomment on this section:</para>

<programlisting language="xml"><![CDATA[<authentication>
  <login-module code="org.gatein.sso.agent.login.SSOLoginModule" flag="required">
    <module-option name="portalContainerName">portal</module-option>
    <module-option name="realmName">gatein-domain</module-option>
  </login-module>
  <login-module code="org.exoplatform.services.security.j2ee.JbossLoginModule" flag="required">
    <module-option name="portalContainerName">portal</module-option>
    <module-option name="realmName">gatein-domain</module-option>
  </login-module>
</authentication>]]></programlisting>

						</listitem>
						<listitem>
							<para>
								If you are running &PRODUCT; in Tomcat, edit <filename>$GATEIN_HOME/conf/jaas.conf</filename>, uncomment on this section and comment other parts:
							</para>
<programlisting>org.gatein.sso.agent.login.SSOLoginModule required;
org.exoplatform.services.security.j2ee.TomcatLoginModule required
portalContainerName=portal
realmName=gatein-domain;</programlisting>

						</listitem>
					</itemizedlist>
					<para>
						At this point, the installation can be tested:
					</para>
					<procedure>
						<step>
							<para>
								Access &PRODUCT; by going to <ulink type="http" url="http://localhost:8888/opensso/UI/Login?realm=gatein">http://localhost:8888/opensso/UI/Login?realm=gatein</ulink> (assuming that the OpenSSO server using Tomcat is still running).
							</para>
						</step>
						<step>
							<para>
								Login with the username <emphasis>root</emphasis> and the password <emphasis>gtn</emphasis> or any account created through the portal.
							</para>
						</step>
					</procedure>
					</step>
			</procedure>
		</section>

		<section id="sect-Reference_Guide-OpenSSO_The_Open_Web_SSO_project-Setup_the_portal_to_redirect_to_OpenSSO">
			<title>Set up the portal to redirect to OpenSSO</title>
			<para>
				The next part of the process is to redirect all user authentication to the OpenSSO server.
			</para>
			<para>
				Information about where the OpenSSO server is hosted must be properly configured within the Enterprise Portal Platform instance. The required configuration is done by modifying three files:
      </para>
				<itemizedlist>
					<listitem>
						<para>
						In the <filename>gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file, modify the 'Sign In' link as follows:
<programlisting><![CDATA[<!--
<a class="Login" onclick="$signInAction"><%=_ctx.appRes("UILoginForm.label.Signin")%></a>
-->
<a class="Login" href="/portal/sso"><%=_ctx.appRes("UILoginForm.label.Signin")%></a>]]></programlisting>
						</para>
					</listitem>
					<listitem>
						<para>
						In the <filename>gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file, modify the 'Sign In' link as follows:
<programlisting><![CDATA[<!--
<a onclick="$signInAction"><%=_ctx.appRes("UILogoPortlet.action.signin")%></a>
-->
<a href="/portal/sso"><%=_ctx.appRes("UILogoPortlet.action.signin")%></a>]]></programlisting>
						</para>
					</listitem>
        </itemizedlist>

        <itemizedlist>
					<listitem>
						<para>
							Replace the entire contents of <filename>gatein.ear/02portal.war/login/jsp/login.jsp</filename> with:</para>
<programlisting language="html">&#60;html&#62;
  &#60;head&#62;
    &#60;script type=&#34;text/javascript&#34;&#62;
     window.location = &#39;/portal/sso&#39;;
    &#60;/script&#62;
  &#60;/head&#62;
  &#60;body&#62;
  &#60;/body&#62;
&#60;/html&#62;</programlisting>
            </listitem>
         </itemizedlist>
         <itemizedlist>
            <listitem>
               <para>
                  Add the following filters at the top of the filter chain in <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename>:</para>

<programlisting language="xml"><![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>http://localhost:8888/opensso/UI/Login?realm=gatein&amp;goto=http://localhost:8080/portal/initiatessologin</param-value>
   </init-param>
</filter>
<filter>
   <filter-name>OpenSSOLogoutFilter</filter-name>
   <filter-class>org.gatein.sso.agent.filter.OpenSSOLogoutFilter</filter-class>
   <init-param>
      <!-- This should point to your SSO authentication server -->
      <param-name>LOGOUT_URL</param-name>
      <param-value>http://localhost:8888/opensso/UI/Logout</param-value>
   </init-param>
</filter>
<filter>
   <filter-name>InitiateLoginFilter</filter-name>
   <filter-class>org.gatein.sso.agent.filter.InitiateLoginFilter</filter-class>
   <init-param>
      <param-name>ssoServerUrl</param-name>
      <param-value>http://localhost:8888/opensso</param-value>
   </init-param>
   <init-param>
      <param-name>loginUrl</param-name>
      <param-value>http://localhost:8080/portal/dologin</param-value>
   </init-param>
   <init-param>
      <param-name>ssoCookieName</param-name>
      <param-value>iPlanetDirectoryPro</param-value>
   </init-param>
</filter>

<!-- Mapping the filters at the very top of the filter chain -->
<filter-mapping>
   <filter-name>LoginRedirectFilter</filter-name>
   <url-pattern>/*</url-pattern>
</filter-mapping>
<filter-mapping>
   <filter-name>OpenSSOLogoutFilter</filter-name>
   <url-pattern>/*</url-pattern>
</filter-mapping>
<filter-mapping>
   <filter-name>InitiateLoginFilter</filter-name>
   <url-pattern>/initiatessologin</url-pattern>
</filter-mapping>]]></programlisting>
            </listitem>
         </itemizedlist>

			<para>
				From now on, all links redirecting to the user authentication pages will redirect to the OpenSSO centralized authentication form.
			</para>
		</section>

	</section>

	<section id="Single_Sign_On-SPNEGO" role="NotInToc">
		<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>The user logs into the desktop, such as a Windows machine.</para>
			</step>
			<step>
				<para>The desktop login is governed by the Active Directory domain.</para>
			</step>
			<step>
				<para>Next, the user opens the 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 the background GSS messages with the Active
					Directory (or any Kerberos Server) to validate the Kerberos ticket from user.</para>
			</step>
			<step>
				<para>The User has a seamless SSO into the web application.</para>
			</step>
		</procedure>

  <section id="SPNEGO_server_configuration">
    <title>SPNEGO Server Configuration</title>
    <para>
       In this section, we will describe some necessary steps for setup Kerberos server on Linux. This server will then be used for SPNEGO authentication against &PRODUCT;
    </para>
    <note>
      <para>If you don't have Linux but you are using Windows and Active Directory domain,
         then the information are not important for you and you may jump to the <xref linkend="Single_Sign_On-SPNEGO-GateIn_Configuration" /> to see how to integrate SPNEGO with &PRODUCT;.
         Please note that Kerberos setup is also dependent on your Linux distribution and so steps can be slightly different in your environment.
      </para>
    </note>
    <procedure>
        <step>
          <para>Correct the setup of network on the machine. For example, if you are using the "server.local.network" domain as your machine where Kerberos and &PRODUCT; are located,
          add the line containing the machine's IP address to the <filename>/etc/hosts</filename> file.
          </para>
          <programlisting>192.168.1.88  server.local.network</programlisting>
          <note>
          <para>It is not recommended to use loopback addresses.</para>
          </note>
        </step>
        <step>
          <para>Install Kerberos with these packages: krb5-admin-server, krb5-kdc, krb5-config, krb5-user, krb5-clients, and krb5-rsh-server.
          </para>
        </step>
        <step>
          <para>Edit the Kerberos configuration file at <filename>/etc/krb5.config</filename>, including:
          </para>
          <itemizedlist>
            <listitem>
              <para>Uncomment on these lines:</para>
<programlisting>default_tgs_enctypes = des3-hmac-sha1
default_tkt_enctypes = des3-hmac-sha1
permitted_enctypes = des3-hmac-sha1</programlisting>
            </listitem>
            <listitem>
              <para>Add <emphasis >local.network</emphasis> as a default realm and it is also added to the list of realms and remove the remains of realms. The content looks like:
              </para>
<programlisting>[libdefaults]
    default_realm = LOCAL.NETWORK

# The following krb5.conf variables are only for MIT Kerberos.
    krb4_config = /etc/krb.conf
    krb4_realms = /etc/krb.realms
    kdc_timesync = 1
    ccache_type = 4
    forwardable = true
    proxiable = true

# The following encryption type specification will be used by MIT Kerberos
# if uncommented.  In general, the defaults in the MIT Kerberos code are
# correct and overriding these specifications only serves to disable new
# encryption types as they are added, creating interoperability problems.
#
# The only time when you might need to uncomment these lines and change
# the enctypes is if you have local software that will break on ticket
# caches containing ticket encryption types it doesn't know about (such as
# old versions of Sun Java).

    default_tgs_enctypes = des3-hmac-sha1
    default_tkt_enctypes = des3-hmac-sha1
    permitted_enctypes = des3-hmac-sha1

# The following libdefaults parameters are only for Heimdal Kerberos.
    v4_instance_resolve = false
    v4_name_convert = {
        host = {
            rcmd = host
            ftp = ftp
        }
        plain = {
            something = something-else
        }
    }
    fcc-mit-ticketflags = true

[realms]
    LOCAL.NETWORK = {
        kdc = server.local.network
        admin_server = server.local.network
    }

[domain_realm]
    .local.network = LOCAL.NETWORK
    local.network = LOCAL.NETWORK

[login]
    krb4_convert = true
    krb4_get_tickets = false</programlisting>
            </listitem>
          </itemizedlist>
        </step>
        <step>
          <para>Edit the KDC configuration file at <filename>/etc/krb5kdc/kdc.conf</filename> that looks like.
          </para>
<programlisting>[kdcdefaults]
    kdc_ports = 750,88

[realms]
    LOCAL.NETWORK = {
        database_name = /home/gatein/krb5kdc/principal
        admin_keytab = FILE:/home/gatein/krb5kdc/kadm5.keytab
        acl_file = /home/gatein/krb5kdc/kadm5.acl
        key_stash_file = /home/gatein/krb5kdc/stash
        kdc_ports = 750,88
        max_life = 10h 0m 0s
        max_renewable_life = 7d 0h 0m 0s
        master_key_type = des3-hmac-sha1
        supported_enctypes = aes256-cts:normal arcfour-hmac:normal des3-hmac-sha1:normal des-cbc-crc:normal des:normal des:v4 des:norealm des:onlyrealm des:afs3
        default_principal_flags = +preauth
    }

[logging]
        kdc = FILE:/home/gatein/krb5logs/kdc.log
        admin_server = FILE:/home/gatein/krb5logs/kadmin.log</programlisting>
          <itemizedlist>
            <listitem>
              <para>Create krb5kdc and krb5logs directory for Kerberos database as shown in the configuration file above.</para></listitem>
            <listitem>
              <para>Next, create a KDC database using the following command.</para>
<command>
sudo krb5_newrealm
</command>
            </listitem>
            <listitem>
              <para>Start the KDC and Kerberos admin servers using these commands:</para>
<command>
sudo /etc/init.d/krb5-kdc restart
sudo /etc/init.d/krb-admin-server restart
</command>
            </listitem>
          </itemizedlist>
        </step>
        <step>
          <para>Add Principals and create Keys.</para>
          <itemizedlist>
            <listitem>
              <para>Start an interactive 'kadmin' session and create the necessary Principals.</para>
<command>
sudo kadmin.local
</command>
            </listitem>
            <listitem>
              <para>Add the &PRODUCT; machine and keytab file that need to be authenticated.</para>
<programlisting>addprinc -randkey HTTP/server.local.network@LOCAL.NETWORK
ktadd HTTP/server.local.network@LOCAL.NETWORK</programlisting>
            </listitem>
            <listitem>
              <para>Add the default &PRODUCT; user accounts and enter the password for each created user that will be authenticated.</para>
<programlisting>addprinc john
addprinc demo
addprinc root</programlisting>
            </listitem>
          </itemizedlist>
        </step>
        <step>
          <para>Test your changed setup by using the command.</para>
<command>
kinit -A demo
</command>
          <itemizedlist>
            <listitem>
              <para>If the setup works well, you are required to enter the password created for this user in Step 5.
                 Without the -A, the kerberos ticket validation involved reverse DNS lookups, which can get very cumbersome to debug if your network's DNS setup is not great.
                 This is a production level security feature, which is not necessary in this development setup. In production environment, it will be better to avoid -A option.
              </para>
            </listitem>
            <listitem>
               <para>After successful login to Kerberos, you can see your Kerberos ticket when using this command.</para>
<command>
klist
</command>
            </listitem>
            <listitem>
              <para>If you want to logout and destroy your ticket, use this command.</para>
<command>
kdestroy
</command>
            </listitem>
          </itemizedlist>
      </step>
    </procedure>
  </section>
  <section id="Single_Sign_On-CAS_Central_Clients">
        <title>Clients</title>
          <para>After performing all configurations above, you need to enable the <emphasis role="bold">Negotiate authentication </emphasis> of Firefox in client machines so that clients could be authenticated by &PRODUCT; as follows:
          </para>
    <procedure>
          <step>
            <para>Start Firefox, then enter the command: <command>about:config </command> into the address field.</para>
          </step>
          <step>
            <para>Enter <emphasis role="bold">network.negotiate-auth</emphasis> and set the value as below:</para>
<programlisting>network.negotiate-auth.allow-proxies = true
network.negotiate-auth.delegation-uris = .local.network
network.negotiate-auth.gsslib (no-value)
network.negotiate-auth.trusted-uris = .local.network
network.negotiate-auth.using-native-gsslib = true</programlisting>
          </step>
    </procedure>
     <note>
        <para>
          Consult documentation of your OS or web browser if using different browser than Firefox.
        </para>
     </note>
  </section>
  <section id="Single_Sign_On-SPNEGO-GateIn_Configuration">
			<title>&PRODUCT; Configuration</title>
        <para>&PRODUCT; uses JBoss Negotiation to enable SPNEGO-based desktop
				SSO for the portal. Here are the steps to integrate SPNEGO with
				&PRODUCT;.
        </para>
			<procedure>
				<step>
					<para>
                        Activate the Host authentication under the <filename>$PLATFORM_JBOSS_HOME/server/default/conf/login-config.xml </filename> file by adding the following host login module:
          </para>
<programlisting language="xml"><![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@LOCAL.NETWORK</module-option>
      <module-option name="keyTab">/etc/krb5.keytab</module-option>
      <module-option name="doNotPrompt">true</module-option>
      <module-option name="debug">true</module-option>
    </login-module>
  </authentication>
 </application-policy>]]></programlisting>

            <para>
               The 'keyTab' value should point to the keytab file that was
               generated by the kadmin kerberos tool. When using Kerberos on Linux, it should be the value of the <emphasis role="bold">admin_keytab</emphasis> parameter from the <filename>kdc.conf</filename> file.
               See the <xref linkend="SPNEGO_server_configuration"/> section for more details.
            </para>
				</step>

        <step>
					<para>
						Extend the core authentication mechanisms to support SPNEGO under
                  <filename>$PLATFORM_JBOSS_HOME/server/default/deployers/jbossweb.deployer/META-INF/war-deployers-jboss-beans.xml</filename> by
						adding the 'SPNEGO' authenticators property.
          </para>

<programlisting language="xml"><![CDATA[<deployment xmlns="urn:jboss:bean-deployer:2.0">
<property name="authenticators">
  <map class="java.util.Properties" 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.gatein.sso.spnego.GateInNegotiationAuthenticator</value>
    </entry>
  </map>
</property>]]></programlisting>
				</step>
				<step>
                   <para>
                     Add the GateIn SSO module binaries by copying <filename>$GATEIN_SSO_HOME/spnego/gatein.ear/lib/sso-agent-VERSION.jar</filename> to the <filename>$PLATFORM_JBOSS_HOME/server/default/deploy/gatein.ear/lib</filename> directory.
                     File <filename>$GATEIN_SSO_HOME/spnego/gatein.ear/lib/spnego-VERSION.jar</filename> needs to be copied to the <filename>$PLATFORM_JBOSS_HOME/server/default/lib</filename> directory.
          </para>
				</step>
				<step>
					<para>
                      Download library <filename>jboss-negotiation-2.0.4.GA</filename> from location
                      <ulink type="html" url="https://repository.jboss.org/nexus/content/groups/public/org/jboss/security/jboss-negotiation/2.0.4.GA/jboss-negotiation-2.0.4.GA.jar">https://repository.jboss.org/nexus/content/groups/public/org/jboss/security/jboss-negotiation/2.0.4.GA/jboss-negotiation-2.0.4.GA.jar</ulink>
                      and copy this file to <filename>$PLATFORM_JBOSS_HOME/server/default/lib</filename> directory as well.
                   </para>
                </step>
                <step>
                  <para>
                     Modify the <filename>$PLATFORM_JBOSS_HOME/server/defaut/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> file as below:
                  </para>

						<programlisting language="xml"><![CDATA[<deployment xmlns="urn:jboss:bean-deployer:2.0">

  <application-policy xmlns="urn:jboss:security-beans:1.0" name="gatein-form-auth-domain">
    <authentication>
      <login-module code="org.gatein.wci.security.WCILoginModule" flag="optional">
        <module-option name="portalContainerName">portal</module-option>
        <module-option name="realmName">gatein-domain</module-option>
      </login-module>
      <login-module code="org.exoplatform.services.security.jaas.SharedStateLoginModule" flag="required">
        <module-option name="portalContainerName">portal</module-option>
        <module-option name="realmName">gatein-domain</module-option>
      </login-module>

      <!-- Uncomment this part to check on each login if user is member of "/platform/users" group and if not
           create such membership -->
      <!--
      <login-module code="org.exoplatform.services.organization.idm.CustomMembershipLoginModule" flag="required">
        <module-option name="portalContainerName">portal</module-option>
        <module-option name="realmName">gatein-domain</module-option>
        <module-option name="membershipType">member</module-option>
        <module-option name="groupId">/platform/users</module-option>
      </login-module>
      -->

      <login-module code="org.exoplatform.services.security.j2ee.JbossLoginModule" flag="required">
        <module-option name="portalContainerName">portal</module-option>
<!-- logout needs to be performed from 'gatein-domain' as it is used for JaasSecurityManager. -->
        <module-option name="realmName">gatein-domain</module-option>
      </login-module>
    </authentication>
  </application-policy>

  <application-policy xmlns="urn:jboss:security-beans:1.0" name="gatein-domain">
    <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>
	 <module-option name="removeRealmFromPrincipal">true</module-option>
	 <module-option name="usernamePasswordDomain">gatein-form-auth-domain</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>
                      This activates SPNEGO LoginModules with fallback to FORM authentication. When SPNEGO is not available and it needs to fallback to FORM, it will use <emphasis role="bold">gatein-form-auth-domain</emphasis> security domain.
                      More details below.
                   </para>
				</step>
				<step>
					<para>
                  Modify <filename>$PLATFORM_JBOSS_HOME/server/default/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> as below.</para>
						<programlisting language="xml"><![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>
      <form-login-config>
	     <form-login-page>/initiatelogin</form-login-page>
	     <form-error-page>/errorlogin</form-error-page>
     </form-login-config>
    </login-config>]]></programlisting>
          <para>
             This integrates SPNEGO support into the Portal web archive by switching the authentication mechanism from the default "FORM"-based to "SPNEGO"-based authentication.
             You can notice that SPNEGO part also contains the <emphasis role="bold">form-login-config</emphasis> element, which is needed if you want to enable fallback to FORM based authentication.
             In this case, portal will try to authenticate user with his Kerberos ticket through SPNEGO. If user don't have Kerberos ticket, he will be redirected to FORM (&PRODUCT; login screen).
             So first attempt is for login with SPNEGO and next attempt is for login with FORM, which is used only if login through SPNEGO is not successful (For example user don't have
             valid Kerberos ticket or his browser doesn't support SPNEGO with our Kerberos server).
          </para>
          <para>
             If you don't want fallback to FORM, you can disable form-login-config part and have only:</para>
                        <programlisting language="xml"><![CDATA[<login-config>
    <auth-method>SPNEGO</auth-method>
    <realm-name>SPNEGO</realm-name>
<!-- <form-login-config>
	     <form-login-page>/initiatelogin</form-login-page>
	     <form-error-page>/errorlogin</form-error-page>
     </form-login-config>
-->
</login-config>]]></programlisting>
        <para> In this case user needs to authenticate through SPNEGO and if that fails, FORM is not shown but user has authentication error with HTTP code 401.</para>

				</step>
				<step>
              <para>Integrate the request pre-processing needed for SPNEGO via filters by adding the following filters to the
                 <filename>$PLATFORM_JBOSS_HOME/server/default/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> at the top of the Filter chain.
              </para>
<programlisting language="xml"><![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>/login</url-pattern>
</filter-mapping>]]></programlisting>

				</step>
				<step>
					<para>
          In <filename>$PLATFORM_JBOSS_HOME/server/default/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file modify the
            'Sign In' link as follows:
<programlisting><![CDATA[<!--
<a class="Login" onclick="$signInAction"><%=_ctx.appRes("UILoginForm.label.Signin")%></a>
-->
<a class="Login" href="/portal/sso"><%=_ctx.appRes("UILoginForm.label.Signin")%></a>]]></programlisting>
          </para>
        </step>
        <step>
                    <para>
                        Start the &PRODUCT; portal using the command below.
                    </para>
                    <command>sudo ./run.sh -Djava.security.krb5.realm=LOCAL.NETWORK -Djava.security.krb5.kdc=server.local.network -c default -b server.local.network</command>
        </step>
        <step>
                    <para>Login to Kerberos with the command.</para>
                        <command>kinit -A demo</command>
                        <para>You should be able to click the 'Sign In' link on the &PRODUCT; portal
                        and the 'demo' user from the &PRODUCT; portal should be automatically
                        logged in.
                    </para>
                </step>
                <step>
                   <para>
                      Let's try to destroy kerberos ticket with command <command>kdestroy</command>, then try to login again. You will now be placed to login screen of &PRODUCT; because you don't have active Kerberos ticket. You can login with predefined account and password "demo"/"gtn" .
                   </para>
                </step>
            </procedure>
        </section>
    </section>
</section>
