Author: bdaw
Date: 2007-09-04 15:09:45 -0400 (Tue, 04 Sep 2007)
New Revision: 8153
Modified:
docs/trunk/referenceGuide/en/modules/sso.xml
Log:
merge CAS integration docs
Modified: docs/trunk/referenceGuide/en/modules/sso.xml
===================================================================
--- docs/trunk/referenceGuide/en/modules/sso.xml 2007-09-04 17:45:33 UTC (rev 8152)
+++ docs/trunk/referenceGuide/en/modules/sso.xml 2007-09-04 19:09:45 UTC (rev 8153)
@@ -5,6 +5,11 @@
<surname>Dawidowicz</surname>
<email>boleslaw dot dawidowicz at redhat dot com</email>
</author>
+ <author>
+ <firstname>Sohil</firstname>
+ <surname>Shah</surname>
+ <email>sshah(a)redhat.com</email>
+ </author>
</chapterinfo>
<title>Single Sign ON</title>
<para>This chapter describes how to setup SSO in JBoss Portal</para>
@@ -143,9 +148,131 @@
authentication cache you may need to restart browser.</note>
</sect2>
</sect1>
- <!--<sect1>
- <title>Using external authentication providers</title>
- <para>TODO:</para>
- </sect1>-->
+ <sect1>
+ <title>CAS - Central Authentication Service</title>
+ <para>This Single Sign On plugin enables seamless integration between JBoss
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>...
+ <sect2>
+ <title>Integration steps</title>
+ <note>The steps below assume that CAS server and JBoss Portal will be
deployed on the same JBoss Application Server instance.
+ CAS will be configured to leverage identity services exposed by JBoss Portal
to perform authentication. Procedure may be
+ sligtly different for other deployment scenarios. Both JBoss Portal and CAS
will need to be configured to authenticate against
+ same database or LDAP server. Please see CAS documentation to learn how to
setup it up against proper identity store.</note>
+ <note>Configuration below assumes that JBoss Application Server is HTTPS
enabled and operates on standard ports: 80 (for HTTP) and 443 (for HTTPS).</note>
+ <para>
+ <orderedlist>
+ <listitem>
+ Install CAS server (v 3.0.7). This should be as simple as deploying
single <emphasis>cas.war</emphasis> file.
+ </listitem>
+ <listitem>
+ Edit
<emphasis>$JBOSS_HOME/server/default/deploy/jboss-portal.sar/portal-server.war/WEB-INF/context.xml</emphasis>
file and enable proper tomcat valve
+ by uncommenting following lines:
+ <programlisting>
+ <![CDATA[
+<Valve className="org.jboss.portal.identity.sso.cas.CASAuthenticationValve"
+ casLogin="https://localhost/cas/login"
+ casValidate="https://localhost/cas/serviceValidate"
+ casServerName="localhost"
+ authType="FORM"
+/>
+ ]]>
+ </programlisting>
+ Update valve options as follow:
+ <itemizedlist>
+ <listitem>
+ <emphasis>casLogin: </emphasis> URL of your CAS
Authentication Server
+ </listitem>
+ <listitem>
+ <emphasis>casValidate: </emphasis> URL of your CAS
Authentication Server validation service
+ </listitem>
+ <listitem>
+ <emphasis>casServerName:</emphasis> the hostname:port
combination of your CAS Authentication Server
+ </listitem>
+ </itemizedlist>
+ <note>CAS client requires to use SSL connection. To learn how to
setup JBoss Application Server to use HTTPS see here</note>
+ </listitem>
+ <listitem>
+ Copy <emphasis>casclient.jar</emphasis> into
<emphasis>$JBOSS_HOME/server/default/deploy/jboss-portal.sar/lib</emphasis>.
+ You can download this file from CAS homepage or from JBoss repository
under <
emphasis>http://repository.jboss.com/cas/3.0.7/lib/</emphasis>
+ <note>The CAS engine does not accept self-signed SSL
certificates. This requirement is fine for production use where a production
+ level SSL certificate is available. However, for testing purposes,
this can get a little annoying. Hence, if you are having this issue,
+ you can use <emphasis>casclient-lenient.jar</emphasis>
instead.</note>
+ </listitem>
+ <listitem>
+ Edit
<emphasis>$JBOSS_HOME/server/default/deploy/jboss-portal.sar/META-INF/jboss-service.xml</emphasis>
file and uncomment following lines:
+ <programlisting>
+ <![CDATA[
+<mbean
+ code="org.jboss.portal.identity.sso.cas.CASAuthenticationService"
+ name="portal:service=Module,type=CASAuthenticationService"
+ xmbean-dd=""
+ xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean">
+ <xmbean/>
+ <depends>portal:service=Module,type=IdentityServiceController</depends>
+ <attribute name="HavingRole"></attribute>
+</mbean>
+ ]]>
+ </programlisting>
+ This will expose special service in JBoss Portal that can be leveraged
by CAS AuthenticationHandler if the server is deployed on the same
+ application server instance. This AuthenticationHandler will be enabled
in next 2 steps.
+ </listitem>
+ <listitem>
+ Edit
<emphasis>$JBOSS_HOME/server/default/deploy/cas.war/WEB-INF/deployerConfigContext.xml</emphasis>
and add following line in the
+ <emphasis>authenticationHandlers</emphasis> section:
+ <programlisting>
+ <![CDATA[
+<bean class="org.jboss.portal.identity.sso.cas.CASAuthenticationHandler"
/>
+ ]]>
+ </programlisting>
+ This can replace default
<emphasis>SimpleTestUsernamePasswordAuthenticationHandler</emphasis> so whole
part of this config file can look
+ as follows:
+ <programlisting>
+ <![CDATA[
+<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">
+ <property
+ name="httpClient"
+ ref="httpClient" />
+ </bean>
+
+ <!--
+ | 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.jboss.portal.identity.sso.cas.CASAuthenticationHandler"
/>
+ </list>
+</property>
+ ]]>
+ </programlisting>
+ </listitem>
+ <listitem>
+ Copy portal-identity-lib.jar and portal-identity-sso-lib.jar files
from
+
<emphasis>$JBOSS_HOME/server/default/deploy/jboss-portal.sar/lib</emphasis> to
+
<emphasis>$JBOSS_HOME/server/default/deploy/cas.war/WEB-INF/lib</emphasis>.
+ </listitem>
+ </orderedlist>
+ </para>
+ <para>
+ To test the integration:
+ <itemizedlist>
+ <listitem>Go to your portal. Typically,
http://localhost:8080/portal</listitem>
+ <listitem>Click on the "Login" link on the main portal
page</listitem>
+ <listitem>This should bring up the CAS Authentication Server's
login screen instead of the default JBoss Portal login screen</listitem>
+ <listitem>Input your portal username and password. For built-in
portal login try user:user or admin:admin</listitem>
+ <listitem>If login is successfull, you should be redirected back to
the portal with the appropriate user logged in</listitem>
+ </itemizedlist>
+ </para>
+ </sect2>
+ </sect1>
+
</chapter>