6 Additional Server Configuration

This chapter contains additional topics pertaining to Oracle Identity Federation server configuration and management. These topics include:

Setting up Single Sign-On Services
Working with Affiliations
Additional LDAP Configuration
Additional Configuration for High Availability
Additional RDBMS Configuration
Session Repository Configuration
Additional HTTP Configuration
Additional Protocol Configuration
Protecting the SOAP Endpoint
Configuring the SAML 2.0 IdP Discovery (Common Domain Cookie) Profile
Configuring the Identity Provider Discovery Service
Setting up Infocard
Additional Run-time Configuration
Additional Federation Data Store Configuration
Setting up Backwards Compatibility for Oracle Identity Federation 10g and ShareID service URLs
Mapping Users through Attributes and NameID in SP Mode
Automatic Account Linking Based on Attribute Query Mapping
User Opt-In and Opt-Out for Single Sign-On
Bypassing User Mapping During Assertion Processing
Overriding NameID Mapping Per Partner
Configuring Audience Restrictions for Assertions
Certificate Path Validation

6.1 Setting up Single Sign-On Services

There are several ways to perform a federated single sign-on (SSO) operation, depending on the back-end in use and where the flow is initialized. Table 6-1 shows the possible combinations:

Table 6-1 Federated Single Sign-On Combinations

Combination	Flow
Oracle Single Sign-On	User accesses a resource protected by `mod_osso`, triggering single sign-on, with Oracle Identity Federation acting as SP.
Oracle Access Manager	User accesses a resource protected by webgate, triggering single sign-on, with Oracle Identity Federation acting as SP.
SP-initiated single sign-on	User initiates single sign-on by directly accessing an Oracle Identity Federation URL, with Oracle Identity Federation acting as SP.
IdP-initiated single sign-on	User initiates a single sign-on by directly accessing an Oracle Identity Federation URL, with Oracle Identity Federation acting as IdP.

This section explains how to configure the different combinations:

Oracle Single Sign-On
Oracle Access Manager
SP-initiated SSO
IdP-initiated SSO

6.1.1 Oracle Single Sign-On

Oracle Single Sign-On can be configured to trigger an SSO operation when requesting a resource protected by mod_osso.

To achieve this, the Oracle Single Sign-On partner application must be defined and must be protected by mod_osso. The partner application must also be configured to use the SSO Security level associated with the SASSO Authentication plug-in. You do this by editing the ORACLE_HOME/sso/conf/policy.properties file of the Oracle Single Sign-On deployment, and setting the partner application (defined by its hostname and port) to the same security level as the SASSOAuthLevel property.

For example:

MediumHighSecurity_AuthPlugin = oracle.security.sso.server.auth.SASSOAuth
MediumSecurity_AuthPlugin = oracle.security.sso.server.auth.SSOServerAuth
...
www.app.com\:7890 = MediumHighSecurity
...
SASSOAuthnUrl= http\://oif-hostname\:oif-port/fed/user/sposso
SASSOLogoutUrl = http\://oif-hostname\:oif-port/fed/user/spsloosso
SASSOAuthLevel = MediumHighSecurity

Save the file and restart the Oracle Single Sign-On server to apply the changes.

The next time a user attempts an unauthenticated access to the protected resource, the user is redirected to Oracle Identity Federation where an SSO operation occurs.

URL Query Parameters

When requesting the protected resource, it is possible to specify URL query parameters that Oracle Identity Federation can use to perform the SSO operation. The parameters are:

providerid - This is the identifier of the identity provider to use to perform the SSO operation (optional). If missing, the default SSO provider, set in Fusion Middleware Control by navigating to Service Provider, then Common, then Default SSO Identity Provider, is used.
federationid - This is the identifier of the affiliation to use for the SSO (optional).

An example of such a URL is:

http://protected_app:port/path?providerid=http%3A%2F%2Fidp.com

Check that the URL query parameter values are correctly URL-encoded.

See Also:

Section 6.2, "Working with Affiliations" for more information

Refer to the Oracle Single Sign-On documentation for details about SSO configuration.

6.1.2 Oracle Access Manager

Oracle Access policies can be set up to initiate an SSO operation when the user requests a resource protected by the Oracle Access Manager WebGate agent.

To do this, use the Oracle Access Policy Manager to set up a policy domain or policy that protects the resource. When creating the authentication rule for the policy domain or policy, select the Fed SSO authentication scheme. Oracle Identity Federation automatically creates this authentication scheme when it is configured to use Oracle Access. The scheme initiates the single sign-on operation when the resource is accessed, resulting in a session for the local user associated with the federated user. Set up the authorization rules and expression for the policy domain or policy to allow access for the resulting local user.

URL Query Parameters

When requesting the protected resource, it is possible to specify URL query parameters that Oracle Identity Federation can use to perform the SSO operation. The parameters are:

providerid - This is the identifier of the identity provider to use to perform the SSO operation (optional). If missing, the default SSO provider, set in Fusion Middleware Control by navigating to Service Provider , then Common, then Default SSO identity provider, is used.
federationid - This is the identifier of the affiliation to use for the SSO (optional).

See Also:
Section 6.2, "Working with Affiliations" for more information

An example of such a URL is:

http://protected_app:port/path?providerid=http%3A%2F%2Fidp.com

Check that the URL query parameter values are correctly URL-encoded.

Refer to the Oracle Access Manager Identity and Common Administration Guide for details about SSO configuration.

6.1.3 SP-initiated SSO

When Oracle Identity Federation server is acting as a service provider, a user can initiate an SSO operation by directly requesting a service at the Oracle Identity Federation/SP instance.

The URL to be requested on Oracle Identity Federation is:

http(s)://OIF_host:OIF_port/fed/sp/initiatesso

URL Query Parameters

It is possible to specify URL query parameters when requesting the URL:

providerid - This is the identifier of the identity provider to use to perform the SSO operation (optional). If missing, the default SSO provider, set in Fusion Middleware Control by navigating to Service Provider, then Common, then Default SSO Identity Provider, is used.
federationid - This is the identifier of the affiliation to use for SSO (optional).

See Also:
Section 6.2, "Working with Affiliations" for more information
returnurl - This is the URL to which the user is sent after a successful SSO operation. It is required if the Unsolicited Relay State property, set in Fusion Middleware Control by navigating to Federations, then Service Providers (Common), is empty.

An example of such a URL is:

http://oif_host:oif_port/fed/sp/initiatesso?providerid=http%3A%2F%2Fidp.com&returnurl=http%3A%2F%FProtectedAppHost%2FProtectedAppPath

Check that the query parameter values are correctly URL-encoded.

6.1.4 IdP-initiated SSO

Oracle Identity Federation provides the ability to initiate an SSO operation by directly requesting a URL at the Oracle Identity Federation instance acting as an IdP; this is called an SSO IdP-initiated operation.

The url to be requested on Oracle Identity Federation is of the form:

http(s)://oif_host:oif_port/fed/idp/initiatesso

URL Query Parameters

It is possible to specify query parameters when requesting that URL:

providerid - This is the identifier of the service provider to use to perform the SSO operation (optional).
federationid - This is the identifier of the affiliation to use for the SSO (optional).

See Also:
Section 6.2, "Working with Affiliations" for more information
returnurl - This is the URL to which the user is sent after a successful SSO operation (optional).

Check that the query parameter values are correctly URL-encoded.

An example of such a URL is:

http://oif_host:oif_port/fed/idp/initiatesso?providerid=http%3A%2F%2Fsp.com&returnurl=http%3A%2F%FProtectedAppHost%2FProtectedAppPath

6.2 Working with Affiliations

The run-time functioning of affiliations depends on whether the Oracle Identity Federation server is acting as an IdP or an SP.

Oracle Identity Federation Acting as IdP

When Oracle Identity Federation is an IdP, provided the affiliation/SP is present and enabled in the circle of trust, the Oracle Identity Federation server is ready to process any requests originating from service providers using the affiliation.

Oracle Identity Federation Acting as SP

As an SP, you can trigger a single sign-on operation with an IdP using an affiliation to which the SP belongs. To do so, include a federationid query parameter in the URL protected by the IdM back-end, and set the parameter value to the affiliation ID.

For example with an Oracle Single Sign-On back-end, assuming that a resource is protected by mod_osso and configured for Oracle Identity Federation authentication, requesting the URL of this resource with the federationid query parameter instructs Oracle Identity Federation to use an affiliation when performing single sign-on with a peer IdP. Here is an example of such a URL:

http://protected_res_host:protected_res_port/path?federationid=http%3A%2F%Faffiliationid

It is also possible to directly access the http://oif_host:oif_port/fed/sp/initiatesso URL with the same federationid query parameter. In this case, Oracle Identity Federation triggers a single sign-on operation, and uses the Unsolicited SSO RelayState for the peer IdP as the URL to which the user is redirected after successful authentication.

Note:

The Unsolicited SSO RelayState is set by navigating to Federations, then Edit Trusted Provider in Fusion Middleware Control.

6.3 Additional LDAP Configuration

This section contains topics for LDAP configuration and maintenance:

Configuring the LDAP Inactivity Setting
Configuring the LDAP Read Timeout Setting
ECID Support for LDAP Connections

6.3.1 Configuring the LDAP Inactivity Setting

When Oracle Identity Federation is integrated with high availability LDAP servers to serve as user data store, federation data store, or authentication engine, the server keeps a pool of LDAP connections that can be re-used for subsequent requests.

Over time, the LDAP server may close some connections due to a long inactivity period, and if left unchecked, this can result in errors and a degradation of performance in Oracle Identity Federation.

You can set an inactivity attribute that tells Oracle Identity Federation how long an LDAP connection should be kept in a pool before being removed due to inactivity. By default the inactivity timeout is set to 300 seconds.

To set the inactivity settings for Oracle Identity Federation, enter the WLST script environment for Oracle Identity Federation and set the following properties:

Set the ldapconnectioninactivitytimeout long property from the authnengines group to the inactivity timeout in seconds to configure the LDAP Authentication Engine Inactivity Timeout as in this example:
```
setConfigProperty('authnengines', 'ldapconnectioninactivitytimeout', '300', 'long')
```
Set the userldapconnectioninactivitytimeout long property from the datastore group to the inactivity timeout in seconds to configure the LDAP user data store Inactivity Timeout as in this example:
```
setConfigProperty('datastore',
'userldapconnectioninactivitytimeout', '300', 'long')
```
Set the fedldapconnectioninactivitytimeout long property from the datastore group to the inactivity timeout in seconds to configure the LDAP Federation Data Store Inactivity Timeout as in this example:
```
setConfigProperty('datastore','fedldapconnectioninactivitytimeout', '300', 'long')
```

6.3.2 Configuring the LDAP Read Timeout Setting

When Oracle Identity Federation is integrated with LDAP servers for user data store, federation data store or LDAP authentication engine, the server communicates with the LDAP directory to retrieve user attributes, authenticate users, look up users and perform related operations.

Sometimes, the LDAP server can become unresponsive, causing the thread/user to wait for a response or an error. To avoid waiting too long for an error when the server is not responding, Oracle Identity Federation sets a read timeout property on the LDAP connection: if the LDAP server does not respond before the read timeout period, an error is generated, Oracle Identity Federation closes the connection, opens a new one and re-issues the LDAP command.

It is possible to set the read timeout setting to tell the Oracle Identity Federation server how long to wait for data from the LDAP server. By default the read timeout is set to 10 seconds.

To set the read timeout settings for Oracle Identity Federation, enter the WLST script environment for Oracle Identity Federation, and set the following properties if necessary (examples are included):

Set the ldapconnectionreadtimeout long property from the authnengines group to the read timeout in seconds to configure the LDAP Authentication Engine Read Timeout:
```
setConfigProperty('authnengines', 'ldapconnectionreadtimeout', 'long','10')
```
Set the userldapconnectionreadtimeout long property from the datastore group to the read timeout in seconds to configure the LDAP user data store read timeout:
```
setConfigProperty('datastore',
'userldapconnectionreadtimeout', 'long', '10')
```
Set the fedldapconnectionreadtimeout long property from the datastore group to the read timeout in seconds to configure the LDAP federation data store read timeout:
```
setConfigProperty('datastore', 'fedldapconnectionreadtimeout', 'long', '10')
```

6.3.3 ECID Support for LDAP Connections

Oracle Identity Federation 11g supports execution context ID (ECID) for DMS and audit purposes.

When creating an LDAP connection with Oracle Internet Directory, Oracle Identity Federation can pass the ECID context to the OID LDAP Connection.

This feature is disabled by default. To enable (disable) the feature, set the following properties to true (false):

Set the ldapuseecid boolean property in authnengines group of config for LDAP authn engine
Set the userldapuseecid boolean property in authnengines group of config for the LDAP user store
Set the fedldapuseecidboolean property in authnengines group of config for LDAP federation data store

Note:

The LDAP server (for which ECID support is being enabled) must be Oracle Internet Directory 11g Release 1 (11.1.1) or later.

6.4 Additional Configuration for High Availability

This section contains additional topics for high availability configuration:

Configuring High Availability LDAP Servers
Configuring the HTTP Session State Sleep/Retry Interval

6.4.1 Configuring High Availability LDAP Servers

By default, Oracle Identity Federation is not configured to integrate with a high availability LDAP server. To integrate Oracle Identity Federation with HA LDAP servers to serve as user data store, federation data store, or authentication engine, Oracle Identity Federation needs to be configured for based on the LDAP server's function.

Enter the WLST script environment for Oracle Identity Federation, then set the following properties as needed:

To integrate the user data store with an HA LDAP server, set the userldaphaenabled boolean property from the datastore group to true; otherwise set it to false:
```
setConfigProperty('datastore','userldaphaenabled', 'true', 'boolean')
```
To integrate the Federation Data Store with an HA LDAP server, set the fedldaphaenabled boolean property from the datastore group to true; otherwise set it to false:
```
setConfigProperty('datastore', 'fedldaphaenabled',
'true', 'boolean')
```
To integrate the LDAP authentication engine with an HA LDAP server, set the ldaphaenabled boolean property from the authnengines group to true; otherwise set it to false:
```
setConfigProperty('authnengines','ldaphaenabled', 'true', 'boolean')
```

6.4.2 Configuring the HTTP Session State Sleep/Retry Interval

When Oracle Identity Federation is deployed in HA mode in a cluster, it can be configured so that the User HTTP session state is replicated across the Oracle WebLogic servers where Oracle Identity Federation is running.

By default the HTTP session state replication is disabled for Oracle Identity Federation. To enable it, refer to Cluster-Wide Configuration Changes in the Oracle Fusion Middleware High Availability Guide.

The rest of this section provides some additional configuration for Oracle Identity Federation when HTTP session state replication is enabled.

Note:

For performance reasons, disabling HTTP session state replication is the preferred approach.

This additional configuration allows the user to visit different Oracle Identity Federation servers without encountering any errors during processing of a federation request.

Sometimes, the HTTP session state is not replicated fast enough between server instances, generating an error when the user accesses a service in an Oracle Identity Federation instance to which the state has not yet been copied.

You can choose one of two options to avoid this issue:

Enable sticky sessions on the load balancer to force a specific user to visit the same Oracle WebLogic Server managed server every time it sends an HTTP request;

or
Set additional configuration properties in Oracle Identity Federation so that, when the server detects that the HTTP session state has not been replicated yet, it can wait to allow the information to be copied. You can enable this feature and configure the wait time.

Note:

For performance reasons, enabling sticky sessions is the preferred approach.

To enable and set the wait time for the User HTTP Session State replication setting for Oracle Identity Federation, enter the WLST script environment for Oracle Identity Federation and set the following properties:

To configure Oracle Identity Federation to wait for the session state to be replicated, set the sessionreplicationenabled boolean property from the serverconfig group to true, otherwise set it to false:
```
setConfigProperty('serverconfig','sessionreplicationenabled', 'true', 'boolean')
```
Set the sessionreplicationtimeout long property from the serverconfig group to the wait time in milliseconds, for example:
```
setConfigProperty('serverconfig', 'sessionreplicationtimeout', '2000', 'long')
```

6.5 Additional RDBMS Configuration

This section contains additional topics for RDBMS configuration for Oracle Identity Federation:

Configuring RDBMS Session Cache
Configuring RDBMS Data Compression

6.5.1 Configuring RDBMS Session Cache

When Oracle Identity Federation is using an RDBMS to store the user session objects, the server uses a caching mechanism to improve performance at runtime: the server keeps a reference to recently used session objects in memory to avoid read access to the database.

Note:

This is a critical feature, since a given user's session is accessed multiple times when performing an SSO operation.

You can configure the maximum number of session entries in the cache, and the maximum time the session is present in the cache before it is cleared. By default, Oracle Identity Federation server caches a maximum of 25,000 session entries, for a maximum time of 300 seconds

It is important to set an optimal timeout, especially in cluster mode where the session can be destroyed by another Oracle Identity Federation server if:

a load balancer is used without sticky sessions
SOAP Logout is enabled

To set maximum number of entries and the timeout settings for Oracle Identity Federation, enter the WLST script environment for Oracle Identity Federation and set the properties as in the following examples:

Set the transientrdbmssessioncachesize long property from the datastore group to the maximum entries:
```
setConfigProperty('datastore', 'transientrdbmssessioncachesize', '25000', 'long')
```
Set the transientrdbmssessioncachetimeout long property from the datastore group to the cache timeout in seconds:
```
setConfigProperty('datastore', 'transientrdbmssessioncachetimeout', '300', 'long')
```

6.5.2 Configuring RDBMS Data Compression

To decrease the amount of data to be stored in an RDBMS, Oracle Identity Federation provides the capability to compress the data before storing it to the database.

When Oracle Identity Federation is integrated with an RDBMS to store its user session Data or Message Data, the decision on when to compress data can be important.

There are three kinds of data that can be compressed:

Note:

Liberty 1.x support is deprecated.

AuthnRequest for SSO Artifact profile: when Oracle Identity Federation acts as an IdP for Liberty 1.x protocol, the server stores the AuthnRequest message in the RDBMS when the artifact profile is used. If Liberty 1.x is not used, this data should not be compressed. By default compression is disabled.
Assertion Response for SSO Artifact profile: when Oracle Identity Federation acts as an IdP for SSO protocols, the server stores the Response message containing the assertion in the RDBMS when the artifact profile is used. This should be enabled if attributes are contained in the assertion. By default compression is enabled.
User Session Data: Oracle Identity Federation stores some session data related to the user at runtime. If several attributes are stored in the user session (set by a custom Authentication Engine, or because the Attributes assertion storage was enabled when Oracle Identity Federation is an SP), then compression should be used. By default compression is disabled.

To configure Oracle Identity Federation to compress data, enter the WLST script environment for Oracle Identity Federation and set the following properties:

Set the transientartifactrequestcompression boolean property from the datastore group to true if the AuthnRequest for SSO Artifact profile should be compressed, otherwise set it to false:
```
setConfigProperty('datastore','transientartifactrequestcompression', 'true', 'boolean')
```
Set the transientartifactresponsecompression boolean property from the datastore group to true if the assertion Response for SSO Artifact profile should be compressed, otherwise set it to false:
```
setConfigProperty('datastore', 'transientartifactresponsecompression', 'true', 'boolean')
```
Set the transientcompression boolean property from the datastore group to true if the user session Data should be compressed, otherwise set it to false:
```
setConfigProperty('datastore', 'transientcompression', 'true', 'boolean')
```

Note:

Liberty 1.x support is deprecated.

6.6 Session Repository Configuration

This section contains topics related to maintaining the session repository.

6.6.1 Storing Assertion Attributes of User Session

The Oracle Identity Federation server features a session store containing the session information of the currently authenticated users. This session repository is capable of storing attributes that Oracle Identity Federation can use, when acting as identity provider (IdP), to populate SSO assertions.

The attributes stored in the user session can be added to the store in two ways:

by a custom authentication engine, by setting a list of attributes to be saved in the user session
with Oracle Identity Federation acting as a service provider (SP), when processing an incoming assertion; Oracle Identity Federation can save the attributes contained in the assertion, and the NameID and providerID in the user session

By default, for performance reasons, the storage of assertion information in the user session is disabled when Oracle Identity Federation acts as an SP.

To configure the Oracle Identity Federation server to store the assertion information, enter the WLST script environment for Oracle Identity Federation instance, and set the following property:

Set the sessionstoreassertionattrs boolean property from the spglobal group to true if the attributes contained in the assertion, and the NameID and providerID, should be stored in the user session:
```
setConfigProperty('spglobal',
'sessionstoreassertionattrs', 'true', 'boolean')
```

otherwise set it to false:

setConfigProperty('spglobal','sessionstoreassertionattrs', 'false', 'boolean')

6.7 Additional HTTP Configuration

This section contains additional topics for HTTP configuration for Oracle Identity Federation:

Configuring HTTP-Only Flag for HTTP Cookies Set by Oracle Identity Federation
Precautions when Customizing the Page in HTTP Post Profile
Using a 303 Status Code for Redirects

6.7.1 Configuring HTTP-Only Flag for HTTP Cookies Set by Oracle Identity Federation

A non-standard extension to RFC2965 extends the set-cookie header further by specifying an HttpOnly flag. When you set this flag, the client (browser) should not make the cookie contents available to scripting environments. For example, the JavaScript document.cookie method should not return the cookie contents. This significantly protects against "cross-site scripting" and similar attacks.

By default Oracle Identity Federation does not set the HttpOnly flag.

The Oracle Identity Federation server can be configured to set the HttpOnly flag when setting in the user's browser:

the cookie used by Oracle Identity Federation to reference the user session
the Oracle Access Manager cookie

To configure Oracle Identity Federation to set the HttpOnly header, enter the WLST script environment for Oracle Identity Federation and set the following properties:

Set the cookiehttponlyenabled boolean property from the serverconfig group to true if the HttpOnly flag should be set when sending the Oracle Identity Federation cookie to the browser, otherwise set it to false:
```
setConfigProperty('serverconfig',
'cookiehttponlyenabled', 'true', 'boolean')
```
Set the oamcookiehttponlyenabled boolean property from the spengines group to true if the HttpOnly flag should be set when sending the Oracle Access Manager cookie to the browser, otherwise set it to false:
```
setConfigProperty('spengines',
'oamcookiehttponlyenabled', 'true', 'boolean')
```

6.7.2 Precautions when Customizing the Page in HTTP Post Profile

The SAML/WS-Fed specifications define a POST profile where a SAML/WS-Federation server will redirect a user's browser to a remote SAML/WS-Fed implementation through the use of an HTML form.

Typically, such a server would send the browser an HTML page containing a FORM with:

the action URL referencing the remote server
some hidden fields containing SAML/WS-Fed message, and/or some attributes

When using that profile, the Oracle Identity Federation server prepares the action URL, the providerID referencing the remote server, and the list of hidden fields to send to the remove server. It then hands over this data to the postprofile.jsp page (contained in the web.war of the $ORACLE_IDM_HOME/fed/install/oif.ear file) that uses the information to build the HTML page to be presented to the browser.

You can customize that page to:

Modify what is displayed to the browser
Add extra fields to send to the remote server

Note:
The remote SAML/WS-Federation server may not be able to process these fields, since they might not be compliant with the specifications.

When modifying the file to fit the particular needs of a deployment, be careful not to interfere with the POST profile, which can occur for example if you remove the required parameters/fields, such as the action URL or the hidden fields set by the Oracle Identity Federation server. To modify the file, unzip the oif.ear and the web.war, make the modification, and re-package the web.war and EAR file.

6.7.3 Using a 303 Status Code for Redirects

Oracle Identity Federation implements the SAML/WS-Fed/Liberty protocols that provide single sign-on (SSO) capabilities to HTTP clients, such as browsers. The protocols and profiles exercised at runtime during SSO operations can involve some HTTP redirects, where the Oracle Identity Federation server issues an HTTP redirect command to the browser.

Note:

Liberty 1.x support is deprecated.

By default, Oracle Identity Federation uses the 302 HTTP status code when issuing a redirect. It is possible to configure the Oracle Identity Federation server to instead use a 303 HTTP status code when issuing a redirect provided the client supports HTTP 1.1.

To configure Oracle Identity Federation to use the 303 HTTP status code when possible, enter the WLST script environment for the Oracle Identity Federation instance, and set the following property:

Set the redirectuse302 boolean property from the serverconfig group to false if the Oracle Identity Federation server should use 303 HTTP status code when possible:
```
setConfigProperty('serverconfig',
'redirectuse302', 'false', 'boolean') 
```
otherwise set the property to true.

6.8 Additional Protocol Configuration

This section contains these topics:

Configuring for eAuth Mode
Configuring the SAML 2.0 LDAP Attribute Profile
Configuring On-Demand Global Logout

6.8.1 Configuring for eAuth Mode

You can configure the Oracle Identity Federation server to comply with the eAuth specifications. Most of the configuration is performed through Fusion Middleware Control, but the specifications require the presence of two attributes in the SSO assertion that can only be configured through the MBeans/WLST scripts:

the us:gov:e-authentication:basic:specVer attribute containing the version of the eAuth specifications supported by this server
the us:gov:e-authentication:basic:Sid attribute containing the session identifier of the user performing the single sign-on

To configure Oracle Identity Federation to set those two attributes (for a specific provider) and to set the value of the eAuth version, enter the WLST script environment for Oracle Identity Federation instance, and set the following properties if needed:

Set the eauthmodeenabled boolean property for the remote provider to true to enable the eAuth mode:

setFederationProperty(REMOTE_PROVIDER_ID,
'eauthmodeenabled', 'true', 'boolean')
##
## replace REMOTE_PROVIDER_ID with the identifier of the remote provider

Set the eauthversion string property from the idpglobal group to the value the Oracle Identity Federation server should use (2.0 for example):
```
setConfigProperty('idpglobal', 'eauthversion', '2.0', 'string')
```

6.8.2 Configuring the SAML 2.0 LDAP Attribute Profile

The SAML 2.0 specifications define the X.500 LDAP attribute profile, listing the attributes that an assertion must contain to be compliant with that profile.

The requirements are as follows:

The format must be urn:oasis:names:tc:SAML:2.0:attrname-format:uri.
The name must be a URI.
The SAML Attribute element must specify an XML Encoding attribute and its value must be set to "LDAP".

The first two requirements are met by configuring the attribute for the Oracle Identity Federation server instance in Fusion Middleware Control.

The last requirement is met by configuring Oracle Identity Federation with WLST scripts; a property is set for a specific provider to which Oracle Identity Federation/IDP/AttributeAuthority will send the attributes contained in an assertion.

How to Use WLST for the X.500 LDAP Attribute Profile

Enter the WLST script environment for the Oracle Identity Federation server instance, then set the attrx500ldapenabled property for the remote provider to which Oracle Identity Federation will provide the assertion.

Set the attrx500ldapenabled boolean property to true to make the server compliant with the X.500 LDAP attribute profile. Otherwise set it to false:

setFederationProperty(REMOTE_PROVIDER_ID,
'attrx500ldapenabled', 'true', 'boolean') 
##
## replace REMOTE_PROVIDER_ID with the identifier of the remote provider

6.8.3 Configuring On-Demand Global Logout

You can specify whether WS-Fed/SAML Global Logout should be executed when a logout operation is invoked at the Oracle Identity Federation server.

In a typical federation deployment, when the user invokes logout at the federation server, the flow is as follows:

The user invokes the Oracle Identity Federation logout service at the /fed/user/logout URL.

See Section 4.2.5, "Launch the Logout Process" for details about the logout service.
Oracle Identity Federation:
- logs the user out of the various authentication engines and SP integration modules (Oracle Access Manager, Oracle Single Sign-On, and others)
- redirects the user for logout from the remote Federation partners involved in the current user session: this operation is called Global Logout.
- finishes the logout operation once the global logout is complete.

You can disable the Global Logout flow with Fusion Middleware Control in two ways:

globally, by selecting the "Local Logout Only" setting described in Section 5.2, "Configuring Server Properties".
on a per-provider basis, by selecting the "Do not perform Global Logout with this Provider" setting on the Oracle Identity Federation Settings tab of the partner configuration section.

While these two approaches provide static control over the logout flow behavior, on-demand global logout lets you specify whether the user can invoke the global logout protocol at runtime.

To specify whether the user can choose global logout, you configure the federation server by setting the slouserprefenabled boolean property of the serverconfig group as follows:

true to allow the user to choose global logout
false to disallow the user from choosing global logout

To set the property, enter the WLST script environment for the Oracle Identity Federation server instance, and set the following property:

setConfigProperty('serverconfig', 'slouserprefenabled', 'true', 'boolean')

When on-demand global logout is enabled, the user can choose to perform the WS-Fed/SAML Logout operation by specifying the globalslo query parameter when invoking the Oracle Identity Federation logout service URL.

This parameter is of type boolean, and accepts one of two values:

true, meaning that the global logout operation should be performed
false, meaning that only the local logout should be performed

Following the instructions in Section 4.2.5, "Launch the Logout Process", the user invokes the service with a URL similar to:

http://hostname:port/fed/user/logout?returnurl=http%3A%2F%2Fanotherhostname%2Fpath&globalslo=false

6.9 Protecting the SOAP Endpoint

Oracle Identity Federation provides two methods to protect the SOAP endpoint used in the SAML 1.x / SAML 2.0 / Liberty 1.x protocols:

SSL with Client Authentication via SSL Certificate: the SOAP endpoint is protected with SSL, and by requiring an SSL Client certificate
HTTP Basic Authentication: with this method, the SOAP endpoint is protected using the HTTP Basic Authentication mechanism.

Note:

Liberty 1.x support is deprecated.

Topics include:

SSL Client Authentication
HTTP Basic Authentication

6.9.1 SSL Client Authentication

Refer to Section 8.1, "Configuring SSL for Oracle Identity Federation" for details on how to:

configure SSL to protect the SOAP URL
configure Oracle Identity Federation to connect to SOAP endpoints protected by SSL

6.9.2 HTTP Basic Authentication

This section describes:

how to configure HTTP Basic Authentication on the server to protect SOAP URLs
how to configure the credentials that are used when connecting to a remote server protected by HTTP basic authentication using the SOAP protocol

Note:

When it is integrated with Oracle Single Sign-On with mod_osso, Oracle Identity Federation cannot be protected using HTTP Basic Authentication.

6.9.2.1 Configuring HTTP Basic Authentication to protect the SOAP URLs

This section lists the steps needed to protect the SOAP endpoints. The configuration changes are made on the Oracle WebLogic administration server.

The steps are as follows:

Configure Oracle WebLogic Server to check created policies

Log in to the Oracle WebLogic Server Administration Console.
On the left-hand pane, select Security Realm, and navigate to myrealm, then Configuration, then Advanced.
Select the following settings:
- Check roles and Policies: "All Web applications and EJBs"
- When Deploying Web Applications or EJBs: "Initialize roles and policies from DD"
  
  Click Save.
Stop the Administration server by navigating to Environment, then Servers, then Control, selecting "AdminServer" and clicking Shutdown - Force Shutdown Now.
From a terminal window, start the Administration server by invoking the script: $DOMAIN_HOME/bin/startWebLogic.sh.

Create a Group and a User

Log in to the Oracle WebLogic Server Administration Console.
On the left-hand pane, select Security Realms and navigate to myrealm, then Users and Groups, then Groups.
Click New and select a name (for example, soapusers). Click OK.
Navigate to Users and Groups, then Users.
Click New and select a name and password. Click OK.
Click on the user you just created and select the Groups tab.
Select the group you created and move it to the Chosen column. Click Save.

To enter additional users, repeat steps 4-7.

Create a Role and a Policy

Log in to the Oracle WebLogic Server's Administration Server console.
On the left-hand pane, select Deployments, expand the Oracle Identity Federation application, and click on "/fed".
Navigate to Security, then Roles.
Click New and select a name (for example, soapusers). In the URL Pattern, enter "/". Click OK.
Click on the role you just created and click Add Conditions.
Select Group and click Next.
Enter the name of the group you created and click Add, then Finish.
Click Save.
On the left-hand pane, select Deployments, expand the Oracle Identity Federation application and click on "/fed".
Navigate to Security, then Policies.
To protect the SOAP endpoint, you need to create a set of policies (one policy per URL you need to protect). The list of URLs that need to be protected is displayed in Table 6-2. To create a policy, follow these steps.:
1. Click New and enter the URL (from Table 1) that needs to be protected. Click OK.
2. Click on the policy you just created and click Add Conditions.
3. Select Role and click Next.
4. Enter the name of the role you created and click Add, then Finish.
5. Click Save.
After creating the group, users, role and policies, restart the administration and managed servers for the changes to take effect.

Table 6-2 URLs which Need Policies Created

Liberty 1.x/SAML 2.0 SOAP Endpoint	SAML 1.x SOAP Endpoint
/idp/soap	/idp/soapv11
/sp/soap	/sp/soapv11
/aa/soap	/aa/soapv11
/ar/soap	/authnauth/soapv11
/authnauth/soap

6.9.2.2 Configuring Oracle Identity Federation to Connect to a Protected SOAP URL

On the client side, Oracle Identity Federation implements support for basic authentication when connecting to peer providers on the SOAP channel. You need to update the Oracle Identity Federation configuration so that the server can use the entered credentials when connecting to the SOAP endpoint of the remote provider.

Take these steps to enable Oracle Identity Federation to connect to a protected SOAP URL:

Log in to the Fusion Middleware Control console for the domain where Oracle Identity Federation is deployed.
Navigate to Oracle Identity Federation, then Administration, then Federations.
Select the remote provider that requires HTTP basic authentication on the SOAP channel, and click Edit.
In the Oracle Identity Federation Settings tab, select Enable HTTP Basic Authentication and enter the user name and password the server must use when connecting to the remote provider.
Click Apply.

6.10 Configuring the SAML 2.0 IdP Discovery (Common Domain Cookie) Profile

SAML 2.0 enables a service provider to discover the identity providers a user has used to authenticate. After authenticating a user, the IdP adds its Provider ID to the value of a cookie in the user's browser. The SP then reads this cookie and discovers the IdPs used. For the IdPs and SPs to write to and read from this cookie, the cookie must be in a domain common to all IdPs and SPs. Thus, this cookie is called the Common Domain Cookie (CDC).

When acting as an SP, if the CDC profile is enabled and an SSO operation is initiated without the provider ID of the target IdP, Oracle Identity Federation reads the common domain cookie and performs SSO with the first IdP in the list. You can also configure Oracle Identity Federation to prompt the user to choose the IdP with which to perform SSO. The user is then able to select from the list of all IdPs in the CDC that are also trusted by Oracle Identity Federation, acting as an SP.

This section describes how to configure Oracle Identity Federation to use the CDC profile. It contains these topics:

Preliminary Steps to Set Up the CDC
Configuring the CDC Profile as an Identity Provider
Configuring the CDC Profile as a Service Provider
Configuring Oracle Identity Federation to Display List of Trusted Providers in CDC

6.10.1 Preliminary Steps to Set Up the CDC

The common domain cookie is always marked as secure, so use of the CDC Profile requires enabling SSL, whether acting as an identity provider or a service provider. To enable SSL, follow the instructions in Section 8.1, "Configuring SSL for Oracle Identity Federation".

6.10.2 Configuring the CDC Profile as an Identity Provider

If Oracle Identity Federation is acting as an IdP, follow these steps to configure the CDC profile:

Log in to Oracle Enterprise Manager and navigate to the Oracle Identity Federation instance.
Navigate to Administration, then Identity Provider.
In the Common tab, check Enable Common Domain and enter the following properties:
- Common Domain URL: The Oracle Identity Federation intro URL in the Common Domain where Oracle Identity Federation is listening:
```
https://hostname_in_common_domain:sslport/fed/idp/intro
```
  For example:
```
https://mycorp.commondomain.com:4443/fed/idp/intro
```
  Note:
  This URL must use HTTPS and the SSL port that you configured earlier.
- Name: The domain in which the cookie is written, for example,.commondomain.com.
  
  Note:
  The name of the domain must always start with a leading period ".".
- Cookie Lifetime (day): The lifetime (in days) of the cookie

6.10.3 Configuring the CDC Profile as a Service Provider

If Oracle Identity Federation is acting as a service provider, follow these steps to configure the CDC profile:

Log in to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.
Navigate to Administration, then Service Provider.
In the Common tab, check Enable Common Domain Cookie Service, and enter the following property:
- Service URL - The Oracle Identity Federation introsso URL in the Common Domain where Oracle Identity Federation is listening:
```
https://hostname_in_common_domain:sslport/fed/sp/introsso
```
  For example:
```
https://mycorp.commondomain.com:4443/fed/sp/introsso
```
  Note:
  This URL must use HTTPS and the SSL port you configured earlier.

6.10.4 Configuring Oracle Identity Federation to Display List of Trusted Providers in CDC

Follow these steps to configure Oracle Identity Federation to prompt the user with the list of trusted IdPs in the common domain cookie when an SSO flow is initiated without the provider ID of the target IdP

Configure the CDC profile as described in Section 6.10.3, "Configuring the CDC Profile as a Service Provider"
Use the Oracle Identity Federation WLST commands or MBeans to set the commondomainidpdiscenabled property in Config "spglobal" to true.

Using the WLST Commands

Use the command:

setConfigProperty('spglobal', 'commondomainidpdiscenabled', 'true', 'BOOLEAN')

SeeChapter 9, "Oracle Identity Federation Command-Line Tools" for more information.

Using MBeans

In the ConfigMXBean named spglobal, invoke the putProperty operation with the following arguments:

Name: "commondomainidpdiscenabled"
Value: "true"
Type: "BOOLEAN"

See Appendix A, "Oracle Identity Federation MBeans" for more information.

6.11 Configuring the Identity Provider Discovery Service

Identity provider discovery is a service that selects an identity provider (possibly through interaction with the user) to use during SSO. While Oracle Identity Federation does not provide an identity provider discovery service, it provides support for using such a service to select an IdP, if one is not passed in the authentication request to the SP during SP-initiated SSO.

For more information refer to the specifications at:

http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-idp-discovery-cs-01.pdf

If acting as a service provider, Oracle Identity Federation can be configured so that if an SSO operation is initiated without the provider ID of the target IdP, the user is redirected to a custom page to select the identity provider with which to perform SSO.

After the user selects an identity provider, the custom page resubmits the SSO request with the chosen IdP to Oracle Identity Federation.

Follow these steps to configure IdP discovery:

Log in to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.
Navigate to Administration, then Service Provider.
In the Common tab, check "Enable Identity Provider Discovery Service", and enter the following property:
- Service URL: The location of the custom page displaying the IdP choices.

6.11.1 Create the IdP Discovery Service Page

Oracle Identity Federation redirects to the IdP Discovery Service page with the following parameters:

return: This is the URL to which the page should send the new request containing the chosen IdP provider ID to Oracle Identity Federation.
returnIDParam: This is the name of the parameter to use to specify the chosen IdP provider ID in the request sent to Oracle Identity Federation.

The page gets the value of these parameters, display a list of IdPs, and send a new request to Oracle Identity Federation specifying the chosen IdP Provider ID.

Note:

Check that the URL query parameter values are correctly URL-encoded.

Example

The following is an example of an IdP discovery service page. This page allows the user to select an identity provider (from the list of provider IDs: http://idp1.com, http://idp2.com, http://idp3.com), and submit the chosen provider ID to Oracle Identity Federation to continue the SSO flow.

<%@ page buffer="5kb" autoFlush="true" session="false"%>
<%@ page language="java" import="java.util.*, java.net.*"%>
 
<%
// Set the Expires and Cache Control Headers
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "Thu, 29 Oct 1969 17:04:19 GMT");
 
// Set request and response type
request.setCharacterEncoding("UTF-8");
response.setContentType("text/html; charset=UTF-8");
 
String submitURL = request.getParameter("return");
String returnIDParam = request.getParameter("returnIDParam");
 
List idps = new ArrayList();
idps.add("http://idp1.com");
idps.add("http://idp2.com");
idps.add("http://idp3.com");
 
%>
 
<html>
  <title>
  Select an Identity Provider
  </title>
<body bgcolor="#FFFFFF"><form  method="POST" action="<%=submitURL%>" id="PageForm" name="PageForm" autocomplete="off">
    <center>
                <table cellspacing="2" cellpadding="5" border="0" width="500">
                    <tr><td colspan="2" align="center">
                         Select an Identity Provider
                    </td></tr>
                    </tr>
                    <tr>
                        <td align="right">Provider ID</td>
                        <td>
                           <select size="1" name="<%=returnIDParam%>">
<%
Iterator idpIT = idps.iterator();
while(idpIT.hasNext())
{
        String idp = (String)idpIT.next();
%>
                                <option value="<%=(idp)%>"><%=idp%></option>
<%
}
%>
 
                           </select>
                         </td>
                    </tr>
                    <tr>
                         <td colspan="2" align="center">
                            <input type="submit" value="Continue"/>
                         </td>
                    </tr>
                </table>
      </center>
     </form>
    </body>
</html>

6.12 Setting up Infocard

Oracle Identity Federation can use Infocard as an authentication engine where the server acts as an RP (Resource Provider) for Infocard.

The flow is as follows:

Oracle Identity Federation determines that the user needs to be challenged for authentication and selects the Infocard Authn Engine
Oracle Identity Federation displays the login page containing the Infocard links. These links contain the claims that Oracle Identity Federation is requesting from the STS servers, and optionally the type of assertion to be returned. Oracle Identity Federation can also individually list the STS servers it recognized, or only one Infocard link, thus not listing the known STS servers.
the user clicks on a link
the Identity Selector installed on the user's machine is launched and displays the cards that can be used for this operation
the user selects a card
the Identity Selector connects to the STS server to retrieve a SAML assertion. (Note: the SAML assertion is encrypted using the Oracle Identity Federation SSL server certificate.)
the Identity Selector presents the SAML assertion to Oracle Identity Federation
Oracle Identity Federation decrypts the assertion using its encryption keystore, and validates the signature
Oracle Identity Federation maps the SAML assertion to a local user, using the SAML 1.x or SAML 2.0 assertion mapping modules, based on the settings listed in the Service Provider page on the SAML 1.x and SAML 2.0 tabs. (Note: this step is similar to a Federation SSO flow, when Oracle Identity Federation acts as the service provider.)
After mapping the assertion to a local user record, the authentication phase is complete and Oracle Identity Federation resumes the operation it was performing before the Infocard authentication engine was invoked

The Infocard authentication engine can additionally request optional attributes from the Infocard providers.

If the Infocard engine is instructed to return some attributes (requested by Oracle Identity Federation acting as IdP, because some of the assertion contents rely on user session attributes populated by the authentication engines), the engine adds those attributes as optional claims to be requested to the Infocard providers.

This section contains these topics:

Server-side Infocard Setup
Client-side Infocard Setup

6.12.1 Server-side Infocard Setup

Server-side setup includes the following:

Set up JCE Policy Files for Oracle WebLogic Server
Update the Oracle Identity Federation Configuration
Add Personal Card Issuer STS
Add Infocard Managed STS

6.12.1.1 Set up JCE Policy Files for Oracle WebLogic Server

Take these steps:

Download Java(TM) Cryptography Extension (JCE) Unlimited Strength Jurisdiction policy files from this URL:

http://www.oracle.com/technetwork/java/javase/downloads/index.html
Unzip the files in all the $JAVA_HOME/jre/lib/security directories located under the Middleware home f older (to find those directories, look for US_export_policy.jar files). For every $JAVA_HOME/jre/lib/security directory, overwrite the default low strength local_policy.jar and US_export_policy.jar files with the ones provided by Oracle.

See Also:
What Is a Middleware Home? in the Oracle Fusion Middleware Administrator's Guide.
Restart the administration server and the managed server where Oracle Identity Federation is running.

6.12.1.2 Update the Oracle Identity Federation Configuration

Go to the Oracle Identity Federation instance in Fusion Middleware Control, and perform the following operations:

Infocard Authentication requires SSL. Configure SSL on Oracle WebLogic Server as explained in Section 8.1, "Configuring SSL for Oracle Identity Federation", and enable SSL on the Oracle Identity Federation server. You need to create a new SSL keystore if it does not already exist.

The SSL server certificate must use the RSA public key algorithm since it is required for SAML encryption operations
For the Oracle Identity Federation encryption wallet, use the SSL keystore used for SSL support in Oracle WebLogic Server. When you use this keystore, the Infocard client uses the SSL server certificate to encrypt the assertion, thus requiring Oracle Identity Federation to use as the encryption wallet the key pair used for SSL traffic.
Load the SSL Java keystore as the Oracle Identity Federation encryption wallet. Navigate to Administration, then Security and Trust, and upload the new wallet keystore, specifying the password and alias.

Note:
You must re-distribute the metadata to trusted partners since the encryption keystore was modified.

Navigate to IdM Data Stores, then Authentication Engines, and enable the Infocard engine. Depending on whether the engine should map the WS-Trust assertion to a record from the user data store, check or uncheck the box for Map Assertion to User.

Note:

You can configure Oracle Identity Federation to add the authentication mechanism as a required claim, so that it is able to request a specific authentication method from the Infocard providers. To enable this feature, check the Include Authentication Mechanism box.

Note:

Leave this box unchecked in most deployments unless Infocard providers support the feature.

If the box is checked, Oracle Identity Federation translates the local authentication mechanism values to SAML authentication methods, as defined in the authentication mechanisms mapping.

Finally, when the box is checked, Oracle Identity Federation verifies that a given Infocard provider supports the inclusion of the authentication mechanism by looking at the provider specific property called "Supports Authentication Mechanisms Claims," which is defined in the Trusted Provider settings of the Remote Provider configuration section.

Select Infocard as the default authentication engine if needed and save the changes.

If you check the Map Assertion to User box, the incoming assertion is mapped to a user record based on the configuration on the SAML 2.0 / SAML 1.x Assertion tab of the Service Provider page.

Note:

When the Infocard authentication engine is invoked for authentication with the authentication mechanism that is mapped to the personal issuer card, only the personal issuer card is displayed on the login page. If invoked with an authentication mechanism different from the one mapped to the Personal Issuer Card, all the Infocard providers are displayed.

6.12.1.3 Add Personal Card Issuer STS

For Oracle Identity Federation to accept an assertion from the personal card issuer STS, it needs to have a trust relationship with the issuer. This trust is established by having the STS defined and enabled in the server's federations.

In Fusion Middleware Control, locate the Oracle Identity Federation instance and perform the following operations:

Navigate to Administration, then Federations, and add a WS-Fed 1.1 IdP identified by http://schemas.xmlsoap.org/ws/2005/05/identity/issuer/self
Select the STS, click Update, then select Update Manually.
From the SSO/Infocard Mode drop-down, select either Infocard if the STS only supports Infocard protocol, or Single Sign-On and Infocard if the STS supports Infocard and SSO protocols.
Infocard states that the relying party (Oracle Identity Federation in this case) should list the attributes or claims that the STS should include in the assertion it creates. With the attributes and the optional NameID contained in the assertion, Oracle Identity Federation can map the assertion to a local user record if configured for that operation.

To add attributes to be requested for the STS, click Attribute Mappings.
Configure attribute mapping to list the attributes required by the Oracle Identity Federation server when the card selector is invoked; for each attribute marked "Require from Infocard", Oracle Identity Federation requires the attribute to be returned in the assertion from the WS-Trust server. The User Attribute Name is used to reference that attribute in Oracle Identity Federation, Assertion Attribute Name is the name of the attribute recognized by the STS, and Format/Namespace is the namespace to which the attribute is bound. The required claim from Oracle Identity Federation to the STS is the concatenation of the namespace, "/", and the assertion attribute name.

For example:
- Add an attribute entry User Attr Name=lastname, Assertion Attr Name=surname, Format or Namespace=http://schemas.xmlsoap.org/ws/2005/05/identity/claims. Check the Require From Infocard box.
- Add another attribute entry with User Attr Name=firstname, Assertion Attr Name=givenname, Format or Namespace=http://schemas.xmlsoap.org/ws/2005/05/identity/claims. Check the Require From Infocard box.
Configure Oracle Identity Federation to map the assertion that the Personal Card Issuer will provide to a local user.

For example, in the Oracle Identity Federation Settings tab, in the Assertion Setting tabs, uncheck the Map User via NameID box, check Map User via Attribute Query and enter the following LDAP query: (&(sn=%lastname%)(givenname=%firstname%))
Save the changes.
Check or uncheck the Supports Authentication Mechanism Claims box to indicate whether the authentication mechanism should be listed as a required Infocard attribute. Not all WS-Trust servers support the ability to specify the requested authentication mechanism through the use of attributes.
Save the changes.

6.12.1.4 Add Infocard Managed STS

For Oracle Identity Federation to accept an assertion from a remote STS, the Oracle Identity Federation server needs to have a trust relationship with the remote server. This trust is established by having the STS defined and enabled in the server's federations.

In Fusion Middleware Control, locate the Oracle Identity Federation instance and perform the following operations:

Add an entry by entering the STS provider ID, selecting IdP and the WS-Fed 1.1 version.
Select the STS, and click Update.
Enter the IdP signature verification certificate.
From the SSO/Infocard Mode drop-down, select either Infocard if the STS only supports Infocard protocol, or Single Sign-On and Infocard if the STS supports both Infocard and SSO protocols.
Infocard states that the relying party (Oracle Identity Federation in the present case) must list the attributes or claims that the STS should include in the assertion it creates. With the attributes and the optional NameID contained in the assertion, the Oracle Identity Federation server can map the assertion to a local user record (if configured for that operation).

To add attributes to be requested for the STS, click Attribute Mappings.
Configure attribute mapping to list the attributes that the Oracle Identity Federation server will require when the card selector is invoked. For each attribute marked "Require from Infocard", Oracle Identity Federation requires the given attribute be returned in the assertion from the WS-Trust server. The User Attribute Name is used to reference that attribute in Oracle Identity Federation, Assertion Attribute Name is the name of the attribute recognized by the STS, and Format/Namespace is the namespace to which the attribute is bound. The required claim from Oracle Identity Federation to the STS is the concatenation of the Namespace, "/", and the assertion attribute name.

For example:
- Add an attribute entry with User Attr Name=lastname, Assertion Attr Name=surname, Format or Namespace=http://schemas.xmlsoap.org/ws/2005/05/identity/claims. Check the Require From Infocard box.
- Add another attribute entry for User Attr Name=firstname, Assertion Attr Name=givenname, Format or Namespace=http://schemas.xmlsoap.org/ws/2005/05/identity/claims. Check the Require From Infocard box.
Configure Oracle Identity Federation to map the assertion that is provided by the Personal Card Issuer to a local user.

For example, in the Oracle Identity Federation Settings tab, in the Assertion Setting tabs, uncheck the "Map User via NameID" box, check Map User via Attribute Query and enter the following LDAP query: (&(sn=%lastname%)(givenname=%firstname%))
Save the changes.

6.12.2 Client-side Infocard Setup

This section contains these topics:

Import the Oracle Identity Federation SSL Certificate
Create a Personal Infocard

6.12.2.1 Import the Oracle Identity Federation SSL Certificate

The client machine must trust the Oracle Identity Federation SSL certificate for Windows Cardspace to trust Oracle Identity Federation and allow the user to use Infocards stored on the local computer. If the client does not trust the certificate authority that generated the SSL server, you must import the certificate.

Take these steps to import the certificate:

Using Internet Explorer, navigate to the URL with format https://host:port.
Right-click on the page.
Select Properties.
Select Certificates.
Click the Certification Path tab.
Select the CA that issued the certificate and view the certificate.
Click Install Certificates, and import the certificate in the trusted root Certification Authorities.

6.12.2.2 Create a Personal Infocard

Take these steps to create a personal Infocard with Windows Cardspace:

Go to the Windows control panel.
Double-click Windows Cardspace (if it is not present, install .NET from the Microsoft download site at http://www.microsoft.com/downloads).
Click Add a Card.
Select Create a Personal Card and fill in the fields.
Save the changes.

6.13 Additional Run-time Configuration

This section describes additional features you can configure to manage run-time behavior.

Validating Target URLs for SSO and Logout Operations
Providing XML Message to SP Engine after SSO Completes
Customizing Error Pages
Configuring Schema Validation for SSO Protocol Messages

6.13.1 Validating Target URLs for SSO and Logout Operations

When performing the SSO and Logout protocols, Oracle Identity Federation executes the SAML/WS-Fed protocol exchanges and then redirects the user to a final target URL, such as:

a protected resource in case of SSO, or
a returnurl when performing logout

These URLs can be specified as query parameters at runtime; for example, the returnurl query parameter for IdP-initiated SSO, logout flows, and so on.

Note:

The returnurl query parameter value must be correctly URL Encoded

Here are some examples of flows where URLs can be specified:

a user can start an IdP-initiated SSO flow by accessing:

/fed/idp/initiatesso?providerid=SP_PROVIDER_ID&returnurl=http%3A%2F%2Furl.com

a user can start the logout flow by accessing:

/fed/user/logout?returnurl=http%3A%2F%2Furl.com

Oracle Identity Federation lets you validate URLs that can be specified at runtime. You configure validation specifying a list of approved hostnames, or approved domains.

Note:

A domain is a string beginning with '.', such as .oracle.com for the Oracle domain.

By default, validation is disabled.

To configure the return URL validation module, enter the WLST script environment for Oracle Identity Federation and set the returnurlvalidationenabled boolean property from the serverconfig group to true (or false) to enable (or disable) the module. For example:

setConfigProperty('serverconfig', 'returnurlvalidationenabled', 'true', 'boolean')

To add a host name or domain to the list of approved URLs/domains, enter the WLST script environment for Oracle Identity Federation, and issue these commands:

Add a host name to the returnurlvalidationlist list:

addConfigPropertyListEntry('serverconfig','returnurlvalidationlist',
'hostname.domain.com','string')

Add a domain to the returnurlvalidationlist list:

addConfigPropertyListEntry('serverconfig','returnurlvalidationlist',
'.domain.com','string')

6.13.2 Providing XML Message to SP Engine after SSO Completes

Oracle Identity Federation acting as SP can provide an XML message containing the assertion received by the server during the federated single sign-on flow. Depending on the binding used, this can be a SAML or SOAP message.

Note that:

The XML message is provided to the SP engine with the attributes received in the assertion.
The message is contained in the map referenced by orafed-xmlmessage.
The attributes map is stored as an attribute in the HttpServletRequest object, referenced by oracle.security.fed.sp.attributes.

To enable sending the message, set the boolean property spattrsincludexmlmessage from the spglobal group to true.

To disable sending the message, set the property to false.

Note:

false is the default configuration.

6.13.3 Customizing Error Pages

Errors can occur in Oracle Identity Federation for various reasons, such as:

page not found
federated single sign-on (SSO) error
runtime error

When an error occurs, the server returns an error code (404, 401 or 500) showing the Oracle WebLogic Server error page to the user.

You can configure Oracle Identity Federation to redirect the user to a custom page based on the error code.

Set the string property or urlerrornnn from the serverconfig configuration group to the URL to which the user should be redirected when Oracle Identity Federation returns the error, where nnn is 401, 404, or 500. (Thus, you can set the urlerror401, urlerror404, and urlerror500 properties.)

Notes:

401 errors occur during Fed SSO operation if the federated SSO fails.
404 errors are raised when the user tries to access one of the Oracle Identity Federation servlets (/fed/idp, /fed/sp, /fed/user...) and the page is not found.
500 errors occur when fatal exceptions occur at runtime.
If the server cannot initialize correctly, Oracle Identity Federation is unable to redirect the user to the urlerror500 URL.

6.13.4 Configuring Schema Validation for SSO Protocol Messages

Oracle Identity Federation supports XML schema validation for SSO protocol messages.

This feature is implemented with the schemavalidationenabled property; validation is off by default.

To enable schema validation, enter the script environment for the Oracle Identity Federation server instance, and set the schemavalidationenabled property to true:

setConfigProperty('serverconfig','schemavalidationenabled','true','boolean')

To disable validation, set the property to false (default value).

setConfigProperty('serverconfig','schemavalidationenabled','false','boolean')

6.14 Additional Federation Data Store Configuration

When Oracle Identity Federation is configured to use an LDAP server or an RDBMS as its federation data store, the server performs various operations to create, locate, update, or delete federation records.

A federation record typically consists of the following data:

IdP NameID: name identifier data created by the identity provider and used in the SAML messages
SP NameID: name identifier data optionally set by the service provider during a Name Identifier Management update operation.

If that NameID is set, it is used in SAML messages; otherwise, the IdP NameID is used.

During an operation that consumes an assertion, when Oracle Identity Federation acts as a service provider, the server tries to locate the federation record referenced in the NameID element contained in the assertion. By default, it first performs a lookup based on the SP NameID; if no results are returned, it performs a lookup based on the IdP NameID.

In some deployments, Oracle Identity Federation:

might not be configured to do any NameID Management protocol exchanges, and
might not have any of its federation records updated to set an SP NameID (that is, the administrator never performed an update operation on any federation records using the administrative tools)

In this case, the first federation record lookup performed during assertion consumption using the SP NameID will never return any records and serves to increase the response time.

If SP NameID lookup is not needed, it is possible to disable it to improve performance. To enable or disable the lookup, enter the WLST script environment for Oracle Identity Federation and make this configuration change:

Note:

By default, the SP NameID lookup is enabled.

Set the fedusespnameidlookup boolean property from the datastore group to true to enable the SP NameID lookup.
Set the fedusespnameidlookup boolean property from the datastore group to false to disable the SP NameID lookup

For example:

setConfigProperty('datastore', 'fedusespnameidlookup', 'false', 'boolean')

6.15 Setting up Backwards Compatibility for Oracle Identity Federation 10g and ShareID service URLs

Background

Oracle Identity Federation 10g, and SHAREid/COREid Federation 2.x, provided service URLs for SAML 1.x and WS-Federation protocol support which were different from the SAML 2.0 and Liberty 1.x service URLs. These URLs have been modified in the 11g Oracle Identity Federation for consistency with the SAML 2.0 and Liberty 1.x service URLs. Customers upgrading to Oracle Identity Federation 11g, who use SAML 1.x or WS-Federation, must inform their partner providers of the new single sign-on service URLs.

Note:

Liberty 1.x support is deprecated.

To ease that transition, Oracle Identity Federation 11g provides a separate module that allows backwards compatibility with the SHAREid service URLs. This module is a JavaEE application you can deploy alongside Oracle Identity Federation, to handle requests for the ShareID/Oracle Identity Federation 10g service URLs and redirect/forward them to the corresponding Oracle Identity Federation 11g service URLs.

Note:

For the SAML1x protocol, in release 10g it was possible to set the authentication response profile binding by setting the "METHOD" query parameter to the desired profile while sending the authentication request. This feature is not supported in 11g, and you must configure the IdP to send the authentication response using the desired profile binding.

Procedure

Take these steps to set up a ShareID proxy:

Note:

If a proxy is configured as in Appendix B, "Using Oracle HTTP Server as a Proxy for Oracle Identity Federation", you need to modify the oif.conf file to also divert /shareid URLs to Oracle WebLogic Server.

See Also:

Getting Started with Oracle WebLogic Server Administration Console in the Oracle Fusion Middleware Administrator's Guide.

At the Oracle WebLogic Server Administration Console, navigate to the Deployments page.
Click Lock & Edit.
Click Install.
Navigate to the location of the shareidupdate.ear file (located in $ORACLE_HOME/fed/install).
Click Next.
Select Install this deployment as an application and click Next.
Select the name of the managed server and click Next.
Select Advanced in the Security section.
Click Finish.
Click Apply Changes.
Returning to the Deployments page, find the new application called "shareidupdate" (Note: you may have to click Next if the application does not appear in the first 10 entries).
If the state of the shareidupdate application is not listed as "Active" select the application and click Start, servicing all requests, and click yes. Now locate the shareidupdate application in the Deployments page; its state should be listed as "Active".

By default, the shareidupdate proxy uses the incoming protocol (HTTP or HTTPS), server name, and server port as the protocol, server name, and server port to which messages should be redirected. Consider using non-default values (when using a proxy server, for example).

To set these values:

Find the shareidupdate web.xml file; it should be in a subfolder of:
```
DOMAIN_HOME/servers/SERVER_NAME/tmp/_WL_user/shareidupdate
```
Add the properties IsSecure, ServerName, and/or ServerPort to the servlets being used. (Note: IsSecure is set to true if desired protocol is HTTPS, false if the desired protocol is HTTP.)
Save changes and restart the application.

For example, the <servlet> element may now contains elements such as:

<init-param>
      <param-name>IsSecure</param-name>
      <param-value>true</param-value>
</init-param>
<init-param>
      <param-name>ServerPort</param-name>
      <param-value>7777</param-value>
</init-value>

6.16 Mapping Users through Attributes and NameID in SP Mode

Oracle Identity Federation acting as an SP can locate a user based on the attributes and name identifier value stored in an assertion without using any federation records.

When configured not to use the federated identity to map the assertion to a user record, Oracle Identity Federation/SP uses the NameID and the attributes contained in the incoming assertion to map the user in the repository. Once the user record is located, Oracle Identity Federation/SP creates an authenticated session for that user in the identity and access management framework and redirects the user to the final target URL.

This flow does not use any federation records, so it is not necessary to have a federation data store configured to use Oracle Identity Federation as the service provider.

If Oracle Identity Federation cannot locate the user during the flow, the default behavior is to return a 401 Unauthorized error to the user. You can configure Oracle Identity Federation to redirect the user to the authentication engine instead, so that custom corrective measures such as user account provisioning can be initiated. This behavior is implemented with the Error when User Mapping fails property; see Section 6.16.2, "Configuring Oracle Identity Federation", under the procedure titled "If the Mapping Fails."

On returning to Oracle Identity Federation from the authentication engine, if the user still cannot be mapped, a final result of 401 is returned.

Limitations

Note these limitations:

Since Oracle Identity Federation/SP does not store any federation records when configured to map the assertion without using federated identities, no account linking information is available in the Identity Federation section of Fusion Middleware Control.
Additionally, the Name Identifier Update and Federation Termination profiles will not complete; if the peer IdP sends a message for one of these profiles, Oracle Identity Federation/SP will return an error message indicating that the federation record could not be found.

This section contains these topics:

Locating a User
Configuring Oracle Identity Federation
Example 1: Assertion Mapping without federated identities using NameID for SAML 2.0
Example 2: Simple Assertion Mapping without Federated Identities with an LDAP/SQL Query
Example 3: Complex Assertion Mapping without Federated Identities with an LDAP/SQL Query
Example 4: Assertion Mapping without Federated Identities using LDAP/SQL Query and NameID Mapping
Example 5: Assertion Mapping without Federated Identities for a Specific IdP

6.16.1 Locating a User

You have two options for locating a user record in the repository:

Using the Name ID Format mapping, where the NameID is linked to a user attribute.
Using an LDAP/SQL query that involves the NameID and the attributes stored in the assertion.

If both options are enabled, Oracle Identity Federation/SP first uses the NameID mapping search, and if no results are returned, it uses the LDAP/SQL query flow.

The query contains placeholders that are replaced by the attribute and NameID values contained in the assertion. The placeholders use a %NAME% format in which Oracle Identity Federation/SP replaces NAME with:

An attribute name, referencing an attribute contained in the assertion. When creating the query, Oracle Identity Federation/SP replaces the %AttributeName% with the value of the attribute referenced by AttributeName.

Note:

The attribute mapping module will have mapped the attributes, contained in the assertion, to the attribute name/values configured for the remote provider. The attribute name needs to reference an attribute from this list.

orafed-nameid-value - indicates that this placeholder should be replaced by the Name ID value
orafed-nameid-qualifier - indicates that this placeholder should be replaced by the Name ID qualifier
orafed-nameid-format - indicates that this placeholder should be replaced by the Name ID format
orafed-providerid - indicates that this placeholder should be replaced by the Peer ProviderID

6.16.2 Configuring Oracle Identity Federation

The SAML 2.0 module supports the use of federated identities, but not the SAML 1.x modules.

To configure Oracle Identity Federation to use federated identities for assertion to user mapping operations:

Log in to Fusion Middleware Control.
Navigate to Administration, then Service Provider, then SAML 2.0, then Assertion Settings.
Check or uncheck Map User via Federated Identity.

To map a user using the NameID:

Log in to Fusion Middleware Control.
Navigate to Administration, then Service Provider, then SAML 2.0, then Assertion Settings.
Check Map User via NameID.
Configure the NameID format and the attribute in the user record to be used during the lookup procedure.

To map a user using an LDAP/RDBMS query:

Log in to Fusion Middleware Control.
Navigate to Administration, then Service Provider, then SAML 2.0, then Assertion Settings.
Check Map User via Attribute Query.
Enter the LDAP or SQL query to be used during the lookup procedure.

If the Mapping Fails

If the mapping fails, you can configure Oracle Identity Federation to invoke the authentication engine instead of returning a 401-error code. To configure the server, perform the following steps:

Log in to Fusion Middleware Control.
Navigate to Administration, then Service Provider, then SAML 2.0, then Assertion Settings.

Uncheck Error when User Mapping fails to invoke the authentication engine that will then have access to the content of the assertion and its attributes.

Note:

6.16.3 Example 1: Assertion Mapping without federated identities using NameID for SAML 2.0

In this example, Oracle Identity Federation/SP uses the NameID contained in the assertion to look up a local user in the LDAP user data store. The format of the NameID is emailAddress, and the search uses the mail attribute of the LDAP user record.

The server is configured to use the NameID mapping functionality to locate the user. Perform the following steps to configure Oracle Identity Federation/SP:

Log in to Fusion Middleware Control.
Navigate to Administration, then Service Provider, then SAML 2.0, then Assertion Settings.
Uncheck Map User via Federated Identity.
Uncheck Map User via Attribute Query.
Check Map User via NameID.
Enable Email Address NameID Format, and enter the attribute of the user record holding the email address (mail typically for LDAP server).
Check Error when User Mapping fails; this will force Oracle Identity Federation to return a 401 error to the browser if the user cannot be located.
Apply the changes.

6.16.4 Example 2: Simple Assertion Mapping without Federated Identities with an LDAP/SQL Query

The server is configured to use the LDAP/SQL Query functionality to locate the user. Perform the following steps to configure Oracle Identity Federation/SP:

Log in to Fusion Middleware Control.
Navigate to Administration, then Service Provider, then SAML 2.0, then Assertion Settings.
Uncheck Map User via Federated Identity.
Check Map User via Attribute Query.
Enter the following LDAP query in the Attribute Query field: (&(mail=%orafed-nameid-value%))
Uncheck Map User via NameID.
Check Error when User Mapping fails; this forces Oracle Identity Federation to return a 401 error to the browser if the user cannot be located.
Apply the changes.

6.16.5 Example 3: Complex Assertion Mapping without Federated Identities with an LDAP/SQL Query

In this example, Oracle Identity Federation/SP uses the SAML attributes for email address and last name in the assertion to look up a local user in the LDAP user data store.

The mail and sn local attributes are obtained from the LDAP user record. The attributes in the assertion are referenced as email and lastname. Oracle Identity Federation/SP is not configured for attribute name mapping, so the LDAP query uses the attribute names contained in the SAML assertion; if attribute name mapping was configured, the LDAP query would use the names resulting from the attribute name mapping (refer to Section 5.9, "Configuring Attribute Mapping and Filtering" for more information).

The server is configured to use the LDAP/SQL query functionality to locate the user. Perform the following configuration steps:

Log in to Fusion Middleware Control.
Navigate to Administration, then Service Provider, then SAML 2.0, then Assertion Settings.
Uncheck Map User via Federated Identity.
Check Map User via Attribute Query.
Enter the following LDAP query in the Attribute Query field: (&(mail=%email%)(sn=%lastname%))
Uncheck Map User via NameID.
Check Error when User Mapping fails; this forces Oracle Identity Federation to return a 401 error to the browser if the user cannot be located.
Apply the changes.

6.16.6 Example 4: Assertion Mapping without Federated Identities using LDAP/SQL Query and NameID Mapping

In this example, Oracle Identity Federation/SP uses the email address contained in the NameID to locate the user. If the operation fails, the last name SAML attribute from the assertion is used to look up a local user in the LDAP user data store, using the local attributes mail and sn from the LDAP user record.

The server is configured to use both NameID Mapping and LDAP/SQL Query to locate the user. Perform the following steps to configure Oracle Identity Federation/SP:

Log in to Fusion Middleware Control.
Navigate to Administration, then Service Provider, then SAML 2.0, then Assertion Settings.
Uncheck Map User via Federated Identity.
Check Map User via Attribute Query.
Enter the following LDAP query in the Attribute Query field: (&(sn=%lastname%))
Check Map User via NameID.
Enable Email Address NameID Format, and enter the attribute of the user record holding the email address (mail typically for LDAP server).
Check Error when User Mapping fails; this forces Oracle Identity Federation to return a 401 error to the browser if the user cannot be located.
Apply the changes.

6.16.7 Example 5: Assertion Mapping without Federated Identities for a Specific IdP

If Oracle Identity Federation/SP needs an attribute-based authentication configuration specific to a peer identity provider, the setup information must be stored in the IdP's entry in the Federations list.

In this example, Oracle Identity Federation /SP is set up for attribute-based authentication for an IdP referenced by http://idp.com. Perform the following steps to configure Oracle Identity Federation/SP:

Log in to Fusion Middleware Control.
Navigate to Administration, then Federations.
Select the identity provider and click Update.
Click the Oracle Identity Federation Settings tab.
Expand the Service Provider/Requester Settings section, and go to assertion settings.
Uncheck Map User via Federated Identity.
Check Map User via Attribute Query.
Enter the following LDAP query in the Attribute Query field: (&(mail=%email%)(sn=%lastname%))
Uncheck Map User via NameID.
Check Error when User Mapping fails; this forces Oracle Identity Federation to return a 401 error to the browser if the user cannot be located.
Apply the changes.

6.17 Automatic Account Linking Based on Attribute Query Mapping

Automatic account linking at the SP allows the service provider to directly map an identity contained in an assertion to a user.

When Oracle Identity Federation is acting as a service provider, and is configured to use federated identities to map the incoming SAML 2.0 assertion, it can automatically create a federation record by locating a user based on the attributes and name identifier received in an assertion.

This section contains topics related to account linking:

Locating the User
Configuring Oracle Identity Federation
Example 1: Automatic Account Linking through NameID mapping for SAML 2.0
Example 2: Simple Automatic Account Linking through LDAP/SQL Query
Example 3: Complex Automatic Account Linking through LDAP/SQLQuery
Example 4: Automatic Account Linking through LDAP/SQL Query and NameID Mapping
Example 5: Automatic Account Linking via Attribute Query for a Specific IdP

6.17.1 Locating the User

When configured to use federated identities and Automatic Account Linking is enabled, the administrator has two options for locating a user record in the repository:

Using the Name ID Format mapping, where the NameID is linked to a user attribute. This uses the existing mapping.
Using an LDAP/SQL query that involves the NameID and the attributes stored in the assertion.

If both options are enabled, Oracle Identity Federation/SP first uses the NameID mapping search, and if no results are returned, it uses the LDAP/SQL query flow. If Oracle Identity Federation/SP cannot locate the user record during this flow, the server challenges the user for credentials.

The administrator specifies in Oracle Identity Federation configuration the LDAP/SQL query to be used when trying to look up a user. The query contains placeholders that are replaced by the attribute and NameID values contained in the assertion. The placeholders use a %NAME% format in which Oracle Identity Federation/SP replaces NAME with:

An attribute name, referencing an attribute contained in the assertion. When creating the query, Oracle Identity Federation/SP replaces %AttributeName% with the value of the attribute referenced by AttributeName.

Note:

The attribute mapping module maps the attributes contained in the assertion to the attribute name/values configured for the remote provider. The attribute name needs to reference an attribute from the list.

orafed-nameid-value - Oracle Identity Federation replaces this placeholder with the Name ID value
orafed-nameid-qualifier - Oracle Identity Federation replaces this placeholder with the Name ID qualifier
orafed-nameid-format - Oracle Identity Federation replaces this placeholder with the Name ID format
orafed-providerid - Oracle Identity Federation replaces this placeholder with the Peer ProviderID

6.17.2 Configuring Oracle Identity Federation

Only the SAML 2.0 module supports the use of federated identities, not the SAML 1.x modules.

To configure Oracle Identity Federation to use federated identities for assertion to user mapping, and to enable automatic account linking operations:

Log in to Fusion Middleware Control.
Navigate to Administration, then Service Provider, then SAML 2.0, then Assertion Settings.
Check Map User via Federated Identity.
Check Enable Auto Account Linking.

To map a user using the NameID:

Log in to Fusion Middleware Control.
Navigate to Administration, then Service Provider, then SAML 2.0, then Assertion Settings.
Check Map User via NameID.
Configure the NameID Format enabled and the attribute in the user record to be used during the lookup procedure of the automatic account linking operation.

To map a user using an LDAP/RDBMS query:

Log in to Fusion Middleware Control.
Navigate to Administration, then Service Provider, then SAML 2.0, then Assertion Settings.
Check Map User via Attribute Query.
Enter the LDAP or SQL query to be used during the lookup procedure of the automatic account linking operation.

6.17.3 Example 1: Automatic Account Linking through NameID mapping for SAML 2.0

The server is configured to use the NameID mapping functionality to locate the user during automatic account linking.

Perform the following steps to configure Oracle Identity Federation/SP:

Log in to Fusion Middleware Control.
Navigate to Administration, then Service Provider, then SAML 2.0, then Assertion Settings.
Check Map User via Federated Identity.
Check Map Enable Auto Account Linking.
Uncheck Map User via Attribute Query.
Check Map User via NameID.
Enable Email Address NameID Format, and enter the attribute of the user record holding the email address (mail typically for LDAP server).
Apply the changes.

6.17.4 Example 2: Simple Automatic Account Linking through LDAP/SQL Query

In this example, Oracle Identity Federation/SP uses the NameID contained in the assertion to look up a local user in the LDAP user data store and automatically create the federation record. The format of the NameID is emailAddress, and the search uses the mail attribute of the LDAP user record.

The server is configured to use the LDAP/SQL query functionality to locate the user. Perform the following steps to configure Oracle Identity Federation/SP:

Log in to Fusion Middleware Control.
Navigate to Administration, then Service Provider, then SAML 2.0, then Assertion Settings.
Check Map User via Federated Identity.
Check Map Enable Auto Account Linking.
Check Map User via Attribute Query.
Set the attribute query to (&(mail=%orafed-nameid-value%))
Uncheck Map User via NameID.
Apply the changes.

6.17.5 Example 3: Complex Automatic Account Linking through LDAP/SQLQuery

In this example, Oracle Identity Federation/SP uses the email address and the last name SAML attributes in the assertion to look up a local user in the LDAP user data store and automatically creates the federation record. The local attributes mail and sn from the LDAP user record are used. The attributes in the assertion are referenced as email and lastname.

Oracle Identity Federation/SP is not configured for attribute name mapping, so the LDAP query uses the attribute names contained in the SAML assertion; if attribute name mapping were configured, the LDAP query would use the names resulting from attribute name mapping (refer to Section 5.9, "Configuring Attribute Mapping and Filtering" for more information on Attribute Name Mapping).

The server is configured to use the LDAP/SQL query functionality to locate the user. Perform the following steps to configure Oracle Identity Federation/SP:

Log in to Fusion Middleware Control.
Navigate to Administration, then Service Provider, then SAML 2.0, then Assertion Settings
Check Map User via Federated Identity.
Check Map Enable Auto Account Linking.
Check Map User via Attribute Query.
Set the Attribute Query to (&(mail=%email%)(sn=%lastname%)).
Uncheck Map User via NameID.
Apply the changes.

6.17.6 Example 4: Automatic Account Linking through LDAP/SQL Query and NameID Mapping

In this example, Oracle Identity Federation/SP uses the email address contained in the NameID to locate the user to create the federation record. If the operation fails, Oracle Identity Federation/SP uses the last name SAML attribute from the assertion to look up a local user in the LDAP user data store. The local attributes mail and sn from the LDAP user record are used.

The server is configured to use the NameID Mapping and LDAP/SQL Query features to locate the user.

Perform the following steps to configure Oracle Identity Federation/SP:

Log in to Fusion Middleware Control.
Navigate to Administration, then Service Provider, then SAML 2.0, then Assertion Settings.
Check Map User via Federated Identity.
Check Map Enable Auto Account Linking.
Check Map User via Attribute Query.
Set the Attribute Query to (&(sn=%lastname%)).
Check Map User via NameID.
Enable Email Address NameID Format, and enter the attribute of the user record holding the email address (mail typically for LDAP server).

6.17.7 Example 5: Automatic Account Linking via Attribute Query for a Specific IdP

If Oracle Identity Federation/SP needs an attribute-based authentication configuration specific to a peer identity provider, then the setup information needs to be stored in the IdP's entry in the Federations list.

In this example, Oracle Identity Federation/SP is using federated identities and is set up for automatic account linking through attribute query for an IdP referenced by http://idp.com.

Perform the following steps to configure Oracle Identity Federation/SP:

Log in to Fusion Middleware Control.
Navigate to Administration, then Federations.
Select the identity provider and click Update.
Click the Oracle Identity Federation Settings tab.
Expand the service provider/Requester Settings section, and go to assertion settings.
Check Map User via Federated Identity.
Check Map Enable Auto Account Linking.
Check Map User via Attribute Query.
Enter the following LDAP query in the Attribute Query field: (&(mail=%email%)(sn=%lastname%)).
Uncheck Map User via NameID.
Check Error when User Mapping fails; this forces Oracle Identity Federation to return a 401 error to the browser if the user cannot be located.
Apply the changes.

6.18 User Opt-In and Opt-Out for Single Sign-On

You can configure Oracle Identity Federation IdP to determine if a user has given (or denied) permission to perform federated single sign-on for the user, based on the value of an attribute in the user's directory record.

If consent has been given, SSO operations can be performed automatically if the user is authenticated at Oracle Identity Federation/IdP, or within the identity and access management (IAM) framework integrated with Oracle Identity Federation. If consent has not been obtained, Oracle Identity Federation/IdP must challenge the user for credentials every time a Federation SSO operation occurs, even if the user is already authenticated at Oracle Identity Federation in the IAM domain.

Note:

In this section, Oracle Identity Federation/IdP refers to Oracle Identity Federation acting as identity provider.

Topics in this section include:

Modes of Operation
Configuring Oracle Identity Federation
Example 1: Off Mode
Example 2: Opt-In Mode
Example 3: Opt-Out Mode
Example 4: Opt-In Mode for a Specific IdP

6.18.1 Modes of Operation

Oracle Identity Federation/IdP can implement this feature in three modes:

Off - The Opt-in/Opt-out functionality is not exercised
Opt-In - If the user attribute for opt-in/opt-out equals the value set by the administrator, Oracle Identity Federation/IdP does not force the user to re-authenticate for Federation SSO operations; otherwise it forces re-authentication.
Opt-Out - If the user attribute for opt-in/opt-out equals the value set by the administrator, then Oracle Identity Federation/IdP forces the user to re-authenticate for Federation SSO operations; otherwise it does not force re-authentication.

6.18.2 Configuring Oracle Identity Federation

To configure Oracle Identity Federation to use Opt-In/Opt-Out:

Log in to Fusion Middleware Control.
Navigate to Administration, then Identity Provider.
Select the Opt-In/Opt-Out mode:
- Off: indicates that the Opt-in/Opt-out feature is not exercised
- Opt-In: indicates that the Opt-in mode is active
- Opt-Out: indicates that the Opt-out mode is active
If the mode is set to Opt-In or Opt-Out, then enter the Opt-In/Out user attribute that references the attribute to retrieve from the user record. Its value is compared against the value set by the administrator.
If the mode is set to Opt-In or Opt-Out, then enter the Opt-In/Out attribute value holding the value set by the administrator and used to compare against the user attribute.

6.18.3 Example 1: Off Mode

In this example, the opt-in/opt-out feature is turned off so that the user is never re-challenged for credentials when a federation record is created on Oracle Identity Federation/IdP.

Perform the following steps to configure Oracle Identity Federation/SP:

Log in to Fusion Middleware Control.
Navigate to Administration, then Identity Provider.
Select Off as the Opt-In/Opt-Out mode.
Apply the changes.

6.18.4 Example 2: Opt-In Mode

In this example, the opt-in/opt-out feature is set to Opt-In, the attribute containing the user setting is fedrecordcreation, and the value indicating that the user opted in is agreed.

Oracle Identity Federation/IdP re-challenges the user for credentials during a federation creation operation only if the fedrecordcreation attribute value of the user is different from agreed.

Perform the following steps to configure Oracle Identity Federation/SP:

Log in to Fusion Middleware Control.
Navigate to Administration, then Identity Provider.
Select Opt-In as the Opt-In/Opt-Out mode.
Set the Opt-In/Out User Attribute to fedrecordcreation.
Set the Opt-In/Out Attribute Value to agreed.
Apply the changes.

6.18.5 Example 3: Opt-Out Mode

In this example, the feature is set to optout, the attribute containing the user setting is fedrecordcreation and the value indicating that the user opted in is disallowed.

Oracle Identity Federation/IdP re-challenges the user for credentials during a federation creation operation only if the user's fedrecordcreation attribute value equals disallowed.

Perform the following steps to configure Oracle Identity Federation/SP:

Log in to Fusion Middleware Control.
Navigate to Administration, then Identity Provider.
Select Opt-Out as the Opt-In/Opt-Out mode.
Set the Opt-In/Out User Attribute to fedrecordcreation.
Set the Opt-In/Out Attribute Value to disallowed.
Apply the changes.

6.18.6 Example 4: Opt-In Mode for a Specific IdP

If Oracle Identity Federation/IdP needs an Opt-In mode configuration specific to a peer service provider, then the setup information needs to be stored in the SP's entry in the Federations list.

In this example, the opt-in/opt-out feature is set to Opt-In, the attribute containing the user setting is fedrecordcreation, and the value indicating that the user opted in is agreed, for an SP referenced by http://sp.com.

Oracle Identity Federation/IdP re-challenges the user for credentials during a federation creation operation only if the fedrecordcreation attribute value of the user is different from agreed.

Perform the following steps to configure Oracle Identity Federation/IdP:

Log in to Fusion Middleware Control.
Navigate to Administration, then Federations.
Select the service provider and click Update.
Click the Oracle Identity Federation Settings tab.
Expand the Identity Provider/Authority Settings section.
Select Opt-In as the Opt-In/Opt-Out mode.
Set the Opt-In/Out User Attribute to fedrecordcreation.
Set the Opt-In/Out Attribute Value to agreed.
Apply the changes.

6.19 Bypassing User Mapping During Assertion Processing

With this feature Oracle Identity Federation, when acting as a service provider, does not attempt to locate a user based on the information contained in the assertion; instead the content of the assertion is passed directly back to the SP Integration module, which implements the user mapping flow.

If Oracle Identity Federation/SP is configured to bypass mapping (that is, to not map the principal identified in the assertion to a local user), Oracle Identity Federation does the following:

creates an Oracle Identity Federation session for the anonymous user, specified in the Oracle Identity Federation administration console in the service provider section. This is required as the server needs to be aware of the user being authenticated at the server and at peer providers (for example, at the logout operations).

Thus, setting the Anonymous User ID in the Oracle Identity Federation pages for Fusion Middleware Control is mandatory.
passes the NameID, attributes, and other information back to the SP Integration module, as specified in Section 10.4.2.3, "Implementing the Service", under the heading "Oracle Identity Federation Assertion Processing".

6.19.1 Configuring Oracle Identity Federation

To configure Oracle Identity Federation to map (or not map) the incoming assertion to a user record:

Log in to Fusion Middleware Control.
Navigate to Administration, then Service Provider, then Common.
Check Map assertion to User Account to configure Oracle Identity Federation to map incoming assertions to user records; uncheck it to not map the assertion.
Apply the changes.

6.20 Overriding NameID Mapping Per Partner

On a per-partner basis, an IdP administrator can override the mapping of NameID formats to local user directory attributes.

To configure this feature at the command line take these steps:

Set up the script environment as described in Chapter 9, "Oracle Identity Federation Command-Line Tools."
Invoke the WLST shell using java weblogic.WLST.

Enter one of these commands based on the name format used:

setFederationProperty('SPproviderID','nameformatemail','attribute-name','string')

if name format is Email Address

setFederationProperty('SPproviderID','nameformatx500','attribute-name','string')

if name format is X509 Subject Name

setFederationProperty('SPproviderID','nameformatunspecified','attribute-name','string')

if name format is Unspecified

setFederationProperty('SPproviderID','nameformatkerberos','attribute-name','string')

if name format is Kerberos

setFederationProperty('providerID','nameformatwindows','attribute-name','string')

if name format is Windows Domain Qualified Name

setFederationProperty('providerID','nameformatcustom','attribute-name','string')

if name format is Custom

Note:

If federation store was set and a federation record exists for the user, the nameid in the federation record is used.

6.21 Configuring Audience Restrictions for Assertions

When using assertions to exchange information, SAML authorities such as an identity provider or attribute authority can set the conditions under which an assertion is valid. Typical conditions might be:

Time before which the assertion is not valid
Time after which the assertion is not considered valid any more
List of providers that can process the assertion. Only a provider listed in the AudienceRestictionCondition element of the assertion is able to use the assertion.

The SAML specifications define the AudienceRestictionCondition as a list of Audience elements, each one referencing a provider that can process the assertion.

By default, Oracle Identity Federation creates an AudienceRestrictionCondition element when generating an assertion, and includes the recipient of the assertion using these rules:

For SAML 1.x protocol exchanges, set the Audience as the Assertion Consumer Service URL of the service provider.
For SAML 2.0 protocol exchanges, set the Audience as the ProviderID of the service provider /Attribute Requestor.
For WS-Fed protocol exchanges using SAML assertions, set the Audience as the ProviderID of the service provider.

When Oracle Identity Federation receives and processes an assertion, by default it validates the AudienceRestrictionCondition, if present, by using the ProviderID or URL where the assertion was posted.

Depending on the deployment scenario, it might be necessary to disable generation and validation of the AudienceRestrictionCondition element; you can do so either at a protocol level (SAML 1.0, SAML 1.1 or SAML 2.0 assertions), or at the trusted provider level.

To configure Oracle Identity Federation to control generation and processing of the AudienceRestrictionCondition for SAML 1.x/SAML 2.0 assertions at a global level, enter the WLST script environment for the Oracle Identity Federation instance, and:

Set the audiencerestrictionenabled boolean property from the idpsaml10, idpsaml11 or idpsaml20 groups to true (default) to enable the generation of AudienceRestrictionCondition when creating a SAML 1.0, SAML 1.1 or SAML 2.0 assertion respectively.
```
setConfigProperty('idpsaml11', 'audiencerestrictionenabled', 'true', 'boolean')
```
Set it to false to disable the generation of the condition
Set the audiencerestrictionenabled boolean property from the spsaml10, spsaml11 or spsaml20 groups to true (default) to enable the validation of AudienceRestrictionCondition when processing a SAML 1.0, SAML 1.1 or SAML 2.0 assertion respectively:
```
setConfigProperty('spsaml11', 'audiencerestrictionenabled', 'true', 'boolean')
```
Set it to false to disable validation of the condition.

To configure Oracle Identity Federation to enable generation and processing of the AudienceRestrictionCondition for a specific trusted provider, enter the WLST script environment for the Oracle Identity Federation instance, and set the audiencerestrictionenabled boolean property for a trusted provider referenced by REMOTE_PROVIDER_ID to true:

setFederationProperty(REMOTE_PROVIDER_ID, 'audiencerestrictionenabled', 'true', 'boolean')

Set the property to false to disable generation and processing of the condition.

You can also configure Oracle Identity Federation to use a custom string when:

Oracle Identity Federation/IdP creates an assertion.

Oracle Identity Federation uses the custom string specified in the configuration to populate the AudienceRestrictionCondition element
Oracle Identity Federation/SP processes an assertion.

Oracle Identity Federation validates the AudienceRestrictionCondition element, if present, by comparing it to the custom string specified in the configuration.

To configure Oracle Identity Federation to use a specific audience value when validating the AudienceRestrictionCondition for SAML 1.x/SAML 2.0 assertions at a global level, enter the WLST script environment for Oracle Identity Federation instance, and set the audiencerestrictionvalue string property from the spsaml10, spsaml11 or spsaml20 groups to the custom value that Oracle Identity Federation uses during the validation of AudienceRestrictionCondition when processing a SAML 1.0, SAML 1.1 or SAML 2.0 assertion respectively:

setConfigProperty('spsaml11', 'audiencerestrictionvalue', 'someglobalvalue', 'string')

If you set the audiencerestrictionvalue to the empty string value, Oracle Identity Federation/SP validates the AudienceRestrictionCondition element as shown above.

To configure Oracle Identity Federation to use a specific Audience value when generating/validating the AudienceRestrictionCondition for a specific trusted provider, enter the WLST script environment for Oracle Identity Federation instance, and set the audiencerestrictionvalue string property for a trusted provider referenced by REMOTE_PROVIDER_ID to use a custom string to generate and validate the condition when creating and processing an assertion:

setFederationProperty(REMOTE_PROVIDER_ID, 'audiencerestrictionvalue', 'customvalue', 'string')

If you set the audiencerestrictionvalue to the empty string value, Oracle Identity Federation/SP populates/validates the AudienceRestrictionCondition element as shown above.

6.22 Certificate Path Validation

Oracle Identity Federation provides a certificate validation module (described in Section 5.10.3, "Security and Trust - Trusted CAs and CRLs") that validates any certificate used for XML digital signature verification by using the certificates of the Trusted CAs and the CRLs uploaded by the administrator.

The module integrates with the JRE CertPathValidation API to validate certificates using the default CertPathValidation module configured in the JVM. When the default CertPathValidation module is the Sun implementation, Oracle Identity Federation can leverage the Online Certificate Status Protocol (OCSP) and the CRL Distribution Point (CDP) features provided by the Sun module.

You manage the certificate validation flow using the following properties:

In Fusion Middleware Control, navigate to the Oracle Identity Federation server instance, then Security and Trust, then Trusted CAs and CRLs section:
- Checking the "Enable Certificate Validation" box enables certificate validation in Oracle Identity Federation
- The Trusted Certificate Authorities table lists all the known and trusted certificates of the CAs
- The Certificate Revocation Lists table contains the CRLs used to check the revocation status of certificates.
the certpathvalidationenabled boolean property in the serverconfig configuration group determines the validation module to be used:
- false means that Oracle Identity Federation's internal certificate validation module is used, based on the Trusted Certificate Authorities and Certificate Revocation Lists tables.
- true means that the JRE CertPathValidation module is used. This module is bootstrapped with the contents of the Trusted Certificate Authorities table to serve as the basis for the trusted CAs.
the certpathvalidationcrlenabled boolean property in the serverconfig configuration group indicates whether the JRE CertPathValidation module should check for certificate revocation using the CRLs listed in the Certificate Revocation Lists table:
- false disables CRL validation in the JRE CertPathValidation module
- true enables CRL validation in the JRE CertPathValidation module

the certpathvalidationocspenabled boolean property in the serverconfig configuration group indicates whether the OCSP plugin of the Sun CertPathValidation implementation is enabled.

false disables OCSP validation
true enables OCSP validation

Notes:

The certpathvalidationcrlenabled must be set to true to enable the OCSP plugin.
Sun CertPathValidation module performs OCSP validation first and, if the operation is inconclusive, it performs a CRL revocation check operation.

the certpathvalidationocspurl string property in the serverconfig configuration group contains the URL of the OCSP server where the Sun CertPathValidation module sends the request for validation.

Note:
(To enable the OCSP functionality set the certpathvalidationocspenabled boolean property to true.

the certpathvalidationocspcertsubject string property in the serverconfig configuration group contains the subject name of the OCSP server's certificate.

Notes:

The matching certificate must also be added to the Oracle Identity Federation trusted CA certificate store.
Ensure the OCSP functionality is enabled with the certpathvalidationocspenabled boolean property set to true.

the certpathvalidationcdpenabled boolean property in the serverconfig configuration group indicates whether the Sun CertPathValidation module will use CDP extensions when performing a CRL revocation check operation.

If the OCSP module is enabled, Oracle Identity Federation sets the following Java Security properties in the JVM:

ocsp.enable is set to true
ocsp.responderURL is set to the OCSP server's URL
ocsp.responderCertSubjectName is set to the subject name of the OCSP server's certificate

See Also:

The Java PKI Programmers Guide for more detail on these system properties:

http://java.sun.com/javase/6/docs/technotes/guides/security/certpath/CertPathProgGuide.html#AppC

If the CDP functionality is enabled, the com.sun.security.enableCRLDP Java system property is set to true.

Note:

For the OCSP and CDP features to be enabled, it is important to set the default CertPathValidation module to the Sun implementation (true by default in a standard installation).