Page Operations
Browse SpaceIntroduction
This guide will walk you through the steps needed to upgrade from JOSSO 1.7 deployment to a JOSSO 1.8. We will use tomcat 6.0.18, but all relevant differences considering jboss deployment will be mentioned.
Prerequisites
To upgrade JOSSO installation we will need:
- JDK 1.5: For optimal results, confirm that your JDK version matches a JDK listed at http://java.sun.com/javase/downloads/index_jdk5.jsp
- Tomcat 6.0
- JOSSO 1.8
Removing the gateway
First what we need to do is to remove old gateway installation.
Under apache-tomcat-6.0.18/webapps remove josso.war file and entire josso folder.
To remove josso.ear from JBoss deploy folder, go to <jboss-server>/server/default/deploy.
Removing old configuration files
Before installing gateway and agent, we need to backup and remove old configuration files.
In case of tomcat 6.0, configuration files are located in apache-tomcat-6.0.18/bin folder.
In case of JBoss, configuration files are located in <jboss-server>/server/default/conf folder.
Backup and remove josso-agent-config.xml, josso-config.xml and josso-gateway-config.xml.
Removing the agent and old libraries
Now we need to backup and remove old libraries since they will no longer be used by JOSSO 1.8.
In case of apache tomcat 6.0 we remove them from folder apache-tomcat-6.0.18/lib.
In case of apache tomcat 5.5 and tomcat 5.0 we remove them from folder <tomcat-server>/server/lib.
In case of JBoss 3.2.6+ we remove libraries from folder <jboss-server>/server/default/deploy/jbossweb-tomcat50.sar.
In case of JBoss 4.0, we remove them from folder <jboss-server>/server/default/deploy/jbossweb-tomcat50.sar.
For JBoss 4.2, we will find libraries in folder <jboss-server>/server/default/deploy/jboss-web.deployer.
We need to remove following libraries:
- axis.jar
- commons-beanutils.jar
- commons-codec-1.2.jar
- commons-collections-3.1.jar (in case of tomcat 5.0/5.5 this file resides in <tomcat-server>/common/endorsed)
- commons-configuration-1.1.jar
- commons-digester.jar
- commons-discovery-0.2.jar
- commons-httpclient-3.0-rc2.jar
- commons-lang-2.0.jar
- commons-logging.jar
- commons-modeler.jar
- jaxrpc.jar
- josso-1.7.jar
- josso-common-1.7.jar (in case of tomcat 5.0/5.5 this file resides in <tomcat-server>/common/lib)
- josso-tomcat60-plugin-1.7.jar*
- saaj.jar
- spring-aop-2.0.7.jar
- spring-beans-2.0.7.jar
- spring-context-2.0.7.jar
- spring-core-2.0.7.jar
- spring-jmx-2.0.7.jar
- wsdl4j-1.5.1.jar
- xmldb-common-20030701.jar
- xmldb-xupdate-20040205.jar
* Note: File josso-tomcat60-plugin-1.7.jar is specific for tomcat 6.0 platform. If you are using different platform, file will have name:
josso-<platform-name><platform-version>-plugin-1.7.jar.
In case of JBoss platform, version 3.2.6+, we also need to remove josso-tomcat50-plugin-1.7.jar. For Jboss 4.0 and Jboss 4.2 platforms filename is
josso-tomcat55-plugin-1.7.jar.
Installing JOSSO 1.8 gateway and agent
Next, we need to install JOSSO 1.8 gateway and agent. Tutorial describing installation of JOSSO 1.8 gateway on tomcat 6.0 can be found here: Install JOSSO Gateway - Tomcat 6.0
After that, we need to install JOSSO 1.8 agent. Tutorial for that can be found here: Setup JOSSO Agent - Tomcat 6.0.
For tutorial on installing gateway and agent on other platforms visit Setup.
During installation of gateway and agent, existing configuration files, jaas.conf, setenv.bat, josso-users.xml and josso-credentials.xml are not replaced unless explicitly ordered using --replace option of install command. Files josso-users.xml and josso-credentials.xml will exist only if we were using memory store in our setup.
Configuring new JOSSO installation
In this section we will describe the differences between JOSSO 1.7 and JOSSO 1.8 in wiring and configuring components using authentication scheme as an example.
JOSSO 1.8 is using Spring and XBean to define its own namespaces in order to add semantics to Spring configuration files. Also, JOSSO 1.8 allows us to separate our configuration into several files and wire components through referencing.
If we wanted, for example, to use basic authentication scheme (username/password) and use memory store with it, this is how we did it in JOSSO 1.7 in josso-gateway-config.xml file:
<domain>
...
<authenticator>
...
<authentication-schemes>
<authentication-scheme>
<name>basic-authentication</name>
<class>org.josso.auth.scheme.UsernamePasswordAuthScheme</class>
<hashAlgorithm>MD5</hashAlgorithm>
...
<credential-store>
<class>org.josso.gateway.identity.service.store.MemoryIdentityStore</class>
<credentialsFileName>josso-credentials.xml</credentialsFileName>
</credential-store>
<credential-store-key-adapter>
<class>org.josso.gateway.identity.service.store.SimpleIdentityStoreKeyAdapter</class>
</credential-store-key-adapter>
</authentication-scheme>
...
</authentication-schemes>
...
</authenticator>
...
</domain>
In JOSSO 1.8 if we want to do the same thing, first we will declare basic authentication namespace in josso-gateway-auth.xml and josso-gateway-config.xml:
<s:beans xmlns:s="http://www.springframework.org/schema/beans" xmlns="urn:org:josso:core" xmlns:basic-authscheme="urn:org:josso:basic:authscheme" ... xsi:schemaLocation="urn:org:josso:basic:authscheme http://www.josso.org/schema/josso-basic-authscheme.xsd ...">
Using XBean we are mapping appropriate classes through namespaces. Every class is an element in a given namespace.
After that we will configure basic authentication in josso-gateway-auth.xml:
...
<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>
...
We configured it to use memory identity store as a credential store using referencing. Memory store is declared in josso-gateway-memory-stores.xml:
<s:beans xmlns:s="http://www.springframework.org/schema/beans" xmlns:memory-istore="urn:org:josso:memory:identitystore" xsi:schemaLocation=" ... urn:org:josso:memory:identitystore http://www.josso.org/schema/josso-memory-identitystore.xsd ..."> <memory-istore:memory-store id="josso-identity-store" credentialsFileName="josso-credentials.xml" usersFileName="josso-users.xml" s:scope="singleton" /> ... </s:bean>
After that, all we have to do is to import josso-gateway-auth.xml to josso-gateway-config.xml and reference our basic authentication element from there:
... <s:import resource="josso-gateway-auth.xml"/> ... <def-auth:authenticator id="josso-authenticator"> <def-auth:schemes> <s:ref bean="josso-basic-authentication"/> ... </def-auth:schemes> </def-auth:authenticator> ...
Testing it
Now we can start our server and try these changes.
Using non-JOSSO classes
Since JOSSO 1.8 uses Spring, we can use classes outside of JOSSO 1.8. For example, if we need to send emails, we can declare Spring Mail Sender in josso-gateway-config.xml. To declare it we don't use namespaces, but regular Spring XML syntax:
...
<s:bean id="josso-spring-mailsender" class="org.springframework.mail.javamail.JavaMailSenderImpl">
<s:property name="host" value="mail.mycompany.com"/>
</s:bean>
...
And then we simply reference it from email password distributor declared in josso-gateway-selfservices.xml:
...
<email-password-distributor id="josso-password-distributor"
mail-from="test@example.com"
mail-to-userproperty="email"
mail-subject="JOSSO Password Reset verification e-mail"
template="/passwordVerificationEmail.vm"
xmlns="urn:org:josso:email:passworddistributor">
<mail-sender>
<s:ref bean="josso-spring-mailsender"/>
</mail-sender>
</email-password-distributor>
...