7:25 a.m.
Author: thomas.heute(a)jboss.com
Date: 2010-02-09 08:25:29 -0500 (Tue, 09 Feb 2010)
New Revision: 1586
Modified:
portal/trunk/docs/reference-guide/en/modules/SSO.xml
Log:
Rewrote the SSO chapter
Modified: portal/trunk/docs/reference-guide/en/modules/SSO.xml
===================================================================
--- portal/trunk/docs/reference-guide/en/modules/SSO.xml 2010-02-09 11:10:41 UTC (rev
1585)
+++ portal/trunk/docs/reference-guide/en/modules/SSO.xml 2010-02-09 13:25:29 UTC (rev
1586)
@@ -1,156 +1,284 @@
-<?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" [
+<?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;
]>
-<chapter id="chap-Reference_Guide-Single_Sign_On">
- <title>Single Sign On</title>
- <section id="sect-Reference_Guide-Single_Sign_On-Overview_of_SSO">
- <title>Overview of SSO</title>
- <para>
- Portal as an integration and aggregation platform provides some form of SSO by itself.
When you log into the portal you gain access to many systems through portlets using a
single identity. Still in many cases you need to integrate the portal infrastructure with
other SSO enabled systems. There are many different Identity Management solutions on the
market. In most cases each SSO framework provides its own way to plug into Java EE
application.
- </para>
- </section>
-
- <section
id="sect-Reference_Guide-Single_Sign_On-CAS_Central_Authentication_Service">
- <title>CAS - Central Authentication Service</title>
- <para>
- This Single Sign On plugin enables seamless integration between GateIn Portal and the
CAS Single Sign On Framework. Details about CAS can be found <ulink
url="http://www.ja-sig.org/products/cas/">here</ulink>
- </para>
- <section
id="sect-Reference_Guide-CAS_Central_Authentication_Service-Integration">
- <title>Integration</title>
- <section id="sect-Reference_Guide-Integration-From_source">
- <title>From source</title>
- <itemizedlist>
- <listitem>
- <para>
- Check out the GateIn SSO component from SVN using the following command:
-<programlisting>
-
-svn co http://anonsvn.jboss.org/repos/gatein/components/sso/tags/<appropr... sso
component version>
+<chapter>
+ <title>Single Sign On</title>
+
+ <section>
+ <title>Overview of SSO</title>
+
+ <para>Portal as an integration and aggregation platform provides some form
+ of SSO by itself. When you log into the portal you gain access to many
+ systems through portlets using a single identity. Still in many cases you
+ need to integrate the portal infrastructure with other SSO enabled
+ systems. There are many different Identity Management solutions on the
+ market. In most cases each SSO framework provides its own way to plug into
+ Java EE application.</para>
+ </section>
+
+ <section>
+ <title>CAS - Central Authentication Service</title>
+
+ <para>This Single Sign On plugin enables seamless integration between
+ GateIn Portal and the CAS Single Sign On Framework. Details about CAS can
+ be found <ulink
+
url="http://www.ja-sig.org/products/cas/">here.</ulink>...
+
+ <para>The integration consitsts in two parts, the first part consists of
+ installing or configuring a CAS server, the second part consists of
+ setting up the portal to use the CAS server.</para>
+
+ <section>
+ <title>CAS server</title>
+
+ <para>First we will set up the server to authenticate against the portal
+ login module. You can find more information about setting up the server
+ by reading the official CAS documentation, here we will install the CAS
+ server on Tomcat</para>
+
+ <section>
+ <title>Obtaining CAS</title>
+
+ <para>You can download CAS from
+ http://www.jasig.org/cas/download.</para>
+
+ <para>Once downloaded extract it in what we will call $CAS_HOME from
+ now.</para>
+ </section>
+
+ <section>
+ <title>Modifying CAS server</title>
+
+ <para>To simplify we will directly modify the sources so that the
+ produced web archive is configured the way we want.</para>
+
+ <para>First we will want to change the authenticaton handler to use
+ the portal authentication handler:</para>
+
+ <para>The CAS Server Plugin makes secure authentication callbacks to a
+ RESTful service installed on the remote GateIn server in order to
+ authenticate a user. 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
+ <emphasis>cas.war/WEB-INF/deployerConfigContext.xml</emphasis>
+ file.</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Open
+
$CAS_HOME/cas-server-webapp/src/main/webapp/WEB-INF/deployerConfigContext.xml</para>
+ </listitem>
+
+ <listitem>
+ <para>Replace: <programlisting role="XML"> <!--
+ | 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.
+ +-->
+ <property name="authenticationHandlers">
+ <list>
+ <!--
+ | This is the authentication handler that authenticates services by means of
callback via SSL, thereby validating
+ | a server side SSL certificate.
+ +-->
+ <bean
class="org.jasig.cas.authentication.handler.support.HttpBasedServiceCredentialsAuthenticationHandler"
+ p:httpClient-ref="httpClient" />
+ <!--
+ | 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.
+ +-->
+ <bean
+
class="org.jasig.cas.authentication.handler.support.SimpleTestUsernamePasswordAuthenticationHandler"
/>
+ </list>
+ </property></programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>With the following (Make sure to set the host, port and
+ context with the values corresponding to your portal)</para>
+
+ <para><programlisting role="XML"><!--
+ | 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.
+ +-->
+ <property name="authenticationHandlers">
+ <list>
+ <!--
+ | This is the authentication handler that authenticates services by means of
callback via SSL, thereby validating
+ | a server side SSL certificate.
+ +-->
+ <bean
class="org.jasig.cas.authentication.handler.support.HttpBasedServiceCredentialsAuthenticationHandler"
+ p:httpClient-ref="httpClient" />
+ <!--
+ | 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.
+ +-->
+ <!-- Integrates with the Gatein Authentication Service to perform
authentication -->
+ <!--
+ | 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
+ +-->
+ <bean
class="org.gatein.sso.cas.plugin.AuthenticationPlugin">
+ <property
name="gateInHost"><value>localhost</value></property>
+ <property
name="gateInPort"><value>8080</value></property>
+ <property
name="gateInContext"><value>portal</value></property>
+ </bean>
+ </list>
+ </property></programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>Copy gatein-cas-plugin-<VERSION>.jar and
+ commons-httpclient-<VERSION>.jar into the newly created
+ directory
+ $CAS_HOME/cas-server-webapp/src/main/webapp/WEB-INF/lib</para>
+ </listitem>
+
+ <listitem>
+ <para>Get an installation of Tomcat and extract it in what we will
+ call $TOMCAT_HOME. Change the default port to avoid a conflict
+ with the default GateIn (for testing purposes). Edit
+ $TOMCAT_HOME/conf/server.xml and replace the 8080 port to
+ 8888.<note>
+ <para>If you are running GateIn with Tomcat on the same
+ machine you will also need to change the port 8005 to
+ something else to avoid port conflicts.</para>
+ </note></para>
+ </listitem>
+
+ <listitem>
+ <para>Go to $CAS_HOME/cas-server-webapp and do 'mvn
+ install'</para>
+ </listitem>
+
+ <listitem>
+ <para>Copy $CAS_HOME/cas-server-webapp/target/cas.war into
+ $TOMCAT_HOME/webapps</para>
+
+ <para>Now you should be able to start Tomcat and access
+ http://localhost:8888/cas but at this stage you won't be able to
+ login.</para>
+ </listitem>
+ </orderedlist>
+ </section>
+</section>
+ <section>
+ <title>Setup the CAS client</title>
+
+ <orderedlist>
+ <listitem>
+ <para>Copy the CAS client core
+
($CAS_HOME/cas-server-webapp/target/cas-server-webapp-<VERSION>/WEB-INF/lib/cas-client-core-<VERSION>.jar
+ into gatein.ear/lib (Or if you are running GateIn in Tomcat, in
+ $GATEIN_HOME/lib)</para>
+ </listitem>
+
+ <listitem>
+ <para>In JBoss AS, edit gatein.ear/META-INF/gatein-jboss-beans.xml
+ and uncomment the section for CAS</para>
+
+ <para><programlisting
role="XML"><authentication>
+ <login-module code="org.gatein.sso.agent.login.SSOLoginModule"
flag="required">
+ </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></para>
+
+ <para>If you are running GateIn in Tomcat, edit
+ $GATEIN_HOME/conf/jaas.conf and uncomment the secion for
+ CAS</para>
+
+ <para><programlisting>org.gatein.sso.agent.login.SSOLoginModule
required
+org.exoplatform.services.security.j2ee.JbossLoginModule required
+portalContainerName=portal
+realmName=gatein-domain</programlisting>At this point, you can test the
+ installation, start GateIn (assuming that the CAS server using
+ Tomcat is still running) by going to http://localhost:8888/cas you
+ should be able to login with username 'root' and password
'gtn' or
+ any account created through the portal.</para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section>
+ <title>Setup the portal to redirect to CAS</title>
+
+ <para>Now we want to tell GateIn to redirect all user authentication
+ to the CAS server.</para>
+
+ <para>The CAS server can be located anywhere on the Internet, and this
+ information must be properly configured within the GateIn instance.
+ This configuration needs to be done in 3 files <itemizedlist>
+ <listitem>
+ <emphasis>In
+ gatein.ear/02portal.war/groovy/portal/webui/UILoginForm.gtmpl
+ replace the javascript at the bottom by:</emphasis>
+
+ <para>
+ <programlisting><script>
+<%=uicomponent.event("Close");%>
+ window.location =
'http://localhost:8888/cas/login?service=http://localhost:8080/portal/private/classic';
+</script>
</programlisting>
- </para>
- </listitem>
- <listitem>
- <para>
- Update <emphasis>packaging/profiles.xml</emphasis> to reflect the
directories where your local JBoss AS 5.1.0.GA and Tomcat 6.0.2 are installed
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section
id="sect-Reference_Guide-Integration-Install_CAS_plugin_into_a_designated_CAS_3.3.4_server">
- <title>Install CAS plugin into a designated CAS (3.3.4) server</title>
- <itemizedlist>
- <listitem>
- <para>
-
-<programlisting>
-
- mvn -Pplugin-cas-install install
-</programlisting>
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section
id="sect-Reference_Guide-Integration-Install_CAS_GateIn_Agent_into_the_designated_GateIn_server">
- <title>Install CAS GateIn Agent into the designated GateIn
server</title>
- <itemizedlist>
- <listitem>
- <para>
-
-<programlisting>
-
- mvn -Pgatein-cas-install install
-</programlisting>
- </para>
- </listitem>
- </itemizedlist>
- </section>
+ </para>
+ </listitem>
- </section>
-
- <section
id="sect-Reference_Guide-CAS_Central_Authentication_Service-CAS_Server_Plugin_Configuration">
- <title>CAS Server Plugin Configuration</title>
- <para>
- The CAS Server Plugin makes secure authentication callbacks to a RESTful service
installed on the remote GateIn server in order to authenticate a user. 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
<emphasis>cas.war/WEB-INF/deployerConfigContext.xml</emphasis> file.
- </para>
- <para>
-
-<programlisting>
-
- <!--
- Note: Modify the Plugin Configuration based on the actual information of a GateIn
instance.
- The instance can be anywhere on the internet...Not on localhost where CAS is
running
- -->
- <bean
class="org.gatein.sso.cas.plugin.AuthenticationPlugin">
- <property
name="gateInHost"><value>localhost</value></property>
- <property
name="gateInPort"><value>8080</value></property>
- <property
name="gateInContext"><value>portal</value></property>
- </bean>
+ <listitem>
+ <emphasis>In gatein.ear/02portal.war/login/jsp/login.jsp replace
+ everything by:</emphasis>
+
+ <para>
+ <programlisting><html>
+ <head>
+ <script type="text/javascript">
+ window.location =
'http://localhost:8888/cas/login?service=http://localhost:8080/portal/private/classic';
+ </script>
+ </head>
+ <body>
+ </body>
+</html>
</programlisting>
- </para>
- </section>
-
- <section
id="sect-Reference_Guide-CAS_Central_Authentication_Service-GateIn_Agent_Configuration">
- <title>GateIn Agent Configuration</title>
- <para>
- In a Single Sign On usecase, the GateIn server re-directs all "private"
resource requests to the CAS server for authentication first. The CAS server can be
located anywhere on the Internet, and this information must be properly configured within
the GateIn instance. This configuration needs to be done in 3 files
- <itemizedlist>
- <listitem>
- <emphasis>gatein.ear/02portal.war/groovy/portal/webui/UILoginForm.gtmpl</emphasis>
- <para>
-
-<programlisting>
-
- <script>
- <%=uicomponent.event("Close");%>
- window.location =
'http://localhost:8888/cas/login?service=http://localhost:8080/portal/private/classic';
- </script>
-</programlisting>
- </para>
- </listitem>
- <listitem>
- <emphasis>gatein.ear/02portal.war/login/jsp/login.jsp</emphasis>
- <para>
-
-<programlisting>
-
- <html>
- <head>
- <script type="text/javascript">
- window.location =
'http://localhost:8888/cas/login?service=http://localhost:8080/portal/private/classic';
- </script>
- </head>
- <body>
- </body>
- </html>
-</programlisting>
- </para>
- </listitem>
- <listitem>
- <emphasis>gatein.ear/02portal.war/WEB-INF/web.xml</emphasis>
- <para>
-
-<programlisting>
-
- <servlet>
- <servlet-name>InitiateLoginServlet</servlet-name>
-
<servlet-class>org.gatein.sso.agent.GenericSSOAgent</servlet-class>
- <init-param>
- <param-name>casServerUrl</param-name>
- <param-value>http://localhost:8888/cas</param-value>
- </init-param>
- </servlet>
-</programlisting>
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
+ </para>
+ </listitem>
- </section>
+ <listitem>
+ <emphasis>In gatein.ear/02portal.war/WEB-INF/web.xml replace the
+ InitiateLoginServlet declaration by:</emphasis>
+ <para>
+ <programlisting><servlet>
+ <servlet-name>InitiateLoginServlet</servlet-name>
+
<servlet-class>org.gatein.sso.agent.GenericSSOAgent</servlet-class>
+ <init-param>
+ <param-name>ssoServerUrl</param-name>
+ <param-value>http://localhost:8888/cas</param-value>
+ </init-param>
+</servlet></programlisting>
+ </para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>From now on, all links redirecting to the user authentication
+ pages will redirect to the CAS centralized authentication form.</para>
+ </section>
+ </section>
+ <section>
+ <title>Open SSO</title>
+
+ <para></para>
+ </section>
</chapter>
-