JBoss® Portal 2.7.2

You must have instance JBoss Portal 2.7 deployed on JBoss AS or JBoss EAP. Description of how to do this is out of scope of this document. You should read Chapter 2 of reference guide if you are in trouble.

In rest of this scenario, we assume that $JBOSS_HOME is the location when your JBoss AS is located and JBoss Portal is deployed on default configuration of your JBoss AS.

Download CAS (version 3.0.7). You can simply download it from http://www.jasig.org/cas/download. Once you have ZIP archive you can unpack it. You will find cas.war file in target directory of your unpacked ZIP archive. It is good idea to unpack this cas.war file to some location to your computer. We assume that you unpack it to /tmp/cas.war directory in rest of this guide. The reason of this is necessity of configuring content of cas.war before we can deploy it to JBoss AS. And it's easier to edit content of directory than content of archive.

You have to copy two JAR libraries from $JBOSS_HOME/server/default/deploy/jboss-portal.sar/lib directory to /tmp/cas.war/WEB-INF/lib directory. The first file is portal-identity-lib.jar and second is portal-identity-sso-lib.jar.

Add this line:

<bean class="org.jboss.portal.identity.sso.cas.CASAuthenticationHandler" />

into file /tmp/cas.war/WEB-INF/deployerConfigContext.xml instead of this line:

<bean class="org.jasig.cas.authentication.handler.support. SimpleTestUsernamePasswordAuthenticationHandler" />

Authentication handler is very important component of CAS server configuration, because it is used to authenticate users. If you will use org.jboss.portal.identity.sso.cas.CASAuthenticationHandler, you will be able to authenticate against CAS server with same credentials as against JBoss Portal, which is deployed on same host.

Add the CAS mbean configuration to $JBOSS_HOME/server/default/deploy/jboss-portal.sar/META-INF/jboss-service.xml file. You have to add this to some place inside server element.

                  
<!-- CAS -->
<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>
                  
                  

Edit $JBOSS_HOME/server/default/deploy/jboss-portal.sar/portal-server.war/WEB-INF/context.xml. Uncomment CAS valve and edit it as follows:

                  
<Valve className="org.jboss.portal.identity.sso.cas.CASAuthenticationValve"
   	casLogin="http://localhost:8080/cas/login"
   	casLogout="http://localhost:8080/cas/logout"
   	casValidate="http://localhost:8080/cas/serviceValidate"
   	casServerName="localhost:8080"
   	authType="FORM"
/>
                 
                  

Little description of attributes:

Go to http://repository.jboss.com/cas/3.0.7/lib/. Download the file casclient-lenient.jar and copy it to $JBOSS_HOME/server/default/deploy/jboss-portal.sar/lib/ directory.

Make sure to use casclient-lenient.jar and not casclient.jar in this step. You have to use casclient-lenient.jar if you use CAS server with HTTP protocol. Another reason is that you are using CAS server with HTTPS protocol but the SSL certificate you are using is not trusted by your Java implementation (or more exactly by the Java process under which JBoss AS with JBoss Portal is running). The more will be said later in this document.

Deploy cas.war into server. This can be donne simply by copying /tmp/cas.war directory into $JBOSS_HOME/server/default/deploy directory.

Go to $JBOSS_HOME/bin directory and start the default configuration of JBoss AS.

When server is started, you can go to http://localhost:8080/portal and try to click to Login link. You shoud be redirected to CAS login screen in http://localhost:8080/cas/login. Now you are able to login with same user credentials as to the JBoss Portal itself without CAS integration. So you can try username/password:admin/admin or user/user if you are using fresh instance of JBoss Portal without any other users created. After successfull login, you should be redirected to JBoss Portal default page and you should see sign Logged in as: admin or Logged in as: user in right up corner.

Now you must secure your JBoss AS instance with CAS (The default instance in our case) if you want to use HTTPS protocol. The first think you need is the SSL certificate your server will use. For production use, it's very suitable if you have SSL certificate from some well-known certification authority, especially if you want to use your host in public environment (not only Intranet in your company). For testing purposes is sufficient that we have only self-signed certificate which can be created by simple tool called keytool. This tool is standard part of Sun Java JDK environment.

So go to your $JBOSS_HOME/server/default/conf directory and generate self-signed certificate by running command:

                  
keytool -genkey -alias jbosskey -keypass changeit -keyalg RSA -keystore server.keystore
                
                  

You have to use password changeit as the answer for the first question. It's good that the keystore password is the same like key password, which is specified by option keypass in command line. The second question is What is your first and last name and you should write the fully-qualified name of your host as answer to this question. For our purposes, it's sufficient if you use value localhost. Other values are not important for our testing purposes and you can fill defacto anythink you want. After all questions are answered by you and the command is finished, you should see file server.keystore in your $JBOSS_HOME/server/default/conf directory.

You have to enable HTTPS connector for JBoss AS. You can do this by editing file $JBOSS_HOME/server/default/deploy/jboss-web.deployer/server.xml. Uncomment the part with HTTPS connector and edit it as follows:

                  
<Connector port="8443" maxHttpHeaderSize="8192" address="${jboss.bind.address}"
           maxThreads="250" minSpareThreads="25" maxSpareThreads="75"
           enableLookups="false" disableUploadTimeout="true"
           acceptCount="100" scheme="https" secure="true"
           clientAuth="false" sslProtocol="TLS"
           SSLEnabled="true"
           keystoreFile="${jboss.server.home.dir}/conf/server.keystore"
           keystorePass="changeit"
/>

                  

Now you can restart your JBoss AS and then going to https://localhost:8443. You will see the warning that the certificate is not trusted. It's fine because you are using your self-signed certificate and your browser doesn't know this certificate. After accepting all warnings you should see the default JBoss AS page and now you are able to secure your CAS server. You should avoid to use self-signed certificates in production environment, because all user see these warnings in their browsers and they are not due to trust you.

If you have any troubles with SSL, you want to use certificate from well-known certification authority or you want to know more about SSL, you can go to

Configure CASAuthenticationValve in $JBOSS_HOME/server/default/deploy/jboss-portal.sar/portal-server.war/WEB-INF/context.xml file. Edit it as follows:

                  
<Valve className="org.jboss.portal.identity.sso.cas.CASAuthenticationValve"
   	casLogin="https://localhost:8443/cas/login"
   	casLogout="https://localhost:8443/cas/logout"
   	casValidate="https://localhost:8443/cas/serviceValidate"
   	casServerName="localhost:8080"
   	authType="FORM"
/>

                  

You can see that we use HTTPS on port 8443 for all URLs related to CAS. But we are still using localhost:8080 for casServerName. So we will use HTTP while going to JBoss Portal. Only access to CAS is secured.

You should use normal casclient.jar instead of casclient-lenient.jar because we are now using HTTPS with CAS. So go to http://repository.jboss.com/cas/3.0.7/lib/ and download casclient.jar. Copy this file to $JBOSS_HOME/server/default/deploy/jboss-portal.sar/lib directory. Don't forget to remove casclient-lenient.jar from this directory too.

Now you should restart your JBoss AS, but you have to run it with special option -Djavax.net.ssl.trustStore. This Java option is really important because you are saying where is file with certificates, which should be trusted by Java. When your JBoss Portal needs to trust CAS, it's important that JBoss AS instance with JBoss Portal trusts CAS server and so we need to say that our self-signed certificate is trustfull.

The whole command for starting JBoss should look like this:

./run.sh -Djavax.net.ssl.trustStore=$JBOSS_HOME/server/default/conf/server.keystore

When server is started, you can go to http://localhost:8080/portal and try to click to Login link. You shoud be redirected to CAS login screen in https://localhost:8443/cas/login. After successfull login, you should be redirected to JBoss Portal default page on http://localhost:8080/portal/auth/portal/default and you should see sign Logged in as: admin or Logged in as: user in right up corner.

Change ports of both connectors in $JBOSS_HOME/server/default/deploy/jboss-web.deployer/server.xml. HTTP connector should look like this:

                     
<Connector port="80" address="${jboss.bind.address}"    
   maxThreads="250" maxHttpHeaderSize="8192"
   emptySessionPath="true" protocol="HTTP/1.1"
   enableLookups="false" redirectPort="443" acceptCount="100"
   connectionTimeout="20000" disableUploadTimeout="true" 
/>

                  

and HTTPS connector like this:

                     
<Connector port="443" maxHttpHeaderSize="8192" address="${jboss.bind.address}"
	maxThreads="250" minSpareThreads="25" maxSpareThreads="75"
	enableLookups="false" disableUploadTimeout="true"
	acceptCount="100" scheme="https" secure="true"
	clientAuth="false" sslProtocol="TLS"
	SSLEnabled="true"
	keystoreFile="${jboss.server.home.dir}/conf/server.keystore"
	keystorePass="changeit"
/>

                  

Change configuration in $JBOSS_HOME/server/default/deploy/jboss-portal.sar/portal-server.war/WEB-INF/context.xml and edit the CAS Authentication Valve as follows:

                     
<Valve className="org.jboss.portal.identity.sso.cas.CASAuthenticationValve"
   	casLogin="https://localhost/cas/login"
   	casLogout="https://localhost/cas/logout"
   	casValidate="https://localhost/cas/serviceValidate"
   	casServerName="localhost"
   	authType="FORM"
/>

                  

Try to restart JBoss AS. Don't forget that you must be root to this step. In linux system you can do it with this command:

sudo ./run.sh -Djavax.net.ssl.trustStore="$JBOSS_HOME/server/default/conf/server.keystore"

You can use JBoss Portal with HTTPS and go to https://localhost/portal and then login. But now you can use HTTP protocol too and you can successfully login with URL http://localhost/portal. HTTPS protocol is always used for CAS but both HTTP and HTTPS protocols can be used for JBoss Portal if it is configured this way.

Create new virtual hosts on your system and use some different names for them. In this scenario, We willl use names cas-01 and cas-02. On linux systems, it can be donne by add these two lines

                     
127.0.1.4       cas-01
127.0.1.5       cas-02

                  

to your /etc/hosts file. You must have root privileges to do this. If you don't have root privileges, than you have to use IP addresses instead of host names in rest of this tutorial (For example: Running of JBoss Portal can be performed by ./run.sh -c cas-01 -b 127.0.1.4 instead of ./run.sh -c cas-01 -b cas-01. You must use IP addresses in your configuration files too.).

Create JBoss AS configuration called cas-01 and deploy JBoss Portal and CAS to it. We pressume that you did previous scenario 1.3 and you have JBoss Portal with CAS properly configured in your default configuration. So only think you have to do is copy your default configuration to new cas-01 configuration. This can be donne with command

                     
cp -r $JBOSS_HOME/server/default $JBOSS_HOME/server/cas-01

                  

on linux systems.

Create JBoss AS configuration called cas-02 and deploy JBoss Portal to it. You can do it by copying cas-01 configuration to new cas-02 configuration and then you can undeploy CAS from cas-02 configuration because you doesn't need CAS server in cas-02. JBoss Portal from cas-02 will be configured against CAS server on cas-01. You can do both thinks on linux systems this way:

                     
cp -r $JBOSS_HOME/server/cas-01 $JBOSS_HOME/server/cas-02
rm -rf $JBOSS_HOME/server/cas-02/deploy/cas.war

                  

You should generate new self-signed certificate for host cas-01 because previous certificate was CN attribute with value localhost. Now we will use host cas-01 for this configuration, so we have to generate new certificate with CN value cas-01.

So go to directory $JBOSS_HOME/server/cas-01/conf and delete file server.keystore if one is here. Now you should generate new certificate with usage of command

                     
keytool -genkey -alias jbosskey -keypass changeit -keyalg RSA -keystore server.keystore

                  

Answer changeit as value for keystore password and answer cas-01 as answer for question about your first and second name. Other answers are not so important.

Go to $JBOSS_HOME/server/cas-02/conf directory and do the same with certificate for cas-02 host. CN attribute should have value cas-02 for this configuration.

Configure CAS Authentication Valve in cas-01 JBoss AS configuration. You can do it by edit $JBOSS_HOME/server/cas-01/deploy/jboss-portal.sar/portal-server.war/WEB-INF/context.xml this way:

                     
<Valve className="org.jboss.portal.identity.sso.cas.CASAuthenticationValve"
   	casLogin="https://cas-01/cas/login"
   	casLogout="https://cas-01/cas/logout"
   	casValidate="https://cas-01/cas/serviceValidate"
   	casServerName="cas-01"
   	authType="FORM"
/>

                  

The important think is, that your HTTP connector must listen on port 80 and your HTTPS connector on port 443 if you want to configure CAS server this way. Look to 1.3 if you are not sure how to configure ports correctly. If you did 1.3 scenario before, than you have ports configured correctly and you won't care about it.

Configure CAS Authentication Valve in cas-02 JBoss AS configuration. You can do it by edit $JBOSS_HOME/server/cas-02/deploy/jboss-portal.sar/portal-server.war/WEB-INF/context.xml this way:

                     
<Valve className="org.jboss.portal.identity.sso.cas.CASAuthenticationValve"
   	casLogin="https://cas-01/cas/login"
   	casLogout="https://cas-01/cas/logout"
   	casValidate="https://cas-01/cas/serviceValidate"
   	casServerName="cas-02"
   	authType="FORM"
/>

                  

Start JBoss AS with cas-01 configuration and bind it to host cas-01.

                     
sudo ./run.sh -c cas-01 -b cas-01 -Djavax.net.ssl.trustStore="$JBOSS_HOME/server/cas-01/conf/server.keystore"

                  

Start JBoss AS with cas-02 configuration and bind it to host cas-02.

                     
sudo ./run.sh -c cas-02 -b cas-02 -Djavax.net.ssl.trustStore="$JBOSS_HOME/server/cas-01/conf/server.keystore"

                  

The parameter javax.net.ssl.trustStore remains in the same location as in cas-01 because you have to trust to SSL certificate which CAS server is using. And that is the certificate from cas-01 configuration.

Try SSO in action. Go to http://cas-01/portal and click to login link. You should be redirected to CAS login page on http://cas-01/cas/login. After login and validating of your credentials, you should be logged and after that you are redirected back to portal on http://cas-01/portal/auth/portal/default. Now try second JBoss Portal on cas-02 host. Go to http://cas-02/portal and click to login link. You are redirected directly to http://cas-02/portal/auth/portal/default without need of filling any credentials. You can see that you are logged on cas-02 with same user as on cas-01. The CAS will grant ticket to second portal automatically because CAS cookie is set with information, that you were logged before.

Download CASIntegrationExampleApp from URL ...TODO... and go to the dir with this application.

You have to edit build.properties file according to your path where you have JBoss AS. Assuming that you will use cas-02 JBoss configuration to deploy the application. So you have property jboss.app.deploy.dir configured as follows:

                     
jboss.app.deploy.dir=${jboss.home}/server/cas-02/deploy

                  

CASIntegrationExampleApp is very small web application with only one servlet. Only important think is, that this application is configured to use CAS for authentication. The configuration is performed by adding CAS Filer to the CASIntegrationExampleApp/WEB_INF/web.xml file. The whole configuration of CAS Filter looks as follows:

                     
	<filter>
		<filter-name>CAS Filter</filter-name>
		<filter-class>edu.yale.its.tp.cas.client.filter.CASFilter</filter-class>
		<init-param>
			<param-name>edu.yale.its.tp.cas.client.filter.loginUrl</param-name>
			<param-value>https://cas-01/cas/login</param-value>
		</init-param>
		<init-param>
			<param-name>edu.yale.its.tp.cas.client.filter.validateUrl</param-name>
			<param-value>https://cas-01/cas/serviceValidate</param-value>
		</init-param>
		<init-param>
			<param-name>edu.yale.its.tp.cas.client.filter.serverName</param-name>
			<param-value>cas-02</param-value>
		</init-param>	
		<init-param>
			<param-name>edu.yale.its.tp.cas.client.filter.wrapRequest</param-name>
			<param-value>true</param-value>
		</init-param>		
	</filter>

	<filter-mapping>
		<filter-name>CAS Filter</filter-name>
		<url-pattern>/*</url-pattern>
	</filter-mapping>	

                  

Little description of init parameters:

You can casify your own applications in very similar way. If you are more interested about configuration of CAS Filter, you can go to http://www.ja-sig.org/wiki/display/CASC/Using+CASFilter.

The class edu.yale.its.tp.cas.client.filter.CASFilter is part of casclient.jar which we used in previous part of this document. Make sure that you have access to this library in your applications.

If you are in directory with CASInterationExampleApp you have to call

                     
ant all

                  

and the application will be deployed to cas-02 server.

Once application is deployed, you can go to http://cas-02/CASIntegrationExampleApp and you should be redirected to CAS login screen. You have to login with same credentials as to Jboss Portal in cas-01 server. Once you are logged, you will be redirected to sample servlet and the name of the authenticated user will be shown.

Go to http://cas-02/portal and click to login link. Now you can see that you are authenticated directly to JBoss Portal without redirecting to CAS.

Go to http://cas-01/portal and click to login link. You should be redirected directly to this portal too.

Create new virtual hosts on your system and use some different names for them. In this scenario, We will use names portal-host and cas-host. On linux systems, it can be donne by add these two lines

                     
127.0.1.6       portal-host
127.0.1.7       cas-host

                  

to your /etc/hosts file. You must have root privileges to do this. If you don't have root privileges, than you have to use IP addresses instead of host names in rest of this tutorial. In later text, cas-host will be a host where CAS server will be deployed and portal-host will be the host where JBoss Portal will be deployed.

Take a fresh JBoss AS or JBoss EAP (for example JBoss-4.2.3.GA is a good). Then create new configuration called cas-conf where CAS will be deployed. You can use this command in linux:

                     
cp -r $JBOSS_HOME/server/default $JBOSS_HOME/server/cas-conf

                  

Deploy JBoss Portal 2.7.2 to the default configuration of JBoss AS. We assume that you use Mysql database on localhost. So your datasource could look like this:

                     
<datasources>
  <local-tx-datasource>
    <jndi-name>PortalDS</jndi-name>
    <connection-url>jdbc:mysql://localhost/jboss_portal?jdbcCompliantTruncation=false
    </connection-url>
    <driver-class>com.mysql.jdbc.Driver</driver-class>
    <user-name>jboss_portal</user-name>
    <password>password</password>
  </local-tx-datasource>
</datasources>       

                  

You can use any other database than Mysql. Only important think is, that you must configure CAS against the same database as JBoss Portal in later steps of this scenario. You can read Chapter 2 of portal reference guide if you have some troubles with deploying JBoss Portal configured against custom datasource.

Configure CAS authentication valve in $JBOSS_HOME/server/default/deploy/jboss-portal.sar/portal-server.war/WEB-INF/context.xml

                     
<Valve className="org.jboss.portal.identity.sso.cas.CASAuthenticationValve"
       casLogin="http://cas-host:8080/cas/login"
       casLogout="http://cas-host:8080/cas/logout"
       casValidate="http://cas-host:8080/cas/serviceValidate"
       casServerName="portal-host:8080"
       authType="FORM"
/>     

                  

Download casclient-lenient.jar from http://repository.jboss.com/cas/3.0.7/lib/ and copy it to $JBOSS_HOME/server/default/deploy/jboss-portal.sar/lib/ directory. If you want to use casclient.jar you have to configure CAS with usage of HTTPS. Go to 1.2 scenario for more informations.

We assume that you have fresh instance of CAS in /tmp/cas.war directory. You have to add following jars to /tmp/cas.war/WEB-INF/lib directory.

Configure CAS against the same database which is used by JBoss Portal. The information about portal users is standardly saved in table jbp_users. Column with username is jbp_uname and column with password is jbp_password. Passwords are hashed by MD5 algorithm.

You have to open /tmp/cas.war/WEB-INF/deployerConfigContext.xml and configure it properly:

Deploy CAS into cas-conf configuration.

                           
cp -r /tmp/cas.war $JBOSS_HOME/server/cas-conf/deploy/
                         

Start both configurations of JBoss AS and bind them to different hosts. First the default configuration with JBoss Portal:

                           
./run.sh -c default -b portal-host
                         

and then cas-conf configuration with CAS server.

                           
./run.sh -c cas-conf -b cas-host
                         

You must have JBoss Portal 2.7 deployed on JBoss AS (version 4.2.2 or 4.2.3) or JBoss EAP. Description of how to do this is out of scope of this document. You should read Chapter 2 of reference guide if you are in trouble.

In rest of this scenario, we assume that $JBOSS_HOME is the location when your JBoss AS is located and JBoss Portal is deployed on default configuration of your JBoss AS.

Start JBoss server and stop it after the full start. This is necessary because of correct initialization of CMS.

Download josso-1.8.0.zip from http://www.josso.org and unzip it to some location on your computer. We assume /tmp/josso-1.8.0 in rest of this document.

Install JOSSO gateway and JOSSO agent to your default configuration of JBoss Portal. Gateway is the core component of JOSSO which acts as the web console and makes the authentication. Gateway is identity provider. JOSSO agent is somethink like listener, which redirects authentication requests to JOSSO gateway. Agent needs to be deployed in same instance like JBoss Portal.

In our case we use only one configuration for both JBoss Portal and JOSSO. So both gateway and agent will be deployed to the default configuration. Installation could be performed with josso-gsh, which you can run by command:

/tmp/josso-1.8.0/bin/josso-gsh
                  

Now you can install gateway and agent to your JBoss AS with command:

gateway install --target $JBOSS_HOME --jboss-instance default --platform jb42
agent install --target $JBOSS_HOME --jboss-instance default --platform jb42
                  

It's possible that you see error about missing DTD document during agent installation. But you can ignore this error. The important assumption is that you have JBoss AS version 4.2.

You have to copy two JAR libraries from $JBOSS_HOME/server/default/deploy/jboss-portal.sar/lib directory to $JBOSS_HOME/server/default/deploy/josso.war/WEB-INF/lib directory. The first file is portal-identity-lib.jar and second is portal-identity-sso-lib.jar.

Uncomment JOSSO logout valve from $JBOSS_HOME/server/default/deploy/jboss-portal.sar/portal-server.war/WEB-INF/context.xml:

<Valve className="org.jboss.portal.identity.sso.josso.JOSSOLogoutValve"/>
                  

Edit $JBOSS_HOME/server/default/deploy/jboss-portal.sar/META-INF/jboss-service.xml and add JOSSOIdentityService mbean to configuration:

<!-- JOSSO -->
<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>

                     
                  

Edit $JBOSS_HOME/server/default/deploy/jboss-portal.sar/portal-server.war/login.jsp. This file should be used for redirecting to JOSSO and only this content should be inside of this file:

<%@page contentType="text/html; charset=iso-8859-1" language="java" session="true" %>
<%
    response.sendRedirect(request.getContextPath() + "/josso_login/");
%>

                        

Other stuff could be commented or deleted.

Add this application policy to the file $JBOSS_HOME/server/default/conf/login-config.xml:

<application-policy name="josso">            
  <authentication>
      <login-module code="org.jboss.portal.identity.sso.josso.JOSSOLoginModule" flag="required">
         <module-option name="debug">true</module-option>
      </login-module>
  </authentication>
</application-policy>


                        

Change the portal security domain to josso in $JBOSS_HOME/server/default/deploy/jboss-portal.sar/portal-server.war/WEB-INF/jboss-web.xml by edit the line with security domain:

<security-domain>java:jaas/josso</security-domain>
                        

Add the file $JBOSS_HOME/server/default/conf/josso-gateway-portal-stores.xml with this content:

<s:beans xmlns:s="http://www.springframework.org/schema/beans"
       xmlns:portal-istore="urn:org:jboss:portal:josso:identitystore"
       xmlns:memory-sstore="urn:org:josso:memory:sessionstore"
       xmlns:memory-astore="urn:org:josso:memory:assertionstore"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd        
        urn:org:josso:memory:sessionstore http://www.josso.org/schema/josso-memory-sessionstore.xsd
        urn:org:josso:memory:assertionstore http://www.josso.org/schema/josso-memory-assertionstore.xsd
        ">
    <!-- ===================================================================== -->
    <!-- JOSSO Identity Store, the id is very important because it is          -->
    <!-- referenced by the identity manager, auth schemes and who knows where  -->
    <!-- else.                                                                 -->
    <!-- ===================================================================== -->
    <portal-istore:portal-store id="josso-identity-store" s:scope="singleton"/>                            

    <!-- ===================================================================== -->
    <!-- JOSSO Session Store, the id is very important because it is           -->
    <!-- referenced by the session manager and who knows where else            -->
    <!-- ===================================================================== -->
    <memory-sstore:memory-store id="josso-session-store"/>

    <!-- ===================================================================== -->
    <!-- JOSSO Assertion Store, the id is very important because it is         -->
    <!-- referenced by the assertion manager and who knows where elese         -->
    <!-- ===================================================================== -->
    <memory-astore:memory-store id="josso-assertion-store"/>
</s:beans>

                        

Edit $JBOSS_HOME/server/default/conf/josso-gateway-config.xml file. It's the main configuration file of JOSSO gateway. You have to change two thinks in the file.

Edit $JBOSS_HOME/server/default/conf/josso-gateway-auth.xml and uncomment bind authentication scheme:

<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
<!-- BIND Authentication Scheme (normally LDAP) -->
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
<!-- Requires a be a bindalble credential store ! -->
<!-- name attribute is important and must not be changed -->
<bind-authscheme:bind-auth-scheme
         id="josso-bind-authentication"
         name="basic-authentication"
         hashAlgorithm="MD5"
         hashEncoding="HEX"
         ignorePasswordCase="false"
         ignoreUserCase="false">


     <bind-authscheme:credentialStore>
         <s:ref bean="josso-identity-store"/>
     </bind-authscheme:credentialStore>

     <bind-authscheme:credentialStoreKeyAdapter>
         <s:ref bean="josso-simple-key-adapter"/>
     </bind-authscheme:credentialStoreKeyAdapter>
</bind-authscheme:bind-auth-scheme>
                    
                  

Edit $JBOSS_HOME/server/default/conf/josso-agent-config.xml and edit it for usage with JBoss Portal application. You should have this content inside your <agent:partner-apps> element.

<agent:partner-apps>
   <agent:partner-app id="jboss_portal" context="/portal"/>
</agent:partner-apps>

                   

All other partner-apps can be commented out or deleted unless you want to use other applications with JOSSO.

Add -Dorg.apache.commons.logging.LogFactory=org.apache.commons.logging.impl.LogFactoryImpl option to your JAVA_OPTS environment variable. The most simple way is to add the line

JAVA_OPTS="$JAVA_OPTS -Dorg.apache.commons.logging.LogFactory=org.apache.commons.logging.impl.LogFactoryImpl"
                  

to your $JBOSS_HOME/bin/run.sh file. (Some place before Display our environment section).

Start JBoss again and now you should be able to test the integration. Go to http://localhost:8080/portal and click to login link. You should be redirected to josso gateway web console. You should be able to login with your portal credentials (for example: admin/admin or user/user). After login, you should be redirected back to Portal and be logged into portal.

You have to enable HTTPS in your default configuration, where is JBoss Portal and JOSSO deployed. You should go through steps 1, 2, 3 of CAS guide - section 1.2.

Now only think you have to change is securing access to gateway and web services in file $JBOSS_HOME/server/default/conf/josso-agent-config.xml:

<!-- Gateway LOGIN and LOGOUT URLs -->
<gatewayLoginUrl>https://localhost:8443/josso/signon/login.do</gatewayLoginUrl>
<gatewayLogoutUrl>https://localhost:8443/josso/signon/logout.do</gatewayLogoutUrl>

<!-- Gateway service locator -->
<gatewayServiceLocator>
    <!-- Other properties for ws-service-locator :
     username, password, servicesWebContext, transportSecurity
   -->
   <protocol:ws-service-locator endpoint="localhost:8443" transportSecurity="confidential" />
</gatewayServiceLocator>

Now you should restart your JBoss AS, but you have to run it with special option -Djavax.net.ssl.trustStore. This Java option is really important because you are saying where is file with certificates, which should be trusted by Java. This is needed for correct usage of secured communication between web services.

The whole command for starting JBoss should look like this:

./run.sh -Djavax.net.ssl.trustStore=$JBOSS_HOME/server/default/conf/server.keystore

When server is started, you can go to http://localhost:8080/portal and try to click to Login link. You shoud be redirected to JOSSO login screen and you can see that HTTPS is used for accessing JOSSO gateway. After successfull login, you should be redirected to JBoss Portal default page on http://localhost:8080/portal/auth/portal/default and you should see sign Logged in as: admin or Logged in as: user in right up corner.

You can also use HTTPS for accessing JBoss Portal. HTTPS can be used on both sides of communication - on JBoss Portal side and on JOSSO side too.

Create new virtual hosts on your system and use some different names for them. In this scenario, We willl use names josso-01 and josso-02. On linux systems, it can be donne by add these two lines

127.0.1.2       josso-01
127.0.1.3       josso-02
              

to your /etc/hosts file. You must have root privileges to do this. If you don't have root privileges, than you have to use IP addresses instead of host names in rest of this tutorial (For example: Running of JBoss Portal can be performed by ./run.sh -c josso-01 -b 127.0.1.2 instead of ./run.sh -c josso-01 -b josso-01. You must use IP addresses in your configuration files too.).

Create JBoss AS configuration called josso-01 and deploy JBoss Portal and JOSSO to it. We assume that you did previous scenario 2.2 and you have JBoss Portal with JOSSO properly configured in your default configuration. So only think you have to do is copy your default configuration to new josso-01 configuration. This can be donne with command

                     
cp -r $JBOSS_HOME/server/default $JBOSS_HOME/server/josso-01

                  

on linux systems.

Create JBoss AS configuration called josso-02 and deploy JBoss Portal to it. It's good to start josso-02 (before installing of JOSSO agent) first without -Dorg.apache.commons.logging.LogFactory option to properly initialization of CMS. Then you can stop it. And then we will configure this portal to authenticate against JOSSO on josso-01 host.

We need to deploy JOSSO agent to josso-02 configuration. You can use josso-gsh in similar way, described in 2.1 - point 4. Only change is, that you will deploy only agent but not gateway. You can install JOSSO agent with command:

agent install --target $JBOSS_HOME --jboss-instance josso-02 --platform jb42

You should configure your JBoss Portal on josso-02 to authentication with JOSSO server on josso-01. Do steps 6, 8, 9, 10 of 2.1 scenario in josso-02 configuration.

Configure JOSSO agent on josso-02 against JOSSO gateway on josso-01. Edit $JBOSS_HOME/server/josso-02/conf/josso-agent-config.xml and edit it for usage with JBoss Portal application. You should have this content inside your <agent:partner-apps> element.

<agent:partner-apps>
   <agent:partner-app id="jboss_portal" context="/portal"/>
</agent:partner-apps>

And gateway should be configured this way:

<!-- Gateway LOGIN and LOGOUT URLs -->
<gatewayLoginUrl>https://josso-01:8443/josso/signon/login.do</gatewayLoginUrl>
<gatewayLogoutUrl>https://josso-01:8443/josso/signon/logout.do</gatewayLogoutUrl>

<!-- Gateway service locator -->
<gatewayServiceLocator>
   <!-- Other properties for ws-service-locator :
    username, password, servicesWebContext, transportSecurity
   -->
   <protocol:ws-service-locator endpoint="josso-01:8443" transportSecurity="confidential" />
</gatewayServiceLocator>

You should generate new self-signed certificate for host josso-01 because previous certificate was CN attribute with value localhost. Now we will use host josso-01 for this configuration, so we have to generate new certificate with CN value josso-01.

So go to directory $JBOSS_HOME/server/josso-01/conf and delete file server.keystore if one is here. Now you should generate new certificate with usage of command

keytool -genkey -alias jbosskey -keypass changeit -keyalg RSA -keystore server.keystore

Answer changeit as value for keystore password and answer josso-01 as answer for question about your first and second name. Other answers are not so important.

For secure communication between Web services on josso-01 side (gateway) and josso-02 (agent) you need to enable SSL in josso-02 too. You should go through steps 1, 2, 3 of CAS guide - section 1.2 but you have to use josso-02 instead of default configuration and you should use CN name josso-02 during certificate generation with keytool.

Configure JOSSO agent on josso-01 against JOSSO gateway on josso-01. Edit $JBOSS_HOME/server/josso-01/conf/josso-agent-config.xml and edit it properly:

<!-- Gateway LOGIN and LOGOUT URLs -->
<gatewayLoginUrl>https://josso-01:8443/josso/signon/login.do</gatewayLoginUrl>
<gatewayLogoutUrl>https://josso-01:8443/josso/signon/logout.do</gatewayLogoutUrl>

<!-- Gateway service locator -->
<gatewayServiceLocator>
   <!-- Other properties for ws-service-locator :
    username, password, servicesWebContext, transportSecurity
   -->
   <protocol:ws-service-locator endpoint="josso-01:8443" transportSecurity="confidential" />
</gatewayServiceLocator>

Run josso-01 configuration and bind it to josso-01 host.

./run.sh -c josso-01 -b josso-01 -Djavax.net.ssl.trustStore=$JBOSS_HOME/server/josso-01/conf/server.keystore

Run josso-02 configuration and bind it to josso-02 host. You have to trust certificate from josso-01 host.

./run.sh -c josso-02 -b josso-02 -Djavax.net.ssl.trustStore=$JBOSS_HOME/server/josso-01/conf/server.keystore

Test SSO. Go to http://josso-01:8080/portal and click to login link. You should be redirected to JOSSO login page on https://josso-01:8443/josso/signon/login.do?josso_back_to=http://josso-01:8080/portal/josso_security_check. Then you can check Remember me checkbox. After login and validating of your credentials, you should be logged and after that you are redirected back to portal on http://josso-01:8080/portal/auth/portal/default. Now try second JBoss Portal on josso-02 host. Go to http://josso-02:8080/portal and click to login link. You are redirected directly to http://josso-02:8080/portal/auth/portal/default without need of filling any credentials. You can see that you are logged on josso-02 with same user as on josso-01.

Install sample partner JOSSO application. You can use josso-gsh in similar way, described in 2.1 - point 4. You can install JOSSO partner application with command:

samples install --target $JBOSS_HOME --jboss-instance josso-01 --platform jb42

Enable your applications in $JBOSS_HOME/server/josso-01/conf/josso-agent-config.xml file:

<agent:partner-apps>
   <agent:partner-app id="jboss_portal" context="/portal"/>
   <agent:partner-app id="MyPartnerApp1" context="/partnerapp" />
</agent:partner-apps>

Test SSO. Go to http://josso-01:8080/partnerapp and click to login link. You should be redirected to JOSSO login page on https://josso-01:8443/josso/signon/login.do?josso_back_to=http://josso-01:8080/partnerapp/josso_security_check. Then you can check Remember me checkbox. After login and validating of your credentials (you should use same credentials as for login to JBoss Portal), you should be logged and after that you are redirected back to partner application and you can see that you are logged in. You can see that you are in same roles as portal user with same name and you should be in Authenticated role as well.

Now try JBoss Portal. Go to http://josso-01:8080/portal and click to login link. You are redirected directly to http://josso-01:8080/portal/auth/portal/default without need of filling any credentials. You can see that you are logged on josso-01 with same user as in partner application.

Create new virtual hosts on your system and use some different names for them. In this scenario, We will use names portal-host and josso-host. On linux systems, it can be donne by add these two lines

                     
127.0.1.6       portal-host
127.0.1.8       josso-host

                  

to your /etc/hosts file. You must have root privileges to do this. If you don't have root privileges, than you have to use IP addresses instead of host names in rest of this tutorial. In later text, josso-host will be a host where JOSSO server will be deployed (JBoss configuration will be josso-conf) and portal-host will be the host where JBoss Portal will be deployed (default configuration).

Take a fresh JBoss AS or JBoss EAP (JBoss-4.2.3.GA is good). Then create new configuration called josso-conf where JOSSO will be deployed. You can use this command in linux:

                     
cp -r $JBOSS_HOME/server/default $JBOSS_HOME/server/josso-conf

                  

Deploy JBoss Portal 2.7.2 to the default configuration of JBoss AS. We assume that you use Mysql database on localhost. So your datasource could look like this:

<datasources>
  <local-tx-datasource>
    <jndi-name>PortalDS</jndi-name>
    <connection-url>jdbc:mysql://localhost/jboss_portal?jdbcCompliantTruncation=false</connection-url>
    <driver-class>com.mysql.jdbc.Driver</driver-class>
    <user-name>jboss_portal</user-name>
    <password>password</password>
  </local-tx-datasource>
</datasources>

You can use any other database than Mysql. Only important think is, that you must configure JOSSO against the same database as JBoss Portal in later steps of this scenario. You can read Chapter 2 of portal reference guide if you have some troubles with deploying JBoss Portal configured against custom datasource.

Install JOSSO gateway to josso-conf and JOSSO agent to default configuration. Agent should be in same configuration where JBoss Portal is. Run this in josso-gsh:

gateway install --target $JBOSS_HOME --jboss-instance josso-conf --platform jb42
agent install --target $JBOSS_HOME --jboss-instance default --platform jb42

Do steps 6, 8, 9, 10 of Section 2.1, “Integration of JBoss Portal and JOSSO deployed on the same host with usage of HTTP protocol” in default configuration to Jossify JBoss Portal.

Configure JOSSO agent on default against JOSSO gateway on josso-conf. Edit $JBOSS_HOME/server/default/conf/josso-agent-config.xml and edit it for usage with JBoss Portal application. You should have this content inside your <agent:partner-apps> element.

<agent:partner-apps>
   <agent:partner-app id="jboss_portal" context="/portal"/>
</agent:partner-apps>

And gateway should be configured this way:

<!-- Gateway LOGIN and LOGOUT URLs -->
<gatewayLoginUrl>http://josso-host:8080/josso/signon/login.do</gatewayLoginUrl>
<gatewayLogoutUrl>http://josso-host:8080/josso/signon/logout.do</gatewayLogoutUrl>

<!-- Gateway service locator -->
<gatewayServiceLocator>
   <!-- Other properties for ws-service-locator :
    username, password, servicesWebContext, transportSecurity
   -->
   <protocol:ws-service-locator endpoint="josso-host:8080" />
</gatewayServiceLocator>

Now we need to configure JOSSO gateway properly. First edit $JBOSS_HOME/server/josso-conf/conf/josso-gateway-config.xml and uncomment josso-db-stores.xml in Stores section:

<!-- Identity, Session and Assertion Stores configuration -->

<!--<s:import resource="josso-gateway-memory-stores.xml" />-->
<s:import resource="josso-gateway-db-stores.xml" />
<!--<s:import resource="josso-gateway-ldap-stores.xml" />-->

In Authenticator section, you should uncomment basic authentication and others could be commented out:

<!-- ===================================================================== -->
<!-- SSO Authenticator, all authentication schemes must be configured here -->
<!-- ===================================================================== -->
<def-auth:authenticator id="josso-authenticator">
  <def-auth:schemes>	    
     <!--<s:ref bean="josso-bind-authentication"/>-->
     
     <s:ref bean="josso-basic-authentication"/>
     <!--<s:ref bean="josso-strong-authentication"/>
     <s:ref bean="josso-rememberme-authentication"/>
     -->
     <!-- Others like NTLM and BIND go here -->
     
  </def-auth:schemes>
</def-auth:authenticator>

Configure JOSSO gateway to authenticate against Database. You should edit $JBOSS_HOME/server/josso-conf/conf/josso-gateway-db-stores.xml. Comment db-istore:datasource-store section and uncomment and properly configure db-istore:jdbc-store. You need to configure database options and couple of SQL queries which are used by josso-db-identity-store:

<!--<db-istore:datasource-store id="josso-identity-store"
     dsJndiName="java:/DefaultDS"
     userQueryString="SELECT NAME FROM JOSSO_USER WHERE LOGIN = ?;"
     rolesQueryString="SELECT ROLE FROM JOSSO_USER_ROLE WHERE LOGIN = ?;"
     credentialsQueryString="SELECT LOGIN AS USERNAME, PASSWORD FROM JOSSO_USER WHERE LOGIN = ?;"
     userPropertiesQueryString="SELECT NAME, VALUE FROM JOSSO_USER_PROPERTY WHERE LOGIN = ?;"
     resetCredentialDml="UPDATE JOSSO_USER SET PASSWORD = ? WHERE LOGIN = ?;"
     relayCredentialQueryString="SELECT LOGIN FROM JOSSO_USER WHERE #?# = ?;" 
/>-->

<db-istore:jdbc-store
            id="josso-identity-store"
            driverName="com.mysql.jdbc.Driver"
            connectionURL="jdbc:mysql://localhost:3306/jboss_portal"
            connectionName="jboss_portal"
            connectionPassword="password"
            userQueryString="SELECT jbp_uname AS NAME FROM jbp_users WHERE jbp_uname = ?;"
            rolesQueryString="SELECT jbp_roles.jbp_name AS ROLE FROM jbp_roles INNER JOIN jbp_role_membership AS jrm ON jrm.jbp_rid = jbp_roles.jbp_rid INNER JOIN jbp_users AS users ON users.jbp_uid = jrm.jbp_uid WHERE users.jbp_uname = ? UNION SELECT 'Authenticated' AS ROLE;"
            credentialsQueryString="SELECT jbp_uname AS USERNAME, jbp_password AS PASSWORD FROM jbp_users WHERE jbp_uname = ?;"
            userPropertiesQueryString="SELECT jbp_name AS NAME, jbp_value AS VALUE FROM jbp_user_prop AS props INNER JOIN jbp_users AS users ON users.jbp_uid = props.jbp_uid WHERE jbp_uname = ?;"
            resetCredentialDml="UPDATE jbp_users SET jbp_password = ? WHERE jbp_uname = ?;"
            relayCredentialQueryString="SELECT jbp_uname AS LOGIN FROM jbp_users WHERE #?# = ?;"
/>

Configure $JBOSS_HOME/server/josso-conf/conf/josso-gateway-auth.xml. Uncomment and edit basic authentication:

<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
<!-- Basic Authentication Scheme                -->
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
<basic-authscheme:basic-auth-scheme
       id="josso-basic-authentication"
       hashAlgorithm="MD5"
       hashEncoding="HEX"
       ignorePasswordCase="false"
       ignoreUserCase="false">

        <basic-authscheme:credentialStore>
            <s:ref bean="josso-identity-store"/>
        </basic-authscheme:credentialStore>

        <basic-authscheme:credentialStoreKeyAdapter>
            <s:ref bean="josso-simple-key-adapter"/>
        </basic-authscheme:credentialStoreKeyAdapter>

    </basic-authscheme:basic-auth-scheme>

Bind authentication should be commented out:

<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
<!-- BIND Authentication Scheme (normally LDAP) -->
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
<!-- Requires a be a bindalble credential store ! -->
<!-- name attribute is important and must not be changed -->
<!--<bind-authscheme:bind-auth-scheme
         id="josso-bind-authentication"
         name="basic-authentication"
         hashAlgorithm="MD5"
         hashEncoding="HEX"
         ignorePasswordCase="false"
         ignoreUserCase="false">


     <bind-authscheme:credentialStore>
         <s:ref bean="josso-identity-store"/>
     </bind-authscheme:credentialStore>

     <bind-authscheme:credentialStoreKeyAdapter>
         <s:ref bean="josso-simple-key-adapter"/>
     </bind-authscheme:credentialStoreKeyAdapter>
</bind-authscheme:bind-auth-scheme>-->

Don't forget to add Mysql JDBC driver to $JBOSS_HOME/server/josso-conf/deploy/josso.war/WEB-INF/lib directory.

Start both configurations of JBoss AS and bind them to different hosts. First the default configuration with JBoss Portal:

./run.sh -c default -b portal-host

and then josso-conf configuration with JOSSO:

./run.sh -c josso-conf -b josso-host