Migrating the SAML2 Profile v1.1 to v1.2

This migration guide describes how to upgrade your existing OpenASelect SAML2 Profile version 1.1 to version 1.2.

Note: If you want to migrate from a versions prior to 1.2, you'll first need to perform all migrations in between.

Note: The SAML2 Profile v1.2 requires OpenASelect Server v1.4 or newer.

Preparation

1. Creating a backup
   • Create a backup of your current OpenASelect installation: TOMCAT_HOME/webapps/openaselect

2. Download the SAML2 Profile v1.2
   • Download the binary distribution of SAML2 Profile v1.2: oas-saml2_profile-1.2-bin.zip.

3. Stop Tomcat

    # /etc/init.d/tomcat stop
   

Database

In SAML2 Profile v1.2 the internal OpenASelect database schema has been modified.If you are using the internal database, the following changes must be made:

• TGT alias storage
  • If you are using the oa_system database for storing TGT aliasses, the following changes must be made on that database:

    ALTER TABLE alias_store_sp RENAME COLUMN tgt_alias TO session_index;
    
    ALTER TABLE alias_store_sp ADD COLUMN unspecified11_user_id character varying(255) DEFAULT NULL;
    ALTER TABLE alias_store_sp ADD COLUMN unspecified20_user_id character varying(255) DEFAULT NULL;
    ALTER TABLE alias_store_sp ADD COLUMN email_user_id character varying(255) DEFAULT NULL;
    
    CREATE INDEX alias_store_sp_index_session_index_sp_id ON alias_store_sp USING btree (session_index,sp_id);
    CREATE INDEX alias_store_sp_index_transient_sp_id ON alias_store_sp USING btree (transient_user_id,sp_id);
    CREATE INDEX alias_store_sp_index_persistent_sp_id ON alias_store_sp USING btree (persistent_user_id,sp_id);
    CREATE INDEX alias_store_sp_index_unspecified11_sp_id ON alias_store_sp USING btree (unspecified11_user_id,sp_id);
    CREATE INDEX alias_store_sp_index_unspecified20_sp_id ON alias_store_sp USING btree (unspecified20_user_id,sp_id);
    CREATE INDEX alias_store_sp_index_email_sp_id ON alias_store_sp USING btree (email_user_id,sp_id);
    

Configuration

Because of some changes in OpenASelect Server v1.4 and SAML2 Profile 1.2 some parts of the configuration (oa.xml) has been changed. Manualy update the configuration in TOMCAT_HOME/webapps/openaselect/WEB-INF/conf/oa.xml of the following modules:

1. SAML2 Profile
   • Remove the websso section that is described in the SAML2 Profile - WebSSO configuration reference.
2. Single Logout Profile
   • Remove the cookie configuration within the Single Logout Profile configuration that has become obsolete, this functionality is moved to the OpenASelect Server so the configuration can be removed.
     • The section <cookie> ... </cookie> can be removed from within the <profile id="sso/logout"> section.

Deployment

Upgrading your OpenASelect Server with SAML2 Profile version 1.1 to 1.2 must be done manually by performing the following steps.

1. Extract the binary distribution zip file to a temporary directory.

2. Change the OpenASelect Server configuration file TOMCAT/webapps/openaselect/WEB-INF/conf/oa.xml as described here.

3. Manually copy each file from the TEMPORARY/openaselect directory to the TOMCAT_HOME/webapps/openaselect directory. This will overwrite your existing installation.

    # cp -r <TEMPORARY>/openaselect <TOMCAT>/webapps/openaselect
   

4. Remove obsolete 3rd party libraries.
   • Remove the following obsolete libraries (jar files supplied by the standard binary distribution):
     • `TOMCAT_HOME/webapps/openaselect/WEB-INF/lib/joda-time-1.5.2.jar
     • `TOMCAT_HOME/webapps/openaselect/WEB-INF/lib/opensaml-2.1.0.jar
     • `TOMCAT_HOME/webapps/openaselect/WEB-INF/lib/openws-1.1.0.jar
     • `TOMCAT_HOME/webapps/openaselect/WEB-INF/lib/slf4j-api-1.5.0.jar
     • `TOMCAT_HOME/webapps/openaselect/WEB-INF/lib/slf4j-log4j12-1.5.0.jar
     • `TOMCAT_HOME/webapps/openaselect/WEB-INF/lib/xmltooling-1.0.1.jar

5. Start Tomcat

    # /etc/init.d/tomcat start
   

6. Verify that OpenASelect has been started successfully.
   • See the installation guide on how to verify the installation.