[portal-commits] JBoss Portal SVN: r8153 - docs/trunk/referenceGuide/en/modules.

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&gt;sshah(a)redhat.com&lt;/email&gt; + </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>