Author: bdaw Date: 2007-09-04 17:54:46 -0400 (Tue, 04 Sep 2007) New Revision: 8156 Modified: docs/trunk/referenceGuide/en/modules/sso.xml Log: JOSSO integration doc Modified: docs/trunk/referenceGuide/en/modules/sso.xml =================================================================== --- docs/trunk/referenceGuide/en/modules/sso.xml 2007-09-04 21:51:32 UTC (rev 8155) +++ docs/trunk/referenceGuide/en/modules/sso.xml 2007-09-04 21:54:46 UTC (rev 8156) @@ -89,16 +89,16 @@ </security-role>]]> </programlisting> <para>This will secure <emphasis>jmx-console</emphasis> web application using BASIC browser authentication and restrict access for - users with <emphasis>Admin</emphasis> role only.</para> + users with <emphasis>Admin</emphasis> role only.</para> </listitem> <listitem> <para> Edit <emphasis>$JBOSS_HOME/server/default/conf/props/jmx-console-roles.properties</emphasis> file and make it contain: </para> - <programlisting> - <![CDATA[ + <programlisting> + <![CDATA[ admin=JBossAdmin,HttpInvoker,Admin]]> - </programlisting> + </programlisting> <para> This file is a simple identity store for this web application authentication. It will make user <emphasis>admin</emphasis> belongs to <emphasis>Admin</emphasis> role. </para> @@ -130,7 +130,7 @@ Edit <emphasis>$JBOSS_HOME/server/default/deploy/jbossweb-tomcat55.sar/server.xml</emphasis> file and uncomment following line: <programlisting> - <![CDATA[ + <![CDATA[ <Valve className=’org.apache.catalina.authenticator.SingleSignOn’/>]]> </programlisting> </para> @@ -144,14 +144,14 @@ be asked for credentials when accessing <emphasis>jmx-console</emphasis>. This should work in both directions. </para> <note>Please note that in this example <emphasis>jmx-console</emphasis> uses <emphasis>BASIC</emphasis> authentication method. - This means that user credentials are cached on the client side by browser and passed on each request. Once authenticated to clear - authentication cache you may need to restart browser.</note> + This means that user credentials are cached on the client side by browser and passed on each request. Once authenticated to clear + authentication cache you may need to restart browser.</note> </sect2> </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>... + <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. @@ -159,15 +159,20 @@ 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> + + <orderedlist> + <listitem> + Install CAS server (v 3.0.7). This should be as simple as deploying single <emphasis>cas.war</emphasis> file. + </listitem> + <listitem> + Copy <emphasis>portal-identity-lib.jar</emphasis> and <emphasis>portal-identity-sso-lib.jar</emphasis> 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> + <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" @@ -176,31 +181,31 @@ 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> + </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" @@ -212,22 +217,22 @@ <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> + </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> + This can replace default <emphasis>SimpleTestUsernamePasswordAuthenticationHandler</emphasis> so whole part of this config file can look + as follows: - <programlisting> + <programlisting> <![CDATA[ <property name="authenticationHandlers"> <list> @@ -253,13 +258,163 @@ </list> </property> ]]> + </programlisting> + </listitem> + </orderedlist> + <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> + <sect1> + <title>JOSSO - Java Open Single SignOn</title> + <para>JBoss Portal enables seamless integration with JOSSO server. More details on JOSSO can be found + <ulink url="http://www.josso.org/">here</ulink></para> + <note>The steps below assume that JOSS server and JBoss Portal will be deployed on the same JBoss Application Server instance. + JOSSO 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 JOSSO will need to be configured to authenticate against + same database or LDAP server. Please see JOSSO documentation to learn how to setup it up against proper identity store.</note> + <note>Configuration below assumes that JOSSO is already installed and deployed in the JBoss Application Server. This involves adding proper jar files + into the classpath and altering several configuration files (adding tomcat valves, security realm and specific JOSSO configuration files). + For JBoss setup please refer to JOSSO <ulink url="http://www.josso.org/jboss4-howto.html">documentation&l... + <sect2> + <title>Integration steps</title> + + <para> + <orderedlist> + <listitem> + Copy <emphasis>portal-identity-lib.jar</emphasis> and <emphasis>portal-identity-sso-lib.jar</emphasis> files from + <emphasis>$JBOSS_HOME/server/default/deploy/jboss-portal.sar/lib</emphasis> to + <emphasis>$JBOSS_HOME/server/default/deploy/josso.ear/josso.war/WEB-INF/lib</emphasis>. + </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.josso.JOSSOLogoutValve"/> + ]]> </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>. + Edit <emphasis>$JBOSS_HOME/server/default/config/josso-agent-config.xml</emphasis> and mapping for portal web application: + <programlisting> + <![CDATA[ +<partner-apps> + + ... + + <partner-app> + <context>/portal</context> + </partner-app> + + ... + + </partner-apps> + ]]> + </programlisting> + Complete config file can look as follows: + <programlisting> + <![CDATA[ +<?xml version="1.0" encoding="ISO-8859-1" ?> +<agent> + <class>org.josso.jb4.agent.JBossCatalinaSSOAgent</class> + <gatewayLoginUrl>http://localhost:8080/josso/signon/login.do</gatewayLoginUrl> + <gatewayLogoutUrl>http://localhost:8080/josso/signon/logout.do</gatewayLogoutUrl> + <service-locator> + <class>org.josso.gateway.WebserviceGatewayServiceLocator</class> + <endpoint>localhost:8080</endpoint> + </service-locator> + <partner-apps> + <partner-app> + <context>/partnerapp</context> + </partner-app> + <partner-app> + <context>/portal</context> + </partner-app> + </partner-apps> +</agent> + ]]> + </programlisting> </listitem> + <listitem> + Edit <emphasis>$JBOSS_HOME/server/default/deploy/jboss-portal.sar/portal-server.war/login.jsp</emphasis> and + <emphasis>$JBOSS_HOME/server/default/deploy/jboss-portal.sar/portal-server.war/erros.jsp</emphasis> and uncomment following line: + <programlisting> + <![CDATA[ +<% + response.sendRedirect(request.getContextPath() + "/josso_login/"); +%> + ]]> + </programlisting> + (make sure to remove java style comment '/* */' - not the xml one). + </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.josso.JOSSOIdentityServiceImpl" + name="portal:service=Module,type=JOSSOIdentityService" + xmbean-dd="" + xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> + <xmbean/> + <depends>portal:service=Module,type=IdentityServiceController</depends> +</mbean> + ]]> + </programlisting> + This will expose special service in JBoss Portal that can be leveraged by JOSSO Credential and Identity Stores if the server is deployed on the same + application server instance. + </listitem> + <listitem> + Edit <emphasis>$JBOSS_HOME/server/default/deploy/josso.ear/josso.war/WEB-INF/classes/josso-gateway-config.xml</emphasis> and configure following elements: + <itemizedlist> + <listitem> + <emphasis>Credential Store: </emphasis> + <programlisting> + <![CDATA[ +<authentication-scheme> + <name>basic-authentication</name> + + ... + + <credential-store> + <class>org.jboss.portal.identity.sso.josso.JOSSOIdentityStore</class> + </credential-store> + + ... + +</authentication-scheme> + ]]> + </programlisting> + </listitem> + <listitem> + <emphasis>SSO Identity Store: </emphasis> + <programlisting> + <![CDATA[ +<sso-identity-manager> + + ... + + <sso-identity-store> + <class>org.jboss.portal.identity.sso.josso.JOSSOIdentityStore</class> + </sso-identity-store> + + ... + +</sso-identity-manager> + ]]> + </programlisting> + </listitem> + </itemizedlist> + </listitem> </orderedlist> </para> <para> @@ -267,7 +422,7 @@ <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>This should bring up the JOSSO 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>