©Copyright International Business Machines Corporation 2007. All rights reserved. U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
NOTE: Before using this information and the product it supports, read the general information under Notices in this document.
Date: Monday, 15 December 2008
This fix pack corrects problems in IBM Tivoli Federated Identity Manager Business Gateway, Version 6.1.1. It requires that IBM Tivoli Federated Identity Manager Business Gateway, Version 6.1.1, be installed. After installing this fix pack, your Tivoli Federated Identity Manager Business Gateway installation will be at level 6.1.1.10.
This fix pack package contains:
This fix pack is distributed as an electronic download from the IBM Support Web Site.
This fix pack package supports the same operating system releases as the Tivoli Federated Identity Manager Business Gateway 6.1.1 release that are listed in the Hardware and software requirements document.
ATTENTION: In March 2007, the following versions of HP-UX Integrity on Itanium® were added to the list of supported operating systems:
If you installed Tivoli Federated Identity Manager Business Gateway on either of these versions, the administration console will display the version number "6.1.1.1." However, TFIMUI and a real fix pack must be installed to create the DE database, register TFIMBG 6.1.1 in the DE database as a deployed application, and register the fix pack as the installed level. Fix pack 1 bundles TFIMUI with it. If starting with a subsequent fix pack then TFIMUI must be downloaded from its download page and installed separately.
ATTENTION: In June, 2008, FP0007 added support for AIX 6.1, including WPARs, and Windows 2008 Server. The Windows 2008 Server certification did not include eWAS as eWAS was not supported there at that time.
ATTENTION: In September, 2008, FP0009 added support for Firefox 3.
6.1.1-TIV-TFIMBG-FP0001
6.1.1-TIV-TFIMBG-FP0003
6.1.1-TIV-TFIMBG-FP0005
6.1.1-TIV-TFIMBG-FP0007
6.1.1-TIV-TFIMBG-FP0009
Tivoli Federated Identity Manager Business Gateway consists of three components that can be installed separately:
All components must be at the same level. Therefore, if you install a fix pack for one of the components, you must install that fix pack for the rest of the components. Components at one release level are not guaranteed to interoperate with components at a different release or fix pack level.
The following problems are corrected by this fix pack. For more information about the APARs listed here, refer to the Tivoli Federated Identity Manager Business Gateway support site.
Be aware of the following considerations before installing this fix pack:
NOTE: Before installing this fix pack, be sure that you have reviewed the prerequisites in Before installing the fix pack.
After you have downloaded the fix pack, you need to perform a few steps before you can run the installation program.
jar -xvf to
unzip the file or download an unzip utility from the HPUX Connect site.chmod +x *.sh
in the /script directory.
variables file
If security is enabled on the WebSphere Application Server where
Tivoli Federated Identity Manager Business Gateway is installed, you must provide
the appropriate passwords in the fix pack variables file.
If security is not enabled, you can skip this step.
If the TFIM runtime is installed on the system, then the three TFIMRuntime passwords must be specified. If the TFIM console is installed on this system then the three TFIMConsole passwords must be specified. If both the runtime and the console are anywhere on this system then both sets of passwords must be given.
The variables file contains the following passwords:
TFIMRuntimeWASPassword=TFIMRuntimeTrustedJksPassword=TFIMRuntimeJksPassword=TFIMConsoleWASPassword=TFIMConsoleTrustedJksPassword=TFIMConsoleJksPassword=To provide the appropriate passwords:
variables in the fix pack
/script directory.
ATTENTION: If you added passwords to the variables file, as
described here, the passwords are in plain text in this file.
Be sure to remove the passwords from this file to prevent a
security breach.
Note that begining with patch 6.1.1-TIV-TFIMBG-LA0004 these instructions apply to each TFIMBG 6.1.1 instance on a system. The addition of the DE discriminant argument to the install script's execution (describe below under step 6) makes the work-around described under APAR IZ03121 no longer necessary.
acsi is running, as follows:
ps -ef|grep acsi/usr/ibm/common/acsi/bin/acsisrv.sh -start.
Then ensure the service is running./script subdirectory of the directory
where you unzipped the fix pack zip file.install.bat on Windows systems./install.sh for AIX, Solaris, Linux, or HP-UXThis command has a single optional argument, the discriminant
under which the TFIM 6.1.1 instance being patched is registered in the
DE database. This argument defaults to /opt/IBM/FIM, the
discriminant used by TFIMUI 1.3 to register any TFIM 6.1.1 instance. So
for the simple case of patching a single TFIM 6.1.1 instance registered
by TFIMUI 1.3 no argument need be provided. For the more complex case,
where more than one TFIM 6.1.1 instance was registered using TFIMUI 1.3
with the procedure described under APAR
IY98408, contact support.
TFIMUI 1.3.0.1 uses a TFIM 6.1.1 instance's installation path as the discriminant when registering an instance, so use the installation path as the install command's argument in this case. If the installation path contains a space then it must be enclosed in double quotes.
ATTENTION: If you added passwords to the variables file, as
described in
Preparing the variables file,
the passwords are in plain text in this file.
Be sure to remove the passwords from this file to prevent a
security breach.
The fix pack install automatically deploys the newly installed Tivoli Federated Identity Manager Business Gateway runtime. However, you should verify that the current deployed version is 6.1.1.10.
Runtime Information
----------------------------------------------
Current deployed version 6.1.1.10 [070406a]
Note: The number within the brackets [070406a] might be different
from this example.
If you want to return your installation to the state it was in prior to installing the fix pack, you can uninstall the fix pack.
ATTENTION -- When you remove the management service and runtime component fix pack, you will lose any configuration (domains, federations, and so on) that you added after the fix pack was installed.
acsi is running, as follows:
ps -ef|grep acsi/usr/ibm/common/acsi/bin/acsisrv.sh -start.
Then ensure the service is running.
variables file that was used when the fix pack was installed,
edit the file and add the appropriate passwords. Then save
and close the file./script directory and the type the uninstall command:
uninstall.bat on Windows systems./uninstall.sh for AIX, Solaris, Linux, or HP-UXThis command has a single optional argument, the discriminant
under which the TFIMBG 6.1.1 instance being patched is registered in the
DE database. This argument defaults to /opt/IBM/FIM, the
discriminant used by TFIMUI 1.3 to register any TFIMBG 6.1.1 instance. So
for the simple case of patching a single TFIMBG 6.1.1 instance registered
by TFIMUI 1.3 no argument need be provided. For the more complex case,
where more than one TFIM/TFIMBG 6.1.1 instance was registered using TFIMUI 1.3
with the procedure described under APAR
IZ03121, contact support.
TFIMUI 1.3.0.1 uses a TFIMBG 6.1.1 instance's installation path as the discriminant when registering an instance, so use the installation path as the uninstall command's argument in this case. If the installation path contains a space then it must be enclosed in double quotes.
The uninstall process will remove the fix pack and revert to the previous versions of files that were changed by the fix pack.
For example, if you had installed fix pack 10 onto a Tivoli Federated Identity Manager Business Gateway 6.1.1.0 system, then after uninstalling fix pack 10 you would see the following:
Suite Name Version
----------------------------------------------------------
Tivoli Federated Identity Manager 6.1.1.0 [050428a]
Note: If you uninstalled the fix pack on an Itanium Tivoli Federated Identity Manager Business Gateway 6.1.1.0 system, the version number displayed will be 6.1.1.1 even after you uninstall the fix pack.
Runtime Information
----------------------------------------------
Current deployed version 6.1.1.0 [061110a]
Note: The number within the brackets [061110a] might be
different from this example.
Note: If you uninstalled the fix pack on an Itanium Tivoli Federated Identity Manager Business Gateway 6.1.1.0 system, the version number displayed will be 6.1.1.1 even after you uninstall the fix pack.
The product documentation for Tivoli Federated Identity Manager Business Gateway, Version 6.1.1, can be found on the information center for IBM Tivoli Federated Identity Manager Business Gateway .
Updates to the documentation follow:
The management console for Tivoli Federated Identity Manager Business Gateway Version 6.1.1 does not have a GUI interface for adding a custom mapping module into a federation or partner trust chain. Patch 2 provides this GUI interface.
Background
Tivoli Federated Identity Manager Business Gateway provides wizards that build trust chains for SAML 1 federations. You must define trust chains when creating a federation and when adding a partner to a federation.
Trust chains convert user identity information from one token type to another token type. The conversion task includes use of an identity mapping module. Administrators use this module to define identity mapping tasks that are specific to their deployments.
Tivoli Federated Identity Manager Business Gateway provides a default mapping module that uses XSLT code to perform identity mapping. You have the option of replacing the default mapping module with a custom mapping module.
You must first develop the custom mapping module and then use the management console to add the module to the trust chain.
Solution summary
To add a custom mapping module:
Solution details:
Step 1: Develop your custom mapping module
This is a programming task that must be completed prior to configuring the module into the federation. You must write a Java(R) class for a new module type and install the class into the plug-ins directory for your domain.
For more information, see:
Step 2: Use the management console to create a new module type.
Step 3: Use the management console to create a new module instance.
Step 4: Use the management console to configure the custom mapping module instance into a trust chain
Step 4a: Create a new trust chain that contains the custom mapping module. Use this step when you are either:
The IBM Tivoli Federated Identity Manager Business Gateway Version 6.1.1 Administration Guide contains the necessary instructions. Use (search for) the instructions entitled "Use Custom Mapping Module Instance" that apply to your task and deployment. (Page numbers refer to the PDF® image):
| Task and Deployment | Page # |
| Creating your federation as the service provider | 123 |
| Adding an identity partner to a federation | 129 |
| Adding an identity provider partner manually | 134 |
| Creating your federation as the identity provider | 137 |
| Adding a service provider partner using metadata | 141 |
| Adding a service provider partner manually | 144 |
Step 4b: Modify an existing trust chain to use the custom mapping module
Use this task when you want to modify an existing trust chain by replacing the default mapping module with your custom mapping module.
The IBM Tivoli Federated Identity Manager Business Gateway Version 6.1.1 Administration Guide contains the necessary instructions. Use (search for) the instructions entitled "Use Custom Mapping Module Instance" that apply to your task and deployment (Page numbers refer to the PDF image):
| Task and Deployment | Page # |
| Modifying federation properties | 162 |
| Modifying partner properties | 166 |
The documentation for the TFIM staging tools that ship with the TFIM 6.1 and later releases has limited information about the valid properties that can be specified in the properties files that are passed as parameters to the staging utilitites. To address this issue, the TFIM Staging Utilities Reference white paper has been written to document the valid properties that can be specified in a properties file used with the TFIM staging utilitites. It can also be found under White Papers on the Tivoli Federated Identity Manager support site,
The IBM Tivoli Federated Identity Manager Business Gateway Version 6.1.1 Problem Determination Guide includes text that refers to a TFIM 6.1.0 whitepaper "Configuring Java Logging for Tivoli Federated Identity Manager 6.1". The text describes how to set trace logging for ISC events, and includes a link that does not resolve.
The text is in Chapter 7, under the topic is "Configuring log
settings". The documentation incorrectly specifies that the
wsadmin command line tool for WebSphere administration must
be used to enable the TFIM product tracing. In fact, the
eWAS administration console can be used to enable the tracing.
This is done by expanding "Troublehooting" in the left frame
and selecting "Logs and Trace". Then select "Change Log Detail
Levels" and set the desired tracing levels.
It is not possible to query the status of the FIM runtime
from the eWAS console. The following wsadmin commands show how
to query the FIM runtime's
status as well as how to start and stop the FIM runtime from the command line.
These commands assume the WAS server instance is named "server1".
wsadmin>$AdminApp listwsadmin>$AdminControl queryNames type=Application,process=server1,name=ITFIMRuntime,*wsadmin>set appManager [$AdminControl queryNames type=ApplicationManager,process=server1,*]wsadmin>$AdminControl invoke $appManager stopApplication ITFIMRuntimewsadmin>set appManager [$AdminControl queryNames type=ApplicationManager,process=server1,*]wsadmin>$AdminControl invoke $appManager startApplication ITFIMRuntimelppchk -v error on AIX (IZ03220)The ISMP version used for fix pack 1 has a defect that can cause AIX's
lppchk -v command to report the following kind of error:
# lppchk -v
lppchk: The following filesets need to be installed or corrected to bring
the system to a consistent state:
FIMLic 6.1.1.1 (COMMITTED)
This error reports an inconsistent update of the ODM database by ISMP. It does not affect the functioning of TFIM at all. A new version of the ISMP is being used as of patch 2 that will no longer make this error. However the error made by earlier installs will still remain.
The following script will eliminate the lppchk -v error
by removing the offending fileset from the ODM database. It takes a single
argument, the fileset name the lppchk -v complained about,
e.g., FIMLic in the example above.
#!/bin/ksh
#echo "Removing LPP $1: Are you sure?" 1>&2
#read foo
#
#case "$foo" in
#yes|y)
# ;;
#*)
# exit 1
#esac
#
LPPID=`ODMDIR=/usr/lib/objrepos odmget -q "name = $1" lpp | grep lpp_id | awk '{print $3}'`
echo "
Removing files of LPP $1..."
lslpp -fcq $1 | awk '(FS = ":") {print "rm -f",$3}' | sh -x 2>&1
echo "
Removing $1 from ODM (inventory,product,history,lpp,vendor)"
ODMDIR=/usr/lib/objrepos odmdelete -o inventory -q "lpp_id = $LPPID"
ODMDIR=/usr/lib/objrepos odmdelete -o product -q "lpp_name = $1"
ODMDIR=/usr/lib/objrepos odmdelete -o history -q "lpp_id = $LPPID"
ODMDIR=/usr/lib/objrepos odmdelete -o lpp -q "name = $1"
ODMDIR=/usr/lib/objrepos odmdelete -o vendor -q "lpp_id = $LPPID"
ODMDIR=/etc/objrepos odmdelete -o inventory -q "lpp_id = $LPPID"
ODMDIR=/etc/objrepos odmdelete -o product -q "lpp_name = $1"
ODMDIR=/etc/objrepos odmdelete -o history -q "lpp_id = $LPPID"
ODMDIR=/etc/objrepos odmdelete -o lpp -q "name = $1"
ODMDIR=/etc/objrepos odmdelete -o vendor -q "lpp_id = $LPPID"
ODMDIR=/usr/share/lib/objrepos odmdelete -o inventory -q "lpp_id = $LPPID"
ODMDIR=/usr/share/lib/objrepos odmdelete -o product -q "lpp_name = $1"
ODMDIR=/usr/share/lib/objrepos odmdelete -o history -q "lpp_id = $LPPID"
ODMDIR=/usr/share/lib/objrepos odmdelete -o lpp -q "name = $1"
ODMDIR=/usr/share/lib/objrepos odmdelete -o vendor -q "lpp_id = $LPPID"
The SAML claims should be part of the STS Universal User so that
they can be referenced from the XSLT mapping modules but are not.
The fix to this defect corrects this oversight. The claims
are made available by defining the TFIM custom runtime property
sts.add.saml.claims. This is done in the
TFIM administration console by selecting "Domain Management"->"Runtime
Node Management", selecting the "Runtime Custom Properties" button, creating
a property with a name of "sts.add.saml.claims" and a value of
"true", and restarting the WAS server.
Due to interactions between assumptions made by the fix pack installer and the operation of the Deployment Engine component embedded in it, the standard instructions for applying a fix pack do not work when patching the 2nd-Nth TFIM 6.1.0, TFIM 6.1.1, or TFIMBG 6.1.1 instance on a system. To simplify the wording, the following work-around describes patching just the 2nd instance of TFIMBG 6.1.1, but the instructions apply equally well to patching the 2nd-Nth instances of TFIM 6.1.0, TFIM 6.1.1, or TFIMBG 6.1.1. Also, the following two italicized words are used below as abbreviations for the following two directory paths:
TFIMUI-dir2nd-TFIMBG-dirThe following steps
must be executed in order to apply a fix pack or an LA patch to the 2nd TFIMBG 6.1.1 instance on a system.
Steps (7) and (12) apply to a Unix/Linux installation where the 2nd TFIMBG instance's
WAS application server did not use localhost but used a separate,
unique IP address instead.
Note that if the WAS application server of the first TFIMBG instance to be patched
did not use localhost but used a separate,
unique IP address instead then the manipulation of localhost described by
step (7) must be performed before
running the update installer and
step (12) must be performed after
running the update installer.
On Windows, replace the .sh file extension in these steps with .bat.
Find the file TFIMUI-dir/DE/test/selectedfeatures.
Add/remove selectedFeature lines in this file until there's one for each feature
in the 2nd TFIMBG. Check the 2nd TFIMBG's <TFIMBG-dir>/etc/version.properties
file for a definitive list of the 2nd TFIMBG's features.
Each feature line in the 2nd-TFIMBG-dir/etc/version.properties file is of the form
itfim.build.version.featurename=6.1.1.n
where featurename is one of the choices in the first column of the table below and n is the installed fix pack number.
Each feature line in the TFIMUI-dir/DE/test/selectedfeatures file is of the form
selectedFeature\#RootIUTypeID[cc05dc31804627bba6e6661c48bf1a81,6.1.1.0]1\featurename=true
where featurename is one of the choices in the second column of the table below.
The mappings from the 2nd-TFIMBG-dir/etc/version.properties feature names
to the TFIMUI-dir/DE/test/selectedfeature feature names are as follows:
2nd-TFIMBG-dir/etc/version.propertiesfeature name |
TFIMUI-dir/DE/test/selectedfeaturesfeature name |
|---|---|
| ewas | #FIMEwasFeat |
| fimpi | #FIMIISPlugFeat |
| mgmtcon | #FIMConsoleFeat |
| rte-mgmtsvcs | #RunTimeAndManagementFeat |
| wsprov | #WSProvisioningFeat |
| wssm | #FIMWssmFeat |
Fixup the last line in the TFIMUI-dir/DE/test/selectedfeatures
file. This line looks like
Variable\#RootIUTypeID[cc05dc31804627bba6e6661c48bf1a81,6.1.1.0]\#InstallLocation=some-TFIMBG-dir
Replace the existing some-TFIMBG-dir with the installation directory path of the
2nd TFIMBG instance.
Change the -r option in the last line of the
TFIMUI-dir/DE/test/install.sh file from whatever TFIMBG installation directory
is there (/opt/IBM/FIM initially) to the
installation directory path of the 2nd TFIMBG instance.
On Unix/Linux, execute the following command:
chmod a+x TFIMUI-dir/DE/test/*.sh.
Execute TFIMUI-dir/DE/test/install.sh to register the 2nd TFIMBG
in the DE database.
If the WebSphere application server hosting the TFIMBG component is not listening on
localhost, then
/etc/hosts file, moving localhost to the line that
defines the IP address used by the 2nd TFIMBG's WAS application server (or create such a
line).acsi service.Go to the unzipped fix pack's files, find the script/ directory.
Change the -r option in the last line of the
script/install.sh file from whatever TFIMBG installation directory
is there (/opt/IBM/FIM initially) to the
installation directory path of the 2nd TFIMBG instance.
Fixup the passwords in the script/variables file to be those of the 2nd TFIMBG.
Execute the script/install.sh file to apply the fix pack to the 2nd TFIMBG.
If the WebSphere application server hosting the TFIMBG component is not listening on
localhost, then
/etc/hosts file made in step (7).acsi service.
The installer sets the wrong com.tivoli.am.fim.was.home value when the product
is installed on Windows. Here is an example of an incorrect entry in the
software.properties file (the file is installed in the directory
/<TFIMBG-installation-directory>/pkg):
com.tivoli.am.fim.was.home=C:\Program FilesIBMWebSphereAppServer
The value should be:
com.tivoli.am.fim.was.home=C:/Program Files/IBM/WebSphere/AppServer
The TFIM runtime can be successfully deployed, but users are never able to select the
runtime to configure it from the runtime node management panel of the TFIM administration
console. The software.properties file must be manually edited to fix the
incorrect entry so that it has the correct slashes ('/') in the path value.
ACUINI0012I Deployment Engine Installation Failed!
Causes: com.ibm.ac.si.install.InstallFailedException:;com.ibm.ac.si.install.UnrecognizedOSException:
ACUINI0045E The current OS is unrecognized by this application:
Name = Linux ; Architecture = ppc ; Version = 2.6.5-7.244-pseries64
linux_ppc_install.bin and getting this error, perform the
following steps.
/opt/IBM/FIMUI/DE/si_inst.sh using a 64-bit JVM.
This script, which installs the DE and the acsi code, uses the java
on $PATH, and the java on $PATH is normally
the 64-bit JVM that came with SLES9
for PPC64 unless $PATH or the soft-link at /usr/lib/java has
been changed. It is possible to change the JVM used through the script's
-javeHome path-to-JVM option.
To determine whether a particular java is 32-bit or 64-bit, first
cd
into the directory containing the java executable to be used,
then execute
# file java
The output will clearly state whether it is a 32-bit or a 64-bit executable.
/opt/IBM/FIMUI/DE/test/install.sh
to register TFIMBG 6.1.1 with the DE's database./scripts/install.sh to install
the fix pack. Be aware of this script's need for Java 1.5
described below under APAR IZ07736.As of patch LA0004 the complex work-around for this defect, documented under APAR IZ03121, is no longer necessary. Together, the installer of patch LA0004 and the new TFIMUI 1.3.0.1 implement a fix for this defect that makes patching the 2nd-Nth TFIM instance on a system much simpler
The essence of the defect was that TFIMUI 1.3 always registered a TFIM/TFIMBG 6.1.1
instance in the Deployment Engine (DE) database using the same key, making it impossible
to discriminate between multiple instances on the same system. The Deployment Engine
uses a two-part key when registering an application instance in its database. The
first part is an application-specific GUID. The second part is an instance-specific
discriminant, an arbitrary string that should be unique for each instance on a system.
Unfortunately, TFIMUI 1.3 always used /opt/IBM/FIM as the discriminant.
The fix to this defect was to have TFIMUI 1.3.0.1 use the installation path of the TFIM/TFIMBG 6.1.1 instance being registered as the discriminant. On Windows the 8.3-form of the installation path is used with a lower-case drive letter. This simple change, while not changing the installation of TFIMUI at all, has several implications.
DE/test directory, registerTFIMInstall.bat(.sh).
Instead of reinstalling TFIMUI for each of the 2nd-NTH instances, this script
must be executed. It, too, has the same single argument as the "install"
scripts./opt/IBM/FIM, the fix pack install scripts'
argument is optional, defaulting to /opt/IBM/FIM. This default
will leave the patching of most existing TFIM/TFIMBG 6.1.1 installations unchanged.acsi script de_lsapp -verbose.
This .bat(.sh) script is found in /usr/ibm/common/acsi/bin
on a Unix system or in c:\Program Files\IBM\Common\acsi\bin
on a Windows sytem. It lists all registered applications and their discriminants.
Caused by: java.lang.RuntimeException:
com.ibm.websphere.management.exception.ConnectorException:
ADMC0053E: The system cannot create a SOAP connector to connect to host
localhost at port 18881 with SOAP connector security enabled.
followed by (a bit farther down)
Caused by:
com.ibm.websphere.management.exception.ConnectorNotAvailableException:
[SOAPException: faultCode=SOAP-ENV:Client; msg=Error opening socket:
javax.net.ssl.SSLHandshakeException: com.ibm.jsse2.util.h: No trusted
certificate found; targetException=java.lang.IllegalArgumentException:
Error opening socket: javax.net.ssl.SSLHandshakeException:
com.ibm.jsse2.util.h: No trusted certificate found]
script.jacl:
set security_item [$AdminConfig list Security]
set argv0 [lindex $argv 0]
set value null
if {[regexp $argv0 enable]} { set value true }
if {[regexp $argv0 disable]} { set value false }
if {[regexp $value null]} {
puts "Wrong parameter, use enable / disable"
return
}
$AdminConfig modify $security_item [list [list enabled $value]]
$AdminConfig save
then executing it from the wsadmin of the console's WAS/eWAS as follows:
wsadmin -username was-adminname -password was-password -f script.jacl [enable | disable]
Caused by: java.lang.UnsupportedClassVersionError:
javax/management/NotificationListener (Unsupported major.minor version 49.0)
/scripts/install.sh to install a fix pack.
This script runs the TFIMBG fix pack installer which requires Java 1.5.SI_JAVA_HOME
on line 44 of /var/ibm/common/acsi/setenv.sh. The normal installation
of TFIMUI points this at a Java 1.5 JVM so there is usually no problem.
The work-around for IZ01850 can leave this variable
pointing at a Java 1.4.2 JVM. The TFIMBG fix pack installer requires Java
1.5.The current TFIM FSSO documentation does not sufficiently document the limitations of the TFIM alias service.
An alias is created when a user agrees to federate their
service provider account with an associated account on an
identity provider. At the end of the federate action an
LDAP alias service on the identity provider will include a
secselfalias and an LDAP alias service on the service
provider
will have a secpartneralias.
Note that only 1 account on a service provider should be
federated to any given identity provider account. Multiple
accounts on different service providers can be federated to
the same account on the identity provider, but only one
account on any given service provider should be federated
with any given account on the identity provider. The
secselfalias generated for a partner, as described in the
product
documentation (Tivoli Federated Identity Manager
Single Sign-on Guide, Chapter 8. Alias Service) contains
as part of the value the ProviderId value of the partner
(service provider) that it is associated with. The rest of
the value of the secselfalias is the randomly generated
alias, so if there are multiple aliases for the same
ProviderId, there is no mechanism for determining which
alias should be provided in an assertion generated for
consumption by that partner.
For example, a user John Smith has accounts jsmith and
jsmith1 on Service Provider 1, johns on
Service Provider 2,
and JohnSmith on the Identity Provider. Both jsmith
and
johns can be federated with the JohnSmith
account, but only
jsmith or jsmith1 should be federated with
the JohnSmith
account. Otherwise, the principal specified in the
generated assertion by the identity provider is indeterminate,
since there are multiple accounts from the same service
provider that are federated with the same identity provider
account. Once John Smith has authenticated to Identity
Provider, and wishes to access resources on Service Provider
1, the alias that is stored in the alias service associated
with the account JohnSmith for Service Provider 1 is
provided
in the assertion sent to Service Provider 1. If there are
multiple aliases for Service Provider 1, it is undefined
which alias will be provided by Identity Provider in the
generated assertion.
The alias values can be updated by performing a NameID update.
The update will change the secselfalias of the identity provider
and secpartneralias of the service provider. This action can be
initiated at either the identity provider or the service provider.
The secselfalias generated for a partner, as described in the
product documentation (Tivoli Federated Identity Manager
Single Sign-on Guide, Chapter 8. Alias Service), contains as part of the value
the ProviderId value
of the partner that it is associated with. The rest of the value
of the secselfalias is the randomly generated alias, so
if there are
multiple aliases for the same ProviderId, there is no
mechanism for
determining which alias should be provided in an assertion generated
for consumption by that partner.
Intermittent failures validating messages received can occur in a TFIM environment if the JVM does not have the fix for IY93387.
Errors in the trace file indicate a falure to validate the received XML:
[9/7/07 17:05:27:807 EST] 0000002d KessServiceJk 3
com.tivoli.am.fim.kess.service.jks.worker.impl.KessServiceJksWorkerImpl
validateXML The certificate retrieved for xml signature validation was:
[
[
Version: V3
Subject: CN=Certificate Name :7100000475, O=Company, C=US
Signature Algorithm: SHA1withRSA, OID = 1.2.840.113549.1.1.5
Key: IBMJCE RSA Public Key:
modulus:
<...modulus value removed...>
public exponent:
65537
Validity: [From: Wed Nov 01 14:28:26 EST 2006,
To: Sun Mar 30 11:46:30 EST 2008]
Issuer: CN=TEST Cert, O=TestCert Company, C=US
SerialNumber: [1162351707]
<...cert information removed for brevity ...>
[9/7/07 17:05:27:813 EST] 0000002d KessServiceJk 3
com.tivoli.am.fim.kess.service.jks.worker.impl.KessServiceJksWorkerImpl
validateXML
Signature was NOT valid on the XML document.
Core Validity: false
SignedInfo: false
Msg: SignatureValue mismatched.
...
This problem is resolved by the APAR IY93387 and is fixed in the JVM 1.4.2 SR9 and JVM 5.0 SR4.
The Java SDK 1.4.2 SR9 fix level can be downloaded from its download page.
The Java SDK 1.5 SR5 fix level can be downloaded from download page.
The fix pack installation of the TFIM runtime must connect to a WAS's SOAP port in order to deploy
the runtime. The fix pack installer acquires its SOAP port value from the following line
in the
/<TFIM-installation-directory>/pkg/software.properties file
of the TFIM instance being patched:
was.soap.port=8880
This value was placed there when the TFIM instance was installed.
For the connection to be successful the WAS being deployed to must still be using that SOAP port.
If it is not then the TFIM fix pack installation fails with lines like the following
in the de_trace.log file:
Caused by: com.ibm.websphere.management.exception.ConnectorNotAvailableException: [SOAPException:
faultCode=SOAP-ENV:Client; msg=Error parsing HTTP status line "...":
java.util.NoSuchElementException; targetException=java.lang.IllegalArgumentException:
Error parsing HTTP status line "...": java.util.NoSuchElementException]
where the "..." are binary bytes from the bad status line.
The SOAP port being used by the WAS is reported at startup in the SystemOut.log file as follows:
ADMC0013I: The SOAP connector is available at port 8886
If the two SOAP port values differ, then change the value in TFIM's
software.properties file to agree with the port being used by WAS and
reapply the fix pack.
On a system with TDI (Tivoli Directory Integrator) 6.1 already installed, the install of a the ITFIMUI may fail with the following output:
Installing Tivoli Federated Identity Manager - Update Installer.
Please wait...
|-----------|-----------|-----------|------------|
0% 25% 50% 75% 100%
||||||||||||||||||||||||||||||||||||||||||||||||||ACUINI0012I
Deployment Engine Installation Failed!
Causes:
com.ibm.ac.si.install.upgrade.DBMigrateException:;java.lang.reflect.InvocationTargetException:null;com.ibm.db2.jcc.c.vd:Non-atomic batch failure.
The batch was submitted, but at least one exception occurred on an individual member of the batch.
Use getNextException() to retrieve the exceptions for specific batched elements.
Entering FakeDeRegistry::execute
Loading input properties from: /opt/IBMFIM61
Found: #RunTimeAndManagementFeat
Found: #FIMConsoleFeat
Found: #FIMWssmFeat
Writting out translated properties to :
/opt/IBMFIM61/FIMUI/DE/test/selectedfeatures
Exiting FakeDeRegistry::execute
Before calling this installation script please call setenv.sh
Updating the inventory ...
Creating uninstaller...
-------------------------------------------------------------------------------
The InstallShield Wizard has successfully installed Tivoli Federated Identity Manager - Update Installer. Choose Finish to exit the wizard.
The problem has only been reported when the TDI 6.1 product is installed first and then ITFIMUI is installed.
To work around this issue, the following workaround steps must be performed:
si_inst.sh script (located in the DE installation
directory, typically /usr/ibm/common/acsi/bin/si_inst.sh for
UNIX/Linux platforms and C:\Program Files\IBM\common\acsi\bin\si_inst.bat
on Windows platforms). This will install DE 1.3 using the Java 1.4.2
configured by TDI 6.0. <fix-pack-directory>/script/install.sh
on UNIX/Linux, <fix-pack-directory>\script\install.bat on Windows).
This will register TFIMBG 6.1.1 in the DE database. A limitation of the z/OS platform can cause TFIM actions to hang and fail. This has been observed with the deployment of the TFIM runtime, and can be diagnosed by examining the WAS log file and looking for a WARNING message such as the following:
Trace: 2008/02/20 15:30:48.909 01 t=9BE748 c=UNK key=P8 (13007002)
ThreadId: 00000044
FunctionName: com.ibm.ws.runtime.component.ThreadMonitorImpl
SourceId: com.ibm.ws.runtime.component.ThreadMonitorImpl
Category: WARNING
ExtendedMessage: BBOO0221W: WSVR0605W: Thread "WebSphere:ORB.thread.pool t=009c22b8"
(00000022) has been active for 181010 milliseconds and may be hung.
There is/are 1 thread(s) in total in the server that may be hung.
To resolve this problem, a WAS environment variable must be defined that increases an essential thread pool size.
To define the environment variable for a standalone application server from the WebSphere administration console, browse to: "Servers" -> "Application servers" -> server_name -> "Server Infrastructure" -> "Administration" -> "Custom properties".
Add the property private_bboo_internal_work_thread_pool_size
with the value of 5.
To define the environment variable for a network deployment configuration from the WebSphere administration console, browse to: "System Administration" -> "Deployment manager" -> "Administration services" -> "Custom properties".
As in the standalone environment, add the property
private_bboo_internal_work_thread_pool
size with the value of 5.
Restart the WAS server that has had the environment changed. To verify that the new value has taken effect, when the server starts look for this message in the output of the server:
BBOM0001I private_bboo_internal_work_thread_pool_size: 5.
These failures have currently only been reported on the deployment of the TFIM runtime, and the value of 5 has resolved the issue. However, if similar error messages are seen performing other TFIM activities, the pool size environment variable should be increased to resolve the problem.
The TFIM 6.1.1 documentation lists the supported user registries in the "User Registry support" section of the "Hardware and Software Requirements" document.
This document lists support for Novell eDirectory 8.6.x and Novell eDirectory 8.7.x. This section does not list Novell eDirectory 8.8.x, because eDirectory 8.8 was not available at the time and the TAM Base product did not claim support for this level yet. However, TAM claimed support for Novell eDirectory 8.8 in the TAM Base 6.0.0 FP0009 README.
Based upon this information, it would seem that TFIM would support eDirectory 8.8.x as a user registry. Support for eDirectory 8.8.x was verified, but in the process it was found that additional configuration steps for eDirectory were required in order to be used by TFIM successfully. These configuration steps are not in the current documentation, so a Tech Note has been written and published that documents the required actions to configure the Novell eDirectory to be a supported TFIM user registry.
The TechNote entitled "Configuration of Novell eDirectory v8.8 required to be a supported TFIM v6.1.1 user registry" has been published and is publicly available on the TFIM support site.
This TechNote MUST be consulted and followed before attempting to use the Novell eDirectory as a TFIM user registry.
Because this is a defect in the Installer, it cannot be fixed in a fix pack. Consequently it is a permanent restriction in TFIM 6.1.1. The same code is used by the fix pack installer so the same restriction applies to fix pack installations.
TechNote #1307656 entitled "A $ symbol in a truststore or key store password prevents installation" documents work-arounds for this restriction and is publicly available on the TFIM support site.
Because this is a defect in the Installer, it cannot be fixed in a fix pack. Consequently it is a permanent restriction in TFIM 6.1.1. The same code is used by the fix pack installer so the same restriction applies to fix pack installations.
Tech Note #1314890 discusses this permanent restriction in more detail.
The TFIM 6.1.1 installer assumes that the WAS profile to which TFIM is being
deployed is listening on localhost. If not, then the work-around
given in
Tech Note #1315020
must be followed.
Because this failure is caused by a WAS administration error, it cannot be fixed in a fix pack. Consequently it is a permanent restriction in TFIM 6.1.1. The same code is used by the fix pack installer so the same restriction applies to fix pack installations.
Tech Note #1315672 discusses the work-around for this permanent restriction in more detail.
When TFIM 6.1.1 is installed with WebSphere security turned off initially then WAS security is turned on, the TFIM file fim.appserver.properties file can become out of sync with the WebSphere configuration. As such, the FIM 6.1.1 fixpack installation will fail with a soap error. An example error that can occur is similar to the following:
...
java.lang.RuntimeException: com.ibm.websphere.management
.exception.ConnectorException: ADMC0016E: The system cannot
create a SOAP connector to connect to host localhost at port
8880.
...
The following should be performed to fix the problem:
Save a copy of the fim.appserver.properties
file, which is located in
FIM_INSTALL_ROOT/etc/fim.appserver.properties
(for example,
/opt/IBM/FIM/etc/fim.appserver.properties).
An example
copy of the fim.appserver.properties file is as follows if
you are using WAS:
#
#WAS configuration information.
#Fri Aug 15 11:47:53 CDT 2008
itfim.mgmtcon.use.existing.was=true
itfim.rte-mgmtsvcs.use.existing.was=true
was.security.enabled=false
was.soap.port=8880
was.install.location=/opt/IBM/WebSphere/AppServer
Modify the fim.appserver.properties file
(changes highlighted in bold) similar to the conifguration
noted below. Be sure sure to add the correct values that
correspond to your system environment.
#
#WAS configuration information.
#Fri Aug 15 11:47:53 CDT 2008
itfim.mgmtcon.use.existing.was=true
itfim.rte-mgmtsvcs.use.existing.was=true
was.truststore.file=/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/etc/trust.p12
was.security.enabled=true
was.soap.port=8880
was.install.location=/opt/IBM/WebSphere/AppServer
was.admin.user.id=wasadmin
Run the TFIM 6.1.1 fixpack installation again.
Note that if you are using eWAS, a modified version of the
fim.appserver.properties may be similar to the configuration
noted below. Again, be sure to add the correct values that
correspond to your system environment.
#
#eWAS configuration information.
#Tue Aug 19 11:11:55 CDT 2008
itfim.mgmtcon.use.existing.was=false
itfim.rte-mgmtsvcs.use.existing.was=false
ewas.soap.port=8881
ewas.truststore.file=/opt/IBM/FIM/ewas/profiles/itfimProfile/etc/trust.p12
ewas.admin.user.id=wasadmin
ewas.security.enabled=true
ewas.install.location=/opt/IBM/FIM/ewas
Because this problem occurs at install time it cannot be fixed in a fix pack. Consequently it is a permanent restriction in TFIM 6.1.1. The same code is used by the fix pack installer so the same restriction applies to fix pack installations.
Tech Note # 1316262 discusses the work-arounds for this permanent restriction in more detail.
A TFIMBG 6.1.1 fix pack can fail to install because the TFIMUI installation quietly failed due to insufficient space in one or more partitions of the disk. This is especially problematic on Unix, where TFIMUI lays down files in /opt, /usr, and /var, which may be independently allocated. Close examination of the de_install.log and de_trace.log files is needed to determine the cause of these failures. They can be prevented by making sure sufficient free space exists before the installations are started.
To avoid insufficient space failure see Tech Note # 1323199 to understand the required space.
Insufficient space failures are rare on Windows because the entire C:\ drive must be almost full for them to happen. Therefore this discussion will talk in terms of the Unix case.
TFIMUI installation failures do not appear on the console. The TFIMUI installation always claims it succeeded. If a fix pack installation fails then look at the
/usr/ibm/common/acsi/de_install.log
file for real TFIMUI installation failures, like exceptions or lines like
File extraction failed, error = 6
(Cannot write file (out of space))
Installation failed, rolling back
Recovery from such a TFIMUI installation failure where part of TFIMUI and DE may have been laid down in /opt, /usr, and/or /var requires the following steps:
/opt/IBM/FIMUI/_uninst/uninstaller.binrm -rf /opt/IBM/FIMUI/usr/ibm/common/acsi/bin/si_inst.sh -r
if possible. If not, then stop the acsi
service (if running) and remove the acsi
service's entry in /etc/host (if present)rm -rf /usr/ibm/common/acsirm -rf /var/ibm/common/acsiNow, if sufficient free space is available then a TFIMUI installation and a TFIMBG 6.1.1 fix pack installation will succeed.
If you install a Tivoli Federated Identity Manager Business Gateway component to the system after the fix pack has been applied, you must reinstall the fix pack on that system, so that all components are at the same level.
To re-apply the fix pack:
<TFIM-UPDATE-INSTALLER>/DE/test/
<TFIM-UPDATE-INSTALLER> is the directory
where the update installer was installed../addconsolefeat.sh on AIX, Linux, Solaris, or HP-UXaddconsolefeat.bat on Windows./addmgmtfeat.sh on AIX, Linux, Solaris, or HP-UXaddmgmtfeat.bat on Windowsaddiisplugin.bat on WindowsNone.
This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan
The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions; therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information that has been exchanged, should contact:
IBM Corporation
2Z4A/101
11400 Burnet Road
Austin, TX 78758
U.S.A.
Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.
Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurement may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.
All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only.
This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.
The following terms are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both:
AIX
IBM
IBM logo
iSeries
pSeries
S/390
Tivoli
Tivoli logo
xSeries
zSeries
Adobe, Acrobat, Portable Document Format (PDF), and PostScript are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States, other countries, or both.
Java and all Java-based trademarks and logos are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Other company, product, and service names may be trademarks or service marks of others.