How to upgrade OpenAM
skatuscak
13 years ago 13.12.2011
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
- start the admin server
- stop the domain server
- remove old DAUI application
- add new DAUI application
- run deploy-config
- start the domain server
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
ERROR: ServiceSchemaImpl.serverEndAttrValidation
java.lang.ClassNotFoundException: com.sun.identity.sm.DomainValidator
ERROR: SMSJAXRPCObjectvalidateServiceAttributes
java.lang.NullPointerException
http://lists.forgerock.org/pipermail/openam/2011-May/001692.html
Any idea on how to resolve these errors?
Hi mic,
Which version of ssoAdminTools did you use? I see that you’re trying to upgrade from OpenSSO 8.0.2 to OpenAM 9.5.1. For me it’s not 100% clear, which version is needed to export config from OpenSSO 8.0.2, in this howto I used ssoAdminTools provided with old version, in your case OpenSSO 8.0.2, other option is to use directly new version provided with OpenAM 9.5.1. Steps from OpenAM wiki are not clear and there could be some incompatibility between versions.
Btw, when I tried to export config from OpenSSO 8.0, it didn’t work for me, and it’s still not clear what was the cause.
See http://lists.forgerock.org/pipermail/openam/2011-November/003839.html
Regards,
Slavomir Katuscak