| Oracle® Identity Federation Administrator's Guide 10g (10.1.4.0.1) Part Number B25355-02 |
|
|
View PDF |
| Oracle® Identity Federation Administrator's Guide 10g (10.1.4.0.1) Part Number B25355-02 |
|
|
View PDF |
This chapter describes additional Oracle Identity Federation administration topics, including:
Oracle Identity Federation provides configuration assistants to support the following tasks:
modification of the transient data store
server uninstallation
Configuration Assistant for Changing the Transient Data Store
This Configuration Assistant allows you to change the type of transient data store used by your Oracle Identity Federation server. You can switch from a memory-based transient store to an RDBMS-based store, or from an RDBMS-based store to a memory-based store.
The Configuration Assistant performs these tasks:
Connects to the RDBMS to create Oracle Identity Federation database tables, if necessary
Packages the application with the new transient data store type
Redeploys Oracle Identity Federation
Updates the Oracle Identity Federation configuration to reflect the new transient data store type
For more information about these tasks, see "Configuration Assistant Operations".
See "Command-Line Configuration Assistant to Change the Transient Data Store" for usage details.
Configuration Assistant for Uninstallation
A Configuration Assistant can also be invoked as a command-line tool to perform server deinstallation. See "Command-Line Configuration Assistant for Uninstallation" for usage details.
This section contains these topics:
The following requirements must be met for the Configuration Assistants to execute properly:
The files used by Oracle Identity Federation and the components it relies upon must be copied to their respective locations.
OC4J must be installed and running.
The deployment tool (dcmctl) must be installed and available to the Configuration Assistant.
The Configuration Assistant must be run from the operating system account which has the correct privileges to access and configure OC4J.
If Oracle Identity Federation is configured to use an LDAP repository to store the federation records, that server must be up and running.
If configuring RDBMS as the new transient data store, a TNS Name must be defined locally referencing the database instance to be used. Refer to the Net Configuration Assistant to create a Local Net Service Name Configuration entry.
Before executing any tasks, the Configuration Assistant validates the parameters you specify on the command line. The assistant can:
verify that the required parameters are present and have valid values
check any connection parameters to LDAP or RDBMS servers by connecting to them
In case of a validation error, the Configuration Assistant displays an error message and returns a status code failure.
The Configuration Assistant performs a number of tasks related to Oracle Identity Federation maintenance:
The Configuration Assistant configures and maintains back-end repositories needed for various tasks including federation records and artifact, message, and session information.
After updating the ear application file with the configuration data supplied through Oracle Universal Installer, the Configuration Assistant deploys Oracle Identity Federation on the OC4J instance.
This section provides details about Oracle Identity Federation command-line tools:
Oracle Identity Federation include a command-line tool that enables the administrator to perform bulk loading of user federation records.
By way of background, note that a federation represents an account linking between a user and two providers. Typically, the two providers agree to identify the individual using the data contained in the federation. When a federation is created, therefore, these providers will have agreed to use some specific piece of information to identify that user.
The bulk federation utility lets the administrator create an ldif file which can then be used to create federation records in an LDAP repository, and these federation records will be linked to users and peer providers.
The steps are as follows:
The utility reads instructions from an input file. For a specific federation record, the input data may contain the identifier of the user who will own the federation, the id of the peer provider with which the federation will be linked, and other parameters.
An ldif file containing LDAP commands is produced.
The administrator then executes the ldif file to populate the target LDAP server with federation records.
Thus the tool does not directly interact with the LDAP server, and the administrator is able to analyze the changes to the repository before bulk-loading federation data.
In addition to creating an ldif file for the LDAP server, the utility generates a result file that contains a list of all federations created. The administrator can then communicate this file to the peer provider for whom the federations are created, since the peer likewise needs to load the corresponding federation information in its repository.
Operating Modes of the Bulk Federation Utility
The bulk-loading tool operates in two modes:
A create mode that uses a limited set of data (user id, peer provider id, and so on) to create:
the federation data
the corresponding LDAP commands
A read mode that reads the input file containing the federation data; in this mode, the tool generates only the ldif file containing the LDAP commands, but no federation data is created.
Bulk Loading Flow
As an example, consider two providers named SP-A and IdP-B. Each provider has 10 users on its system, and the administrators wish to create federations for all of these users using the bulk federation load utility.
The steps they will take to achieve this are as follows:
One of the providers (for example, SP-A) creates an input file listing the federations to be created. For each federation data to be created, it contains: the user ID at SP-A, the remote provider ID (IdP-B), and some additional information.
The SP-A administrator next uses the bulk load tool in create mode; the tool reads the input file and creates two files: the ldif file containing LDAP commands for the SP-A federation LDAP server, and an output file of federation data.
The SP-A administrator uses the ldif file to populate SP-A's LDAP Federation server: at the completion of this step, the federation records have been created at SP-A.
At IdP-B, the administrator receives the output file and uses that file with the bulkload utility in read mode: the tool reads that file and creates an ldif file containing LDAP commands.
Finally, the IdP-B administrator executes the LDAP commands against its LDAP Federation server to create federation records in IdP-B: at that point, the federations are existing at both providers.
In create mode, the tool generates new federation account-linking data based on the contents of an input file. For each federation record, the input file contains the following information:
Table 9-1 Fields of Input File in Create Mode of Bulk Load
| Field | Description | Required? |
|---|---|---|
|
UserID |
This is the user identifier used by Oracle Identity Federation to uniquely reference a user in the user data store. |
Yes |
|
UserDescription |
This is the human-readable user identifier that will be set on the LDAP federation record. |
Yes |
|
ProviderID |
This is the identity of the peer provider with which the federation is created. |
Yes |
|
Version |
This is the federation version. Specify 1.1, 1.2, or 2.0. |
Yes |
|
Type |
This is the type of federation. The possible values are:
|
Yes |
|
AffiliationID |
This is the AffiliationID in configurations where Oracle Identity Federation acts as an affiliation. Note: This is not the ProviderID of Oracle Identity Federation. |
Yes, if Type is OIF_AFFILIATION_IDP |
Here is a sample input file for use in the create mode:
UserID: user1b1 UserDescription: user1bb1 ProviderID: http://sp.oracle.com Version: 2.0 Type: OIF_IDP_SP UserID: user1b2 UserDescription: user1bb2 ProviderID: http://sp.oracle.com Version: 2.0 Type: OIF_IDP_SP UserID: user1b1 UserDescription: user1bb1 ProviderID: http://idp.oracle.com Version: 2.0 Type: OIF_SP_IDP
In read mode, the tool reads and processes existing federation account-linking data from the input file without creating any new federations. For each federation record the input file will contain the following information:
Table 9-2 Fields of Input File in Read Mode of Bulk Load
| Field | Description | Required? |
|---|---|---|
|
UserID |
This is the user identifier used by Oracle Identity Federation to uniquely reference a user in the user data store. |
Yes |
|
UserDescription |
This is the human-readable user identifier that will be set on the LDAP federation record. |
Yes |
|
ProviderID |
This is the identity of the peer provider with which the federation is created. |
Yes |
|
Version |
This is the federation version. Specify 1.1, 1.2, or 2.0. |
Yes |
|
Type |
This is the type of federation. The possible values are:
|
Yes |
|
AffiliationID |
This is the AffiliationID in configurations where Oracle Identity Federation acts as an affiliation. Note: This is not the ProviderID of Oracle Identity Federation. |
Yes, if Type is OIF_AFFILIATION_IDP |
|
IdPNameID |
This is the federation's IdP Name Identifier. |
Yes |
|
SPNameID |
This is the federation's SP Name Identifier. |
No |
|
Format |
This is the format of the federation's Name Identifier. |
No |
|
Qualifier |
This is the qualifier of the federation's Name Identifier. |
No |
Here is a sample input file for use in the read mode:
userid: user1b1 userdescription: user1bb1 providerid: http://sp.oracle.com idpnameid: id-SHMeaEZkk4jqiHl32BmmIAcBy4o- format: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent qualifier: http://sp.oracle.com version: 2.0 type: OIF_IDP_SP userid: user1b2 userdescription: user1bb2 providerid: http://sp.oracle.com idpnameid: id-QTqtXv13IE493asxqGF-CoeBuRM- format: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent qualifier: http://sp.oracle.com version: 2.0 type: OIF_IDP_SP userid: user1b1 userdescription: user1bb1 providerid: http://idp.oracle.com idpnameid: id-He4Nvgeiz4BLzhRhlPzebViLQbU- format: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent qualifier: http://stadm04.us.oracle.com:7780/fed/sp version: 2.0 type: OIF_SP_IDP
In both create and read modes, the tool produces three output files:
an ldif file
a result file
an error file
LDIF File
This file contains the LDAP statements an administrator will need to execute against the LDAP server. Executing the ldif file populates the server with user federation records. You typically achieve this by using an ldapmodify command of the form:
ldapmodify –a –c –x –D "cn=Admin,dc=example,dc=com" –w PASSWORD
-h LDAP_HOSTNAME –p LDAP_PORT –f LDIF_FILE
Result File
The result file contains information about the federation records that were created. This file is typically communicated to third party providers, who use it to populate their federation repository with corresponding federation records.
See Table 9-2 for a description of the result file.
Error File
The error file contains records of any input entries that could not be processed. The error record consists of:
UserID - this is the identifier used by Oracle Identity Federation to uniquely reference a user in the data store.
ProviderID - this is the identity of the peer provider with which the federation is created.
The bulk load utility is invoked at the command line as follows:
java –jar bulkload.jar <parameters>
The parameters are:
-f INPUT_FILE - This is the file with the information specifying the federation records to create.
-dir OUTPUT_DIR - This is the directory in which to create the output files such as the ldif file, the result file and the error file.
-oifdir OIF_DIR - This is the top-level Oracle Identity Federation directory. Typically it is the directory containing the bin, conf, lib and log directories.
-c - This is the create mode. It specifies that federation records need to be created. The tool will generate IdPNameID, Format and Qualifier fields.
-r - This is the read mode. It specifies that the federation records information is contained in the input file and no federation data should be created, instead it should be read from the file to produce the ldif and result files.
Example 1
java -jar fed/lib/bulkload.jar -f user-fed-data.dat -dir /saveDir -oifdir $ORACLE_HOME/fed -c
This command directs the tool to read a file containing a list of users for which federations are to be created, and produce 1) an ldif file that the administrator can execute against its LDAP server to create the records, and 2) another file that contains the federation information that should be sent to the peer providers for which the federations were created.
Example 2
java -jar fed/lib/bulkload.jar -f peer-user-fed-data.dat -dir /saveDir -oifdir $ORACLE_HOME/fed -r
This command directs the tool to read a file sent by a peer provider (a file that was created by the bulk load tool, for example), and to create an ldif file based on that input file that would contain commands to create federation records.
Example 3
This example brings together the concepts described earlier in this section, to illustrate all the steps to achieve a bulk load of federation users from beginning to end.
In this example, the input file of users is created at the IdP side, and the IdP federation server is populated. The result file is then used at the SP to generate the necessary data to populate the data records at the SP server.
Create the input file.
UserID: buser9 UserDescription: buser9 ProviderID: http://platinum-ob.us.oracle.com:7780/fed/sp Version: 1.2 Type: OIF_IDP_SP UserID: buser10 UserDescription: buser10 ProviderID: http://goofy.us.oracle.com:7785/fed/sp Version: 1.2 Type: OIF_IDP_SP
Navigate to the Oracle_Home\fed\lib directory and generate the result.ldif and result.txt files. For example:
D:\osfshome2\jdk\bin\java -jar bulkload.jar -f users -dir D:\osfshome2\fed\lib -oifdir D:\osfshome2\fed -c
Import the result.ldif into the IdP directory. For example:
ldapmodify -h platinum-ob.us.oracle.com -a -f result.ldif -D "cn=orcladmin" -w malibu97 -p 13060
Copy the result.txt file to the SP, and modify the file to conform to the SP; this means changing the serverid, type, userid, userdescription, and providerid values.
At the SP, read the result.txt file into the bulk tool to generate an ldif file. For example:
C:\OraHome_030306>jdk\bin\java -jar fed\lib\bulkload.jar -f c:\orahome_030306\fed\lib\result.txt -dir c:\orahome_030306\fed -oifdir c:\orahome_030306\fed -r
Import the resulting ldif file into the directory at the SP:
ldapmodify –a –c –x –D "cn=Directory Manager" –w 97malibu –h akeim2.us.oracle.com –p 440 –f result.ldif
Users should now be able to do single sign-on without having to log in at the SP, because the federations already exist.
For a description of this utility, see "Configuration Assistants".
The installation configuration assistant is invoked at the command line as follows (the tool will prompt for the RDBMS password):
java -jar $ORACLE_HOME/fed/lib/install.jar <parameters>
The parameters are:
-oh $ORACLE_HOME - This is the location of the ORACLE_HOME variable referencing the Oracle Application Server installation directory. Required.
-transient <TYPE> This is the type of repository to use as the transient data store in Oracle Identity Federation. The possible values are memory or rdbms. Required.
-dbtnsname <TNSNAME> - This is the RDBMS TNS name. Required if an RDBMS is used for the transient data store.
-dbusername <USERNAME> - This is the RDBMS username. Required if an RDBMS is used for the transient data store.
-uselocalconfig <BOOLEAN> - This is an optional parameter that can be used with -transient rdbms, to control whether this instance's local configuration settings will overwrite any settings currently stored in the database. The possible values are "true" or "false". If "true", configuration settings in the Oracle Identity Federation server's local files will replace any settings currently stored in the selected database. If "false", or this parameter is omitted, settings stored in the RDBMS (if there are any) will overwrite the local configuration files. The default is "false".
As mentioned earlier, this is an optional parameter that can be specified if an RDBMS is used for the transient data store.
Requirements
Prior to running the configuration assistant, set the following environment variables:
$ORACLE_HOME: environment variable referencing the Oracle Home directory. For example:
Windows
set ORACLE_HOME=c:\DIR
Linux bash shell
export ORACLE_HOME=/DIR
On Linux, you need to set the LD_LIBRARY_PATH to include the $ORACLE_HOME/lib directory. This assumes that the ORACLE_HOME environment variable is already set. For example:
export LD_LIBRARY_PATH=$ORACLE_HOME/lib
On Windows, you need to set the PATH environment variable to include the %ORACLE_HOME%/lib and %ORACLE_HOME%/bin directories. This assumes that the ORACLE_HOME environment variable is already set. For example:
set PATH=%ORACLE_HOME%/bin;ORACLE_HOME%/lib;%path%
Example 1
$ORACLE_HOME/jdk/bin/java -jar $ORACLE_HOME/fed/lib/install.jar -oh ORACLE_HOME -transient memory
Note that the transient data will be stored in memory.
Example 2
$ORACLE_HOME/jdk/bin/java -jar $ORACLE_HOME/fed/lib/install.jar -oh ORACLE_HOME -transient rdbms -dbusername USERNAME -dbtnsname TNSNAME
Note that the transient data will be stored in RDBMS.
The configuration assistant provides an uninstall feature to perform the following operations:
Destroy all federation records created by the Oracle Identity Federation server being un-installed.
Destroy all auxiliary and non sensitive data if all federation records were destroyed in the first step. Oracle Identity Federation is the only server using the LDAP federation server to store data, so it is safe to destroy the structural data.
Remove the attributes and object classes that the configuration assistant added to the LDAP schema at installation time.
Note:
This feature is not supported for Microsoft Active Directory as the directory does not allow entries to be removed from its schema.Destroy the RDBMS transient tables, if any, used to store persistent data.
The configuration assistant notifies the un-installer if:
Oracle Identity Federation used an RDBMS database to store persistent data
An LDAP store was used to store federation records
If an LDAP or RDBMS operation needs to be performed, the uninstallation tool would prompt for LDAP or RDBMS connection information that is then passed to the configuration assistant. That way, the administrator can specify the correct information and credentials required to perform administrative tasks in the LDAP or RDBMS server.
See Also:
For complete Oracle Identity Federation uninstallation procedures, see "Un-installing Oracle Identity Federation"The uninstallation configuration assistant is invoked at the command line as follows (the tool will prompt for the LDAP/RDBMS password):
java -jar $ORACLE_HOME/fed/lib/uninstall.jar <parameters>
The parameters are:
-uninstall - Launches the uninstallation process. Required.
-oh ORACLE_HOME - This is the location of the ORACLE_HOME variable referencing the OracleAS installation directory. Required.
-removefed true|false - Indicates whether to remove federation records from the LDAP server.
-ldap true|false - Indicates whether to remove the Oracle Identity Federation schema from the LDAP server.
-ldaptype - Indicates the type of repository. The possible values are oid, msad, iplanet, and tivoli.
-ldapurl - This is the LDAP URL.
-ldapusername - This is the username of the LDAP administrator.
-db - Indicates whether to remove transient Oracle Identity Federation tables from the RDBMS server.
-dbtnsname <TNSNAME> - This is the RDBMS TNS name. Required if -db is true.
-dbusername <USERNAME> - This is the RDBMS username. Required if -db is true.
Note:
To see a list of parameters and possible values, run the tool without specifying any parameters.Requirements
If you plan to remove the RDBMS tables created by Oracle Identity Federation, take these steps prior to running the uninstallation tool:
Set environment variables.
On Linux
Set the LD_LIBRARY_PATH variable to include the $ORACLE_HOME/lib directory. This assumes that the ORACLE_HOME environment variable is already set. For example:
export LD_LIBRARY_PATH=$ORACLE_HOME/lib
On Windows
Set the PATH environment variable to include the %ORACLE_HOME%/lib and %ORACLE_HOME%/bin directories. This assumes that the ORACLE_HOME environment variable is already set. For example:
set PATH=%ORACLE_HOME%/bin;ORACLE_HOME%/lib;%path%
Retrieve the TNS Name referencing the RDBMS. This value, which you can find in the $ORACLE_HOME/network/admin/tnsnames.ora file, is the identifier referencing the connection information used to connect to the database.
Example 1
java -jar fed/lib/uninstall.jar -uninstall -oh $ORACLE_HOME -removefed true -ldap false -ldapurl ldap://ldap.com -ldapusername admin -db false
This command removes all the federation records from the LDAP server.
Example 2
java -jar fed/lib/uninstall.jar -uninstall -oh ORACLE_HOME -removefed true -ldap true -ldaptype oid -ldapurl ldap://ldap.com -ldapusername admin -db false
This command:
removes all the federation records from the LDAP server
removes the Oracle Identity Federation schema from the LDAP server
Example 3
java -jar fed/lib/uninstall.jar -uninstall -oh ORACLE_HOME -removefed true -ldap true -ldaptype oid -ldapurl ldap://ldap.com -ldapusername admin -db true -dbtnsname orcl -dbusername scott
This command:
removes all the federation records from the LDAP server
removes the Oracle Identity Federation schema from the LDAP server
removes the transient Oracle Identity Federation tables from the RDBMS server
With the 10.1.4.2.0 patch set, Oracle Identity Federation provides a new command line tool to perform bulk delete operations of federation records from the Federation Data Store.
This tool removes federation records directly from the LDAP server used as the Federation Data Store without notifying the remote provider; thus, the Liberty 1.x/SAML 2.0 protocols will not be exercised to notify the provider that the federation record was locally deleted.
Use the tool to remove federation records when:
the remote provider no longer exists
the remote provider is not in the circle of trust
the remote provider does not support the Federation Termination protocols
the local administrator wishes to remove federation records without notifying the remote provider
Note:
To remove a federation record and notify the remote provider, use the Identity Federation tab in the Oracle Identity Federation Administration Console to delete the federation: that operation will connect to the remote provider to indicate that the record is being deleted.You can use the federation delete tool in different ways:
to remove all federation records of a specific user
to remove all federation records linked to a specific remote provider
to remove all federation records of a list of users
Examples of each type of usage appear below.
Invoke the federation delete tool at the command line as follows (the LDAP password is entered during command execution):
java -jar $ORACLE_HOME/fed/lib/fedadmin.jar <parameters>
The parameters are:
-oh ORACLE_HOME - This is the ORACLE_HOME directory. Required.
-ldapurl url - the URL of the LDAP Federation Data Store
-ldapusername username - the LDAP username to use to connect to the LDAP Federation Data Store
-providerid id - the Provider ID for which federations need to be removed
-userid id - the user ID for which federations need to be removed
-useridfile file - absolute path to the file containing the list of user IDs for which federations need to be removed
Example 1
To remove all federation records of a specific user, the administrator specifies the identifier of the user.
For example, the following command deletes all federation records belonging to the user alice:
java -jar $ORACLE_HOME/fed/lib/fedadmin.jar -oh $ORACLE_HOME -ldapurl ldap://ldap.com -ldapusername ADMIN -userid alice
Note:
The identifier value must be of the same type as the User ID Attribute configured in the User Data Store section of the Oracle Identity Federation Administration Console.Example 2
To remove all federation records linked to a specific remote provider, the administrator specifies the Provider ID of the remote provider.
For example, the following command deletes all federation records linked to the provider identified by http://idp.com/idp:
java -jar $ORACLE_HOME/fed/lib/fedadmin.jar -oh $ORACLE_HOME -ldapurl ldap://ldap.com -ldapusername ADMIN -providerid http://idp.com/idp
Example 3
To remove all federation records of a list of users, the administrator specifies a file containing identifiers of the users:
For example, the following command:
java -jar $ORACLE_HOME/fed/lib/fedadmin.jar -oh $ORACLE_HOME -ldapurl ldap://ldap.com -ldapusername ADMIN -useridfile users.txt
where the file users.txt contains:
alice bob charlie
deletes all federation records belonging to users alice, bob, and charlie.
Note:
The identifier values must be of the same type as the User ID Attribute configured in the User Data Store section of the Oracle Identity Federation Administration Console.This section explains topics relevant to Oracle Identity Federation server performance, including:
Communication between two federation servers occurs by means of the SOAP-over-HTTP protocol. Oracle Identity Federation provides these default connection limits:
The number of concurrent connections to a single host is limited to 4.0
The number of maximum total connections is limited to 100.
You can override the default limits by setting the relevant connection parameters:
Log on to the Enterprise Manager console.
At the console, navigate to OC4J_FED -> Administration -> Server Properties.
Add these entries to the Java Options configuration:
-Dhttp.fed.host=VALUE1 -Dhttp.fed.max.conn=VALUE2
where VALUE1 and VALUE2 are values set by the administrator.
Restart OC4J_FED.
When Oracle Identity Federation uses a database as its transient data store, the server uses a connection manager to open and maintain SQL connections to the database.
By default, connection manager uses the following settings when working with an RDBMS as the transient data store:
| JDBC Connection Setting | Default Value |
|---|---|
| Minimum number of connections | 1 |
| Maximum number of connections | 150 |
| Maximum inactivity timeout (the connection will be closed if inactive after this period) | 7200 seconds |
| Connection wait timeout (maximum time to wait for a new connection) | 30 seconds |
The administrator can override these settings using these steps:
Log on to the Enterprise Manager console.
At the console, navigate to OC4J_FED - > Administration - > Server Properties
Add the following entries to the Java Options configuration corresponding to the settings:
-Dfed.jdbc.min.conn=VALUE to set the minimum number of connections
-Dfed.jdbc.max.conn=VALUE to set the maximum number of connections
-Dfed.jdbc.max.usage=VALUE to set the maximum inactivity timeout in seconds
-Dfed.jdbc.conn.timeout=VALUE to set the connection wait timeout in seconds
Save the settings and restart OC4J_FED.
By default, Oracle HTTP Server is configured for general use cases.
To efficiently handle heavy loads, you may need to tune Oracle HTTP Server for improved performance. To achieve this, open the ORACLE_HOME/Apache/Apache/conf/httpd.conf file and modify the following properties:
Note:
The values given here are for illustration only. The actual values you employ will vary depending on your machine and operating system configuration.| Setting | Example Value | Meaning |
|---|---|---|
KeepAlive |
off | Turns off the KeepAlive feature. When KeepAlive is on, connections are not freed until timeout occurs. |
MaxClients |
512 | Increases the number of clients that Apache can process concurrently. |
MinSpareServers |
20 | This is the minimum number of processes Apache can use. |
MaxSpareServers |
250 | This is the maximum number of processes Apache can use. Caution: This setting can be memory-intensive. |
StartServers |
100 | This is the number of processes to create at startup. Caution: This setting can be memory-intensive. |
Note:
You may also need to optimize the IdM framework that is integrated with Oracle Identity Federation (Oracle SSO, Oracle Access Manager, or SiteMinder) with respect to HTTP connections.Finally, you should also take into account the IdM components that are integrated with the Oracle Identity Federation server, and tune their settings appropriately. For example, tuning Oracle HTTP Server settings for OracleAS Single Sign-On may be helpful in optimizing the performance of the federation server.
Oracle Identity Federation leverages Oracle Application Server to support several strategies for ensuring high availability. These strategies can be employed both within an application server instance and across a cluster that includes multiple application server instances. Oracle Identity Federation supports the Cold Failover Cluster (CFC) or active-passive high availability configuration, where the Oracle Application Server Infrastructure is typically deployed on a two-node hardware cluster with a shared storage device. This configuration requires the use of an RDBMS as the transient data store.
Note:
To support High Availability configurations, the "Advanced Install" option must be selected during Oracle Identity Federation installation. For more information, see "Advanced Installation Procedure".Key features of Oracle Identity Federation that impact high availability are described in these sections:
Oracle Identity Federation is a web application deployed to OC4J (in the OC4J_FED container), and multiple HTTP requests from the same client may need to access the application. However, if Oracle Identity Federation running on the OC4J server experiences a problem resulting in failure of the OC4J process or instance, the state associated with a client request may be lost. Here are some ways to guard against such failures:
Using an RDBMS as the transient data store
In this configuration, Oracle Identity Federation saves the transient session and profile state in the database. When the active server instance goes down, the passive (standby) server instance is brought online and restores session and profile state using information from the database, thus avoiding the loss of the Oracle Identity Federation state due to server failure. Storing transient data in the RDBMS is a requirement for high availability. You must use this feature with Oracle Identity Federation on multiple OC4J processes or instances.
Running on Multiple OC4J Processes
In this configuration, the OC4J instance on which Oracle Identity Federation runs is configured for multiple OC4J processes. The OC4J instance configuration is valid for one or more OC4J processes, and these processes communicate the Web session state to each other, thereby providing protection against software problems like an OC4J process failure or hang.
Running on Multiple OC4J Instances
In this configuration, multiple active instances of Oracle Identity Federation are deployed to multiple OC4J instances. The Web session state must be replicated across the server instances using the replication facilities provided by the OC4J clustering framework, and the state is managed using Oracle Enterprise Manager Application Server Control.
If using load balancers, it is important to ensure that all Oracle Identity Federation sessions are directed to the same server instance.
Oracle Identity Federation stores configuration information centrally in the RDBMS transient data store when configured for such a store. This ensures that if configuration changes occur in one federation server instance, all other server instances are able to use the most up-to-date configuration settings.
Note:
It takes approximately 10 seconds for the changes to propagate to all active server instances.When using SAML 1.x or WS-Federation protocols, you will need to manually replicate the ORACLE_HOME/fed/shareid/oblix/config/keystore file to the different Oracle Identity Federation instances. This file contains the peer providers' certificate, which is used to verify signatures in SAML 1.x/WS-Federation protocol messages.
In order to ensure high availability of Oracle Identity Federation, it is necessary to ensure high availability of the specific data repositories that are being used with the server (LDAP, RDBMS, and so on). Refer to product- and vendor-specific documentation for details about configuring specific data stores.
For RDBMS repositories, a good starting point is the Oracle Database High Availability Overview, which is part of the Administration document set in the Oracle9i Database Server documentation library.
If your site contains a redundant infrastructure of LDAP servers, for example a topology where the servers are fronted by a load balancer that re-routes requests to a different LDAP server when a directory instance goes down, the Oracle Identity Federation server should be configured using these steps:
Log on to the Oracle Enterprise Manager console.
At the console, navigate to OC4J_FED - > Administration - > Server Properties.
Add the following entry to the Java Options field:
-Dfed.ldap.ha=true
Save the settings and restart OC4J_FED.
For more information about high availability features that you can leverage in your Oracle Identity Federation installation, see the Oracle Application Server High Availability Guide.
For information about Cold Failover Cluster configurations for high availability, see the Oracle Application Server High Availability Guide in the 10g Release 2 (10.1.2) documentation library.
This section explains configuration and other steps required for installing Oracle Identity Federation behind a load balancer.
Take these steps to set up a load balancer with Oracle Identity Federation:
Note:
These steps are specific to the F5 load balancer.Follow the standard installation process to install all Oracle Identity Federation instances on corresponding load balanced host machines. Details are provided in Chapter 3, "Installing Oracle Identity Federation".
There is no need to choose a virtual hostname, as it is required for Cold Failover Cluster in the advanced installation procedure.
Choose the transient data store in the advanced installation procedure.
Install all Oracle Identity Federation instances pointing to the same transient data store.
In the F5 load balancer administration console, create a pool with all Oracle Identity Federation instances, and enable the application persistence property for this pool. Set the persistence type to Active HTTP Cookie, set the method to insert, and the set expiration to the desired value.
Create a virtual server member mapped to the newly created pool.
Enable HTTP monitoring on all member nodes in the pool.
On all Oracle Identity Federation servers instances, change the ServerName and Port parameters in the httpd.conf file to the Virtual Server name and port.
For all Oracle Identity Federation servers that are both load-balanced and integrated with OracleAS Single Sign-On, register the load balancer URL (for example, http://lbr.us.oracle.com:80) to all load-balanced Oracle Identity Federation servers by running this command from the command prompt:
<OIF_HOME>/sso/bin/ssoreg.bat -oracle_home_path %ORACLE_HOME% -site_name
<Load_Balancer_Host_Name> -config_mod_osso TRUE -mod_osso_url
<Load_Balancer_URL:Port>
On all Oracle Identity Federation servers, update the configuration by running this command from the command prompt:
dcmctl updateconfig
Restart the HTTP server from the Oracle Enterprise Manager console on all the Oracle Identity Federation server instances.
In the Oracle Identity Federation administration console, under Server Configuration - > Server Properties, change the server hostname and port number to the Virtual Server name and port number of the load balancer.
Restart the Oracle Identity Federation instances from the Oracle Enterprise Manager console.
Distribute the new metadata file to the peer providers.
When using SAML 1.x or WS-Federation protocols, you will need to manually replicate the ORACLE_HOME/fed/shareid/oblix/config/keystore file to the different Oracle Identity Federation instances. This file contains the peer providers' certificate, which is used to verify signatures in SAML 1.x/WS-Federation protocol messages.
Additionally, when setting up SAML 1.x or WS-Federation SSO in load-balanced mode, make sure that the URLs in MyDomain at the Load-balanced provider, and in the load-balanced Domain at the other provider, have the hostname and address of the load-balancer machine (as opposed to, for example, the hostname and address of one of the load-balanced Oracle Identity Federation instances).
The Oracle Identity Federation monitoring console cannot be load balanced; this is because only one server should be responsible for monitoring one or more Oracle Identity Federation instances. Therefore, you need to modify the Oracle HTTP Server settings to correctly enable the monitoring features on the console, as well as on the Oracle Identity Federation servers.
Make sure that the HTTP ports and URLs used for monitoring operations are not integrated with the load balancer. You can accomplish this by creating an Oracle HTTP Server Virtual host that will forward requests made to the /fed and /fedmon URLs to the local OC4J_FED container.
The new virtual host will need these settings:
ServerName, Port, and Listen directive values for the virtual host set to the local values
Oc4jMount directives that forward /fed and /fedmon URLs to the OC4J_FED container
For example, the definition of such a virtual host in ORACLE_HOME/Apache/Apache/conf/httpd.conf could look like this:
Listen 7799
NameVirtualHost *:7799
<VirtualHost *:7799>
ServerName local.machine.com
<IfModule mod_oc4j.c>
Oc4jMount /fed OC4J_FED
Oc4jMount /fed/* OC4J_FED
Oc4jMount /fedmon OC4J_FED
Oc4jMount /fedmon/* OC4J_FED
</IfModule>
</VirtualHost>
Take these steps:
Modify the httpd.conf file using the example as a guide.
Execute the command:
dcm/bin/dcmctl updateconfig
Restart Oracle HTTP Server:
opmn/bin/opmnctl restartproc process-type=HTTP_Server
After creating the virtual host, access the monitoring console using the URL of the virtual host.
Add the URLs of Oracle Identity Federation servers to monitor. The URL should point to the local virtual host value, not the load-balanced URL.
The monitoring console will now be ready to configure to monitor the Oracle Identity Federation server.
This section explains how to set up a proxy server for Oracle Identity Federation.
Due to the standalone nature of Oracle Identity Federation, you cannot utilize the usual procedures for setting up an application server proxy. Instead, use the steps provided here to set up an Oracle HTTP Server as a proxy for Oracle Identity Federation:
Install Oracle HTTP Server for the proxy server.
Edit the ORACLE_HOME/Apache/Apache/conf/httpd.conf file.
Uncomment these lines:
<IfModule mod_proxy.c>
ProxyRequests On
</IfModule>
Unset the ProxyRequests directive:
ProxyRequests Off
Add these directives after ProxyRequests Off:
ProxyPass /sso HTTP://OIF-HOST:OIF-PORT/sso ProxyPass /fed HTTP://OIF-HOST:OIF-PORT/fed ProxyPass /shareid HTTP://OIF-HOST:OIF-PORT/shareid ProxyPassReverse /sso HTTP://OIF-HOST:OIF-PORT/sso ProxyPassReverse /fed HTTP://OIF-HOST:OIF-PORT/fed ProxyPassReverse /shareid HTTP://OIF-HOST:OIF-PORT/shareid #ProxyPass /fedadmin HTTP://OIF-HOST:OIF-PORT/fedadmin #ProxyPass /fedmon HTTP://OIF-HOST:OIF-PORT/fedmon #ProxyPass /uixi http://OIF-HOST:OIF-NON-SSL-PORT/uixi #ProxyPassReverse /fedadmin HTTP://OIF-HOST:OIF-PORT/fedadmin #ProxyPassReverse /fedmon HTTP://OIF-HOST:OIF-PORT/fedmon #ProxyPassReverse /uixi http://OIF-HOST:OIF-NON-SSL-PORT/uixi #ProxyPass /osso_login_success HTTP://OIF-HOST:OIF-PORT/ osso_login_success #ProxyPass /osso_logout_success HTTP://OIF-HOST:OIF-PORT/ osso_logout_success #ProxyPassReverse /osso_login_success HTTP://OIF-HOST:OIF-PORT/ osso_login_success #ProxyPassReverse /osso_logout_success HTTP://OIF-HOST:OIF-PORT/ osso_logout_success
where:
HTTP is http for an open connection or https for a secure connection from the proxy to Oracle Identity Federation
OIF-HOST is the hostname of the Oracle Identity Federation server
OIF-PORT is the HTTP or HTTPS port number of the Oracle Identity Federation server. Omit the entry for HTTP port 80 or HTTPS port 443.
OIF-NON-SSL-PORT is the http port number of the Oracle Identity Federation server. Omit the entry for HTTP port 80.
Note:
Uncomment the /fedadmin or /fedmon directives only if you need to expose the Oracle Identity Federation administration or monitoring consoles to users on the internet.
Uncomment the /uixi directives if any of the /fedadmin or /fedmon directives is enabled.
Uncomment the /osso_login_success and /osso_logout_success directives if Oracle Identity Federation is integrated with Oracle Single Sign-On Server.
Caution:
Oracle recommends that you do not make the administration and monitoring consoles available through the proxy.Comment out the mod_oc4j include:
#include "ORACLE_HOME/Apache/Apache/conf/mod_oc4j.conf
If using SSL from the proxy to the Oracle Identity Federation server, add an additional directive after ProxyPassReverse directives:
SSLProxyWallet file:OHS_HOME/Apache/Apache/conf/ssl.wlt/default
where OHS_HOME is the install directory for the proxy Oracle HTTP Server. If you have not already done so, also import the certificate of the CA that issued the Oracle Identity Federation server certificate in this wallet. See "Configuring SSL Server on Oracle Identity Federation" for details.
If using SSL with the proxy, follow the instructions in "Configuring SSL Server on Oracle Identity Federation". Omit the section about editing the mod_oc4j.conf file.
If you require SSL client certificate authentication for the IdP/source side of the SAML 1.x Artifact profile, do the following for the proxy Oracle HTTP Server:
Copy the Perl script shown here to the appropriate location.
Unix: ORACLE_HOME/perl/lib/site_perl/5.6.1/Apache/SSLClientCertHeader.pm
Windows: ORACLE_HOME\Apache\Apache\mod_perl\site\5.6.1\lib\Apache\SSLClientCertHeader.pm
This script sets the ssl_client_certificate header that Oracle Identity Federation uses to complete the client certificate authentication.
package Apache::SSLClientCertHeader;
use Apache::Constants qw(OK DECLINED);
use Apache::URI ();
use strict;
sub handler {
my $r = shift;
$r->subprocess_env;
my $clientcert = $r->subprocess_env("SSL_CLIENT_CERT");
my $outstr;
# Remove newlines from certificate before setting header.
for my $i (split "\n", $clientcert) {
if (!($i =~ /^-/)) {
chomp($i);
$outstr .= $i;
}
}
$r->header_in("ssl_client_cert", $outstr);
return OK;
}
1;
Add these directives to the VirtualHost for the SSL client certificate authentication port in ORACLE_HOME/Apache/Apache/conf/ssl.conf:
<VirtualHost _default_:CLIENT-CERT-PORT>
. . .
SSLOptions +ExportCertData +CompatEnvVars
PerlModule Apache::SSLClientCertHeader
PerlFixupHandler Apache::SSLClientCertHeader
</VirtualHost>
Copy an existing virtual host first, similar to the steps for just configuring the Oracle Identity Federation server with client certificate mode. The new virtual host should have the client certificate port number of the proxy. Also, update the responder port on the Domain page of the Oracle Identity Federation administration console with the client certificate port of the proxy server.
Restart Oracle HTTP Server to make the configuration changes effective. You can test the proxy by invoking:
HTTP://PROXY-HOST:PROXY_PORT/shareid/saml/ObSAMLTransferService
You should get an Oracle Identity Federation error with Error ID TSE002.
Determine the proxy HTTP or HTTPS ports through the Ports page of the Enterprise Manager Console:
Oracle HTTP Server Listen port (http)
Oracle HTTP Server Listen (SSL) port (https)
Reconfigure Oracle Identity Federation to use the proxy host and port for its external URLs. Make these changes in the Oracle Identity Federation administration console:
Server Configuration - > General:
- Server Hostname
- Server Port
- SOAP Port
SAML 1.x/WS-Fed - > Domains - > MyDomain:
- Error URL
- Transfer URL
- Responder URL
- SourceID (blank to regenerate for new ResponderURL)
- Identity Realm STS URL
- Receiver URL
- Resource Realm STS URL
Note:
Do not modify the Signing Certificate Subject DN or Issuer DN, as these must continue to match the generated certificate.Restart Oracle Identity Federation to make the General server configuration changes effective.
If using Oracle Access Manager as the IdM, use the Access System Console to update the Fed SSO authentication schemes:
Access System Console - > Access System Configuration - > Authentication Management:
- Fed SSO - SAML 1.x
- Fed SSO - WS-Federation
- Fed SSO - SAML 2.0/Liberty 1.x
Change the Challenge Redirect parameter for each scheme to use the proxy host and port.
Communicate the changes to partners using this Oracle Identity Federation, if necessary. Partners using SAML 2.0 or Liberty 1.x will need to download new metadata. Partners using SAML 1.x or WS-Federation will need to manually update their configurations with the Oracle Identity Federation MyDomain configuration set in Step 6.
If Oracle Identity Federation is integrated with Oracle Single Sign-On, some additional steps are required.
Update the Oracle Single Sign-On Partner application:
- Go to the Oracle Single Sign-On administration console (http://osso_host:osso_port/pls/orasso).
- Click Single Sign-On Administration.
- Click Administer Partner Applications.
- Choose the partner application referencing the Oracle Identity Federation server, and edit the application configuration.
- Replace the http(s), hostname and port number by the proxy's values for Home URL, Success URL, and Logout URL.
- Click OK.
Update the policy.properties file:
- Open the ORACLE_HOME/sso/conf/policy.properties file in the Oracle Single Sign-On deployment.
- Replace the http(s), hostname and port number by the proxy's value for the SASSOAuthnUrl and SASSOLogoutUrl entries.
- Save and close the file.
Restart the OC4J_SECURITY instance of the Oracle Single Sign-On deployment by using the command:
opmn/bin/opmnctl restartproc process-type=OC4J_SECURITY
