| Oracle® OpenSSO Fedlet Interoperability Guide for Oracle Identity Federation 11g Release 1 (11.1.1.3.0) Part Number E17847-01 |
|
|
View PDF |
| Oracle® OpenSSO Fedlet Interoperability Guide for Oracle Identity Federation 11g Release 1 (11.1.1.3.0) Part Number E17847-01 |
|
|
View PDF |
This chapter describes how to configure the Java Oracle OpenSSO Fedlet (Java Fedlet) with a Java service provider (SP) application, so that the application can function with a remote identity provider (IdP) such as an Oracle Identity Federation (OIF) identity provider.
This chapter describes the following tasks for configuring the Java Oracle OpenSSO Fedlet:
Configuring the Java Oracle OpenSSO Fedlet Using the ConfigureFedlet Program
Configuring an Oracle Identity Federation Identity Provider for the Java Oracle OpenSSO Fedlet
Integrating the Java Oracle OpenSSO Fedlet into an Existing Application
Configuring the Java Oracle OpenSSO Fedlet with an Existing Application After Single Sign-On
Configuring the Java Oracle OpenSSO Fedlet for Single Logout
Configuring the Java Oracle OpenSSO Fedlet for Multiple Identity Providers
Configuring the Java Oracle OpenSSO Fedlet to Use the Identity Provider Discovery Service
Configuring the Java Oracle OpenSSO Fedlet for SAML 2.0 Attribute Query
Configuring the Java Oracle OpenSSO Fedlet for Signing and Encryption
Caution:
When you configure the Oracle OpenSSO Fedlet, you might need to specify certain passwords, depending on the feature you are configuring. For example, for signing and encryption, you must provide passwords for the
.keypass and .storepass files.
Although the Java Fedlet supports clear-text passwords, it is highly recommended in a production environment that you encrypt these passwords using the fedletEncode.jsp or as described in Section 3.2.3, "Encrypting a Password Using the ConfigureFedlet Program."
Before you configure the Java Oracle OpenSSO Fedlet, perform these tasks:
Download and unzip the Oracle-OpenSSO-Fedlet.zip file, as described in Chapter 2, "Installing the Oracle OpenSSO Fedlet."
If you plan to deploy the Java Fedlet sample application, fedlet.war, or another Java application, deploy a supported web container, as listed in the Section 1.2, "Oracle OpenSSO Fedlet Supported Standards and Applications."
If you plan to configure the Java Fedlet to use the attribute query feature and you are using an Oracle Identity Federation identity provider, set the Enable Attribute Query Responder option for the Oracle Identity Federation identity provider server instance before you generate the identity provider metadata (idp.xml file).
For more information, see Section 3.4.1, "Generating the Metadata for an Oracle Identity Federation Identity Provider."
Note:
The tasks in this chapter include steps that must be performed on both the Java Fedlet service provider side and the identity provider side. Depending on your deployment, you might be performing all tasks yourself, or you might have to provide the Java Fedlet service provider information to an identity provider administrator. Several considerations are:The Java Fedlet service provider metadata file is named sp.xml.
You or an identity provider administrator must import this file into the identity provider using the appropriate administration console or CLI command.
If you reconfigure the Java Fedlet, and change the sp.xml file, re-import the revised file into the identity provider.
The Java Fedlet service provider extended metadata file is named sp-extended.xml. Any changes you make in the file should be conveyed to the identity provider administrator, so that the appropriate changes can be made to the identity provider.
For example, if you change the wantLogoutResponseSigned attribute to true, you should communicate this change to the administrator, so that the identity provider can be modified to sign the logout response.
ConfigureFedlet ProgramThe ConfigureFedlet program configures the Java Oracle OpenSSO Fedlet without requiring you to perform some configuration steps manually. The ConfigureFedlet program can perform these functions:
Configure the Java Fedlet and optionally generate the Java Fedlet sample application WAR file, as described in Section 3.2.2, "Configuring the Java Oracle OpenSSO Fedlet Using the ConfigureFedlet Program."
Encrypt Fedlet passwords such as the keystore and private key passwords, as described in Section 3.2.3, "Encrypting a Password Using the ConfigureFedlet Program."
To determine whether you should run the ConfigureFedlet program or configure the Java Fedlet manually (or do both), see Section 3.2.1, "Considerations for Running the ConfigureFedlet Program."
After you configure and run the Java Fedlet, the debug logs are available under the Java Fedlet home /fedlet/debug directory. Log messages are written to the web container log files.
ConfigureFedlet ProgramTo configure the Java Fedlet, you can either run the ConfigureFedlet program or perform the configuration steps manually. You can also run the ConfigureFedlet program to do basic configuration for the Java Fedlet and then perform additional configuration manually, as required for your deployment. In some scenarios, such as configuring multiple identity providers or the identity provider discovery server, you must perform the manual configuration steps.
This section describes the following topics:
ConfigureFedlet ProgramThis section describes the configuration tasks that the ConfigureFedlet can perform, so you can decide whether you want to run the program or perform the configuration steps manually.
The ConfigureFedlet program can perform the following configuration tasks for the Java Fedlet:
Configure the Java Fedlet for single sign-on, single logout, and attribute query with the identity provider
Generate the Java Fedlet service provider metadata
Import the identity provider metadata
Generate the default keystore and keypair for signing and encryption
Generate the sample application WAR file
If you need to perform the following tasks, however, configure the Java Fedlet manually, as described in this chapter:
Configure multiple identity providers
Configure the identity provider discovery service
Use a nondefault keystore and keypair
Modify the extended identity provider metadata for customization, such as enabling signing for the logout request and response
Integrate the Java Fedlet with a service provider application
fedletsample.warThe ConfigureFedlet program asks whether you want to generate the fedletsample.war file during the configuration:
If the fedletsample.war is generated, you can deploy the WAR file to a web container and use it as a sample Java Fedlet deployment. The WAR file contains the Java Fedlet source code, as well as samples, located in the SampleApp directory.
If the fedletsample.war is not generated, you can bundle the fedlet.war in an EAR or WAR application file, customize the application if you wish, deploy the application, and then provide the configuration files generated by the ConfigureFedlet program.
ConfigureFedlet ProgramThe ConfigureFedlet program configures the Java Fedlet by prompting you for information and then populating the Java Fedlet configuration files.
To determine whether you should run the ConfigureFedlet program or configure the Java Fedlet manually (or do both), see Section 3.2.1, "Considerations for Running the ConfigureFedlet Program."
When you run the ConfigureFedlet program, it displays the following prompts. You might want to obtain this information before you run the program:
Enter the directory with path where Oracle-OpenSSO-Fedlet.zip is extracted to:
Enter the URL where this Fedlet will be deployed on (in http(s)://host.domain:port/uri format):
Note: If you are using Oracle Identity Federation as the identity provider and plan to configure the identity provider discovery service, https is required for the protocol.
Enter Fedlet Provider ID:[fedlet_sp_sample]
Do you want to generate keystore and key pair for the Fedlet? 1=yes/2=no [1]
Enter Fedlet keystore password: and Re-enter Fedlet keystore password:
Enter Fedlet key password: and Re-enter Fedlet key password:
Do you want to import IDP metadata? 1=yes/2=no [1]
Enter IDP metadata filename with path:
Include sample and generate fedlet sample.war? 1=yes/2=no [1]
Enter the directory with path where the newly generated Fedlet configuration and optionally fedletsample.war should be saved to:
To configure the Java Fedlet using the ConfigureFedlet program:
Make sure that $JAVA_HOME/bin is in your PATH variable, so that JDK commands such as jar, java, and keytool are accessible.
If necessary, download and unzip the Oracle-OpenSSO-Fedlet.zip, as described in Section 3.1, "Before You Configure the Java Oracle OpenSSO Fedlet."
The ConfigureFedlet program is available in the Java Fedlet java/install directory after you unzip the Oracle-OpenSSO-Fedlet.zip file.
If you want the program to import the identity provider metadata, retrieve the metadata and store it in a file named idp.xml.
For more information, see Section 3.4.1, "Generating the Metadata for an Oracle Identity Federation Identity Provider."
Extract the original fedlet.war file included in the Oracle-OpenSSO-Fedlet.zip. For example:
cd WAR_DIR jar xvf FEDLET_ZIP_DIR/java/fedlet.war
Run the ConfigureFedlet program to configure and optionally to create the fedletsample.war.
For example, on Solaris and Linux systems:
java -classpath WAR_DIR/WEB-INF/lib/opensso-sharedlib.jar: WAR_DIR/WEB-INF/lib/openfedlib.jar: FEDLET_ZIP_DIR/java/install/lib/configurefedlet.jar oracle.security.fed.fedlet.install.ConfigureFedlet
Or, on Windows systems:
java -classpath WAR_DIR\WEB-INF\lib\opensso-sharedlib.jar; WAR_DIR\WEB-INF\lib\openfedlib.jar; FEDLET_ZIP_DIR\java\install\lib\configurefedlet.jar oracle.security.fed.fedlet.install.ConfigureFedlet
The ConfigureFedlet program prompts you for input and then configures the Java Fedlet.
The Java Fedlet configuration files are generated in the directory you specify.
If you reply 1 (yes) to "Include sample and generate fedletsample.war?", the program also generates the fedletsample.war in the same location.
If you generated the fedletsample.war in the previous step, deploy the WAR to a web container using the Java Fedlet deployment URL you specified when you ran the program.
If a fedletsample.war was not generated, copy FEDLET_OUTPUT_DIR/fedlet to a directory indicated by the system property user.home or com.sun.identity.fedlet.home.
You can then add application logic to the fedlet.war or embed the fedlet.war in your application. Deploy the final WAR or EAR file to a web container to the Java Fedlet deployment URL you specified when you ran the ConfigureFedlet program.
The ConfigureFedlet program generates the service provider metadata in the sp.xml file in the Java Fedlet java/conf directory.
Give the sp.xml file to the identity provider administrator to import into the identity provider.
Or, you can also give the Java Fedlet deployment URL to the identity provider administrator, so that the administrator can export the service provider metadata using the exportmetadata.jsp. For example:
https://fedlet-host.example.com:fedlet-port/uri/saml2/jsp/exportmetadata.jsp
By default, the Java Fedlet wants an assertion to be signed and signs its AuthnRequest (if the keystore is configured).
Configure the identity provider for the Java Fedlet by adding the Java Fedlet as a trusted service provider and importing the service provider metadata (sp.xml file).
To configure an Oracle Identity Federation identity provider, see Section 3.4, "Configuring an Oracle Identity Federation Identity Provider for the Java Oracle OpenSSO Fedlet."
The Java Fedlet is now configured and ready to run.
If the fedletsample.war is deployed, you can test the Java Fedlet sample by accessing the Java Fedlet sample deployment URL. For example:
https://fedlet-host.example.com:fedlet-port/uri/index.jsp
ConfigureFedlet ProgramYou can run the ConfigureFedlet program to encrypt passwords such as the keystore and private key passwords. Use the encrypted passwords in the Java Fedlet configuration files for the Java Fedlet to use at run time.
For example, to encrypt a password:
Run the ConfigureFedlet program with the -e option. For example:
java -classpath WAR_DIR/WEB-INF/lib/opensso-sharedlib.jar: WAR_DIR/WEB-INF/lib/openfedlib.jar: FEDLET_ZIP_DIR/java/install/lib/configurefedlet.jar -D"com.sun.identity.fedlet.home=fedlet-configuration-directory" oracle.security.fed.fedlet.install.ConfigureFedlet -e
Enter a plain text password at the following prompt:
Enter password to be encrypted:
The program encrypts and returns the password. For example:
AQICVrMwQO5kkGifaGA88et605mWTFMPl18a
Copy the encrypted password to use with the Java Fedlet.
This section describes how to configure the Java Oracle OpenSSO Fedlet manually, without running the ConfigureFedlet program.
Note:
If thefedlet.war or fedletsample.war files need to be customized to either include specific application logic or to integrate with an existing application, follow these steps:
Customize the fedlet.war application or include the fedlet.war in an EAR application file.
Perform the manual configuration steps in this section.
Deploy the WAR or EAR file.
To configure the Java Oracle OpenSSO Fedlet manually, follow these steps:
Create your Java Fedlet home directory, which is the directory where the Java Fedlet reads its metadata, circle of trust, and configuration properties files. The default location is the fedlet subdirectory under the home directory of the user running the Java Fedlet web container (indicated by the user.home JVM property).
For example, if this home directory is /home/webservd, the Java Fedlet home directory is:
/home/webservd/fedlet
To change the Java Fedlet default home directory, set the value of the JVM run-time com.sun.identity.fedlet.home property to the desired location. For example:
-Dcom.sun.identity.fedlet.home=/export/fedlet/conf
The Java Fedlet then reads its metadata, circle of trust, and configuration files from the /export/fedlet/conf directory.
Copy the following configuration files from the Java Fedlet java/conf directory to the Java Fedlet home directory:
sp.xml-template
sp-extended.xml-template
idp-extended.xml-template
fedlet.cot-template
Rename the files you copied and drop -template from each name:
sp-extended.xml
sp.xml
idp-extended.xml
fedlet.cot
In the files that you copied and renamed in the Java Fedlet home directory, replace the tags shown in the next table:
| Tag | Replace With |
|---|---|
| FEDLET_COT | Name of your circle of trust. |
| FEDLET_ENTITY_ID | ID (name) for the Java Fedlet service provider application. For example: fedletsp |
| FEDLET_PROTOCOL | Protocol of the web container for the Java Fedlet service provider application (such as fedlet.war). For example: https
Note: If you are using an Oracle Identity Federation identity provider and plan to configure the identity provider discovery service, |
| FEDLET_HOST | Host name of the web container for the Java Fedlet service provider application (such as fedlet.war). For example: fedlet-host.example.com |
| FEDLET_PORT | Port number of the web container for the Java Fedlet service provider application (such as fedlet.war). For example: 80 |
| FEDLET_DEPLOY_URI | Deployment URI of the web container for the Java Fedlet service provider application (such as fedlet.war). For example: fedlet |
| IDP_ENTITY_ID | Entity ID (name) of the remote identity provider. For example: oifidp |
If the Java Fedlet service provider or identity provider entity ID contains a percent sign (%) or comma (,), escape the character before replacing it in the fedlet.cot file. For example, change “%” to “%25” and “,” to “%2C”.
Copy the FederationConfig.properties file from the Java Fedlet java/conf directory to the Java Fedlet home directory.
Get the identity provider standard metadata XML file and copy it to the Java Fedlet home directory. This file must be named idp.xml.
For an Oracle Identity Federation identity provider, retrieve the metadata either from Oracle Enterprise Manager Fusion Middleware Control or by directly accessing a URL.
Note:
If you plan to configure the Java Fedlet to use the attribute query feature, set the Enable Attribute Query Responder option for the Oracle Identity Federation identity provider server instance before you generate the identity provider metadata (idp.xml file).For more information, see Section 3.4.1, "Generating the Metadata for an Oracle Identity Federation Identity Provider."
Configure the identity provider for the Java Fedlet by adding the Java Fedlet as a trusted service provider and importing the metadata file.
To configure an Oracle Identity Federation identity provider, see Section 3.4, "Configuring an Oracle Identity Federation Identity Provider for the Java Oracle OpenSSO Fedlet."
Test your Fedlet configuration for single sign-on and single logout follows:
Deploy the fedlet.war file into your web container. Links to start the Java Fedlet service provider and identity provider initiated single sign-on are displayed.
Click the links to be redirected to the identity provider for login and then for single sign-on to the Java Fedlet service provider.
Upon successful completion, a Fedlet service provider JSP page shows the single sign-on response and assertion.
After you configure and run the Java Fedlet, the debug logs are available under the Java Fedlet home /fedlet/debug directory. Log messages are written to the web container log files.
This section describes how to configure an Oracle Identity Federation identity provider for the Java Oracle OpenSSO Fedlet, including:
Generating the Metadata for an Oracle Identity Federation Identity Provider
Configuring an Oracle Identity Federation Identity Provider for the Java Oracle OpenSSO Fedlet
To configure the Java Fedlet, you need the identity provider XML metadata in a file named idp.xml.
To generate the XML metadata for an Oracle Identity Federation identity provider, follow these steps:
Login to Oracle Fusion Middleware Control as an administrator who has the privileges required to manage the Oracle Identity Federation identity provider server instance you want to configure.
In Fusion Middleware Control, select the Oracle Identity Federation identity provider server instance in the topology panel at left.
If you are configuring the Java Fedlet for attribute query, set the Enable Attribute Query Responder option:
Navigate to Oracle Identity Federation, Administration, and then Identity Provider.
On the SAML 2.0 tab, under Protocol Settings, check Enable Attribute Query Responder.
Click Apply.
Generate the Oracle Identity Federation identity provider XML metadata, either from Oracle Enterprise Manager Fusion Middleware Control or by directly accessing a URL.
To generate the Oracle Identity Federation identity provider metadata from Fusion Middleware Control:
Navigate to Oracle Identity Federation, Administration, Security and Trust, and then Provider Metadata.
Select Identity Provider as the Provider Type and SAML 2.0 as the Protocol.
Click Generate.
Or, to generate the Oracle Identity Federation identity provider metadata, go to a URL of the form:
http://host:port/fed/idp/metadata
Name the identity provider metadata file idp.xml and copy the file to the Java Fedlet home directory.
Continue with Section 3.2, "Configuring the Java Oracle OpenSSO Fedlet Using the ConfigureFedlet Program" or Section 3.3, "Configuring the Java Oracle OpenSSO Fedlet Manually."
After you configure the Java Oracle OpenSSO Fedlet on the service provider side and create the Java Fedlet service provider metadata file (sp.xml), configure the identity provider by adding the Java Fedlet as a trusted service provider and importing the metadata file.
To configure Oracle Identity Federation as an identity provider for the Java Fedlet, follow these steps:
Login to Oracle Fusion Middleware Control as an administrator who has the privileges required to manage the Oracle Identity Federation identity provider server instance you want to configure.
Add the Java Fedlet service provider as a trusted provider for the Oracle Identity Federation identity provider:
In Fusion Middleware Control, select the Oracle Identity Federation identity provider server instance in the topology panel at left.
Navigate to Oracle Identity Federation, Administration, and then Federations.
On the Federations page, click Add.
The Add Trusted Provider dialog appears. Upload the Java Fedlet service provider metadata file (sp.xml) from the file system.
Click OK.
Configure the new Java Fedlet trusted provider you added in Step 2:
Navigate to Oracle Identity Federation, Administration, and then Federations.
On the Federations page, select the Java Fedlet trusted provider and click Edit.
For Oracle Identity Federation Settings, select the following settings (if they have not been set globally):
Check Enable Attributes in Single Sign-On (SSO).
If you are using the Java Fedlet attribute query feature, check Send Signed for Response with Assertion - SOAP.
Also, for the Java Fedlet attribute query feature, click Edit for Attribute Mapping and Filters and add the mappings for the attribute names. When you add an attribute pair, check Get Value from User Session.
Click Apply.
If you want to use identity provider initiated single sign-on and single logout, change the default NameID format to Transient/One-Time Identifier for the Java Fedlet service provider:
In Fusion Middleware Control, select the Oracle Identity Federation identity provider server instance in the topology panel at left.
Navigate to Oracle Identity Federation, Administration, and then Federations.
On the Federations page, select the Java Fedlet trusted provider and click Edit.
For Oracle Identity Federation Settings, set Default NameID Format to Transient/One-Time Identifier.
Click Apply.
If you make additional configuration changes made to the Java Fedlet, such as changes made in the service provider extended metadata file (sp-extended.xml), convey these changes to the identity provider administrator, so that the appropriate changes can be made on the identity provider side.
If you reconfigure the Java Fedlet and change the sp.xml file, re-import the revised metadata file into the identity provider.
To integrate the Java Oracle OpenSSO Fedlet into an existing Java application, follow these steps:
If you have not configured the Java Fedlet, see Section 3.2, "Configuring the Java Oracle OpenSSO Fedlet Using the ConfigureFedlet Program" or Section 3.3, "Configuring the Java Oracle OpenSSO Fedlet Manually."
Extract the fedlet.war file in a temporary directory.
Copy all other files to your application WAR staging directory and overlay them with your existing application WAR structure.
Optionally, you can remove index.jsp, fedletEncode.jsp and the Java Fedlet java/conf directory from the temporary directory created in Step 1 before you do the copy.
Create the new application WAR and redeploy it in your web container.
The SampleApp directory includes the sample Java Fedlet application named fedletSampleApp.jsp, which includes these functions and sample code:
Invokes a util method to complete the SAML 2.0 protocol processing
Returns a map containing various data, including response and assertion attributes for further processing by your application.
Provides sample code showing how your application can retrieve the data from the returned map
You can either modify the fedletSampleApp.jsp and add your application specific application logic or replace the fedletSampleApp.jsp with your own servlet or JSP.
To replace the fedletSampleApp.jsp with a new servlet or JSP, follow these steps:
Modify your web.xml file to set the servlet and servlet-mapping elements for your new servlet or JSP. Map your new servlet or JSP to the url-pattern "/fedletapplication" because it is the URI set in the Java Fedlet metadata (the assertion consumer URL). For example:
<servlet> <servlet-name>yourapplication</servlet-name> <jsp-file>/Your-Application.jsp</jsp-file> </servlet> <servlet-mapping> <servlet-name>yourapplication</servlet-name> <url-pattern>/fedletapplication</url-pattern> </servlet-mapping>
Copy following code from fedletSampleApp.jsp into your application using the appropriate import statement:
Map map;
try {
// invoke the Fedlet processing logic. this will do all the
// necessary processing conforming to SAMLv2 specifications,
// such as XML signature validation, Audience and Recipient
// validation etc.
map = SPACSUtils.processResponseForFedlet(request, response);
} catch (SAML2Exception sme) {
response.sendError(response.SC_INTERNAL_SERVER_ERROR, sme.getMessage());
return;
} catch (IOException ioe) {
response.sendError(response.SC_INTERNAL_SERVER_ERROR, ioe.getMessage());
return;
} catch (SessionException se) {
response.sendError(response.SC_INTERNAL_SERVER_ERROR, se.getMessage());
return;
} catch (ServletException se) {
response.sendError(response.SC_BAD_REQUEST, se.getMessage());
return;
}
After your application obtains the returned map object, refer to the sample code in fedletSampleApp.jsp to retrieve the data required by your application.
Single logout permits the session termination of all participants in a session simultaneously. Any participant in the session can initiate the logout request.
When using the Java Oracle OpenSSO Fedlet, the session state is maintained by the service provider application and not the Java Fedlet itself. Therefore, the service provider application performs the session termination and application logout for the user. The Java Fedlet simply provides support for the SAML 2.0 single logout communications. User log out from the application itself and single logout of the user from the identity provider can be initiated by the Java Fedlet or by the identity provider.
The Java Fedlet application decides whether to delete a user session before requesting single logout or after a successful single logout response is returned from the identity provider. It is also the Java Fedlet application's responsibility to invoke single logout for each identity provider with which it has successfully completed single sign on.
This section includes these topics about single logout:
Implementing Single Logout for the Java Oracle OpenSSO Fedlet Service Provider Application
Implementing the Java Oracle OpenSSO Fedlet Adapter SPI for Single Logout
Single logout can be initiated on the Java Fedlet side using the HTTP Redirect profile or the HTTP POST profile. In the Java Fedlet initiated single logout, the user clicks on a link specified by the service provider application.
The Java Fedlet service provider application logs the user out locally, and then sends the logout information to the spSingleLogoutInit.jsp. The JSP forms a logout request and sends it to the identity provider. After receiving a successful logout response from the identity provider, the Java Fedlet notifies an Adapter class of the result of the Global Logout operation.
For that purpose, the Java Fedlet obtains an instance of the implementation of the com.sun.identity.saml2.plugins.FedletAdapter service provider interface (SPI), which contains the necessary methods for logout and post processing. The default implementation class, com.sun.identity.saml2.plugins.DefaultFedletAdapter, is provided with OpenSSO or you could write a new implementation. This section provides the following topics:
On the identity provider side, single logout can be initiated using the HTTP POST profile or the HTTP Redirect profile. In identity provider initiated single logout, the Java Fedlet receives the logout request from the identity provider, verifies it, and obtains an instance of the FedletAdapter implementation.
The SPI invokes the doFedletSLO() method to log the user out of the service provider application. Then, the Java Fedlet forms a Logout Response based on the outcome and sends it to the identity provider. The default implementation of the Java Fedlet Adapter (com.sun.identity.saml2.plugins.DefaultFedletAdapter) is provided, or you can write a new implementation.
The com.sun.identity.saml2.plugins.FedletAdapter SPI provides the functionality for single logout, which can initiated by either the Java Fedlet service provider application or the identity provider. The com.sun.identity.saml2.plugins.DefaultFedletAdapter is the default implementation that is provided with the OpenSSO Fedlet.
Single logout initiated by the Java Fedlet service provider application:
For single logout initiated by the Java Fedlet service provider application, the onFedletSLOSuccess() and the onFedletSLOFailure() methods must be invoked after the Java Fedlet receives the logout response from the identity provider.
If the SAML 2.0 single logout response is successful, the onFedletSLOSuccess() method is called. This method can perform post processing after a successful single logout. If you are using com.sun.identity.saml2.plugins.DefaultFedletAdapter, the method posts information regarding the logout to the logout.jsp, provided with the Java Fedlet.
If the SAML 2.0 single logout response is not successful, the onFedletSLOFailure() method is called. This method is for post processing after an unsuccessful single logout and can perform developer-provided logic to handle the situation. If you are using com.sun.identity.saml2.plugins.DefaultFedletAdapter, it posts information regarding the logout to the logout.jsp, also provided with the Java Fedlet.
Single logout initiated by the identity provider:
For single logout initiated by the identity provider, the doFedletSLO() method must be invoked after the Java Fedlet receives the single logout request. The method initiates user log out from the application itself and the logout of the user from the identity provider.
You can write a new implementation by implementing the three methods as required in your application. Then, compile the class and integrate it into your application. If you are writing a new implementation, here are several considerations:
Defining the FedletAdapter SPI Implementation in the Metadata
The fedletAdapterClass attribute is new to the Java Fedlet's extended metadata. (It is not displayed in the entity provider extended metadata.) The value of fedletAdapterClass is the implementation of the fedletAdapter SPI, which by default is com.sun.identity.saml2.plugins.DefaultFedletAdapter.
Using the DefaultFedletAdapter Implementation
com.sun.identity.saml2.plugins.DefaultFedletAdapter is the default implementation of the FedletAdapter provided with the Java Fedlet. It works in tandem with logout.jsp. Application specific logic related to the logout can be added to logout.jsp for functions such user management and session management. You can also use the DefaultFedletAdapter with your own JSP or servlet, but you must define the location of the page as the value of the appLogoutUrl attribute in the Java Fedlet extended metadata.
Using the logout.jsp
If you do not use the logout.jsp with your new implementation, you must write your own JSP or servlet and define it. See the previous item for more information.
In some deployments, you might want to configure the Java Oracle OpenSSO Fedlet with multiple identity providers. This section describes how to add one or more additional identity providers such as an Oracle Identity Federation identity provider.
This scenario also applies to an existing deployment with the Java Fedlet installed with Oracle OpenSSO 8.0 Update 1 as an identity provider, and you now want to add an additional Oracle Identity Federation identity provider. Oracle OpenSSO 8.0 Update 1 must be installed and running. For information about OpenSSO 8.0 Update 1, see the OpenSSO 8.0 Update 1 Release Notes at http://docs.sun.com/doc/821-1818.
Note:
This section uses file names for adding a second identity provider. For example,idp2.xml, fedlet2.cot, and idp2-extended.xml. If necessary, rename these files using the appropriate number for the identity provider you are adding.To configure the Java Fedlet for an additional identity provider such an Oracle Identity Federation identity provider, follow these steps:
Get the XML metadata file for the additional identity provider and name this file idp2.xml.
For an Oracle Identity Federation identity provider, retrieve the metadata either from Oracle Enterprise Manager Fusion Middleware Control or by directly accessing a URL.
To retrieve the Oracle Identity Federation identity provider metadata from Fusion Middleware Control:
Navigate to Oracle Identity Federation, Administration, Security and Trust, and then Provider Metadata.
Select Identity Provider as the Provider Type and SAML 2.0 as the Protocol.
Click Generate.
Add this new identity provider to the Java Fedlet circle of trust:
To add the new identity provider to an existing circle of trust:
In the fedlet.cot file in your Fedlet home directory, append the new identity provider entity ID (indicated by the entityID attribute in the idp2.xml metadata file) to the value of the sun-fm-trusted-providers attribute, using a comma (,) as a separator.
To add the new identity provider to a new Java Fedlet circle of trust:
Create a new file named fedlet2.cot in your Fedlet home directory. Use the existing fedlet.cot as a template, but change the value of the cot-name attribute to the name of the new circle of trust (for example, cot2). Include both the new identity provider entity ID and the Java Fedlet entity ID as value for the sun-fm-trusted-providers attribute, with the two entity IDs separated by a comma (,).
In the sp-extended.xml file, add the new circle of trust name to the value of the cotlist attribute. For example, for a circle of trust named cot2:
<Attribute name="cotlist"> <Value>saml2cot</Value> <Value>cot2</Value> </Attribute>
In the Java Fedlet home directory, create a new idp2-extended.xml file as the extended metadata for the new identity provider. Use the existing idp-extended.xml file as a template, but change the entity ID to the new identity provider entity ID. Change the value for the cotlist attribute to the circle of trust name, if a new circle of trust is created for the identity provider.
Make sure that the second identity provider is a remote identity provider by setting the hosted attribute in the EntityConfig element to false.
Restart the Java Fedlet web container.
The Java Fedlet metadata XML file (sp.xml) must be imported into the additional identity provider and added to the same circle of trust as the identity provider entity. Either import the sp.xml file into the identity provider, or give the file to your identity provider administrator to import.
Note:
Any additional configuration changes made to the Java Fedlet, such as changes made in the service provider extended metadata file (sp-extended.xml), must be communicated to the identity provider administrator, so that the appropriate changes can be made on the identity provider side.
If you reconfigure the Java Fedlet and change the sp.xml file, re-import the revised file into the identity provider.
Repeat these steps for any additional identity providers you want to add for the Java Fedlet.
If the Java Fedlet is configured with multiple identity providers in a circle of trust, you can configure the JAva Fedlet to use the identity provider discovery service to determine the preferred identity provider.
The discovery service must be configured for the identity providers you are using with the Java Fedlet. For information about configuring the identity provider discovery service in Oracle Identity Federation, see the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Federation.
To configure the Java Fedlet to use the identity provider discovery service:
In the FederationConfig.properties file in the Java Fedlet home directory, set the following properties:
com.iplanet.am.cookie.encode=true
com.sun.identity.saml2.idpdiscovery.cookiedomain=cookie-domain
where the cookie-domain follows the format .example.com
Restart the Java Fedlet web container.
Set up the identity provider discovery service for each of the remote identity providers.
Access the Java Fedlet index.jsp page, and you are presented with an identity provider selection page. Do not click the “use IDP discovery service...” link yet, because the preferred identity provider has not been set yet. Choose one of the identity providers, and complete the single sign-on process. The preferred identity provider is then set by the discovery service.
Check the cookies. You should find one _saml_idp cookie set.
Close and then reopen your browser. The _saml_idp cookie should be still be present.
Access the Java Fedlet index.jsp page again and choose the “use IDP discovery service to find out preferred IDP” link.
You are redirected to the identity provider discovery service to find the preferred identity provider and then sent to the Java Fedlet with the chosen identity provider to start the Java Fedlet initiated single sign-on.
The Java Oracle OpenSSO Fedlet supports SAML 2.0 attribute query to query an identity provider such as an Oracle Identity Federation identity provider for specific identity attribute values. You can configure the Java Fedlet to sign the query and encrypt the query. Signing is required for issuing a Java Fedlet query, but encryption is optional.
To configure the Java Fedlet for SAML 2.0 attribute query, follow these steps:
If you are using an Oracle Identity Federation identity provider, enable the Attribute Query Responder option for the Oracle Identity Federation identity provider server instance, as described in Section 3.4.1, "Generating the Metadata for an Oracle Identity Federation Identity Provider."
If you have not copied the identity provider standard metadata XML file (idp.xml) to the Java Fedlet home directory, copy this metadata file now.
Enable XML signing to sign the Attribute Query, as described in Section 3.11, "Configuring the Java Oracle OpenSSO Fedlet for Signing and Encryption." For Attribute Query, signing is required, but encryption is optional.
Add the certificate generated in the previous step to the RoleDescriptor element in the Java Fedlet sp.xml file.
If you run the ConfigureFedlet program to configure the Java Fedlet, you do not have to do this step manually. The program adds the certificate for you.
In the following example, there are two KeyDescriptor tags in which you paste the certificate. One is for signing and another is for encryption. If you are not enabling encryption, the KeyDescriptor use="encryption" tag is not required.
<RoleDescriptor xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:query="urn:oasis:names:tc:SAML:metadata:ext:query"
xsi:type="query:AttributeQueryDescriptorType"
protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<KeyDescriptor use="signing">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
<ds:X509Certificate>
--certificate--
</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</KeyDescriptor>
<KeyDescriptor use="encryption">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
<ds:X509Certificate>
--certificate--
</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc">
<xenc:KeySize xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">128</xenc:KeySize>
</EncryptionMethod>
</KeyDescriptor>
</RoleDescriptor>
In the Java Fedlet sp-extended.xml file, specify the value for the signingCertAlias attribute and if configured, for the encryptionCertAlias attribute.
If you run the ConfigureFedlet program to configure the Java Fedlet, you do not have to do this step manually.
If you plan to configure the identity provider to encrypt the assertion, also encrypt the NameID element. Thus, the value of the wantNameIDEncrypted attribute must be set to true. Add the XML code to the AttributeQueryConfig element. For example:
<Attribute name="signingCertAlias"> <Value>test</Value> </Attribute> <Attribute name="encryptionCertAlias"> <Value>test</Value> </Attribute> <Attribute name="wantNameIDEncrypted"> <Value>true</Value> </Attribute>
In this example, test is the alias for the sample key.
After you configure the Java Fedlet, update the identity provider with the changes you made to the Java Fedlet by importing the service provider metadata (sp.xml) into the identity provider.
If you are using an Oracle Identity Federation identity provider, continue with Section 3.4.2, "Configuring an Oracle Identity Federation Identity Provider for the Java Oracle OpenSSO Fedlet."
The Java Oracle OpenSSO Fedlet supports XML signature verification and decryption of encrypted assertion and NameID elements and their corresponding attributes. To configure the Java Fedlet for signing and encryption, follow these steps:
Create a keystore file named keystore.jks using the keytool utility.
Add the private key (and public certificate if applicable) used for signing and the private key (and public certificate if applicable) used for encryption to the keystore.jks file.
Create a .storepass file.
Add the password to the .storepass file. To encrypt the password, use fedletEncode.jsp. Or, see Section 3.2.3, "Encrypting a Password Using the ConfigureFedlet Program."
Create a .keypass file.
Add the password to the .keypass file. To encrypt the password, use fedletEncode.jsp. Or, see Section 3.2.3, "Encrypting a Password Using the ConfigureFedlet Program."
If you are using clear-text passwords (which is not recommended), comment out the following line in the FederationConfig.properties file:
com.sun.identity.saml.xmlsig.passwordDecoder=
com.sun.identity.fedlet.FedletEncodeDecode
Set the following attributes in the FederationConfig.properties file, where path is the complete path to the respective file:
com.sun.identity.saml.xmlsig.keystore=path/keystore.jks com.sun.identity.saml.xmlsig.storepass=path/.storepass com.sun.identity.saml.xmlsig.keypass=path/.keypass
Use keytool to export the signing certificate. For example:
keytool -export -keystore keystore.jks -rfc -alias test
The tool prompts you to enter the password used to access keystore.jks and then generates the certificate.
If you need an encryption certificate, use keytool to export it, as shown in the previous step. (Or use the same certificate for both signing and encryption.)
Create a KeyDescriptor XML block and add the encryption certificate to it. Note the use="signing" tag of the KeyDescriptor element:
<KeyDescriptor use="signing">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
<ds:X509Certificate>
MIICQDCCAakCBEeNB0swDQYJKoZIhvcNAQEEBQAwZzELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNh
bGlmb3JuaWExFDASBgNVBAcTC1NhbnRhIENsYXJhMQwwCgYDVQQKEwNTdW4xEDAOBgNVBAsTB09w
ZW5TU08xDTALBgNVBAMTBHRlc3QwHhcNMDgwMTE1MTkxOTM5WhcNMTgwMTEyMTkxOTM5WjBnMQsw
CQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEUMBIGA1UEBxMLU2FudGEgQ2xhcmExDDAK
BgNVBAoTA1N1bjEQMA4GA1UECxMHT3BlblNTTzENMAsGA1UEAxMEdGVzdDCBnzANBgkqhkiG9w0B
AQEFAAOBjQAwgYkCgYEArSQc/U75GB2AtKhbGS5piiLkmJzqEsp64rDxbMJ+xDrye0EN/q1U5Of\+
RkDsaN/igkAvV1cuXEgTL6RlafFPcUX7QxDhZBhsYF9pbwtMzi4A4su9hnxIhURebGEmxKW9qJNY
Js0Vo5+IgjxuEWnjnnVgHTs1+mq5QYTA7E6ZyL8CAwEAATANBgkqhkiG9w0BAQQFAAOBgQB3Pw/U
QzPKTPTYi9upbFXlrAKMwtFf2OW4yvGWWvlcwcNSZJmTJ8ARvVYOMEVNbsT4OFcfu2/PeYoAdiDA
cGy/F2Zuj8XJJpuQRSE6PtQqBuDEHjjmOQJ0rV/r8mO1ZCtHRhpZ5zYRjhRC9eCbjx9VrFax0JDC
/FfwWigmrW0Y0Q==
</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</KeyDescriptor>
Create another KeyDescriptor XML block and add the encryption certificate to it. Note the use="encryption" tag of the KeyDescriptor element:
<KeyDescriptor use="encryption">
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
<X509Data>
<X509Certificate>
MIICQDCCAakCBEeNB0swDQYJKoZIhvcNAQEEBQAwZzELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNh
bGlmb3JuaWExFDASBgNVBAcTC1NhbnRhIENsYXJhMQwwCgYDVQQKEwNTdW4xEDAOBgNVBAsTB09w
ZW5TU08xDTALBgNVBAMTBHRlc3QwHhcNMDgwMTE1MTkxOTM5WhcNMTgwMTEyMTkxOTM5WjBnMQsw
CQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEUMBIGA1UEBxMLU2FudGEgQ2xhcmExDDAK
BgNVBAoTA1N1bjEQMA4GA1UECxMHT3BlblNTTzENMAsGA1UEAxMEdGVzdDCBnzANBgkqhkiG9w0B
AQEFAAOBjQAwgYkCgYEArSQc/U75GB2AtKhbGS5piiLkmJzqEsp64rDxbMJ+xDrye0EN/q1U5Of\+
RkDsaN/igkAvV1cuXEgTL6RlafFPcUX7QxDhZBhsYF9pbwtMzi4A4su9hnxIhURebGEmxKW9qJNY
Js0Vo5+IgjxuEWnjnnVgHTs1+mq5QYTA7E6ZyL8CAwEAATANBgkqhkiG9w0BAQQFAAOBgQB3Pw/U
QzPKTPTYi9upbFXlrAKMwtFf2OW4yvGWWvlcwcNSZJmTJ8ARvVYOMEVNbsT4OFcfu2/PeYoAdiDA
cGy/F2Zuj8XJJpuQRSE6PtQqBuDEHjjmOQJ0rV/r8mO1ZCtHRhpZ5zYRjhRC9eCbjx9VrFax0JDC
/FfwWigmrW0Y0Q==
</X509Certificate>
</X509Data>
</KeyInfo>
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc">
<KeySize xmlns="http://www.w3.org/2001/04/xmlenc#">128</KeySize>
</EncryptionMethod>
</KeyDescriptor>
In the sp.xml file, add the XML blocks with the signing and encryption certificates under the SPSSODescriptor element. For example:
<EntityDescriptor entityID="fedlet" xmlns="urn:oasis:names:tc:SAML:2.0:metadata">
<SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="false"
protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<b><KeyDescriptor use="signing">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
<ds:X509Certificate>
MIICQDCCAakCBEeNB0swDQYJKoZIhvcNAQEEBQAwZzELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNh
bGlmb3JuaWExFDASBgNVBAcTC1NhbnRhIENsYXJhMQwwCgYDVQQKEwNTdW4xEDAOBgNVBAsTB09w
ZW5TU08xDTALBgNVBAMTBHRlc3QwHhcNMDgwMTE1MTkxOTM5WhcNMTgwMTEyMTkxOTM5WjBnMQsw
CQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEUMBIGA1UEBxMLU2FudGEgQ2xhcmExDDAK
BgNVBAoTA1N1bjEQMA4GA1UECxMHT3BlblNTTzENMAsGA1UEAxMEdGVzdDCBnzANBgkqhkiG9w0B
AQEFAAOBjQAwgYkCgYEArSQc/U75GB2AtKhbGS5piiLkmJzqEsp64rDxbMJ+xDrye0EN/q1U5Of\+
RkDsaN/igkAvV1cuXEgTL6RlafFPcUX7QxDhZBhsYF9pbwtMzi4A4su9hnxIhURebGEmxKW9qJNY
Js0Vo5+IgjxuEWnjnnVgHTs1+mq5QYTA7E6ZyL8CAwEAATANBgkqhkiG9w0BAQQFAAOBgQB3Pw/U
QzPKTPTYi9upbFXlrAKMwtFf2OW4yvGWWvlcwcNSZJmTJ8ARvVYOMEVNbsT4OFcfu2/PeYoAdiDA
cGy/F2Zuj8XJJpuQRSE6PtQqBuDEHjjmOQJ0rV/r8mO1ZCtHRhpZ5zYRjhRC9eCbjx9VrFax0JDC
/FfwWigmrW0Y0Q==
</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</KeyDescriptor></b>
<b><KeyDescriptor use="encryption">
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
<X509Data>
<X509Certificate>
MIICQDCCAakCBEeNB0swDQYJKoZIhvcNAQEEBQAwZzELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNh
bGlmb3JuaWExFDASBgNVBAcTC1NhbnRhIENsYXJhMQwwCgYDVQQKEwNTdW4xEDAOBgNVBAsTB09w
ZW5TU08xDTALBgNVBAMTBHRlc3QwHhcNMDgwMTE1MTkxOTM5WhcNMTgwMTEyMTkxOTM5WjBnMQsw
CQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEUMBIGA1UEBxMLU2FudGEgQ2xhcmExDDAK
BgNVBAoTA1N1bjEQMA4GA1UECxMHT3BlblNTTzENMAsGA1UEAxMEdGVzdDCBnzANBgkqhkiG9w0B
AQEFAAOBjQAwgYkCgYEArSQc/U75GB2AtKhbGS5piiLkmJzqEsp64rDxbMJ+xDrye0EN/q1U5Of\+
RkDsaN/igkAvV1cuXEgTL6RlafFPcUX7QxDhZBhsYF9pbwtMzi4A4su9hnxIhURebGEmxKW9qJNY
Js0Vo5+IgjxuEWnjnnVgHTs1+mq5QYTA7E6ZyL8CAwEAATANBgkqhkiG9w0BAQQFAAOBgQB3Pw/U
QzPKTPTYi9upbFXlrAKMwtFf2OW4yvGWWvlcwcNSZJmTJ8ARvVYOMEVNbsT4OFcfu2/PeYoAdiDA
cGy/F2Zuj8XJJpuQRSE6PtQqBuDEHjjmOQJ0rV/r8mO1ZCtHRhpZ5zYRjhRC9eCbjx9VrFax0JDC
/FfwWigmrW0Y0Q==
</X509Certificate>
</X509Data>
</KeyInfo>
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc">
<KeySize xmlns="http://www.w3.org/2001/04/xmlenc#">128</KeySize>
</EncryptionMethod>
</KeyDescriptor></b>
<NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</NameIDFormat>
<AssertionConsumerService index="1" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
Location="http://server.sun.com:7070/fedlet/fedletapplication"/>
</SPSSODescriptor>
</EntityDescriptor>
The AuthnRequestsSigned attribute is set to true, configuring the Java Fedlet to sign all authentication requests.
In the Java Fedlet sp-extended.xml file, set values for the following attributes:
signingCertAlias contains the alias of the XML signing certificate in the keystore.
encryptionCertAlias contains the alias of the XML encryption certificate in the keystore.
To enforce what the Java Fedlet service provider encrypts, set the following attributes in the sp-extended.xml file to true:
wantAssertionEncrypted
wantNameIDEncrypted
wantAttributeEncrypted
To enforce what the Java Fedlet service provider signs and wants signed, set the following attributes to true.
wantAuthnRequestsSigned in the idp.xmlfile tells the Java Fedlet what to sign
AuthnRequestsSigned and WantAssertionsSigned in the sp.xml file tells the identity provider what the Java Fedlet plans to sign.
wantArtifactResponseSigned in the sp-extended.xml file tells the Java Fedlet what to sign.
wantPOSTResponseSigned in the sp-extended.xml file
wantLogoutRequestSigned in the sp-extended.xml file
wantLogoutResponseSigned in the sp-extended.xml file
If the identity provider requires signing for specific messages, set the respective attributes to true in the idp-extended.xml file. For example, wantLogoutRequestSigned and wantLogoutResponseSigned.
Note:
If you set attributes in thesp-extended.xml file, convey this information to the identity provider administrator, so that the necessary configuration changes can be made in the identity provider.Restart the Java Fedlet web container.
Import the Java Fedlet sp.xml file into the identity provider.
If you are using an Oracle Identity Federation identity provider, see Section 3.4.2, "Configuring an Oracle Identity Federation Identity Provider for the Java Oracle OpenSSO Fedlet."
The following table describes the Oracle OpenSSO Fedlet Java APIs that you can use in a service provider application.
See Also:
Oracle OpenSSO 8.0 Update 2 Java API Reference in the following documentation collection:http://docs.sun.com/coll/1767.1
The getPolicyDecisionForFedlet method described in the Java API reference is not currently supported.
Table 3-1 Oracle OpenSSO Fedlet Java APIs
| Fedlet Java API | Description |
|---|---|
com.sun.identity.saml2.profile SPACSUtils processResponseForFedlet |
Processes responses from an identity provider to the Java Fedlet service provider application. |
com.sun.identity.saml2.profile AttributeQueryUtil getAttributeMapForFedlet |
Sends the attribute query to the specified attribute authority, validates the response, and returns the attribute map to the Java Fedlet. |
com.sun.identity.saml2.plugins FedletAdapter |
Provides the following methods:
|
|
 Copyright © 2001, 2010, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|