3 Deploying Oracle Identity Federation

This chapter describes key deployment scenarios, including integration with identity and access management systems, Web servers, and back-end data stores. It contains these topics:

Introduction
Deployment Scenarios

3.1 Introduction

Oracle Identity Federation operates in a heterogeneous environment and is interoperable with a wide variety of platforms and applications. It supports multiple options for data stores and authentication providers.

To resolve deployment issues and questions, refer to Chapter 2, "Planning Oracle Identity Federation Deployment" which provides extensive background information to help you plan your deployment:

Section 2.1, "Architecture Options" provides details about supported protocols and profiles, and what to consider when evaluating deployment options.
Section 2.6, "Sizing Guidelines" explains performance factors and provides topology recommendations.
Section 2.7, "Implementation Checklist"provides a deployment checklist.

The next section describes different deployment scenarios and provides step-by-step instructions for configuring Oracle Identity Federation to work with key components of the federation environment.

3.2 Deployment Scenarios

This section describes the steps needed to implement common Oracle Identity Federation deployment scenarios. It contains these sections:

Deploying Oracle Identity Federation with Oracle HTTP Server
Deploying Oracle Identity Federation with Oracle Single Sign-On
Deploying Oracle Identity Federation with Oracle Access Manager
Deploying Oracle Identity Federation with a Sun Java System Web Server
Integrating with Third-Party Identity & Access Management Modules
Using the Test SP Engine

3.2.1 Deploying Oracle Identity Federation with Oracle HTTP Server

HTTP Servers are deployed in the Web Tier.

Most Identity Management components can function without the Web Tier, but for most enterprise deployments, the Web Tier is desirable. To support enterprise level single sign-on using products such as Oracle Single Sign-On and Oracle Access Manager, the Web Tier is required.

This section describes the steps needed to install and deploy Oracle Identity Federation so that it is integrated with Oracle HTTP Server.

When installing the IdM suite, select Oracle HTTP Server in the Select Components screen. This will install Oracle HTTP Server.

After installation, issue the following command-line instruction to create the instance:

$AS_INST/bin/opmnctl createcomponent -componentType OHS -componentName $OHS_NAME

where $AS_INST represents the application server instance home, and $OHS_NAME is the name of the new OHS component

Next, take these steps to link Oracle HTTP Server to the managed server where Oracle Identity Federation is running:

Open $AS_INST/config/OHS/$OHS_NAME/moduleconf/oif.conf

where $AS_INST represents the application server instance home
If Oracle Identity Management was installed in stand-alone mode, uncomment and set the WebLogicHost and WebLogicPort variables to reference the WebLogic managed server where Oracle Identity Federation is running (for example myhost.us.mycorp.com and 7499).
If the Oracle Identity Management is installed in clustered mode, uncomment and set the WebLogicCluster variable to reference the Oracle WebLogic Server managed servers where Oracle Identity Federation is running (for example myhost1.us.mycorp.com:7499, myhost2.us.mycorp.com:7499).
Save the file and exit.
Restart OHS.

3.2.1.1 Starting and Stopping the Oracle HTTP Server Instance

The commands to start, stop, and restart OHS respectively are as follows:

$AS_ISNT/bin/opmnctl startproc process-type=OHS
$AS_ISNT/bin/opmnctl stopproc process-type=OHS
$AS_ISNT/bin/opmnctl restartproc process-type=OHS

where AS_INST represents the application server instance home.

Next, take these steps to update the Oracle Identity Federation configuration:

Log in to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.
Navigate to Administration, then Server Properties.
Change the hostname to reflect the hostname configured in OHS, if they are different.
Change the Port/SSL Enabled and SOAP Port/SSL Enabled information to reflect the OHS configuration.
Save the changes.
Since the Oracle Identity Federation metadata has changed, redistribute the metadata to any remote partners to notify them of the changes.

3.2.2 Deploying Oracle Identity Federation with Oracle Single Sign-On

This section describes the steps needed to install and deploy Oracle Identity Federation so that it is integrated with Oracle Single Sign-On.

Deployed in this manner, Oracle Identity Federation can leverage the authentication capabilities offered by Oracle Single Sign-On when local user authentication is required. Oracle Identity Federation can:

integrate with OHS and Oracle Single Sign-On to serve as the authentication engine
integrate with Oracle Single Sign-On to serve as the SP integration Module.

Briefly, the steps to achieve this deployment are:

Create and Manage the Oracle HTTP Server Instance
Integrate Oracle Single Sign-On with OHS
Configure Oracle Identity Federation to use Oracle Single Sign-On as the Authentication Engine
Configure Oracle Identity Federation for Oracle Single Sign-On SP Integration
Configure Oracle Single Sign-On
Testing Federated Single Sign-On

Detailed instructions for these steps follow.

Note:

Oracle Identity Federation does not support the ability to force re-challenging the user for credentials when integrated with Oracle Single Sign-On, so that Oracle Identity Federation cannot support use cases where reauthentication must be forced.

For example, if an SP sends an AuthnRequest with ForceAuthn="true" to an Oracle Identity Federation IdP, and Oracle Identity Federation is integrated with Oracle Single Sign-On, the ForceAuthn flag is ignored.

3.2.2.1 Create and Manage the Oracle HTTP Server Instance

To configure OHS, follow the instructions in Section 3.2.1, "Deploying Oracle Identity Federation with Oracle HTTP Server".

3.2.2.2 Integrate Oracle Single Sign-On with OHS

This integration is necessary to deploy Oracle Identity Federation with Oracle Single Sign-On.

Start by registering the mod_osso module in 11g Release 1 (11.1.1) OHS with the 10g Oracle Single Sign-On server as a partner application.

For details on this procedure, refer to Configuring and Administering Partner Applications in the Oracle Application Server Single Sign-On Administrator's Guide for 10g.

You need to run ssoreg from the Oracle Single Sign-On server to generate an osso.conf file and manually copy it to the partner application (AS_INST of the Oracle Identity Federation instance).

Here is an example for registering a remote partner application on an Oracle Single Sign-On server:

$ORACLE_HOME/sso/bin/ssoreg.sh 
-site_name oif.server.com:7499 
-config_mod_osso TRUE 
-mod_osso_url http://oif.server.com:7499
-remote_midtier 
-config_file oif.server.com.osso.conf

Restart the OC4J_SECURITY instance of the Oracle Single Sign-On Server.

After you run this command, a file named oif.server.com.osso.conf is created in the directory where the commmand was invoked. Copy that file to $AS_INST/config/OHS/$OHS_NAME/.

The next step is to set up mod_osso.

Copy $AS_INST/config/OHS/$OHS_NAME/disabled/mod_osso.conf to $AS_INST/config/OHS/$OHS_NAME/moduleconf. All files in the moduleconf directory are read when OHS is started.

Open the $AS_INST/config/OHS/$OHS_NAME/moduleconf/mod_osso.conf file and set the OssoConfigFile directive to reference the Oracle Single Sign-On configuration file that was created and then copied to the OHS config directory:

OssoConfigFile ${ORACLE_INSTANCE}/config/${COMPONENT_TYPE}/${COMPONENT_NAME}/oif.server.com.osso.conf

Note:

If SSL is not enabled, you must add the OssoSecureCookies directive and set it to off; otherwise mod_osso will set the cookie as secure and instruct the browser to only send the cookie over HTTPS.

For details, see Secure Transmission of mod_osso Cookies in the Oracle Application Server Single Sign-On Administrator's Guide.

The mod_osso.conf file should look like this:

LoadModule osso_module ${ORACLE_HOME}/ohs/modules/mod_osso.so
 
<IfModule mod_osso.c>
    OssoIpCheck off
    OssoIdleTimeout off
    OssoConfigFile ${ORACLE_INSTANCE}/config/${COMPONENT_TYPE}/${COMPONENT_NAME}/oif.server.com.osso.conf
 
</IfModule>
 
#
# If you would like to have short hostnames redirected to
# fully qualified hostnames to allow clients that need
# authentication via mod_osso to be able to enter short
# hostnames into their browsers uncomment out the following
# lines
#
#PerlModule Apache::ShortHostnameRedirect
#PerlHeaderParserHandler Apache::ShortHostnameRedirect

Restart OHS for the configuration changes on mod_osso and mod_wl to take effect.

3.2.2.3 Configure Oracle Identity Federation to use Oracle Single Sign-On as the Authentication Engine

In this task you configure the server to use the Oracle Single Sign-On authentication engine. For more information, see Section 2.3.1, "Engines in Oracle Identity Federation".

Start with these steps to enable the Oracle Single Sign-On authentication engine:

Log in to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.
Navigate to Administration, then Authentication Engines, then Oracle SSO.
Enable the engine.
Save the changes.

If Oracle Single Sign-On is only integrated as an authentication engine for Oracle Identity Federation, you will need to set up the Oracle Single Sign-On server to configure it for logout, and configure the Oracle Identity Federation server to configure it for logout.

To set up Oracle Single Sign-On:

Open $ORACLE_HOME/sso/conf/policy.properties.
Uncomment SASSOLogoutUrl.

Set the Oracle Identity Federation hostname/port information:

SASSOLogoutUrl = http\://oif-hostname\:oif-port/fed/user/authnsloosso

Save the changes and exit.
Restart the OC4J_SECURITY instance.

To set up Oracle Identity Federation:

Log in to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.
Navigate to Administration, then Authentication Engines, then Oracle SSO.
Enable logout.
Enter the Oracle Single Sign-On Server Logout URL:
```
http://osso-hostname:osso-port/sso/logout
```
Save the changes.

3.2.2.4 Configure Oracle Identity Federation for Oracle Single Sign-On SP Integration

This task involves enabling Oracle Single Sign-On as a service provider integration module, and if needed, disable logout for the Oracle Single Sign-On authentication engine.

First, take these steps to enable the Oracle Single Sign-On SP Module in Oracle Identity Federation:

Log in to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.
Navigate to Administration, then Service Provider Integration Modules, then Oracle SSO.
Enable the SP Module.
Select the authentication mechanism that will be used to locally authenticate users if federated identities are used during Federation SSO and if a federation record needs to be created during the SSO operation.
Enter the username attribute that Oracle Identity Federation needs to provide to Oracle SSO. Default is uid.
Enter the Oracle Single Sign-On server login URL:
```
http://osso-hostname:osso-port/sso/auth
```
Enter the Oracle Single Sign-On server logout URL:
```
http://osso-hostname:osso-port/sso/logout
```
Check Logout Enabled.
Click Regenerate OSSO Secret to create an encryption key that will be saved in a file and provided to Oracle Single Sign-On. Save the keystore locally.
Save the changes.

If Oracle Single Sign-On is integrated as an authentication engine for Oracle Identity Federation as well as an SP integration module, then the Oracle Single Sign-On authentication engine logout must be disabled, as the SP integration module is managing the logout. To disable the logout for Oracle Single Sign-On authentication engine in Oracle Identity Federation:

Log in to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.
Navigate to Administration, then Authentication Engines, then Oracle SSO.
Disable logout.
Save the changes.

3.2.2.5 Configure Oracle Single Sign-On

This part of the setup requires setup on the Oracle Single Sign-On server, and partner configuration.

Note:

A partner application is an Oracle Application Server-based application or a non-Oracle application that delegates the authentication function to the Oracle Single Sign-On server. A partner application is responsible for determining whether a user authenticated by Oracle Single Sign-On is authorized to use the application.

To set up Oracle Single Sign-On:

Copy the keystore file previously generated to the $ORACLE_HOME/sso/conf location and save it as a keystore.
Open $ORACLE_HOME/sso/conf/policy.properties.
Uncomment SASSOAuthnUrl, SASSOLogoutUrl, SASSOAuthLevel and MediumHighSecurity_AuthPlugin.
Set the Oracle Identity Federation hostname/port information for: SASSOAuthnUrl= http\://oif-hostname\:oif-port/fed/user/sposso
Set the Oracle Identity Federation hostname/port information for: SASSOLogoutUrl = http\://oif-hostname\:oif-port/fed/user/spsloosso
Set the authentication level for the Oracle Identity Federation plugin: SASSOAuthLevel = MediumHighSecurity
Set the MediumHighSecurity_AuthPlugin, which will define the Oracle Identity Federation plug-in: MediumHighSecurity_AuthPlugin = oracle.security.sso.server.auth.SASSOAuth
Save the changes and exit.
Restart the OC4J_SECURITY instance

To configure a partner to use Oracle Identity Federation as the authentication plug-in:

Open $ORACLE_HOME/sso/conf/policy.properties.
Add the partner application to be protected by the authentication level mapped to the Oracle Identity Federation plug-in. For example: content.example.com\:8888 = MediumHighSecurity.
Save the changes and exit.
Restart the OC4J_SECURITY instance.

3.2.2.6 Testing Federated Single Sign-On

Take these steps to test your federated single sign-on setup:

Use a web browser to access a protected resource. When prompted by the identity provider, log in using credentials in the IdP's domain. When prompted by the service provider, log in using credentials in the SP's domain. You should now be redirected to the protected resource.

For details about protecting partner applications and resources see Oracle Application Server Single Sign-On Administrator's Guide.
Log out, and then try to access the protected resource again. You should be prompted for login only by the identity provider.

3.2.3 Deploying Oracle Identity Federation with Oracle Access Manager

This section describes the steps needed to install and deploy Oracle Identity Federation so that it is integrated with Oracle Access Manager. Integration enables Oracle Identity Federation to interact with Oracle Access Manager to create an authenticated user session.

The steps illustrate a deployment scenario consisting of two nodes:

The section is broken out into separate instructions for the different component installation and deployment tasks:

Create and Manage OHS
Integrate Oracle Access Manager as an Authentication Engine
Integrate Oracle Access Manager as an SP Integration Module

Note Added for Bug 7679823

Note:

Oracle Access Manager policy objects created by Oracle Identity Federation should not be changed from within Oracle Access Manager Policy/Access Manager administration interface; these objects can be identified by the description "Created by OIF. Do not modify". Modifying such objects from Oracle Access Manager can lead to synchronization issues; always update these policy objects from Fusion Middleware Control.

3.2.3.1 Create and Manage OHS

The steps to create and manage your 11g Release 1 (11.1.1) OHS component instance are:

Create the OHS instance.
Link OHS instance to the Oracle WebLogic Server managed server where Oracle Identity Federation is running.
Update the Oracle Identity Federation configuration.
Manage the OHS instance.

Create the Oracle HTTP Server Instance

Note:

$OHS_NAME refers to the name of the OHS component.

Execute this command to create the instance:

$AS_ISNT/bin/opmnctl createcomponent -componentType OHS -componentName $OHS_NAME

Link Oracle HTTP Server Instance to the Managed Server

To enable OHS to connect to the managed server where Oracle Identity Federation runs, take these steps:

Open $AS_ISNT/config/OHS/$OHS_NAME/moduleconf/oif.conf.
If the Idm installation is in standlone mode, uncomment and set the WebLogicHost and WebLogicPort variables to reference the WLS managed server where Oracle Identity Federation is running (for example myhost.mycorp.com and 7499)
If the Idm installation is in clustered mode, uncomment and set the WebLogicCluster variable to reference the WLS managed servers where Oracle Identity Federation is running (for example myhost1.mycorp.com:7499, myhost2.mycorp.com:7499)
Save the changes, exit, and restart OHS.

See Also:
"Section 3.2.1.1, "Starting and Stopping the Oracle HTTP Server Instance" for restart instructions.

Update the OHS Configuration in Oracle Identity Federation

To enable the Oracle Identity Federation server to recognize the OHS, take these steps:

Locate the Oracle Identity Federation instance in Fusion Middleware Control.
Navigate to Administration, then Server Properties.
Change the hostname to reflect the hostname configured in OHS, if different.
Change the Port/SSL Enabled and SOAP Port/SSL Enabled information to reflect the OHS configuration.
Save the changes.
Since the Oracle Identity Federation metadata will have changed, redistribute the metadata to any remote partners to notify them of the changes.

Manage the Oracle HTTP Server Instance

To start OHS:

$AS_ISNT/bin/opmnctl startproc process-type=OHS

where $AS_INST is the application server instance home.

To stop OHS:

$AS_ISNT/bin/opmnctl stopproc process-type=OHS

To restart OHS:

$AS_ISNT/bin/opmnctl restartproc process-type=OHS

3.2.3.2 Integrate Oracle Access Manager as an Authentication Engine

See Also:

Section 2.3, "Authentication Engines" to review the features and benefits of authentication engines.

Oracle Access Manager as an authentication engine protects the /fed/user/authnoam URL.

The steps to configure this feature are:

Verify requirements and update default OHS configuration
Integrate OHS with Oracle Access Manager
Configure Oracle Access Manager
Configure Oracle Identity Federation

Verify Requirements

Take these steps to verify component versions:

Verify that the Oracle Access Manager server is at Version 10.1.4.2 with 10.1.4.2 BP04 or above, or Version 10.1.4.3.
Verify that the Oracle Access Manager WebGate is installed for 11gR1 OHS (2.2).

Take these steps at the OHS:

Edit the $AS_ISNT/config/OHS/$OHS_NAME/httpd.conf file.
Uncomment the User and Group directives in the httpd.conf file, or add it.
Replace the default values of nobody with the user and users group that installed OHS 11g Release 1 (11.1.1), or add the user and users group if User and Group directives were missing.

For example:
```
User oracle
Group dba
```

Integrate Oracle HTTP Server with Oracle Access Manager

Use the Oracle Access Manager console to create a new AccessGate and associate it with an Access Server instance.

See Also:

Oracle Access Manager Access Administration Guide for details about the Web-based user interface.

See Also:

Oracle Access Manager Installation Guide for details about installing WebGate.

On the machine where OHS is installed, install WebGate using these steps:

Launch the Install Wizard to install WebGate for Oracle HTTP Server11g
Enter the AccessGate details as well as the AccessServer connection information.
Enter the location of the Oracle HTTP Server httpd.conf file (it should be $AS_ISNT/config/OHS/$OHS_NAME/httpd.conf) in order for WebGate to integrate with Oracle HTTP Server.

Configure Oracle Access Manager

Oracle Access Manager needs to protect an Oracle Identity Federation resource through WebGate. Since the WebGate is already installed, Oracle Access Manager needs only to have a policy that will protect the Oracle Identity Federation server in order to use Oracle Access Manager as an authentication engine. Once Oracle Access Manager authenticates, it will need to provide to Oracle Identity Federation the user identifier as an HTTP header.

Take these steps to configure Oracle Access Manager:

See Also:

Oracle Access Manager Access Administration Guide for details about the Web-based user interface.

Go to the Oracle Access Manager console and navigate to the Policy Manager.
Protect the /fed/user/authnoam resource in a domain with an authentication scheme and an authorization rule.
In the Authorization Rule, go to the Actions tab, click Modify and in the Authorization Success section, add a Return property that will be an HTTP header with a value set to the user ID. (For example, set Type to headervar, set Name to userid, set Return Attribute to uid.)

Configure Oracle Identity Federation

Take these steps:

Locate the Oracle Identity Federation instance in Fusion Middleware Control.
Navigate to Administration, then Authentication Engines, then Oracle Access Manager.
Enable the Engine.
Enter the HTTP header containing the User ID.
Perform these logout configuration steps if Oracle Identity Federation and Oracle Access Manager are integrated only through the authentication engine framework. Otherwise, disable logout for Oracle Access Manager authentication Engine here and see Section 3.2.3.3, "Integrate Oracle Access Manager as an SP Integration Module" to configure logout operation.
- Check the Logout Enabled box if logout needs to be enabled.
- Check the Clear Cookie box if resetting the Oracle Access Manager cookie is enough for Oracle Identity Federation to log the user out of the Oracle Access Manager domain.
- Check Redirect to Logout URL and fill in the URL if Oracle Identity Federation needs to redirect the user to a specific URL for Oracle Access Manager logout. See the note below for more information.
Save the changes.

Note:
When the user needs to be redirected to an Oracle Access Manager URL for logout (in case Oracle Access Manager needs to perform extra operations), you need to configure Oracle Identity Federation by checking the Redirect to Logout URL box, and entering the URL to which the user is redirected. When Oracle Identity Federation redirects the user to that URL, it will append a return URL as a query parameter; this is the Oracle Identity Federation URL to which the user is redirected after performing the extra Oracle Access Manager operations.
The query parameter to be appended to the Oracle Access Manager logout URL is referenced by returnurl.

Note:

The fix for Oracle Access Manager bug 5736326 is required when protecting the /fed/user/authnoam URL with HTTP Basic Authentication.

Using an Alternate Return Attribute for the HTTP Header

When Oracle Identity Federation is integrated with Oracle Access Manager for authentication, WebGate is protecting the /fed/user/authnoam URL, and Oracle Access Manager is configured to pass the user identifier as an HTTP Header to Oracle Identity Federation, the policy protecting the /fed/user/authnoam URL contains an authorization rule with an action that will add an HTTP Header with a return attribute referencing the user ID from the LDAP user record. This return attribute is the same as the Unique User ID set in Fusion Middleware Control when you navigate to the Oracle Identity Federation instance, under Administration, then Data Stores, then User Data Store section.

Due to a bug, orclguid cannot be used as the Return Attribute for the HTTP Header containing the user identifier. As a workaround for this bug, the unique user identifier needs to be changed to another attribute. To perform the change:

change the Return Attribute in the Oracle Access Manager console to the new attribute (uid for example)
in Fusion Middleware Control navigate to Oracle Identity Federation Administration, then Data Stores, then User Data Store section, change the Unique User ID to the new attribute (uid for example)
if other authentication engines were used, check that their Unique User ID attributes is correctly updated
if Oracle Identity Federation was integrated with Oracle Access Manager through the Oracle Access Manager SP Integration Module, update the integration as follows: after performing the above changes, navigate to the Oracle Identity Federation instance in Fusion Middleware Control, then Administration, then SP Integration Modules, then OAM SP Engine, enter the Oracle Access Manager Admin Credentials, select the created Authentication Schemes to be updated, and click on "Configure Oracle Access Manager": this will update the mapping rules in Oracle Access Manager to reflect the new attribute

3.2.3.3 Integrate Oracle Access Manager as an SP Integration Module

This task enables the SP integration module to interact with Oracle Access Manager.

The basic steps are:

Verify requirements
Install Oracle Access Server SDK
Integrate Oracle Access Manager with Oracle Access Server SDK
Update the Oracle WebLogic Server Classpath
Configure Oracle Identity Federation
Integrate Oracle Identity Federation with Oracle Access Manager
Protect an Oracle Access Manager Resource with Oracle Identity Federation

Verify Requirements

Take these steps:

Ensure Access Server SDK 10g is installed.
In a high availablity (HA) environment, the Access Server SDK needs to be installed on different machines, and integrated as different AccessGates with Oracle Access Manager.

Note:
When deploying in an HA environment, be sure to read and complete the instructions in the section High Availability Considerations for Integration with Oracle Access Manager in the Oracle Fusion Middleware High Availability Guide.
Be sure to follow the directions regarding the directory where the Access Server SDK is installed, and restart all managed servers.

Install Oracle Access Server SDK

Configure Oracle Identity Federation to reference the directory where the SDK is installed.

If the SDK is installed in the Domain Home directory, you can reference the SDK folder relative to the Domain Home folder; otherwise, Oracle Identity Federation needs to reference the SDK folder using an absolute path.

To use Oracle Identity Federation in an HA environment, it is preferable to install the Access Server SDK under the Domain Home folder, using the same directory name relative path on the different machines where Oracle Identity Federation is installed. This way, the different Oracle Identity Federation instances share the same configuration; specifically, the directory where the Access Server SDK is installed has the same value for all the Oracle Identity Federation instances.

Integrate Oracle Access Manager with Oracle Access Server SDK

This task enables a new AccessGate to be associated with an Access Server instance.

On the Oracle Access Manager console, create the new AccessGate with Access Management Service enabled, and associate it with the Access Server instance.

See Also:

Oracle Access Manager Access Administration Guide for details about the Web-based user interface.

Integrate the Access Server SDK by invoking the configureAccessGate script:

$ACCESS_SERVER_SDK/oblix/tools/configureAccessGate -i $ACCESS_SERVER_SDK -t AccessGate -w $ACCESS_GATE_ID -m open -h $ACCESS_SERVER_HOST -p $ACCESS_SERVER_PORT

replacing:

$ACCESS_SERVER_SDK by the absolute path of the Access Server SDK directory
$ACCESS_GATE_ID by the identifier for this Acccess Gate
$ACCESS_SERVER_HOST by the hostname of machine where the Access Server is installed
$ACCESS_SERVER_PORT by the port of the Access Server.

Update the Oracle WebLogic Server Environment

The managed server where Oracle Identity Federation is running needs to be able to access the JAR file and the shared libraries required for Oracle Access Manager integration.

To update the environment:

Stop managed server.

See Also:
Starting and Stopping WebLogic Servers in the Oracle Fusion Middleware Administrator's Guide.
Copy the jobaccess.jar file from the $ASDK_DIR/oblix/lib folder to the $DOMAIN/lib folder.
The next step depends on the version of Oracle Access Manager you are running.
- If you are at Oracle Access Manager version 10.1.4.3 or later and want to start the managed server from the WebLogic administration console, follow these steps:
  - Open the WebLogic administration console.
  - Navigate to Servers, then Managed Server, then Configuration, then Server Start.
  - In the text box for Arguments, append -Djava.library.path to include ASDK_DIR/oblix/lib.
  - Save the changes.
  - Start the managed server from the console.

If you are at Oracle Access Manager version 10.1.4.2 or earlier, or if you are at Oracle Access Manager version 10.1.4.3 and wish to start managed server from the command line:
- Copy the jobaccess.jar file from the $ASDK_DIR/oblix/lib folder to the $DOMAIN/lib folder.
- Stop managed server.
- On Linux, open the file $DOMAIN/bin/startManagedWebLogic.sh:
  
  Add the following lines:
```
LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:accessSDK installdir/oblix/lib
export LD_LIBRARY_PATH
```
  If the Oracle Access Manager version is 10.1.4.2 or earlier, add the following two lines as well:
```
LD_ASSUME_KERNEL=2.4.19 
export LD_ASSUME_KERNEL
```
- On Windows, open the file $DOMAIN/bin/startManagedWebLogic.cmd:
  
  Add the following line:
```
set PATH=%PATH%;AccessSDK_InstallDir/oblix/lib
```
- Start managed server from the command line (not the administration console).

Configure Oracle Identity Federation

Take these steps:

Locate the Oracle Identity Federation instance in Fusion Middleware Control.
Navigate to Administration, then Service Provider Integration Modules, then Oracle Access Manager.
Enable the SP module.
Select the authentication mechanism to use when processing a SAML assertion (required in some cases when a local federation record needs to be created for the user).
Enter the directory where the Access Server SDK is installed. If the SDK is installed under the $DOMAIN_HOME directory, then the path to the folder can be relative to $DOMAIN_HOME; otherwise the path must be absolute.
Enter the default authentication scheme that Oracle Identity Federation should use when creating user sessions in Oracle Identity Federation.
Enter the cookie domain that Oracle Identity Federation will set when creating the Oracle Access Manager cookie.
Oracle Identity Federation can set the Oracle Access Manager cookie as either a persistent cookie or a session cookie. For a persistent cookie, enter the time in minutes during which the cookie will be valid; for a session cookie, enter 0.
Check whether the cookie should be marked as secure: in this case, the browser will send the cookie over an HTTPS connection.
Check the Logout Enabled box if logout needs to be enabled (recommended).
Check the Clear Cookie box if resetting the Oracle Access Manager cookie is enough for Oracle Identity Federation to log the user out of the Oracle Access Manager domain.
Check Redirect to Logout URL and fill in the URL if Oracle Identity Federation needs to redirect the user to a specific URL for Oracle Access Manager logout.

Note:
When the user needs to be redirected to an Oracle Access Manager URL for logout (in case Oracle Access Manager needs to perform extra operations), you need to configure Oracle Identity Federation by checking the Redirect to Logout URL box, and entering the URL to which the user is redirected. When Oracle Identity Federation redirects the user to that URL, it will append a return URL as a query parameter; this is the Oracle Identity Federation URL to which the user is redirected after performing the extra Oracle Access Manager operations.
The query parameter to be appended to the Oracle Access Manager logout URL is referenced by returnurl.
Save your changes.

Note:

The cookie domain must be set on the Webgate for the protected resource. An example of a cookie domain is:
```
.us.oracle.com
```
You use Fusion Middleware Control to configure the user data store that Oracle Identity Federation uses when creating policy objects in the Oracle Access Manager Policy Server.

If you change the user data store through Fusion Middleware Control:
- redo the Oracle Identity Federation/Oracle Access Manager integration
- update the existing authentication schemes that were created by Oracle Identity Federation in the Oracle Access Manager Policy Server.

Integrate Oracle Identity Federation with Oracle Access Manager

After processing an incoming SSO assertion and identifying the user, Oracle Identity Federation will create an Oracle Access Manager session for that user in the Oracle Access Manager domain. To do so, Oracle Identity Federation will:

Use a policy domain created by Oracle Identity Federation at configuration time.
Map the Oracle Identity Federation authentication mechanism, representing the authentication method used by the IdP to challenge the user, to an Oracle Access Manager authentication scheme that was created by Oracle Identity Federation at configuration time. If the mapped Oracle Access Manager authentication scheme does not exist, then Oracle Identity Federation will use the default authentication scheme entered in the Oracle Identity Federation configuration section
Interact with Oracle Access Manager to create the user session, by specifying the policy domain and the authentication scheme for that session

The policy domain name that you enter for Oracle Identity Federation cannot reference an existing policy domain that was not created by Oracle Identity Federation. It must be created by Oracle Identity Federation.
Set the Oracle Access Manager cookie in the user's browser

For proper integration, Oracle Identity Federation needs to create policy objects and authentication schemes in Oracle Access Manager. Perform the following operations:

Note:

This task assumes you have the appropriate administrator credentials for Oracle Access Manager. Ensure that the Oracle Access Manager Master Administrators account is used to create the policy objects.

See Also:

Oracle Access Manager Access Administration Guide

Locate the Oracle Identity Federation instance in Fusion Middleware Control.
Navigate to Administration, then Service Provider Integration Modules, then Oracle Access Manager.
Expand the Oracle Access Manager Properties section.
Enter the Oracle Access Manager credentials to configure Oracle Access Manager.

Note:
Credentials will only be used to connect to the Oracle Access Manager Server for configuration when you click the Configure Oracle Access Manager button; these credentials are not stored in any Oracle Identity Federation configuration file.
Enter the Host ID that Oracle Identity Federation must use when configuring the policy domain. Define the Host ID in the Oracle Access Manager server. The Host ID must contain the hostname:port information that the Oracle Identity Federation server is configured to use, and its variations.

Note:
This is a required parameter.
Enter the default authorization rule that will be used when creating the Policy Domain.
The available Oracle Identity Federation authentication mechanisms are listed in the table; for each, the table lists the mapped authentication scheme name and its authentication scheme level. These mappings are stored in Oracle Identity Federation only by default, and you need to select the mechanisms and schemes to be created, updated, or deleted in Oracle Access Manager.

When you select a scheme to create, and click Configure Oracle Access Manager, the scheme is created with the specified name and level, and mapped to the corresponding authentication mechanism in the Oracle Identity Federation configuration. One of the created schemes MUST be selected as the default Oracle Access Manager authentication scheme used by Oracle Identity Federation. By default this value is password-protected by Oracle Identity Federation, so if nothing is selected as default, then the password-protected authentication scheme must be selected for create. If you select a scheme to delete, likewise, the scheme is deleted from Oracle Access Manager. If you select a scheme for update, the authentication scheme level, whether scheme is the default Oracle Access Manager authentication scheme used by Oracle Identity Federation, and its name, are updated in Oracle Access Manager.

Note:
In order that the server can update/delete the authentication scheme, it must not be in use by any domains.
Click Configure Oracle Access Manager.

Protect an Oracle Access Manager Resource with Oracle Identity Federation

See Also:

Oracle Access Manager Access Administration Guide

After integrating Oracle Identity Federation with Oracle Access Manager and creating authentication schemes, you can now protect resources using the schemes you have created. Protecting a resource with a specific scheme has the following effect:

When a non-authenticated user (or an authenticated user with authentication level lower than that of the scheme) tries to access a resource protected by an Oracle Identity Federation authentication scheme, the Oracle Access Manager server redirects the user to Oracle Identity Federation for Federation SSO.
Oracle Access Manager provides Oracle Identity Federation the resource being requested as well as the Oracle Identity Federation authentication scheme name to be used.
Oracle Identity Federation maps that authentication scheme to an authentication mechanism, and then to a SAML/WS-Fed authentication method.
Oracle Identity Federation starts the Federation SSO flow by sending the user to an identity provider and by specifying the authentication method to use in challenging the user for authentication.
The IdP will challenge the user, create an assertion and send the user back to Oracle Identity Federation with the assertion.
Oracle Identity Federation processes the assertion, extracting from it the method used to authenticate the user and map it to an authentication mechanism.
After successful processing, Oracle Identity Federation maps the authentication mechanism to an authentication scheme and creates an Oracle Access Manager session for the user.
Oracle Identity Federation redirects the user to the requested resource.
Finally Oracle Access Manager grants access to the resource for the authenticated user.

3.2.4 Deploying Oracle Identity Federation with a Sun Java System Web Server

This section describes how to integrate the Sun Java System Web Server with Oracle Identity Federation to serve as a web proxy.

This section contains the following topics:

Requirements
Configuring Oracle Identity Federation Without a Web Proxy Server
Configuring Oracle Identity Federation Behind a Web Proxy Server
Updating the Identity and Access Management servers
Sun Java System Web Server Sample Configuration Files

3.2.4.1 Requirements

When using a proxy in front of Oracle Identity Federation, the host name and port number of the proxy server instance are used to access Oracle Identity Federation, and are set in the Oracle Identity Federation configuration.

3.2.4.2 Configuring Oracle Identity Federation Without a Web Proxy Server

Start by installing Oracle Identity Federation, and configure and integrate it with any back-ends (LDAP, RDBMS, Oracle Access Manager, and others) required by your deployment. This includes:

configuring Oracle Identity Federation for SSO SAML protocols
adding trusted providers to Oracle Identity Federation's Federations
integrating Oracle Identity Federation with back-ends

See Also:

3.2.4.3 Configuring Oracle Identity Federation Behind a Web Proxy Server

When configuring Oracle Identity Federation behind a Web Proxy server, the steps are similar to the ones performed in a non-Web Proxy server environment as described in Section 3.2.4.2, "Configuring Oracle Identity Federation Without a Web Proxy Server", except that:

The Web Proxy server will be configured to reference Oracle Identity Federation
The Oracle Identity Federation configuration will use the hostname and port information of the Web Proxy Server

Follow the standard procedures to configure Oracle Identity Federation as shown in Section 3.2.4.2, "Configuring Oracle Identity Federation Without a Web Proxy Server", with these modifications:

Change the configuration URLs to their respective proxy server URLs.

In Fusion Middleware Control, navigate to Administration, then Server Properties.
Collect the metadata using the proxy URLs, not actual URLs, then upload the metadata.

Navigate to Administration, then Security and Trust, and retrieve the metadata (the hostname/port information in the metadata will now use the new values). Distribute the metadata to the remote providers.
At the Access System console, create a host identifier in the format:
```
proxy-host:port
```
and change the challenge redirect of the authentication scheme to proxy-host:port.

See Also:

Oracle Access Manager Access Administration Guide for details about the Web-based user interface.

For details about configuring the Sun One proxy server for Oracle Identity Federation, see Guidelines for Modifying the obj.conf File in the document titled Oracle Fusion Middleware Using Web Server Plug-Ins with Oracle WebLogic Server.

3.2.4.4 Updating the Identity and Access Management servers

Oracle Identity Federation will now be accessed by the users through the Web Server Proxy, and the Identity and Access Management Servers need also to be updated so that they reference the proxy instead of the local Oracle Identity Federation machine.

Go to any back end that references Oracle Identity Federation (such as Oracle Access Manager or Oracle Single Sign-On), and update their configuration so that it uses the hostname/port values of the Web Proxy Server instead of the local machine where Oracle Identity Federation is installed.

3.2.4.5 Sun Java System Web Server Sample Configuration Files

The Web Proxy Server will need to forward the HTTP requests to the machine where Oracle Identity Federation is installed.

This section provides samples of the obj.conf and magnus.conf configuration files.

Sample obj.conf File

<Object name="default">
AuthTrans fn="match-browser" browser="*MSIE*" ssl-unclean-shutdown="true"
NameTrans fn="assign-name" from="/*" name="serverexample"
NameTrans fn="ntrans-j2ee" name="j2ee"
NameTrans fn=pfx2dir from=/mc-icons dir="/home/pfx/SunOne6.1/ns-icons" name="es-internal"
NameTrans fn=document-root root="$docroot"
PathCheck fn=unix-uri-clean
PathCheck fn="check-acl" acl="default"
PathCheck fn=find-pathinfo
PathCheck fn=find-index index-names="index.html,home.html,index.jsp"
ObjectType fn=type-by-extension
ObjectType fn=force-type type=text/plain
Service method=(GET|HEAD) type=magnus-internal/imagemap fn=imagemap
Service method=(GET|HEAD) type=magnus-internal/directory fn=index-common
Service method=(GET|HEAD|POST) type=*~magnus-internal/* fn=send-file
Service method=TRACE fn=service-trace
Error fn="error-j2ee"
AddLog fn=flex-log name="access"
</Object>

<Object name="j2ee">
Service fn="service-j2ee" method="*" 
</Object>
 
<Object name="cgi">
ObjectType fn=force-type type=magnus-internal/cgi
Service fn=send-cgi user="$user" group="$group" chroot="$chroot" dir="$dir" 
   nice="$nice"
</Object>
 
<Object name="es-internal">
PathCheck fn="check-acl" acl="es-internal"
</Object>
 
<Object name="send-compressed">
PathCheck fn="find-compressed" 
</Object>
 
<Object name="compress-on-demand">
Output fn="insert-filter" filter="http-compression"
</Object>

 
# Execute these instructions for any resource with the assigned name
# "server.example.com" 
<Object name="serverexample">
# Proxy the requested resource to the URL 
# "http://server.example.com:8080"
Service fn="service-passthrough" servers="http://unit1.mycorp.co.in:1234"
</Object>

Sample magnus.conf File

#
# The NetsiteRoot, ServerName, and ServerID directives are DEPRECATED.
# They will not be supported in future releases of the Web Server.
NetsiteRoot /home/pfx/SunOne6.1
ServerName calgary
ServerID https-oif_idp_flagstaff
#
RqThrottle 128
DNS off
Security off
PidLog /home/pfx/SunOne6.1/https-oif_idp_flagstaff/logs/pid
User pfx
StackSize 131072
TempDir /tmp/https-oif_idp_flagstaff-65cd125c
 
Init fn=flex-init access="$accesslog" format.access="%Ses->client.ip% 
   - %Req->vars.auth-user% [%SYSDATE%] \"%Req->reqpb.clf-request%\" 
   %Req->srvhdrs.clf-status% %Req->srvhdrs.content-length%"
Init fn="load-modules" shlib="/home/pfx/SunOne6.1/bin/https/lib/libj2eeplugin.so" shlib_flags="(global|now)"
Init fn="load-modules" shlib="/home/pfx/SunOne6.1/bin/https/passthrough/plugins/passthrough
   /libpassthrough.so"

3.2.5 Integrating with Third-Party Identity & Access Management Modules

Oracle Identity Federation provides cross-domain Single Sign-On using standard protocols such as SAML, Liberty, and WS-Federation.

Out of the box, Oracle Identity Federation integrates with several Identity and Access Management (IAM) products, including:

Oracle AS Single Sign-On
Oracle Access Manager
LDAP Standalone
Infocard

See Also:

Section 1.2.2, "Architecture" for a discussion of Oracle Identity Federation and its relationship to other federation components.

Oracle Identity Federation also provides a framework for developers to integrate custom or third-party Identity and Access Management solutions. This section explains the components of this framework, and shows you how to configure and integrate a custom IAM solution into the framework.

Note:

Oracle strongly discourages users from deploying any applications on the Oracle WebLogic Managed Server other than the custom integration and authentication described in this section, because doing so introduces potential security risks. Extraneous applications deployed in the Oracle WebLogic Managed Server can potentially affect the security of the federation server by allowing rogue software to change the behavior of the server flows.

This section includes the following topics related to custom engine implementation:

Architecture and Flows
Creating a Custom Authentication Engine
Creating a Custom SP Integration Engine
Logout

3.2.5.1 Architecture and Flows

At runtime, Oracle Identity Federation interacts with two types of external modules: a user data store, and an Identity and Access Management system.

Oracle Identity Federation works with the user data store to:

locate a user after local authentication
locate a user after processing an incoming SAML assertion
retrieve attributes for a specific user

The Identity and Access Management (IAM) system provides access control for protected resources. Oracle Identity Federation, as the federation server, interacts with IAM to:

authenticate a user when the server needs to obtain a user's local identity. This operation might occur when the server acts as an IdP, or when the server, as an SP, needs to authenticate the user during initial account linking/federation creation.
create an authenticated session for a specific user when the server processes an incoming SAML assertion and asserts the user's identity to the IAM system
process logout flows; in this case, the federation server invokes IAM capabilities to log the user out of the system

3.2.5.1.1 Architecture

Figure 3–1 depicts the different external and internal modules of an Oracle Identity Federation deployment, and how they interact at runtime:

Figure 3-1 Oracle Identity Federation Module Interactions

For the sake of this discussion, Oracle Identity Federation is depicted as three internal modules:

the Identity Federation Engine, which is responsible for creating and processing SAML messages such as AuthnRequest, assertion, and logout messages.

This module:
- works with the user data store when processing SAML messages;
- interacts with the authentication engine when it is necessary for a user to be locally identified; and
- interacts with the SP integration engines when the user is redirected to the IAM component after processing an assertion.
the authentication engines, which are responsible for processing requests from the federation engine to authenticate users. This module interacts with the IAM component and the user data store to authenticate the user and retrieve the unique identifier Oracle Identity Federation uses to reference the user.

This module can be invoked in either IdP or SP mode when local authentication is required.

After authenticating the user, the authentication engine sends the authentication information, such as the user's identifier, the time of authentication, and other data to the federation engine.
After successfully processing an incoming SAML assertion and locating the user referenced by the assertion, the federation engine instructs the SP integration Engine to create an authenticated session for that user in the IAM domain. It passes the necessary information (user's identifier, authentication time, and so on) to the SP integration Engine, which interacts with the IAM server to create the session.

3.2.5.1.2 Authentication Engine Framework

The authentication engine framework of Oracle Identity Federation is designed to authenticate a user, and includes several internal plug-ins that allow it to interact with the various IAM servers supported out of the box, such as:

Oracle Single Sign-On
Oracle Access Manager
Username/Password using an LDAP Server
Username/Password using an RDBMS Server
Username/Password using an RDBMS Table
InfoCard
Federation SSO Proxy
JAAS

Additionally, Oracle Identity Federation provides a framework so that the server can be integrated with third party authentication modules. The integrators have two approaches to customize Oracle Identity Federation to interact with other authentication platforms:

Design and implement an authentication module that will interact with Oracle Identity Federation using internal JavaEE Servlet forwards. The new module would also be linked to the third party authentication solution responsible of authenticating the user.
Leverage JAAS to use a specific Login module. Oracle Identity Federation will include an authentication engine, based on internal forwards, which uses the JAAS libraries to authenticate the user. This allows integrators to re-use any JAAS compliant login modules that already exist for use in Oracle Identity Federation server modules by configuring Oracle Identity Federation.

Here is a step-by-step description of how the authentication engine interacts with the other federation server components in a typical user flow:

The user accesses Oracle Identity Federation for an SSO operation (in either SP or IdP mode).
An internal process in the server determines that the user needs to be identified using a specific authentication mechanism (either the default one from the configuration or one requested by a remote service provider).
The Federation Server determines which authentication engine to use to challenge/identify the user for the specified authentication mechanism.
The Federation Server then internally forwards the user's request to the Web Context and Login Relative Path of the authentication engine to challenge/identify the user, and it passes some information, specified via Java Objects stored as Attributes of the HttpServletRequest instance:
- The authentication mechanism to use when challenging the user for identification
- An identifier referencing the current action that is being performed
- The ProviderID and the description of the remote service provider for which this local authentication is requested, if a Federation SSO operation is performed
- The identifier referencing the engine used to authenticate the user
- The identifier of the user
- The Force Authentication flag, indicating whether or not the engine should challenge the user even if the user is already authenticated.
- The Is Passive flag, indicating whether or not the engine is allowed to visually interact with the user.
- Optionally, a map of attributes that need to be set by the engine: these attributes are required in order for Oracle Identity Federation/IdP to create correctly the assertion with the AttributeStatement, as specified by the configuration for that specific remote provider.
- Optionally, a String containing the Oracle Identity Federation session identifier, if the user has already an active session. Oracle Identity Federation is passing the sessionID of the already existing user session (if one exists), to the authentication engine, so that the engine can persist state linked to the user, and it can reference that data by using the sessionID value. Later on, when the logout flow is being executed, Oracle Identity Federation will pass the sessionID that is being logged out to the engine, so that the engine can delete the data that was used for this user session.
The authentication engine processes the incoming request, and it has access to the information stored as HttpServletRequest attributes.
The authentication engine interacts with the IAM component and may challenge the user for credentials. After successful authentication, it may set a cookie (for example, to maintain the authenticated session with the IAM server and/or the target application).
The authentication module sends the user back to Oracle Identity Federation using an internal forward (Web Context /fed and Login Relative Path /user/loginsso), and it passes the following information as HttpServletRequest attributes:
- The identifier of the user
- Authentication time
- Expiration time of the authenticated session
- The authentication mechanism used to identify the user
- The identifier referencing the action that was being performed, from the request
- The identifier referencing the Engine used to authenticate the user
- Optionally, a map of attributes that will be stored in the user session.
- Optionally, a String containing the Oracle Identity Federation session identifier that Oracle Identity Federation needs to use to reference the Oracle Identity Federation user session. This allows the engine and Oracle Identity Federation to share the same identifier to reference the user session. Later on, when the logout flow is being executed, Oracle Identity Federation passes the sessionID that is being logged out to the engine, so that the engine can delete the data that was used for this user session.
Note:
- If the user ID attribute is empty but the Authentication Time and authentication mechanism attributes are not empty, it will mean to Oracle Identity Federation that the authentication succeeded, but that the user is unknown on the server. This is useful when Oracle Identity Federation, acting as an IdP, is configured to use the attributes passed by the engine to create an assertion
- If the Authentication Time or Authentication Mechanism attributes are empty, it indicates to Oracle Identity Federation that the authentication failed.
Oracle Identity Federation performs these actions:
- processes the incoming request
- retrieves the data embedded as attributes in the HttpServletRequest
- locates the user in the user data store
- creates a session for the user
- sets a cookie, and
- resumes the SSO operation.

3.2.5.1.3 SP Integration Engine Framework

The SP integration Engine included with Oracle Identity Federation consists of a servlet that processes requests from the server to create a user authenticated session at the IAM server. The engine includes several internal plug-ins that allow it to interact with different IAM servers, such as:

Oracle Single Sign-On
Oracle Access Manager
Oracle Identity Federation Test Application

Additionally, Oracle Identity Federation will provide a framework so that the server will be able to be integrated with third party IAM frameworks: the customized SP integration Module will interact with Oracle Identity Federation using internal J2EE Servlet forwards, and it will communicate with the third party IAM system to create the user authenticated session.

Here is a step-by-step description of how an SP integration Engine interacts with the Oracle Identity Federation Framework in a typical user flow:

The user attempts to access a resource protected by the IAM solution, and configured to use Federation SSO to authenticate the user.
The IAM deployment redirects the user to the corresponding SP integration Module on Oracle Identity Federation.
The SP integration Module decodes the information sent by the IAM deployment and internally forward the user to the Oracle Identity Federation server with the following information set as HttpServletRequest attributes:
- An optional authentication mechanism specifying to the SP which authentication mechanism to request the IdP to use during authentication.
  
  Note:
  if set, this parameter is used to determine the IdP to use, disregarding the default parameter described next.
- An optional Provider ID referencing the IdP to use for the Federation SSO. If missing, Oracle Identity Federation uses the IdP mapped for the specified authentication mechanism. If no IdP could be found, Oracle Identity Federation will use the IdP configured as the Default SSO IdP
- An optional federation ID referencing the affiliation to use to trigger the Federation SSO
- The relay state. It can contain a small string, for example a reference to some data saved in a repository or a small URL pointing to the protected resource to redirect the user to after completion of the SSO operation
- The identifier of the SP engine that started the SSO flow
- An optional boolean indicating if the Oracle Identity Federation server should authenticate the user locally using the authentication engines or if a Federation SSO should be started by redirecting the user to an IdP for authentication
- A Boolean object indicating whether or not to use the configuration stored in Oracle Identity Federation or to only start the SSO based on the information being passed by the SP engine, except the IdP
- A Boolean object indicating whether or not the SP should ask the IdP to challenge the user even if already authenticated
- A Boolean object indicating whether or not the SP should allow the IdP to create a federation record if one does not yet exist, during the SSO operation
- A Boolean object indicating whether or not the SP should ask the IdP not to interact with the user during the SSO operation
- A String representing the binding to use when sending the AuthnRequest
- A String representing the binding to use when sending the response with the assertion
- An optional authentication mechanism comparison specifying to the SP which authentication context comparison to request the IdP to use during authentication
- A String representing the NameID format the SP will ask to the IdP for the SSO operation
Oracle Identity Federation initiates a Federation SSO operation with a remote IdP.
The IdP authenticates the user and, if necessary, redirects the user, with an assertion, to the federation server acting as an SP.
The server processes the assertion and locates the user in the user data store. The user is now authenticated at the federation server.
Oracle Identity Federation internally forwards the user back to the SP integration Module by using the Web Context and Login Relative Path of that module configured in Oracle Identity Federation. The server will pass the following data as HttpServletRequest attributes:
- A Boolean object indicating if the SSO operation was successful
- The identifier of the user
- Authentication time
- Expiration time of the authenticated session
- The authentication mechanism used to identify the user
- The relay state
- The contents of the assertion: the NameID, the Issuer of the assertion and the optional attributes. Note: the content of the assertion is not passed as XML Data, that is the original assertion will not be passed back to the module. The extra data will be referenced as:
  - orafed-nameid-value containing the Name ID value
  - orafed-nameid-qualifier containing the Name ID qualifier
  - orafed-nameid-format containing the Name ID format
  - orafed-providerid containing the Peer ProviderID
- The top status of the SAML Response
- The low status of the SAML Response if any
- The status message if any
- The ProviderID that created the SSO assertion
- The identifier of the SP engine that will process the above information
- A String containing the Oracle Identity Federation identifier of the user session. Oracle Identity Federation is passing the sessionID of the user session to the SP engine, so that it can persist state linked to the user, and it can reference that data by using the sessionID value. Later on, when the logout flow is being executed, Oracle Identity Federation will pass the sessionID that is being logged out to the engine, so that the engine can delete the data that was used for this user session.
The SP integration Engine interacts with the IAM server to create an authenticated session for the user. The session is based on the data received from Oracle Identity Federation.
The SP integration Engine redirects the user to the final target URL.

3.2.5.1.4 Logout

When logging out, Oracle Identity Federation and the Authentication/SP Engines will need to be logged out. This will involve:

Logging out the user from the authentication engines
Logging out the user from the SP Engines
Performing the SAML/WS-Fed Global Logout profiles
Logging the user out from Oracle Identity Federation

Figure 3-2 Oracle Identity Federation Module Interactions

There are several ways to invoke the logout:

The user invokes the Oracle Identity Federation logout server, at /fed/user/logout by specifying an optional return URL. In this case, Oracle Identity Federation will logout the user from Authentication/SP Engines, the remote SAML providers and from Oracle Identity Federation itself, and Oracle Identity Federation will redirect the user to the return URL, or display the logout result page.
The user is redirected from a remote SAML/WS-Fed provider to Oracle Identity Federation using the Global Logout protocol. In this case, Oracle Identity Federation will logout the user from Authentication/SP Engines, the remote SAML/WS-Fed providers (except the one that sent the logout message), from Oracle Identity Federation itself and redirect the user back to the remote SAML provider that sent the original message.
The user initiates logout from an environment integrated with an Authentication/SP Engine. In that case, that environment would invoke the Authentication/SP Engine for logout, and the Engine would then send the user to Oracle Identity Federation for Logout. From that point, Oracle Identity Federation would log out the user from the Authentication/SP Engines (except the engine that redirected the user to Oracle Identity Federation), from Oracle Identity Federation itself and redirect the user back to the Authentication/SP Engine that started the flow

Note:

Internal forwards will be used to send the user from Oracle Identity Federation to the Authentication/SP Engines and from the Authentication/SP Engines to Oracle Identity Federation.

Oracle Identity Federation invokes Authn/SP Engine

When Oracle Identity Federation sends the user to the Authentication/SP Engine, it will:

Perform an internal forward to the web context and relative logout path of the engine
Specify the engine ID of the invoked Engine for logout
Optionally the identifier of the user session being logged out

When the Authentication/SP Engine will have logged the user out, the engine will internally forward the user back to Oracle Identity Federation, it will:

Perform an internal forward to the /fed web context and /user/logoutretsso
Specify the engine ID of the invoked Engine

Authn/SP invokes Oracle Identity Federation

When an Authentication/SP Engine invokes Oracle Identity Federation for logout, it will:

Perform an internal forward to the /fed web context and /user/logoutsso
Specify the engine ID of the invoked Engine for logout
Specify a return URL where Oracle Identity Federation will redirect the user after logout.

At the end of the Logout flow, the user will be logged out from Oracle Identity Federation and redirected to the return URL.

3.2.5.1.5 Requirements

Oracle Identity Federation's design is consistent with certain requirements regarding authentication operations and SP integration (where a user session is created at the IAM server). Consequently, you must meet the following requirements when implementing a custom authentication engine or an SP integration Engine:

The authentication engine, the SP integration Engine, the Identity Federation Engine and the IAM server must use the same user data store as the user repository. This store contains the user data used to look up and authenticate users.
The authentication engine and the SP integration engine must include a Java Servlet /JSP.
The data exchanges between Oracle Identity Federation and the Authentication/SP integration engines are done via internal HTTP request forwarding. This is actually an internal API call between the modules that relies on the J2EE servlet framework via the HTTP protocol.
A logout service needs to be implemented and made available to the authentication engine and/or the SP integration engine. This logout service must be published as Servlet/JSP.

3.2.5.2 Creating a Custom Authentication Engine

This section explains how to plan, develop, and implement a custom authentication engine.

3.2.5.2.1 Planning a Custom Authentication Engine

Creating a customized authentication engine involves:

creating a service that will process incoming requests from Oracle Identity Federation
implementing a module to authenticate a user
creating a service that forwards the user to the federation server with the required information
deciding whether or not the authentication engine will set a cookie after authenticating a user. If yes, the authentication module must be integrated into the logout process (see Section 3.2.5.4, "Logout")
packaging the services and module into a web application, and deploying the application to the Oracle WebLogic Managed Server where Oracle Identity Federation is running
configuring Oracle Identity Federation to reference the new authentication engine.
ensuring that the user identifier returned by the authentication engine references the same user in the Oracle Identity Federation User Data Store

3.2.5.2.2 Developing and Implementing the Authentication Module

Several aspects of module development are explained here.

URLs

Communication between the federation engine and the authentication engine occurs through internal servlet forwards that are equivalent to API calls. These forwards use the following J2EE API:

ServletContext.getContext(String contextPath)
   .getRequestDispatcher(String relativePath)
   .forward(HttpServletRequest request, 
      HttpServletResponse response)

where:

contextPath is the root context path of the web application. For example, the contextPath of Oracle Identity Federation is /fed.
relativePath is the service URL to which to forward the user; it is relative to the contextPath. For example, after authenticating a user, the authentication engine uses /user/loginsso as the relativePath when forwarding the user.

Oracle Identity Federation needs to be aware of the ID of the new authentication engine, as well as the contextPath and the relativePath. This is the URL that will process authentication requests issued by the federation server.

Adding or Modifying an Authentication Engine

To add an authentication engine or modify one:

Go to Fusion Middleware Control and locate the Oracle Identity Federation instance.
Navigate to Administration then Authentication Engines.
To add an authentication engine, click Add and enter a name for that authentication engine. Oracle Identity Federation generates an ID for that new engine

Note:
the name will only be used in Fusion Middleware Control for display purposes while the ID will be used during communications between Oracle Identity Federation and the authentication engine
To modify an authentication engine, select it and:
- Enable or disable the engine
- Specify the contextPath of the authentication engine in the Web Context field
- Specify the relative path of the login service of the authentication engine in the Login Relative Path field
- Enable or disable logout
- Specify the relative path of the logout service of the authentication engine in the Logout Relative Path field
Click Apply.

Implementing the Service

This section describes the roles that are played by the authentication engine, and the processing tasks that the service must be able to handle for a successful implementation.

The authentication engine needs to:

process requests from the federation engine
forward the user to the federation server after a successful authentication

When processing authentication requests from the server, the engine must process the following incoming data:

The authentication mechanism to use when challenging the user for identification as a String (identified by oracle.security.fed.authn.authnmech)
An identifier referencing the current action that is being performed as a String (identified by oracle.security.fed.authn.refid)
The ProviderID and the description of the remote service provider for which this local authentication is requested, if a Federation SSO operation is performed as a String (identified by oracle.security.fed.authn.providerid and oracle.security.fed.authn.providerdescription).
The identifier referencing the Engine used to authenticate the user (identified by oracle.security.fed.authn.engineid)
The identifier of the user as a String, if set (identified by oracle.security.fed.authn.userid)
The Force Authentication flag, a Boolean object, indicating whether or not the engine should challenge the user even if the user is already authenticated. If missing, False is assumed. (identified by oracle.security.fed.authn.forceauthn)
The Is Passive flag, a Boolean object, indicating whether or not the engine is allowed to visually interact with the user. If missing, False is assumed. (identified by oracle.security.fed.authn.passive)
Optionally, a map of attributes that need to be set by the engine: these attributes are required in order for Oracle Identity Federation/IdP to create correctly the assertion with the AttributeStatement, as specified by the configuration for that specific remote provider. (identified by oracle.security.fed.authn.attributes)

When Oracle Identity Federation receives an SSO assertion, processes it and requests that the user be locally authenticated because the server was not able to map the assertion to a local user, the Map contains this data from the assertion:
- orafed-nameid-value – the user's Name ID value
- orafed-nameid-qualifier – the user's Name ID qualifier
- orafed-nameid-format – the user's Name ID format
- orafed-providerid – the IdP's ProviderID
- orafed-assertionid - the ID of the assertion
- orafed-xmlmessage - the optional XML message containing the assertion.
See Section 6.13.2, "Provide XML Message to SP Engine after SSO Completes" for details.
Optionally, a String containing the Oracle Identity Federation session identifier, if the user has already an active session. Oracle Identity Federation is passing the sessionID of the already existing user session (if one exists), to the authentication engine, so that the engine can persist state linked to the user, and it can reference that data by using the sessionID value. Later on, when the logout flow is being executed, Oracle Identity Federation will pass the sessionID that is being logged out to the engine, so that the engine can delete the data that was used for this user session. (identified by oracle.security.fed.sessionid).

After successful authentication, the engine must forward the user to the federation server with the rootContext of the federation engine being /fed, and the relativePath /user/loginsso.

Oracle Identity Federation expects this data when processing the internal forward:

The identifier of the user as a String (identified by oracle.security.fed.authn.userid)
Authentication time as a Date object (identified by oracle.security.fed.authn.authntime)
Expiration time of the authenticated session as a Date object (identified by oracle.security.fed.authn.expirationtime)
The authentication mechanism used to identify the user as a String (identified by oracle.security.fed.authn.authnmech)
The identifier referencing the action that was being performed, from the request (identified by oracle.security.fed.authn.refid)
The identifier referencing the Engine used to authenticate the user (identified by oracle.security.fed.authn.engineid)
Optionally, a Map of attributes that will be stored in the user session. This map will have String objects as the keys and a set of objects as the values (identified by oracle.security.fed.authn.attributes).
Optionally, a String containing the Oracle Identity Federation session identifier that Oracle Identity Federation will need to use to reference the Oracle Identity Federation user session. This allows the engine and Oracle Identity Federation to share the same identifier to reference the user session. Later on, when the logout flow is being executed, Oracle Identity Federation will pass the sessionID that is being logged out to the engine, so that the engine can delete the data that was used for this user session. (identified by oracle.security.fed.sessionid)

Notes:

If the oracle.security.fed.authn.userid attribute is empty but the oracle.security.fed.authn.authntime and oracle.security.fed.authn.authnmech attributes are not empty, it will mean to Oracle Identity Federation that the authentication succeeded, but that the user is unknown on the server. This is useful when Oracle Identity Federation, acting as an IdP, is configured to use the attributes passed by the engine to create an assertion
If the oracle.security.fed.authn.authntime or oracle.security.fed.authn.authnmech attributes are empty, it will mean to Oracle Identity Federation that the authentication failed

Here are some additional implementation requirements:

If the service needs to set any cookies, perform this operation before forwarding the user to the federation server.
Set the cookie path value to "/". This is required because of the internal forwards between the Oracle Identity Federation web application and the authentication engine web application; the user's browser needs to send the cookies related to the authentication engine, even when it is accessing only the federation server. This way, at an internal forward from the federation server to the authentication engine, the cookies set by the engine are available in the HTTP Request.

3.2.5.2.3 Sample Authentication Module for Oracle Single Sign-On Integration

This section describes how to integrate a custom authentication engine with OracleAS Single Sign-On.

Setup

In this example, the application server where Oracle Identity Federation is running has been integrated with the Oracle Single Sign-On server, and the SSO module statically protects the /engine/forward.jsp URL.

Additionally, the user data store configured for Oracle Identity Federation references the Oracle Internet Directory server used by Oracle Single Sign-On.

See Also:

Section 3.2.2, "Deploying Oracle Identity Federation with Oracle Single Sign-On" for more information on SSO integration.

Packaging

The authentication engine consists of a Web application with a root context set to /engine, and contains two JSP pages:

authentication.jsp which processes the incoming request from Oracle Identity Federation
forward.jsp which is protected by Oracle Single Sign-On, and which forwards the user back to the federation server with the required data.

Adding the Engine

To add the engine:

Go to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.
Navigate to Administration, then Authentication Engines. Select the Authentication Engines - Custom tab.
To add an Authentication Engine, click Add and enter a name for that Authentication Engine. Oracle Identity Federation will generate an ID for that new engine: this ID will be reference by TEST_ENGINE_ID for this test
Select the authentication engine to modify it:
- Enable the engine.
- Set "/engine" as the Web Context of the authentication engine
- Set "/authentication.jsp" as the Login Relative Path of the Authentication Engine
Click Apply.

Implementation of authentication.jsp

<%@page buffer="5" autoFlush="true" session="false"%>
<%@page language="java" import="java.net.*"%>
<%
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "Thu, 29 Oct 1969 17:04:19 GMT"); 
 
String authnMech = (String)request.getAttribute("oracle.security.fed.authn.authnmech");
String refid = (String)request.getAttribute("oracle.security.fed.authn.refid");
 
String redirectURL = "/engine/forward.jsp?refid=" +
   (refid != null ? URLEncoder.encode(refid) : "");
 
response.sendRedirect(redirectURL);
%>

Implementation of forward.jsp

<%@page buffer="5" autoFlush="true" session="false"%>
<%@page language="java" import="java.util.*"%>
<%
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "Thu, 29 Oct 1969 17:04:19 GMT");
 
String refid = request.getParameter("refid");
String userID = request.getRemoteUser();
String authnMethod = "oracle:fed:authentication:password-protected";
Date now = new Date();
 
request.setAttribute("oracle.security.fed.authn.engineid", TEST_ENGINE_ID);
request.setAttribute("oracle.security.fed.authn.userid", userID);
request.setAttribute("oracle.security.fed.authn.refid", refid);
request.setAttribute("oracle.security.fed.authn.authnmech", authnMethod);
request.setAttribute("oracle.security.fed.authn.authntime", now);

request.getSession().getServletContext().getContext("/fed").getRequestDispatcher("/user/loginsso").forward(request, response);
%>

Since the Oracle Single Sign-On framework sets cookies in the user's browser, the authentication engine should be integrated into the logout flow; see Section 3.2.5.4, "Logout".

3.2.5.2.4 Sample Authentication Module for LDAP Integration

This section shows how to integrate a customized authentication engine with a standalone LDAP server.

Setup

The user data store configured in Fusion Middleware Control for Oracle Identity Federation references the LDAP server used by the Authentication Engine.

Packaging

The authentication engine consists of a Web application with a root context set to /engine, and contains two JSP pages:

loginpage.jsp, which processes the incoming request from the federation server, and displays the login page.
ldapforward.jsp, which authenticates the user's credentials against the LDAP server; upon success it forwards the user to the federation server.

Adding the Engine

To add the engine:

Go to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.
Navigate to Administration, then Authentication Engines. Select the Authentication Engines - Custom tab.
To add an Authentication Engine, click Add and enter a name for that Authentication Engine. Oracle Identity Federation will generate an ID for that new engine: this ID will be reference by TEST_ENGINE_ID for this test
Select the authentication engine to modify it:
- Enable the engine
- Set "/engine" as the Web Context of the authentication engine
- Set "/loginpage.jsp" as the Login Relative Path of the Authentication Engine
Save the changes.

Implementation of loginpage.jsp

<%@page buffer="5" autoFlush="true" session="false"%>
<%@page language="java" import="java.net.*"%>
<%
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "Thu, 29 Oct 1969 17:04:19 GMT");
 
String refid = request. getAttribute("oracle.security.fed.authn.refid");
 
String postURL = "/engine/ldapforward.jsp?refid=" +
   (refid != null ? URLEncoder.encode(refid) : "");
 
String msg = request.getParameter("message");
%>
<HTML>
<BODY>
<FORM action="<%=postURL%>" method="POST">
<% if(msg != null && msg.length() > 0) { %> <%=msg%><BR/> <%}%>
Username: <INPUT type="text" name="username"/><BR/>
Password: <INPUT type="password" name="password"/><BR/>
<INPUT type="submit" value="Submit"/>
</FORM>
</BODY>
</HTML>

Implementation of forward.jsp

<%@page buffer="5" autoFlush="true" session="false"%>
<%@page language="java" import="java.util.*, javax.naming.*, javax.naming.directory.*, java.net.*"%>
<%
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "Thu, 29 Oct 1969 17:04:19 GMT");
 
String refid = request.getParameter("refid");
String authnMethod = "oracle:fed:authentication:password-protected";
 
String userID = request.getParameter("username");
String password = request.getParameter("password");
Date now = new Date();
 
Hashtable env = new Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
env.put(Context.PROVIDER_URL, "ldap://mynode.us.mycorp.com:389");
env.put(Context.SECURITY_AUTHENTICATION, "simple");
env.put(Context.SECURITY_PRINCIPAL, "cn=" + userID + ",cn=users,dc=us,dc=oracle,dc=com");
env.put(Context.SECURITY_CREDENTIALS, password);
 
try {
   DirContext ctx = new InitialDirContext(env);
} catch (NamingException ex) {
   String redirectURL = "/engine/loginpage.jsp?refid=" +
      (refid != null ? URLEncoder.encode(refid) : "") + "&message=" + URLEncoder.encode(ex.toString() + " for " + userID);
   response.sendRedirect(redirectURL);
   return;
}
 
request.setAttribute("oracle.security.fed.authn.engineid", TEST_ENGINE_ID);
request.setAttribute("oracle.security.fed.authn.userid", userID);
request.setAttribute("oracle.security.fed.authn.refid", refid);
request.setAttribute("oracle.security.fed.authn.authnmech", authnMethod);
request.setAttribute("oracle.security.fed.authn.authntime", now);
 
request.getSession().getServletContext().getContext("/fed").getRequestDispatcher(“/user/loginsso”).forward(request, response);
%>

Logout

Since no cookies are set in this flow, the authentication engine is not required to integrate with the logout flow (described in Section 3.2.5.4, "Logout").

3.2.5.3 Creating a Custom SP Integration Engine

This section explains how to plan, develop, and implement a custom SP integration engine.

See Also:

Section 3.2.5.1.1, "Architecture" for a description of the SP integration engine and how it fits into Oracle Identity Federation architecture.

3.2.5.3.1 Planning a Custom SP Integration Engine

The steps for developing a custom SP integration engine involve:

creating a service to process requests from Oracle Identity Federation in SP mode
implementing a module to create an authenticated session for a user at the IAM server
redirecting the user to the final target URL
deciding whether the SP integration engine will set a cookie after it creates an authenticated session at the IAM Server. If so, the engine needs to be integrated into the logout process (Section 3.2.5.4, "Logout").
packaging these services and module into a web application, and deploying it to Oracle WebLogic Managed Server where the federation server is running
configuring Oracle Identity Federation to reference the new SP Integration module.
if the SP integration engine accesses a user repository, ensuring that it is the same user data store configured in Fusion Middleware Control for use by Oracle Identity Federation

3.2.5.3.2 Developing and Implementing the Integration Module

This section describes how to develop the integration module and how to implement it in the federation environment.

URLs

Communication between the Identity Federation Engine and the SP integration engine requires internal servlet forwards that are equivalent to API calls. These forwards are achieved with the following JavaEE API:

ServletContext.getContext(String contextPath)
   .getRequestDispatcher(String relativePath)
   .forward(HttpServletRequest request, 
      HttpServletResponse response)

where

contextPath is the root context path of the web application. For example, the contextPath of Oracle Identity Federation is /fed.
relativePath is the service URL to which the uses is forwarded, and is relative to the contextPath. For example, when starting a Federation SSO flow, the SP integration engine uses /sp/startsso as the relativePath when forwarding the user.

Oracle Identity Federation needs to be aware of the ID as well as the contextPath and the relativePath of the new SP integration engine; This is the URL that will process the result of the Federation SSO operation after the federation server has processed the incoming assertion.

Adding or Modifying an SP Integration Engine

To add or modify the SP integration engine take these steps:

Go to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.
Navigate to Administration then SP Integration Modules. Click the Custom SP Engine tab.
To add an SP integration engine, click Add and enter a name for that SP integration engine. Oracle Identity Federation will generate an ID for that new engine

Note:
the name will only be used in Fusion Middleware Control for display purposes while the ID will be used during communication between Oracle Identity Federation and the Authentication Engine
To modify an SP integration engine, select it and:
- Enable or disable the engine
- Specify the contextPath of the SP integration engine in the Web Context field
- Specify the relative path of the login service of the SP integration engine in the Login Relative Path field
- Select the authentication mechanism to use if a local authentication procedure needs to occur during the assertion processing (this can happen when Federated Identities are used to map the assertion to a user record, if the Federation record does not exist: in this case, the user will need to be locally authenticated in order to perform the one time operation that will create the record)
- Enable or disable logout
- Specify the relative path of the logout service of the SP integration engine in the Logout Relative Path field
Save your changes.

Implementing the Service

Upon receiving a request from Oracle Identity Federation, the SP integration engine needs to:

create an authenticated session for the user
redirect the user to the final URL

To initiate a Federation SSO operation, the SP integration module will need to forward the user to Oracle Identity Federation by specifying the following data as HttpServletRequest attributes:

An optional authentication mechanism specifying to the SP which authentication mechanism to request the IdP to use during authentication. (identified by oracle.security.fed.sp.authnmech). This parameter is ignored if usedefault is true or missing.

Note:
if set, this parameter will be used to determine the IdP to use, as described below, disregarding the usedefault parameter
An optional Provider ID referencing the IdP to use for the Federation SSO. If missing, Oracle Identity Federation will use the IdP mapped for the specified authentication mechanism. If no IdP could be found, Oracle Identity Federation will use the IdP configured as the default SSO IdP. The value is a String (identified by oracle.security.fed.sp.providerid)
An optional federation ID referencing the affiliation to use to trigger the Federation SSO, as a String (identified by oracle.security.fed.sp.federationid)
The relay state. It can contain a small string, for example a reference to some data saved in a repository or a small URL pointing to the protected resource to redirect the user to after completion of the SSO operation. (identified by oracle.security.fed.sp.relaystate)
The identifier of the SP engine that started the SSO flow, as a String (identified by oracle.security.fed.sp.engineid)
An optional boolean indicating if Oracle Identity Federation should authenticate the user locally using the authentication engines or if a Federation SSO should be started by redirecting the user to an IdP for authentication, as a Boolean (identified by oracle.security.fed.sp.localauthn ; default is false)
A Boolean object indicating whether or not to use the configuration stored in Oracle Identity Federation or to only start the SSO based on the information being passed by the SP engine, except the IdP (identified by oracle.security.fed.sp.usedefault). If missing, true is assumed.
A Boolean object indicating whether or not the SP should ask the IdP to challenge the user even if he/she is already authenticated (identified by oracle.security.fed.sp.forceauthn). This parameter is ignored if usedefault is true or missing.
A Boolean object indicating whether or not the SP should allow the IdP to create a federation record if one does not yet exist, during the SSO operation (identified by oracle.security.fed.sp.allowfedcreation). This parameter is ignored if usedefault is true or missing.
A Boolean object indicating whether or not the SP should ask the IdP not to interact with the user during the SSO operation (identified by oracle.security.fed.sp.passive). This parameter is ignored if usedefault is true or missing.
A String representing the binding to use when sending the AuthnRequest (identified by oracle.security.fed.sp.requestbinding). This parameter is ignored if usedefault is true or missing. Acceptable values are httpredirect, httpost, httppostsimple depending on the protocol
A String representing the binding to use when sending the Response with the assertion (identified by oracle.security.fed.sp.responsebinding). This parameter is ignored if usedefault is true or missing. Acceptable values are artifact or httpost depending on the protocol.
An optional authentication mechanism comparison specifying to the SP which authentication context comparison to request the IdP to use during authentication. (identified by oracle.security.fed.sp.authnmechcomparison). This parameter is ignored if usedefault is true or missing.
A String representing the NameID format the SP will ask to the IdP for the SSO operation (identified by oracle.security.fed.sp.nameidformat). This parameter is ignored if usedefault is true or missing.

Oracle Identity Federation will then perform a SAML/WS-Fed SSO operation with a remote IdP, process the assertion, map it optionally to a local user record and finally will forward the user back to the SP integration engine that initiated the operation by specifying the following information as HttpServletRequest attributes:

A Boolean object indicating if the SSO operation was successful (identified by oracle.security.fed.sp.authnresult)
The identifier of the user as a String (identified by oracle.security.fed.sp.userid)
Authentication time as a Date object (identified by oracle.security.fed.sp.authntime)
Expiration time of the authenticated session as a Date (identified by oracle.security.fed.sp.expirationtime)
The authentication mechanism used to identify the user as a String (identified by oracle.security.fed.sp.authnmech)
The relay state as a String (identified by oracle.security.fed.sp.relaystate)
The contents of the assertion: the NameID, the issuer of the assertion and the optional attributes. Note: the content of the assertion is not passed as XML Data, that is the original assertion will not be passed back to the module. The data will be passed as a Map with Strings as keys and Set of Objects as values (identified by oracle.security.fed.sp.attributes). The extra data will be referenced as:
- orafed-nameid-value containing the Name ID value
- orafed-nameid-qualifier containing the Name ID qualifier
- orafed-nameid-format containing the Name ID format
- orafed-providerid containing the Peer ProviderID
- orafed-assertionid - the ID of the assertion
- orafed-xmlmessage - the optional XML message containing the assertion
  
  See Section 6.13.2, "Provide XML Message to SP Engine after SSO Completes" for details.
The top status of the SAML Response as a String (identified by oracle.security.fed.sp.topstatus)
The low status of the SAML Response if any, as a String (identified by oracle.security.fed.sp.lowstatus)
The status message if any as a String (identified by oracle.security.fed.sp.statusmessage)
The ProviderID that created the SSO assertion as a String (identified by oracle.security.fed.sp.providerid)
The identifier of the SP engine that will process the above information (identified by oracle.security.fed.sp.engineid)
A String containing the Oracle Identity Federation identifier of the user session. Oracle Identity Federation is passing the sessionID of the user session to the SP engine, so that it can persist state linked to the user, and it can reference that data by using the sessionID value. Later on, when the logout flow is being executed, Oracle Identity Federation will pass the sessionID that is being logged out to the engine, so that the engine can delete the data that was used for this user session. (identified by oracle.security.fed.sessionid)

Using this data, the SP integration engine creates an authenticated session and redirects the user to the final target URL.

If the service needs to set cookies, the cookie path must be set to "/". This is necessary because of the internal forwards between the Oracle Identity Federation and SP integration engine web applications; the user's browser needs to send the cookies related to the SP integration engine, even when accessing only the federation server. This way, when an internal forward occurs from the federation server to the SP integration engine, the cookie set by the latter will be available in the HTTP Request.

3.2.5.3.3 Sample Integration Modules

The next two sections provide examples of implementing a custom authentication engine:

Sample Integration Module 1: Oracle WebLogic Server JavaEE Integration
Sample Integration Module 2: Customized Single Sign-On Integration

Note:

Oracle strongly discourages users from deploying any applications on the Oracle WebLogic Managed Server other than the ones for custom integration and authentication described as sample integration modules 1 and 2 below, because doing so introduces potential security risks. Extraneous applications deployed in the Oracle WebLogic Managed Server can potentially affect the security of the federation server by allowing rogue software to change the behavior of the server flows.

3.2.5.3.4 Sample Integration Module 1: Oracle WebLogic Server JavaEE Container Integration

This section shows a simple SP integration engine that uses the javax.servlet.http.HttpSession to set an attribute. The presence of this attribute shows whether or not a user is authenticated.

Note:

The example in this section is intended for illustration only and should not be used in a production environment. Indeed, it supposes that other applications deployed on the Oracle WebLogic Managed Server will consume data set by the SP integration engine, which is an approach strongly discouraged by Oracle. Furthermore, this example might not function properly in certain deployments, especially when propagating HttpSession across J2EE applications.

Setup

The SP integration engine will not interact with the user data store used by Oracle Identity Federation.

Packaging

The SP integration engine consists of a Web application with a root context set to /engine, and contains two JSP pages:

wlsintegration.jsp, which processes the request from the federation server and creates an HttpSession with a feduserid attribute containing the user's identifier
application.jsp, which serves as an application. It looks for the HttpSession's feduserid attribute, and triggers a Federation SSO if the attribute is not found

Adding or Modifying an SP Integration Engine

To add or modify the SP integration engine take these steps:

Go to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.
Navigate to Administration, then SP Integration Modules. Click the Custom SP Engine tab.
To add an SP integration engine, click Add and enter a name for that SP integration engine. Oracle Identity Federation generates an ID for that new engine: this ID will be reference by TEST_ENGINE_ID for this test
To modify an SP integration engine, select it and:
- Enable the engine
- Set "/engine" as the Web Context of the authentication engine
- Set "/wlsintegration.jsp" as the Login Relative Path of the SP integration engine
- Select the authentication mechanism to use if a local authentication procedure needs to occur during the assertion processing (this can happen when Federated Identities are used to map the assertion to a user record, if the Federation record does not exist: in this case, the user will need to be locally authenticated in order to perform the one time operation that will create the record)
Save your changes.

Implementation of application.jsp

<%@page buffer="5" autoFlush="true" session="false"%>
<%@page language="java" import="java.net.*"%>
<%
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "Thu, 29 Oct 1969 17:04:19 GMT");
 
String userid = (String)request.getSession().getAttribute("feduserid");
if (userid == null || userid.length() == 0) {
           request.setAttribute("oracle.security.fed.sp.engineid", TEST_ENGINE_ID);  
request.setAttribute("oracle.security.fed.sp.usedefault", Boolean.TRUE);
request.setAttribute("oracle.security.fed.sp.relaystate", "/engine/application.jsp");
      request.getSession().getServletContext().getContext("/fed").getRequestDispatcher("/sp/startsso").forward(request, response);
 return;
}
%>
Welcome <%=userid%>

Implementation of wlsintegration.jsp

<%@page buffer="5" autoFlush="true" session="false"%>
<%@page language="java" import="java.util.*"%>
<%
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "Thu, 29 Oct 1969 17:04:19 GMT");
 
String userid = (String)request.getAttribute("oracle.security.fed.sp.userid"); 
String targetURL  = (String)request.getAttribute("oracle.security.fed.sp.relaystate");
 
request.getSession().setAttribute("feduserid", userid);
response.sendRedirect(targetURL);
%>

Logout

Since this application sets up an HttpSession in the Oracle WebLogic Managed Server instance, the SP Integration engine must be integrated in the logout flow (see Section 3.2.5.4, "Logout").

3.2.5.3.5 Sample Integration Module 2: Customized Single Sign-On Integration

This section shows an SP integration engine that uses a simple Single Sign-On framework based on a cookie containing the username and the expiration time of the authenticated session.

Note:

This example is intended for illustration only and should not be used in a production environment. For example, the cookies set in this example are not encrypted, allowing an attacker to impersonate a user by manually constructing such cookies.

Setup

The SP integration engine will not interact with the user data store used by Oracle Identity Federation. The Engine will set up a cookie, for the entire domain, containing the user's identifier as a String variable and the session timeout as a long.

Packaging

The SP integration engine consists of a Web application with a root context set to /engine, and contains two JSP pages:

domainintegration.jsp, which processes the request from the Oracle Identity Federation server and creates a cookie with the user ID and session timeout
domainapplication.jsp, which serves as an application. It looks for the cookie and triggers a federation SSO if the cookie is not found.

Adding or Modifying an SP Integration Engine

To add or modify the SP integration engine take these steps:

Go to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.
Navigate to Administration, then SP Integration Modules. Click the Custom SP Engine tab.
To add an SP integration engine, click Add and enter a name for that SP integration engine. Oracle Identity Federation will generate an ID for that new engine: this ID will be reference by TEST_ENGINE_ID for this test
To modify an SP integration engine, select it and:
- Enable the engine
- Set "/engine" as the Web Context of the authentication engine
- Set "/domainintegration.jsp" as the Login Relative Path of the SP integration engine
- Select the authentication mechanism to use if a local authentication procedure needs to occur during the assertion processing (this can happen when Federated Identities are used to map the assertion to a user record, if the Federation record does not exist: in this case, the user will need to be locally authenticated in order to perform the one-time operation that will create the record)
Save your changes.

Implementation of domainapplication.jsp

<%@page buffer="5" autoFlush="true" session="false"%>
<%@page language="java" import="java.net.*, java.util.*"%>
<%
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "Thu, 29 Oct 1969 17:04:19 GMT");
 
Cookie[] cookies = request.getCookies();
String userid = null;
Date timeout = null;
for(int i = 0, size = (cookies != null ? cookies.length : 0); i < size; i++) {
   String name = cookies[i].getName();
   if ("spintegrationcookie".equals(name)){
      String value = cookies[i].getValue();
      StringTokenizer st = new StringTokenizer(value, "*");
      userid = st.nextToken();
      timeout = new Date(Long.parseLong(st.nextToken()));
      break;
   }
}
if (userid == null || userid.length() == 0) {
request.setAttribute("oracle.security.fed.sp.engineid", TEST_ENGINE_ID);  
request.setAttribute("oracle.security.fed.sp.usedefault", Boolean.TRUE);
request.setAttribute("oracle.security.fed.sp.relaystate", "/engine/domainapplication.jsp");
request.getSession().getServletContext().getContext("/fed").getRequestDispatcher("/sp/startsso").forward(request, response);
   return;
}
%>
Welcome <%=userid%>. You are logged until <%=timeout%>

Implementation of domainintegration.jsp

<%@page buffer="5" autoFlush="true" session="false"%>
<%@page language="java" import="java.util.*"%>
<%
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "Thu, 29 Oct 1969 17:04:19 GMT");
 
String userid = (String)request.getAttribute("oracle.security.fed.sp.userid"); 
String targetURL  = (String)request.getAttribute("oracle.security.fed.sp.relaystate");
Date expirationInst = (Date)request.getAttribute("oracle.security.fed.sp.expirationtime");
String cookieValue = userid + "*" + expirationInst.getTime();
Cookie cookie = new Cookie("spintegrationcookie", cookieValue);
cookie.setDomain(".us.oracle.com");
cookie.setPath("/");
response.addCookie(cookie);
response.sendRedirect(targetURL);
%>

Logout

Since this sample application sets up a domain cookie, the SP Integration engine must be integrated into the logout flow (see Section 3.2.5.4, "Logout").

3.2.5.4 Logout

This section explains how to configure logout flows.

3.2.5.4.1 Changing Logout Flow

This section contains topics relevant to redirection during logout.

URLs

During the logout operations, the user is being redirected between the federation engine and the logout service of the Authentication and SP integration engines.

Oracle Identity Federation needs to be aware of the location of the logout service in order to redirect the user to the servlet/jsp page for logout. This URL is defined in the Logout location field of the Authentication and SP Integration engines. The URL can be defined as the union of the Web Context of the engine and the Logout Relative path.

Implementing the Logout Service

The operations that need to be performed by the logout service include:

processing requests from the federation engine, logging the user out of the IAM framework and sending the user back to Oracle Identity Federation
processing requests from the IAM framework, sending the user to Oracle Identity Federation for logout, receiving the user back from Oracle Identity Federation after logout and sending the user to the IAM framework

Oracle Identity Federation invokes Authn/SP Engine

When Oracle Identity Federation sends the user to the Authentication/SP Engine, it will:

Perform an internal forward to the web context and relative logout path of the engine
Specify the engine ID of the invoked Engine on the HttpServletRequest the attribute referenced by oracle.security.fed.authn.engineid (if the engine is an Authentication Engine) or oracle.security.fed.sp.engineid (if the engine is an SP Engine)
Optionally specify on the HttpServletRequest the attribute referenced by oracle.security.fed.sessionid that will hold the identifier of the user session being logged out (String object)

When the Authentication/SP Engine will have logged the user out, the engine will internally forward the user back to Oracle Identity Federation, it will:

Perform an internal forward to the /fed web context and /user/logoutretsso
Specify the engine ID of the invoked Engine on the HttpServletRequest the attribute referenced by oracle.security.fed.authn.engineid (if the engine is an Authentication Engine) or oracle.security.fed.sp.engineid (if the engine is an SP Engine), and that attribute value will be the identifier of the engine that performed the logout operation

Authn/SP invokes Oracle Identity Federation

When an Authentication/SP Engine invokes Oracle Identity Federation for logout, it will:

Perform an internal forward to the /fed web context and /user/logoutsso
Specify the engine ID of the invoked Engine on the HttpServletRequest the attribute referenced by oracle.security.fed.authn.engineid (if the engine is an Authentication Engine) or oracle.security.fed.sp.engineid (if the engine is an SP Engine), and that attribute value will be the identifier of the engine being invoked for logout
Specify a return URL where Oracle Identity Federation will redirect the user after logout. That URL will be specified via HttpServletRequest attribute, referenced by oracle.security.fed.logout.returnurl.

At the end of the Logout flow, the user will be logged out from Oracle Identity Federation and redirected to the return URL.

3.2.5.4.2 Sample Logout Services

In the next two sections, these scenarios of logout services are outlined:

Logout Service Example #1 describes a custom logout service when both the Authentication and SP Integration engines are customized
Logout Service Example #2 describes a custom logout service when only the SP Integration engine is customized

3.2.5.4.3 Logout Service Example #1

This section describes how to integrate a custom Logout Service, assuming that both the Authentication and SP Integration engines have been customized, that is, the default engines are not used anymore.

Setup

In this example, the authentication engine is the LDAP engine described in section 3.3.2, and the SP integration engine is the Oracle WebLogic Server Integration engine described in Section 3.2.5.3.4, "Sample Integration Module 1: Oracle WebLogic Server JavaEE Container Integration".

Packaging

The Logout service consists of a JSP page bundled with the Authentication and SP Integration engines:

logout.jsp, which will process the request from Oracle Identity Federation, remove the feduserid attribute from the HttpSession object, set in the wlsintegration.jsp page, and redirect the user to either Oracle Identity Federation or the doneURL parameter.

Updating the Engine

To update the engine:

Go to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.
Navigate to Administration, then SP Integration Modules. Click the Custom SP Engine tab.
To modify an SP integration engine, select it and:
- Enable logout engine
- Set "/logout.jsp" as the Logout Relative Path of the SP integration engine
Save your changes.

Implementation of logout.jsp

<%@page buffer="5" autoFlush="true" session="false"%>
<%@page language="java" import="java.net.*"%>
<%
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "Thu, 29 Oct 1969 17:04:19 GMT");
 
request.getSession().removeAttribute("feduserid");
 
request.setAttribute("oracle.security.fed.sp.engineid", TEST_ENGINE_ID); 
 
request.getSession().getServletContext().getContext("/fed").getRequestDispatcher("/user/logoutretsso").forward(request, response);
%>

3.2.5.4.4 Logout Service Example #2

This section describes how to integrate a custom Logout Service, assuming that the SP Integration engine has been customized.

Setup

In this example, the SP integration engine is the customized SSO Integration engine described in Section 3.2.5.3.5, "Sample Integration Module 2: Customized Single Sign-On Integration".

Packaging

The Logout service consists of a JSP page bundled with the Authentication and SP Integration engines:

domainlogout.jsp, which will process the request from Oracle Identity Federation, remove the cookie, and redirect the user to the /logoutretsso URL.

Updating the Engine

To update the engine:

Go to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.
Navigate to Administration, then SP Integration Modules .
To modify the SP integration engine, select it and:
- Enable logout engine
- Set "/domainlogout.jsp" as the Logout Relative Path of the SP integration engine
Save your changes.

Implementation of domainlogout.jsp

<%@page buffer="5" autoFlush="true" session="false"%>
<%@page language="java" import="java.net.*"%>
<%
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "Thu, 29 Oct 1969 17:04:19 GMT");
 
Cookie cookie = new Cookie("spintegrationcookie", "");
cookie.setDomain(".us.oracle.com");
cookie.setPath("/");
cookie.setMaxAge(0);
response.addCookie(cookie);
 
request.setAttribute("oracle.security.fed.sp.engineid", TEST_ENGINE_ID); 
 
request.getSession().getServletContext().getContext("/fed").getRequestDispatcher("/user/logoutretsso").forward(request, response);
%>

3.2.6 Using the Test SP Engine

Oracle Identity Federation provides a test SP engine for the purpose of Single Sign-On testing. The following sections describe how to use the test SP engine.:

Configure the Test SP Engine
Use the Test SP Engine for SP-Initiated SSO
Use the Test SP Engine with IdP-Initiated SSO
Test SP Engine Results

Note:

The test SP engine must be disabled in a production environment.

3.2.6.1 Configure the Test SP Engine

Take these steps to enable/disable the test SP engine:

Log in to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.
Navigate to Administration, then Service Provider Integration Modules.
In the Test SP tab, select/unselect Enable Engine.

To make the test SP engine the default SP engine, follow these steps:

Log in to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.
Navigate to Administration, then Service Provider Integration Modules.
Select Default SP Integration Module to be Test SP (Note: The test SP engine must be enabled).

3.2.6.2 Use the Test SP Engine for SP-Initiated SSO

To use the test engine, you can initiate a single sign-on flow at the following URL:

HTTP://OIF-SP-HOST:OIF-SP-PORT/fed/user/testspsso

where:

HTTP is http for an open connection and https for a secure connection
OIF-SP-HOST is the hostname of the Oracle Identity Federation service provider server
OIF-SP-PORT is the http or https port number of the Oracle Identity Federation service provider server. Omit the entry for http port 80 or https port 443.

When you click the Start SSO button, a request is sent to the Oracle Identity Federation service provider to start Single Sign-On (that is, an authentication request is sent to the identity provider) with the information provided on the page. You can specify the following parameters:

IdP Provider ID: This is the Provider ID or description of the identity provider to which to the service provider will send the authentication request.
Authn Request Binding: This specifies the binding the service provider will use to send the authentication request. Applies only to SAML 2.0 protocol
Force Authentication: If checked, the identity provider is forced to authenticate the user, instead of possibly relying on a previous authentication context. Applies only to SAML 2.0/WS-Fed protocols.
Is Passive: If checked, the identity provider must not interact with the user. Applies only to SAML 2.0 protocol.
Relay State: In this field, you can enter any string. This is either an identifier for the request or a return URL and is returned as a relay state after the Oracle Sign-On flow has been performed.
Use Default Configuration: If checked, Oracle Identity Federation will use the default configuration for the following properties:
- Allow Federation Creation
- SSO Response Binding
- Name ID Format
- Requested Authentication Mechanism
- Authentication Mechanism Comparison
If not checked, the following applies:
- Allow Federation Creation: If not checked, the identity provider must not create a federation for the user, if one does not exist. Applies only to SAML 2.0 protocol
- SSO Response Binding: This specifies the binding that the service provider will request the identity provider to use when sending the response. Applies only to SAML protocols
- Name ID Format: This specifies the Name ID format that the service provider will request the identity provider to use when locating or creating a federation for the user. Applies only to SAML 2.0 protocol.
- Requested Authentication Mechanism: This specifies the local authentication mechanism that the service provider will use. The service provider will map this local mechanism to a protocol-specific method, and specify this method in its authentication request to the identity provider. (See Section 5.14.1, "About Authentication Mechanisms".) Applies only to SAML 2.0/WS-Fed protocols
- Authentication Mechanism Comparison: If using SAML 2.0, specifies the comparator that the identity provider will use when determining the authentication mechanism to use. Options are:
  - EXACT: the identity provider must use the requested authentication mechanism
  - MINIMUM: the identity provider must use a mechanism that is at least as strong as the requested authentication mechanism
  - BETTER: the identity provider must use a mechanism that is stronger than the requested authentication mechanism
  - MAXIMUM: the identity provider must use a mechanism that is as strong as possible without exceeding the strength of the requested mechanism

3.2.6.3 Use the Test SP Engine with IdP-Initiated SSO

You can also use the test SP engine to test IdP-initiated Single Sign-On. In the service provider, simply enable the test SP engine and configure the default SP engine to be Test SP, and begin IdP-initiated SSO from the identity provider. The test SP engine will display the results of the Single Sign-On operation.

3.2.6.4 Test SP Engine Results

After Single Sign-On has been performed, the test SP engine displays the results of the operation, including:

SSO Authentication Result: whether or not the operation was successful
User Identifier: the User ID of the user for which Single Sign-On was performed
Authentication Instant: the instant at which the identity provider authenticated the user.
Session Expiration Instant: the instant at which the user session will become invalid.
Authentication Mechanism: the local mechanism used to authenticate the user.
SSO Primary Status Code: The primary status code in the assertion received from the identity provider.
SSO Secondary Status Code: The secondary status code in the assertion received from the identity provider.
SSO Status Message: The status message in the assertion received from the identity provider.
IdP Provider ID: The Provider ID of the identity provider that authenticated the user.
A list of the attributes from the assertion received from the identity provider, including:
- orafed-providerid: The Provider ID of the identity provider that authenticated the user.
- orafed-nameid-format: The format of the Name ID of the user federation.
- orafed-nameid-value: The Name ID of the user federation.
- orafed-assertionid: The ID of the assertion received from the identity provider.
- Any user attributes included in the assertion received from the identity provider.