IBM Tivoli Federated Identity Manager, Version 6.2.2

Migrating SAML 2.0 alias service entries

Use the alias service migration tool to preserve existing aliases from earlier versions of Tivoli® Federated Identity Manager.

About this task

The alias service stores mappings between a user identity and one or more string aliases on a per federation context basis. In the actual alias service interfaces, this federation context is also called as the partner ID. The primary clients of the alias service are SAML 2.0 federations by using persistent name identifiers.

In the earlier versions of Tivoli Federated Identity Manager (before 6.2.2), the federation context is the ProviderID of the SAML partner. There is no difference between the federation context if two or more federations import the same partner metadata. This task might cause potential privacy and functional problems.

In this version, a unique identifier is introduced in the partner ID parameter of the UserIdDescriptor object that is passed to the alias service client. This approach includes the federation ID in the partner ID as part of alias service operations for SAML 2.0 federations. It also uses a per-partner federation property to toggle how a partner stores and retrieves aliases from the alias service.

Existing aliases and federations work without any migration. But if they are modified to use the new alias service format, you must use the alias service migration tool to migrate existing aliases.

Tivoli Federated Identity Manager provides an alias service delegate so that an authenticated user can manage their alias service entries. The delegate is accessed through the /sps/alias URI and uses a query string parameter called partner to determine which partner to obtain aliases for.

For SAML 2.0 federations that are using the new format of storing aliases, the query string parameter value must be in the format federationID|partnerID. For example:

For old format aliases:
https://fim1.ibm.com:9443/sps/alias?partner=https://fim2.ibm.com:9443/sps/saml20sp/saml20
For new format aliases:
https://fim1.ibm.com:9443/sps/alias?partner=https://fim1.ibm.com:9443/sps/saml20idp/saml20|https://fim2.ibm.com:9443/sps/saml20sp/saml20

Procedure

  1. On a computer that hosts the Tivoli Federated Identity Manager management service, access the command line.
  2. Configure the CLASSPATH to include the following jar files:
    • itfim-alias-migration.jar (available from <FIM_HOME>/tools/aliasmigration/ directory)
    • The WebSphere® Application Server web services thin client jar (available from <WAS_HOME>/runtimes/ and commonly called com.ibm.ws.webservices.thinclient_X.Y.Z.jar, where X.Y.Z depends on the WebSphere Application Server version being used)
    • com.ibm.ws.security.crypto.jar (available from <WAS_HOME>/plugins/)
    For example, enter the following command in a UNIX or Linux command line: CLASSPATH=.:/opt/IBM/WebSphere/AppServer/plugins/com.ibm.ws.security.crypto.jar:/opt/IBM/FIM/tools/aliasmigration/itfim-alias-migration.jar:/opt/IBM/WebSphere/AppServer/runtimes/com.ibm.ws.webservices.thinclient_7.0.0.jar
  3. Perform one of the following steps:
    UNIX
    Load the setupCmdLine.sh script into the current shell (../setupCmdLine.sh).
    setupCmdLine.sh is located in <WAS_HOME>/profiles/<profile_name>/bin, where <WAS_HOME> is typically /opt/IBM/WebSphere/AppServer.
    Windows
    Run the setupCmdLine.bat file.
    setupCmdLine.bat is located in <WAS_HOME>/profiles/<profile_name>/bin, where <WAS_HOME> is typically C:\Program Files\WebSphere\AppServer.
  4. Run the following command to start the alias service migration tool: 
    java com.tivoli.am.fim.alias.migration.AliasMigration 
-type <ldap|db2|derby> -infoscvurl <http(s)://tfim-host:tfim-port/Info/
InfoService> -partnerName <partner display name>
-federationName <federation display name>
    The following table outlines the common JDBC or LDAP-specific options of the tool:
    Table 1. Alias service migration tool parameters
    Parameter Description Other
    -type <type> The type of alias service that is being migrated. Can be either LDAP, DB2®, or Derby. Required, All types
    -infosvcurl <url> The URL for the Tivoli Federated Identity Manager Infomation Service, which is typically http://fim-host:fim-port/Info/InfoService. Required, All types
    -infosvcuser <username> The user name for authenticating with the Tivoli Federated Identity Manager Information Service, which is used in web service call BA header. Optional, All types
    -infosvcpwd <password> The password for authenticating with the Tivoli Federated Identity Manager Information Service, which is used in web service call BA header. Optional, All types
    -partnerName <display name> The display name of the partner whose aliases must be migrated. Required, All types
    -federationName <display name> The display name of the federation whose aliases must be migrated. Required, All types
    -reverse Perform a reverse migration as opposed to a forward migration. Optional, All types
    -h <host> The host parameter of the LDAP server for the alias service. Required, LDAP only
    -p <port> The port parameter of the LDAP server for the alias service. Default value is 389. Optional, LDAP only
    -D <bind dn> The LDAP bind credential. For example, cn=root. Optional, LDAP only
    -w <password> The LDAP bind password. Optional, LDAP only
    -file <filename> Outputs the alias changes to a file. For LDAP, this parameter is an LDIF file. For JDBC, this file contains a series of SQL statements. Optional, All types
    -Z Enables the SSL connection to the LDAP server. Optional, LDAP only
    -configRoot <suffix> Overrides the alias service config root. Default value is cn=itfim. Optional, LDAP only
    -silent Performs migration without a confirmation prompt for LDAP access. Optional, LDAP only
    Notes:
    1. You must use the WebSphere Application Server Java™ to run this tool.
    2. If the Tivoli Federated Identity Manager Information Service requires authentication though BA header, you can pass parameters to the tool. See Table 1 for details.

      If the Information Service uses an SSL endpoint, you must configure the SSL client properties. One way to configure this is to specify 'com.ibm.SSL.ConfigURL' as a Java system property and point it to the WebSphere Application Server ssl.client.props file. This file is typically available at <WAS_HOME>/profiles/AppSrv01/properties/ssl.client.props.

      To set this property as a Java system property, specify it on the command line: 
      -Dcom.ibm.SSL.ConfigURL=file://<WAS_HOME>/profiles/AppSrv01/
   properties/ssl.client.props
      A sample command that configures the SSL client properties: 
      java -Dcom.ibm.SSL.ConfigURL=file://<WAS_HOME>/profiles/AppSrv01/properties/
   ssl.client.props com.tivoli.am.fim.alias.migration.AliasMigration
   -type derby -infosvcurl https://fim.ibm.com:9443/Info/InfoService 
   -federationName saml20idp -partnerName saml20sp -infosvcuser fimadmin 
   -infosvcpwd password
      An example of SSL connection on LDAP is: 
      java -Dcom.ibm.SSL.ConfigURL=file://<WAS_HOME>/profiles/AppSrv01/properties/
   ssl.client.props com.tivoli.am.fim.alias.migration.AliasMigration 
   -type ldap -infosvcurl http://fim1.demo.com:9080/Info/InfoService 
   -partnerName "saml20sp_CoName" -infosvcuser fimadmin -infosvcpwd password 
   -h fim1.demo.com -D cn=root -w Passw0rd -federationName "saml20idp" 
   -p 636 -Z -reverse -file ldif_sec.txt

      You can specify a Java system property to output logging information. To enable Java logging, specify -DLogging.Level=<FINE|FINER|FINEST|ALL> on the command line as part of tool invocation.

      Here is an example: 
      java -DLogging.Level=ALL com.tivoli.am.fim.alias.migration.AliasMigration 
   -type ldap -infosvcurl http://fim1.demo.com:9080/Info/InfoService 
   -partnerName "saml20sp_CoName" -h fim1.demo.com -D cn=root -w Passw0rd 
   -federationName saml20idp -reverse -silent -file ldif.txt
Parent topic: Upgrading to version 6.2.2

Feedback