Migrating the SAML2 Authentication Method v1.0 to v1.1

This migration guide describes how to upgrade your existing OpenASelect SAML2 Authentication Method version 1.0 to version 1.1.

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

Note: The SAML2 Authentication Method v1.1 requires OpenASelect Server v1.4 or newer and SAML2 Profile v1.2 or newer.

Preparation

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

2. Download the SAML2 Authentication Method v1.1
   • Download the binary distribution of SAML2 Authentication Method v1.1: oas-saml2_authentication-1.1-bin.zip.

3. Stop Tomcat

    # /etc/init.d/tomcat stop
   

Database

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

1. SAML2 organization/IdP storage
   • If you are using the oa_model database for storing remote SAML2 organizations/IdP's, the following changes must be made on that database:

     ALTER TABLE saml2_orgs ADD COLUMN enabled boolean DEFAULT TRUE;
     

2. 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_idp ADD COLUMN session_index character varying(343) DEFAULT NULL;
     ALTER TABLE alias_store_idp ADD COLUMN transient_user_id character varying(256) DEFAULT NULL;
     ALTER TABLE alias_store_idp ADD COLUMN persistent_user_id character varying(255) DEFAULT NULL;
     ALTER TABLE alias_store_idp ADD COLUMN unspecified11_user_id character varying(255) DEFAULT NULL;
     ALTER TABLE alias_store_idp ADD COLUMN unspecified20_user_id character varying(255) DEFAULT NULL;
     ALTER TABLE alias_store_idp ADD COLUMN email_user_id character varying(255) DEFAULT NULL;
     
     CREATE INDEX alias_store_idp_index_session_index_idp_id ON alias_store_idp USING btree (session_index,idp_id);
     CREATE INDEX alias_store_idp_index_transient_idp_id ON alias_store_idp USING btree (transient_user_id,idp_id);
     CREATE INDEX alias_store_idp_index_persistent_idp_id ON alias_store_idp USING btree (persistent_user_id,idp_id);
     CREATE INDEX alias_store_idp_index_unspecified11_idp_id ON alias_store_idp USING btree (unspecified11_user_id,idp_id);
     CREATE INDEX alias_store_idp_index_unspecified20_idp_id ON alias_store_idp USING btree (unspecified20_user_id,idp_id);
     CREATE INDEX alias_store_idp_index_email_idp_id ON alias_store_idp USING btree (email_user_id,idp_id);
     

Configuration

Because of some changes in OpenASelect Server v1.4 and SAML2 Authentication Method 1.1 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. SP Role Single Logout Profile
   • Add this profile for Single Logout support.
2. SAML2 Authentication Method
   • Rename the organizations section to idps as described in the SAML2 Authentication Method configuration reference.
   • Rename the organization section to idp as described in the SAML2 Authentication Method configuration reference.
   • Change the value of the class parameter in the idps section as described in the SAML2 Authentication Method configuration reference.

Deployment

Upgrading your OpenASelect Server with SAML2 Authentication Method version 1.0 to 1.1 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.