How to upgrade OpenAM

In my previous articles [1] and [2] I explained how to install simple OpenAM architecture. Now I wrote one more article related to this architecture. This article provides detailed steps how to do an upgrade of this architecture from OpenAM 9.0 to OpenAM 9.5.4.

Installation steps from [1] and [2] are written for OpenAM 9.5.3, however they are valid also for OpenAM 9.0. This article expects that you have installed this architecture with OpenAM 9.0.

For upgrade I used steps from OpenAM wiki [3]. These steps are a bit incomplete for me, so I wrote down this step-by-step howto.

Summary

At the beginning, I summarized my upgrade steps for OpenAM running on GlassFish application server:

• install ssoAdminTools for the old version of OpenAM (9.0)
• backup old OpenAM configuration (using ssoadm tool)
• remove OpenAM configuration from the directory server
• undeploy the old version of OpenAM
• remove the OpenAM configuration directory
• restart the GlassFish domain
• deploy the new version of OpenAM (9.5.4)
• run through the OpenAM configuration setup
• install ssoAdminTools for the new version of OpenAM (9.5.4)
• stop the GlassFish domain
• restore old OpenAM configuration (using ssoadm tool)
• start the GlassFish domain

Backup

First step in the wiki is to use ssoadm command to export OpenAM configuration. For a newbie, there is one significant problem – where to get ssoadm? This command is not part of OpenAM installation – it is part of ssoAdminTools package that is provided with OpenAM, however it is required to install it additionally.

Installation of ssoAdminTools is a bit tricky, you need to unzip a package and then run the setup script, however setup script doesn’t do an installation to selected path as expected, but creates configutration files in the directory, where it is started from. To create this configuration, you will need the path for OpenAM server config file (/opt/oam-config for environment from [1] or [2]) and if you use SSL connection to directory server, you need to have CA certificate imported to JDK keystore ($JAVA_HOME/jre/lib/security/cacerts, steps to import are explained in [2]).

mkdir /opt/ssoadm90
cd /opt/ssoadm90
unzip /home/profiq/opensso90/tools/ssoAdminTools.zip

./setup
Path to config files of OpenSSO server (example: /opensso):/opt/oam-config
Debug Directory:/opt/oam-debug
Log Directory:/opt/oam-log
The scripts are properly setup under directory: /opt/ssoadm90/opensso
Debug directory is /opt/oam-debug.
Log directory is /opt/oam-log.
The version of this tools.zip is: ForgeRock OpenAM Express
    Build 9(2010-February-07 13:29)
The version of your server instance is: ForgeRock OpenAM Express
    Build 9(2010-February-07 13:29)

cd /opt/ssoadm90/opensso/bin
echo oamadmin > /tmp/svcs.pwd
chmod 400 /tmp/svcs.pwd

./ssoadm export-svc-cfg -u amadmin -f /tmp/svcs.pwd -e opensso 
    -o /tmp/svcs.xml

Service Configuration was exported.

cp -r /opt/oam-config /opt/oam-config.backup

One more thing to backup is LDAP content:

/opt/OpenDJ-2.4.4/bin/export-ldif --includeBranch dc=example,dc=com 
    --backendID userRoot --ldifFile /tmp/backup.ldif
[16/Nov/2011:14:36:49 +0100] category=BACKEND severity=INFORMATION
    msgID=9437595 msg=Local DB backend userRoot does not specify the number
    of lock tables:
    defaulting to 97
[16/Nov/2011:14:36:49 +0100] category=BACKEND severity=INFORMATION
    msgID=9437594 msg=Local DB backend userRoot does not specify the number
    of cleaner threads:
    defaulting to 24 threads
[16/Nov/2011:14:36:50 +0100] category=JEB severity=NOTICE msgID=8847510
    msg=Due to changes in the configuration, index dc_example_dc_com_memberof
    is currently operating in a degraded state and must be rebuilt before it
    can be used
[16/Nov/2011:14:36:50 +0100] category=JEB severity=NOTICE msgID=8847510
    msg=Due to changes in the configuration, index
    dc_example_dc_com_sunxmlKeyValue is currently operating in a degraded
    state and must be rebuilt before it can be used
[16/Nov/2011:14:36:50 +0100] category=JEB severity=NOTICE msgID=8847510
    msg=Due to changes in the configuration, index
    dc_example_dc_com_iplanet-am-user-federation-info-key is currently
    operating in a degraded state and must be rebuilt before it can be used
[16/Nov/2011:14:36:50 +0100] category=JEB severity=NOTICE msgID=8847510
    msg=Due to changes in the configuration, index
    dc_example_dc_com_sun-fm-saml2-nameid-infokey is currently operating in a
    degraded state and must be rebuilt before it can be used
[16/Nov/2011:14:36:51 +0100] category=JEB severity=NOTICE msgID=8847447
    msg=Exported 408 entries and skipped 0 in 0 seconds (average rate
    812.7/sec)

OpenAM
In a few steps you will run OpenAM setup, and you will need to set a configuration store there. If you want to reuse the same root suffix for configuration store as was used before upgrade, you need to delete old configuration data, otherwise OpenAM setup could fail.

/opt/OpenDJ-2.4.4/bin/ldapdelete --useSSL -h ds-1.profiq.cz -p 1636 -D 
    "cn=Directory Manager" -w dsmanager -x ou=services,dc=example,dc=com
The server is using the following certificate:
Subject DN: CN=ds-1.profiq.cz, O=profiq, C=cz
Issuer DN: CN=ca, O=profiq, C=cz
Validity: Fri Nov 11 07:59:57 CET 2011 through Fri Nov 11 07:59:57
CET 2016
Do you wish to trust this certificate and continue connecting to the server?
Please enter "yes" or "no":yes
Processing DELETE request for ou=services,dc=example,dc=com
DELETE operation successful for DN ou=services,dc=example,dc=com

You have to undeploy old version of OpenAM and remove its old configuration directory:

cd /opt/glassfish/bin
./asadmin undeploy --user domain2adm --host oam-1.profiq.cz --port=8989 
    --target server opensso
Please enter the admin password>domain2pwd
Command undeploy executed successfully.

rm -rf /opt/oam-config

Now restart the OpenAM domain (when I tried to do it without this step, OpenAM setup failed, probably there was something left from old OpenAM, even after it was undeployed):

/opt/glassfish/domains/oamdomain/bin/stopserv
Server was successfully stopped.

/opt/glassfish/domains/oamdomain/bin/startserv
admin username:domain2adm
admin password: domain2pwd
master password: domain2master
Redirecting output to /opt/glassfish/domains/oamdomain/logs/server.log

You can watch server status tailing a log file:

tail -f /opt/glassfish/domains/oamdomain/logs/server.log

Now deploy the new version OpenAM:

./asadmin deploy --user domain2adm --host oam-1.profiq.cz --port=8989 
    --contextroot opensso --name opensso --target server 
    /home/profiq/opensso/deployable-war/opensso.war
Please enter the admin password> domain2pwd
Command deploy executed successfully.

Now OpenAM is deployed, you have to configure it as you did in old installation. Even if this config would be later replaced by the config from old version (backup you created using ssoadm), you need to pass these steps to create OpenAM configuration directory, that is used by ssoadm.

Go to https://oam-1.profiq.cz:1081/opensso (you have to use link to your OpenAM instance here):

Create New Configuration

1. General

• Password: oamadmin
• Confirm Password: oamadmin

2. Server Settings:

• Server URL: https://oam-1.profiq.cz:1081
• Cookie Domain: .profiq.cz
• Platform Local: en_US
• Configuration Directory: /opt/oam-config

3. Configuration Data Store Settings

• First Instance
• OpenDS or Sun Java System Directory Server
• SSL/TLS enabled: check
• Host Name: ds-1.profiq.cz
• Port: 1636
• Encryption Key: <default>
• Root Suffix: dc=example,dc=com
• Login ID: cn=Directory Manager
• Password: dsmanager

4. User Data Store Settings

• User Data Store Type: OpenDS
• SSL/TLS enabled: check
• Directory Name: ds-1.profiq.cz
• Port: 1636
• Root Suffix: dc=example,dc=com
• Login ID: cn=Directory Manager
• Password: dsmanager

5. Site Configuration

• Part of site configuration: No

6. Default Policy User Agent

• Password: agentuser
• Confirm Password: agentuser

7. Summary

• Create Configuration

Configuration directory for upgraded OpenAM is now ready. You have to configure ssoAdminTools to used this directory (you need new ssoAdminTools instance, using version provided with OpenAM 9.5.4):

mkdir /opt/ssoadm954
cd /opt/ssoadm954
unzip /home/profiq/opensso/tools/ssoAdminTools.zip
./setup
Path to config files of OpenAM server (example: /opensso):/opt/oam-config
Debug Directory:/opt/oam-debug
Log Directory:/opt/oam-log
The scripts are properly setup under directory: /opt/ssoadm954/opensso
Debug directory is /opt/oam-debug.
Log directory is /opt/oam-log.
The version of this tools.zip is: 9.5.4 Build 1516 (2011-December-07 09:55)
The version of your server instance is: 9.5.4 Build 1516 (2011-December-07
    09:55)

Now stop OpenAM domain, this step was not mentioned on the wiki, however I did it to prevent possible mismatch between configurations:

/opt/glassfish/domains/oamdomain/bin/stopserv

Import old OpenAM configuration to new configuration directory:

cd /opt/ssoadm954/opensso/bin
./ssoadm import-svc-cfg -u amadmin -f /tmp/svcs.pwd -e opensso 
    -X /tmp/svcs.xml

Directory Service contains existing data. Do you want to delete it? [y|N] y
Please wait while we import the service configuration...
Service Configuration was imported.

And start OpenAM domain again, with restored configuration:

/opt/glassfish/domains/oamdomain/bin/startserv
admin username:domain2adm
admin password: domain2pwd
master password: domain2master
Redirecting output to /opt/glassfish/domains/oamdomain/logs/server.log

You can watch server status tailing a log file:

tail -f /opt/glassfish/domains/oamdomain/logs/server.log

Now you can test, whether you are able to login as an admin user (and whether you see your old configuration) and as a test user.

TEST: Login as an admin user

Steps:

https://oam-1.profiq.cz:1081/opensso

• User Name: amadmin
• Password: oamadmin

Access Control -> / (Top Level Realm) -> Agents -> 2.2 Agents

Youu should see authuiadmin agent, that is part of old configuration, that was used before an upgrade. If you don’t see it, then configuration was not properly transfered.

Log Out

Expected output:

User is successfully logged in, authuiadmin agent exists, user is successfully logged out.

TEST: Login as a test user

Steps:

https://oam-1.profiq.cz:1081/opensso

• User Name: testuser1
• Password: password

https://oam-1.profiq.cz:1081/opensso/UI/Logout

Expected output:

User is successfully logged in and out.

DAUI

Steps to upgrade DAUI are again related to my architecture from [1] and [2], and are for Sun Web Server 7, they would differ for other web containters.

To upgrade DAUI, make sure that admin server is running, and domain server is down:

/opt/ws7/admin-server/bin/startserv
Sun Java System Web Server 7.0U8 (64-Bit) B01/20/2010 08:17
info: CORE5076: Using [Java HotSpot(TM) 64-Bit Server VM, Version 1.6.0_17] 
    from [Sun Microsystems Inc.]
info: WEB0100: Loading web module in virtual server [admin-server] at
    [/admingui]
info: WEB0100: Loading web module in virtual server [admin-server] at
    [/jmxconnector]
info: HTTP3072: admin-ssl-port: https://da-1.profiq.cz:8990 ready to accept
    requests
info: CORE3274: successful server startup

/opt/ws7/https-da-1.profiq.cz/bin/stopserv
server has been shutdown

Steps to create DAUI war file are the same as for standard deployment:

cd /home/profiq/opensso
mkdir war-staging
cd war-staging
jar xf ../deployable-war/opensso.war
cd ../deployable-war
chmod +x createwar.sh
./createwar.sh -s ../war-staging -t distauth -w auth.war

Steps to install DAUI are also the same, but before adding DAUI application, you need to remove the old one it first.

cd /opt/ws7/bin
./wadm remove-webapp --user=admin --host=da-1.profiq.cz --port=8990 
--config=da-1.profiq.cz --vs=da-1.profiq.cz --uri=/auth
Please enter admin-user-password> web4dmin
CLI201 Command 'remove-webapp' ran successfully

./wadm add-webapp --user=admin --host=da-1.profiq.cz --port=8990 
--config=da-1.profiq.cz --vs=da-1.profiq.cz --uri=/auth 
/home/profiq/opensso/deployable-war/auth.war
Please enter admin-user-password> web4dmin
CLI201 Command 'add-webapp' ran successfully

./wadm deploy-config --user=admin --host=da-1.profiq.cz --port=8990 
da-1.profiq.cz
Please enter admin-user-password> web4dmin
CLI201 Command 'deploy-config' ran successfully

Now start the domain:

/opt/ws7/https-da-1.profiq.cz/bin/startserv
Sun Java System Web Server 7.0U8 (64-Bit) B01/20/2010 08:17
info: CORE5076: Using [Java HotSpot(TM) 64-Bit Server VM, Version 1.6.0_17]
    from [Sun Microsystems Inc.]
info: WEB0100: Loading web module in virtual server [da-1.profiq.cz] at 
    [/auth]
info: HTTP3072: http-listener-1: http://da-1.profiq.cz:8080 ready to accept 
    requests
info: HTTP3072: http-listener-2: https://da-1.profiq.cz:8081 ready to accept 
    requests
info: CORE3274: successful server startup

And finally, verify that upgrade was successfull and you are able to authenticate using DAUI.

TEST: Access Web Server using authentication

https://da-1.profiq.cz:8081/auth/UI/Login?goto=/

User Name: testuser1
Password: password
https://da-1.profiq.cz:8081/auth/UI/Logout

Expected output:

At first, OpenAM login page is displayed and after login, Web Server page is displayed. Logout should work too.

References

[1] How to deploy OpenAM with DAUI
[2] How to deploy OpenAM with DAUI using SSL
[3] Upgrade OpenAM 9 to OpenAM 9.5
[4] OpenDS – Importing and Exporting Data