This chapter describes additional Oracle Identity Federation administration topics, including:
This section explains how to set up a proxy server for Oracle Identity Federation. Since Oracle Identity Federation is a stand-alone server, you cannot use the usual procedures for setting up an application server proxy. Instead, use the steps provided here to set up an Oracle HTTP Server as a proxy for Oracle Identity Federation:
If not previously created with the IdM installer, create an Oracle HTTP Server component using the following command:
$AS_ISNT/bin/opmnctl createcomponent -componentType OHS -componentName $OHS_NAME
where $AS_ISNT is the directory where the application server instance is installed, and $OHS_NAME is the name of the new Oracle HTTP Server component.
Edit the file $AS_ISNT/config/OHS/$OHS_NAME/moduleconf/oif.conf. If this file is not present, create it with this content:
# References the WebLogic server or Cluster where OIF is running
<Location /fed>
# Standalone install
# WebLogicHost myweblogic.server.com
# WebLogicPort 7499
# Clustered install
# WebLogicCluster w1s1.com:7499,w1s2.com:7499,w1s3.com:7499
SetHandler weblogic-handler
</Location>
If the IdM install is in stand-alone mode, uncomment and set the WebLogicHost and WebLogicPort variables to reference the WebLogic managed server where Oracle Identity Federation is running.
# Standalone install WebLogicHost OIF-HOST WebLogicPort OIF-PORT
If the IDM install is in clustered mode, uncomment and set the WebLogicCluster variable to reference the WebLogic managed servers where Oracle Identity Federation is running:.
# Clustered install WebLogicCluster OIF-HOST-1:OIF-PORT-1,OIF-HOST-2:OIF-PORT-2,OIF-HOST-3:OIF-PORT-3
If using SSL from the proxy to Oracle Identity Federation, edit the $ORACLE_HOME/ohs/conf/httpd.conf file. Add the following directive:
WlSSLWallet "${ORACLE_INSTANCE}/config/${COMPONENT_TYPE}/${COMPONENT_NAME}/keystores/default"
If you have not already done so, import the certificate of the certificate authority that issued Oracle Identity Federation certificate in this wallet. See Section 8.2, "Configuring SSL for Oracle Identity Federation" for details.
If using SSL with the proxy, follow the instructions in Section 8.2, "Configuring SSL for Oracle Identity Federation". Omit the section about editing the mod_wl.conf file.
Restart Oracle HTTP Server to make the configuration changes effective.
$AS_ISNT/bin/opmnctl restartproc process-type=OHS
Determine the proxy HTTP or HTTPS ports by going to Fusion Middleware Control, locating the Oracle HTTP Server instance, and navigating to Administration, then Ports Configuration. You can test the proxy by invoking:
HTTP://PROXY-HOST:PROXY_PORT/fed/sp/metadata
Reconfigure Oracle Identity Federation to use the proxy host and port for its external URLs. Locate the Oracle Identity Federation instance in Fusion Middleware Control, and navigate to Administration, then Server Properties, then Connection Settings:
Host
Port
SOAP Port
SSL Enabled
If using Oracle Access Manager as the identity management system, use the Access System console to update the Fed SSO authentication schemes. In the console, navigate to Access System Configuration, then Authentication Management. Change the Challenge Redirect parameter for each Oracle Identity Federation Authentication scheme to use the proxy host and port.
See Also:
Oracle Access Manager Access Administration Guide for details about the Web-based user interface.Communicate the changes to partners using this Oracle Identity Federation server, if necessary. Partners using SAML 2.0, SAML 1.x, or Liberty 1.x will need to download new metadata. Partners using WS-Federation will need to manually update their configurations.
If Oracle Identity Federation is integrated with Oracle Single Sign-On, some additional steps are required. Follow the instructions in these sections:
To configure SSL between Oracle HTTP Server and Oracle WebLogic Server, refer to:
This section contains these topics:
Note:
Keystores, trusted certificates and certificates for Oracle Identity Federation are managed the same way as they are for any other Oracle Fusion Middleware component. For details, see the Oracle Fusion Middleware Administrator's Guide.This section explains how to configure the SSL port for Oracle WebLogic Server, and how to configure Oracle Identity Federation to use SSL.
Take these steps to configure the SSL port and keystore for the Oracle WebLogic Server for which you are setting up SSL:
Log in to the Oracle WebLogic Server administration console and navigate to Environment, then Servers.
Select the server for which you want to set up SSL.
Check SSL Listen Port Enabled and enter an SSL listening port number (for example. 443).
We will subsequently refer to this port as $SSL_PORT.
Click Save.
Go to the Keystores tab, and click Lock & Edit.
In Keystores, select an option that includes Custom Identity.
In the Identity section, fill in properties as follows:
Custom Identity Keystore: location of keystore containing the SSL private key and certificate
Custom Identity Keystore type: jks
Custom Identity Keystore Passphrase: storepassword
Click Save.
Go to the SSL tab.
In the Identity section, fill in properties as follows:
Private Key Alias: keyalias
Private Key Passphrase: keypassword
Click Save, then click Activate Changes.
Restart the server.
To verify that SSL was set up correctly, go to https://$HOSTNAME:$SSL_PORT; a certificate should be presented. View the certificate; the subject should match the cn entered when creating the certificate.
Notes:
The CN of the SSL server certificate must be the fully qualified hostname, for example eaevma1302.de.mycorp.com, not eaevma1302.·
For complete information on how to set up SSL on Oracle Weblogic Server, refer to Configuring SSL in Oracle Fusion Middleware Securing Oracle WebLogic Server.
If you wish to configure Oracle WebLogic Server to require a client SSL certificate, take the following steps:
Log in to the Oracle WebLogic Server administration console and navigate to Environment, then Servers.
Select the server for which you want to set up SSL.
Go to the SSL tab, then Advanced.
For the property "Two Way Client Cert Behavior", select "Client Certs Requested and Enforced".
Click Save.
Go to the Keystores tab.
In Keystores, select an option that has the type of Trust Keystore type you wish to configure, and populate the fields in the Trust section.
Click Save, and click Activate Changes.
Restart the server.
You will need to import the CA that issued the client certificate into the Trust Keystore you specified in the Oracle WebLogic Configuration. If it is a Java Keystore, you can use the following command:
keytool -import -alias aliasfortrustedca -trustcacerts -file trustedcafile.pem -keystore keystorelocation -storepass truststorepassword
Once you have enabled an SSL listening port and uploaded the server and trusted certificates to the respective keystores, you will need to configure Oracle Identity Federation to use SSL.
Follow these steps:
Log in to Fusion Middleware Control and locate the Oracle Identity Federation instance.
Navigate to Server Properties.
Update the port (and SOAP port, if necessary) to reflect the SSL port configured in the Oracle Weblogic Server administration console.
Check the SSL Enabled checkbox.
To force the use of SSL if a request is received at a non-SSL port, check the Force SSL box. Leave unchecked otherwise.
To force client authentication, check the Require Client Certificate box. Leave unchecked otherwise.
Click Apply.
You must re-generate and re-distribute metadata to peer providers after enabling SSL.
Notes:
Changing the port (and SOAP port) modifies the server's metadata to reflect the correct service URLs.
The metadata at the peer providers' sites must be updated with the new version.
There are two ways to configure Oracle Identity Federation as an SSL client to connect to remote SSL servers:
Set up Oracle Identity Federation to use the Oracle WebLogic Server keystores as its Identity and Trust repositories. This approach is described in Section 8.2.2.1, "Configuring Oracle WebLogic Server" and Section 8.2.2.2, "Configuring Keystore Passwords in Oracle Identity Federation".
Set up Oracle Identity Federation to use its own Identity and Trust keystores. This approach is described in Section 8.2.2.3, "Alternative Way to Configure Oracle Identity Federation as SSL Client".
Topics in this section include:
Configuring Keystore Passwords in Oracle Identity Federation
Alternative Way to Configure Oracle Identity Federation as SSL Client
Some SSL Servers might require authentication of the client performed during the SSL handshake. This operation is typically done by having the SSL Client present an SSL Client certificate to the SSL Server.
This section describes how to configure Oracle WebLogic Server and Oracle Identity Federation to present a Client SSL certificate when it is requested by an SSL server. This requires:
setting up trust for the CA that issued the SSL server certificates
obtaining a certificate for the Oracle Identity Federation SSL client.
Take these steps to achieve this:
Log in to the Oracle WebLogic Server administration console and navigate to Environment, then Servers.
Select the server for which you want to set up SSL.
Go to the Keystores tab, and click Lock & Edit.
In Keystores, select an option that includes Custom Identity and the Trust Keystore type you wish to configure.
In the Identity section, fill in properties as follows:
Custom Identity Keystore: location of keystore with SSL private key and certificate
Custom Identity Keystore type: identity keystore type
Custom Identity Keystore Passphrase: storepassword
In the Trust section, fill in the properties with the Trust Keystore information.
Click Save, then click Activate Changes.
Restart the server.
If Oracle Identity Federation needs to connect to a remote provider and provide an SSL client certificate, you must configure the identity and trust keystore passwords in Oracle Identity Federation setup, not in Oracle WebLogic Server. Follow these steps:
Log in to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.
Navigate to Administration, then Server Properties.
Under Outbound Connections -> SSL Settings, enter the values of these two properties:
WebLogic Server Identity Keystore Password - the password of the Identity Keystore you entered in the Oracle WebLogic Server configuration.
WebLogic Server Trust Keystore Password - the password of the Trust Keystore you entered in the Oracle WebLogic Server configuration. If this property is left empty, the trust keystore will be opened without a password.
If you do not wish to enter Identity and Trust Keystore information in the Oracle WebLogic Server configuration, there is an alternate way to configure Oracle Identity Federation as an SSL Client when connecting to remote SSL servers.
With this approach, you will need to use the Oracle Identity Federation WLST commands or MBeans to set certain configuration properties. You will also need to enter the keystore passwords in the credential store.
You will need to set these five properties in Config "serverconfig" to the following values:
usewlssslconfig - false
clientsslkeystoreloc - the path and filename of the Identity Keystore. The path must be absolute or relative to the Domain Home.
clientsslkeystoretype – the Identity Keystore type. If no type is specified, the type is assumed to be JKS.
clientssltruststoreloc – the path and filename of the Trust Keystore. The path must be absolute or relative to the Domain Home.
clientssltruststoretype – the Trust Keystore type. If no type is specified, the type is assumed to be JKS.
Example: Using the WLST commands
setConfigProperty('serverconfig', 'usewlssslconfig', 'false', 'BOOLEAN')
setConfigProperty('serverconfig', 'clientsslkeystoreloc', '/usr/local/ssl/keystore', 'STRING')
setConfigProperty('serverconfig', 'clientsslkeystoretype', 'JKS', 'STRING')
setConfigProperty('serverconfig', 'clientssltruststoreloc', '/usr/local/ssl/truststore', 'STRING')
setConfigProperty('serverconfig', 'clientssltruststoretype', 'JKS', 'STRING')
See Chapter 9, "Oracle Identity Federation Command-Line Tools" for details about WLST command usage.
Example: Using the MBeans
In the ConfigMXBean with name "serverconfig", invoke the "putProperty" operation five times with the following arguments:
| Property Name | Property Value | Property Type |
|---|---|---|
| usewlssslconfig | false | BOOLEAN |
| clientsslkeystoreloc | /usr/local/ssl/keystore | STRING |
| clientsslkeystoretype | JKS | STRING |
| clientssltruststoreloc | /usr/local/ssl/keystore | STRING |
| clientssltruststoretype | JKS | STRING |
See Appendix A, "Oracle Identity Federation MBeans" for details.
You will need to store the Identity and Trust keystore passwords in the credential store. The keys for these passwords in the credential store are:
clientsslkeystorepwd – the password of the Identity Keystore
clientssltruststorepwd – the password of the Trust Keystore
Following is an example of how to use WLST commands to create and update these passwords in the credential store. This example assumes that Oracle Identity Federation is deployed with application name "OIF"; the password of both the Identity and Trust keystore is denoted as "mypassword".
Create the keystore credentials:
createCred(map="OIF", key="clientsslkeystorepwd", user="UniqueUserNameCredential", password="mypassword", desc="identity keystore pwd") createCred(map="OIF", key="clientssltruststorepwd", user="UniqueUserNameCredential", password="mypassword", desc="trust keystore pwd")
Update the keystore credentials:
updateCred(map="OIF", key="clientsslkeystorepwd", user="UniqueUserNameCredential", password="mypassword", desc="identity keystore pwd") updateCred(map="OIF", key="clientssltruststorepwd", user="UniqueUserNameCredential", password="mypassword", desc="trust keystore pwd")
See Section 4.5, "Managing Credentials for Oracle Identity Federation" for details.
When Oracle Identity Federation needs to connect to an LDAP Server using SSL, you first need to add the LDAP's CA certificate to the Trust keystore in the Oracle WebLogic Server Administration Console; this information is provided on the Server/Keystores configuration screen for the managed server where Oracle Identity Federation is running.
You must also enter the Trust keystore password in Oracle Identity Federation configuration (See Section 8.2.2.1, "Configuring Oracle WebLogic Server" and Section 8.2.2.2, "Configuring Keystore Passwords in Oracle Identity Federation").
Notes:
Oracle Identity Federation does not support client authentication when connecting to LDAP servers.
Oracle Identity Federation will only use the WLS Trust keystore when connecting to LDAP servers.
When Searching LDAP Server over SSL
If the User and/or Federation Data Stores are LDAP servers using SSL, and you wish to use the search operations in Fusion Middleware Control (navigate to Administration, then Identities), you will need to import the LDAP's CA certificate to the JVM's cacert keystore.
When performing the search operation, you will see the following error printed in the logs:
SEVERE: NamingException: error while interacting with an LDAP server or JNDI module javax.naming.NameNotFoundException: remaining name: env/jmx/runtime
This is expected and will not affect the search.
Oracle Identity Federation provides a way to update signing and/or encryption wallets smoothly, without interrupting service.
When you need to replace a signing or encryption wallet and a new one is uploaded, Oracle Identity Federation saves the old wallet. The server then continues to use the old wallet in all transactions until it is removed. However, generated metadata will contain the new wallet information as well as the old information. This allows time to notify remote providers about the change.
Once new metadata has been created and distributed to all remote providers, the old wallet can be deleted and Oracle Identity Federation will use the newly uploaded wallet for all subsequent transactions.
Follow these steps when replacing a signing or encryption wallet:
Upload the new wallet.
Log in to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.
Navigate to Administration, then Security and Trust.
In the Wallets tab, click Update.
Check the Update checkbox for the wallet you want to update.
Select the keystore type, wallet location, password, and alias.
Click OK.
Generate and distribute new metadata.
Log in to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.
Navigate to Administration, then Security and Trust.
In the Provider Metadata tab, under the Generate Metadata section, select the provider type and the protocol of the metadata to be generated, and click Generate.
Save the generated metadata.
Distribute the generated metadata to all remote peer providers.
Delete the old wallet.
Log in to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.
Navigate to Administration, then Security and Trust.
In the Wallets tab, click Update.
In the wallet that you have updated, click Delete old Wallet.
By default, Oracle Identity Federation supports low-strength cryptographic key sizes for encryption/decryption operations such as XML encryption.
In order to use strong symmetric encryption algorithms, such as AES-256, you need to modify the JVM to include the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction policy from Sun Microsystems.
Take these steps:
Download Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction policy files from this URL:
http://java.sun.com/javase/downloads/index.jsp
Unzip the files in all the $JAVA_HOME/jre/lib/security directories located under the $BEA_HOME folder (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 Sun Microsystems.
Restart the administration server and the managed server where Oracle Identity Federation is running.
Oracle Identity Federation provides a plug-in framework to customize the business processing of the operations performed by the server. Plug-in features and an example are provided here.
This section describes some key facts about the plug-in framework.
The processing flow is as follows:
You can implement a plug-in that will be invoked in various sections of the business flows.
The plug-in can analyze data collected during the execution of the operation, and decide whether an extra business step should be required.
If any additional actions are to be performed, the plug-in returns to Oracle Identity Federation a URL where the user needs to be redirected.
The redirection URL can contain query string parameters set by the plug-in.
Oracle Identity Federation appends one query string parameter, referenced by refID, to be sent when the user is returning to Oracle Identity Federation
Once the extra operation is performed, the user must be redirected to Oracle Identity Federation with the refid parameter, to the following URL:
http(s)://OIF-HOST:OIF-PORT/fed/user?refid=VALUE_RETRIEVED_FROM_REDIRECT_URL
These steps are needed to implement the plug-in:
Register the plug-in in the Oracle Identity Federation configuration file.
- Package the plug-in in a JAR file and add this to the CLASSPATH.
The plug-in will need to extend the oracle.security.fed.plugins.bizops.OperationListener interface, and will need to implement the "public ListenerResult process(int operationType, OperationData params)" method. This method has two arguments, the first one being the type of operation being performed and the second some parameters relative to the operation that will allow the plug-in to make a decision. The method returns a ListenerResult class containing a status and an optional redirectURL. If the status is OK, the Oracle Identity Federation will resume its operations, otherwise it will redirect the user to the specified redirection URL.
The operations include:
OperationTypes.BUSINESS_IDP_CREATE_PERSISTENT_FEDERATION: indicates a persistent federation is created on the IdP side
OperationTypes.BUSINESS_IDP_CREATE_TRANSIENT_FEDERATION: indicates a transient federation is created on the IdP side
OperationTypes.BUSINESS_IDP_SSO: indicates an SSO operation performed on the IdP side
The parameters passed in the OperationData object are:
BusinessProcessingConstants.DATA_STRING_PROVIDERID: references the Service Provider ID. Type is String
BusinessProcessingConstants.DATA_STRING_USERID: references the User ID. Type is String
BusinessProcessingConstants.DATA_STRING_SESSIONID: references the Session ID. Type is String
BusinessProcessingConstants.DATA_STRING_NAMEID_FORMAT: references the Name ID Format of the federation being created. Type is String
BusinessProcessingConstants.DATA_STRING_PROTOCOL_VERSION: references the protocol being executed. Type is String
BusinessProcessingConstants.DATA_BOOLEAN_AUTHNREQUEST_ISPASSIVE: references the IsPassive field from the AuthnRequest. Type is Boolean
The returned status values of the ListenerResult class can be:
BusinessProcessingConstants.STATUS_OK: indicates that the plug-in does not require any particular action.
BusinessProcessingConstants.STATUS_REDIRECT: indicates that the plug-in wishes to redirect the user to a URL.
Follow these steps to add a plug-in to the Oracle Identity Federation configuration file:
Open the $DOMAIN_HOME/config/fmwconfig/servers/wls_oif1/applications/OIF_11.1.1.2.0/configuration/config.xml file
Locate the Config XML element whose attribute name is serverconfig.
Locate the PropertiesList XML element whose attribute name is businessprocessingplugins.
Add a Property XML child element to the PropertiesList. The text child of the Property element should be the classname of the plug-in, and the type attribute of this element should be string.
Save and exit.
Here is an example of the configured file:
<FederationConfig xmlns="http://xmlns.oracle.com/fed/schema/oif-11_2.xsd" version="0" activationenabled="false">
<Config name="serverconfig">
...
<PropertiesList name="businessprocessingplugins">
<Property type="string">oracle.security.fed.plugins.BusinessProcessingSample</Property>
</PropertiesList>
...
</Config>
...
</FederationConfig>
A sample plug-in might look like this:
package oracle.security.fed.plugins;
import java.net.URLEncoder;
import java.util.Set;
import java.util.HashSet;
import oracle.security.fed.plugins.bizops.BusinessProcessingConstants;
import oracle.security.fed.plugins.bizops.BusinessProcessingException;
import oracle.security.fed.plugins.bizops.ListenerResult;
import oracle.security.fed.plugins.bizops.OperationData;
import oracle.security.fed.plugins.bizops.OperationListener;
import oracle.security.fed.plugins.bizops.OperationTypes;
// in this example, the plug-in will redirect the user to an external page the first time a user
// creates a persistent federation. Later on, if the user creates another federation (with the same
// provider or another one), the plug-in will not redirect the user anymore.
// Note: restarting the server will wipe out the cached information from the plug-in, resetting the data
// indicating whether or not any user was already redirected to the external page.
public class BusinessProcessingSample implements OperationListener {
private Set licenseAgreements = new HashSet();
public ListenerResult process(int operationType, OperationData params)
throws BusinessProcessingException {
ListenerResult result = new ListenerResult(BusinessProcessingConstants.STATUS_OK);
switch(operationType)
{
case OperationTypes.BUSINESS_IDP_CREATE_PERSISTENT_FEDERATION:
String userid = params.getStringProperty(BusinessProcessingConstants.DATA_STRING_USERID);
if (!licenseAgreements.contains(userid))
{
// redirect to remote page
result.setStatus(BusinessProcessingConstants.STATUS_REDIRECT);
StringBuffer sb = new StringBuffer();
sb.append("http://WEB-SERVER-HOST:WEB-SERVER-PORT/businesstest.jsp?providerid=");
sb.append(URLEncoder.encode(params.getStringProperty(BusinessProcessingConstants.DATA_STRING_PROVIDERID)));
sb.append("&userid=");
sb.append(URLEncoder.encode(params.getStringProperty(BusinessProcessingConstants.DATA_STRING_USERID)));
result.setRedirectURL(sb.toString());
// add the user to the license agreement set
licenseAgreements.add(userid);
}
break;
}
return result;
}
}
Here is a sample redirect page:
<%@ page language="java"
import="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");
String providerid = request.getParameter("providerid");
String userid = request.getParameter("userid");
String refid = request.getParameter("refid");
String returnurl = "http://OIF-HOST:OIF-PORT/fed/user?refid=" + URLEncoder.encode(refid);
%>
<html>
<body>
License Agreeement approved for:
ProviderID = <%=providerid%>
<BR>
UserID = <%=userid%>
<BR>
<a href="<%=returnurl%>">Click here to resume flow</a>
</body>
</html>
The Business Processing Plug-in API (javadoc) is available at: