Enabling Virtual Federation With OpenSSO, Part 2: A Tutorial

Print-friendly Version

Part 1 of this series introduces OpenSSO's virtual-federation capability and its Secure Attributes Exchange (SAE) component. Here in Part 2, you learn how to configure OpenSSO to federate applications, using those features. Contents   -  Process -  Configuring OpenSSO for Virtual Federation -  Modifying the OpenSSO Application's Shared Secret on the SP -  Testing Virtual Federation With OpenSSO's SAE Sample -  Setting the Advanced Configurations -  Conclusion -  References -  Discussion

OpenSSO is a Sun-sponsored, open-source project that offers core identity capabilities, including security for Web applications, single sign-on (SSO), federation, and identity services. Based on Sun Java System Access Manager, the project is the foundation for Sun OpenSSO Enterprise 8, the commercial release. In addition to working with enterprise-focused standards like SAML 2.0, XACML, and WS-Federation, OpenSSO works with community-based subproject protocols like OpenID and Information Cards.

This article describes end-to-end virtual federation between an identity provider (IdP) application and a service provider (SP) application. However, for real-world deployments, you might choose to configure only one side of the virtual federation (either the IdP side or SP side only). For example, if only the IdP side is set up, the IdP application identity attributes will continue to be sent across to a Security Assertion Markup Language (SAML) 2.0-compliant product on the other end. (The IdP OpenSSO instance sends plain SAML 2.0 "on the wire.") Similarly, an SP-side only deployment is capable of transferring attributes from any SAML 2.0-compliant IdP product to an SP application, by means of the SP-side OpenSSO instance processing the SAML 2.0 assertion.

Figure 1 illustrates how virtual federation and SAE work. For brevity, this example assumes that OpenSSO is running at both the IdP and SP sides, and that SAE is used on either side. The packaged SAE Demo application included with OpenSSO is used as an example.

Figure 1: Process of Virtual Federation and SAE (Click image for larger view.)

The process goes as follows:

1. A user authenticates to the identity provider's (IdP's) application.
   
   Note: Even though OpenSSO can authenticate users, many legacy applications have their own authentication mechanism. To efficiently federate, loosely couple a legacy application with OpenSSO by retaining the former's authentication mechanism and adopting OpenSSO's federation capabilities.
   
   
2. The authenticated user accesses the IdP's application and clicks a link that points to a service provided by another application in a different domain.
   
   
3. Through Secure Attribute Exchange (SAE), the IdP's application assembles the appropriate user attributes (authentication and user data), encodes and signs it with OpenSSO's lightweight virtual-federation library, and posts the now secure attributes to the IdP's local OpenSSO instance.
   
   
4. The IdP's local OpenSSO instance verifies the authenticity of the encoded attributes.
   
   
5. The IdP's local OpenSSO instance initiates the appropriate SAML 2.0 SSO protocol and sends the attributes to the SP. The dispatch is part of the SAML assertion, with only plain SAML 2.0 "on the wire."
   
   Note: To use SAE, however, you must use OpenSSO.
   
   
6. The SP's local OpenSSO instance signs and encodes the attributes with SAE and sends them to the SP's application.
   
   
7. The SP's application verifies and decodes the attributes.
   
   
8. The SP's application serves the user according to the attributes received.
   
   Note: The SP end of the process need not involve SAE. Since the attributes are carried in a SAML assertion, the SP can invoke the requested application through another means, such as an OpenSSO Fedlet. However, SAE is highly recommendable because it seamlessly secures the last-mile transfer of user attributes from the SP's OpenSSO instance to the SP's application.

This section describes how to configure OpenSSO for virtual federation, using the out-of-the-box SAE sample application.

Note: Some of the steps mention the URL protocol://hostname:portnumber/contextroot, where:

• protocol is either http or https.
  
  
• hostname is the fully qualified domain name (FQDN) of the server. Important: Do not specify a numeric IP address or localhost.
  
  
• portnumber is the number of the port on which the Web container is listening.
  
  
• contextroot is the location in which you deployed the OpenSSO.war file in the Web container.

The host names, port numbers, and context roots in the procedures are examples only. Replace them with the real-life names in your environment.

Setting Up Two OpenSSO Instances
First, set up two OpenSSO instances by deploying the OpenSSO.war file and running the Configurator for each of them:

• The first instance, the IdP www.idp.com, is at http://www.idp.com:8888/opensso/.
  
  
• The second instance, the SP www.sp.com, is at http://www.sp.com:7777/opensso/.

Configuring the IdP Instance (Signing, Entities, and Circle of Trust)
Next, follow these steps to configure the IdP instance:

1. Log in to the OpenSSO Administration Console at http://www.idp.com:8888/opensso/UI/Login as amAdmin with the corresponding password you specified while configuring OpenSSO.
   
   Note: Typical real-world deployments are Secure Sockets Layer (SSL)-enabled HTTPS applications. However, for this example, SSL has not been enabled.
   
   The Administration Console is displayed. See Figure 2.
   
   

   Figure 2: OpenSSO Administration Console (Click image for larger view.)

    
   
2. Click Create Hosted Identity Provider under Create SAMLv2 Providers.
   
   The "Create a SAMLv2 Identity Provider on this Server" screen is displayed.
   
   
3. Under Signing Key, choose test from the drop-down menu.
   
   To enforce SAML 2.0 SSO with the browser-based POST profile, you must enable assertion signing by means of a signing key.
   
   
4. Under Circle of Trust, type mycot or a COT name of your choice in the New Circle of Trust text field. Click Configure at the top-right corner. See Figure 3.
   
   

   Figure 3: "Create a SAMLv2 Identity Provider on this Server" Screen (Click image for larger view.)

    
   OpenSSO displays the message: Your Identity Provider has been configured.
   
   
5. Click Finish.

Configuring the SP Instance (Entities and Circle of Trust)
Now configure the SP instance:

1. Log in to the OpenSSO Administration Console at http://www.sp.com:7777/opensso/task/Home as amAdmin.
   
   
2. Click Create Hosted Service Provider under Create SAMLv2 Providers.
   
   
3. Under Signing Key, choose test from the drop-down menu.
   
   
4. Under Circle of Trust, type mycot or a COT name of your choice in the New Circle of Trust field. Click Configure at the top-right corner. See Figure 4.
   
   

   Figure 4: "Create a SAMLv2 Service Provider on this Server" Screen (Click image for larger view.)

    
   OpenSSO displays the message: Service provider is configured. You can modify the provider's profile under the Federation tab. Do you want to create a remote identity provider?
   
   
5. Click Yes.
   
   The Create a SAMLv2 Remote Identity Provider screen is displayed.
   
   
6. In the "URL where metadata is located" text field, type protocol://FQDN:portnumber/contextroot/saml2/jsp/exportmetadata.jsp as your IdP instance. An example is http://www.idp.com:8888/opensso/saml2/jsp/exportmetadata.jsp.
   
   
7. Click Configure at the top-right corner. See Figure 5.
   
   

   Figure 5: "Create a SAMLv2 Service Provider on this Server" Screen (Click image for larger view.)

    
   OpenSSO displays the message: Identity provider is configured. You can modify the provider's profile under the Federation tab.
   
   
8. Click OK.

To double-check that the settings are correct, click the Federation tab and verify that mycot is under Circle of Trust and that the two entities—http://www.idp.com:8888/opensso and http://www.sp.com:7777/opensso—are under Entity Providers.

Configuring the IdP Instance (Remote SP)
Complete the configuration process for the IdP:

1. In the OpenSSO Administration Console, click Register Remote Service Provider under Create SAMLv2 Providers.
   
   
2. In the "URL where metadata is located" text field, type protocol://FQDN:portnumber/contextroot/saml2/jsp/exportmetadata.jsp as your SP instance. An example is http://www.sp.com:7777/opensso/saml2/jsp/exportmetadata.jsp.
   
   
3. Click Configure at the top-right corner. See Figure 6.
   
   

   Figure 6: Create a SAMLv2 Remote Service Provider Screen (Click image for larger view.)

    
   OpenSSO displays the message: Service provider is configured. You can modify the provider's profile under the Federation tab.
   
   
4. Click OK.

To double-check that the settings are correct, click the Federation tab and verify that mycot is under Circle of Trust and that the two entities—the URLs to your IdP and SP instances in the form of protocol://FQDN:portnumber/contextroot—are under Entity Providers.

Configuring the IdP for Virtual Federation
This section shows you how to configure the IdP for virtual federation.

Setting the Realm Attributes

1. Log in to the OpenSSO Administration Console at http://www.idp.com:8888/opensso/UI/Login as amAdmin.
   
   
2. Set the Ignore Profile service attribute:
   
   
   1. Click the Access Control tab.
      
      
   2. Under Realms, click / (Top Level Realm) and then click the Authentication tab, followed by Advanced Properties.
      
      The Core screen for Realm Attributes is displayed.
      
      
   3. Under User Profile, select Ignored.
      
      
   4. Click Save at the top right corner. See Figure 7.
      
      

      Figure 7: Core Screen for Realm Attributes (Click image for larger view.)

       
      
   5. Click Back to Authentication.
      
      
   6. Click Back to Access Control.
   
   
3. Click the Federation tab. Under Entity Providers, click the http://www.idp.com:8888/opensso entity.
   
   
4. Click the Assertion Processing tab.
   
   
5. Under Attribute Mapper, type mail=mail in the New Value text field. Click Add.
   
   
6. Repeat steps 4 and 5 with branch=branch for the New Value text field. Click Save.

Generating the Encoded Password on the IdP

1. Open a new browser window and go to http://www.idp.com:8888/opensso/encode.jsp.
   
   Troubleshooting tip: If you see a No permission error message, it's likely because of a bug in encode.jsp. Log out and log back in as amadmin (all lowercase this time).
   
   
2. Type my-idp-secret in the "Enter the password to encode" text field. Click Encode. See Figure 8.
   
   

   Figure 8: Screen for Password to Encode (Click image for larger view.)

    
   OpenSSO displays the encoded password.
   
   
3. Copy the password and save it for later use.
   
   In our case, the password is AQICWa2eBPG0AIcwxGsZsf60Cp9x9eZmwn8h. The one you generate will be different.

Configuring SAE on the IdP

1. Navigate back to the SAE Configuration tab of the IdP by clicking the Federation tab, followed by www.idp.com and Advanced.
   
   
2. Verify that the IdP URL reads http://www.idp.com:8888/opensso/idpsaehandler/metaAlias/idp.
   
   
3. Under Per Application Security Configuration, type the following string in the New Value text field and then click Add:
   
   url=http://www.idp.com:8888/opensso/samples/saml2/sae/ saeIDPApp.jsp|type=symmetric|secret=AQICWa2eBPG0AIcwxGsZsf60Cp 9x9eZmwn8h
   
   In this string, replace AQICWa2eBPG0AIcwxGsZsf60Cp9x9eZmwn8h with the encoded password you obtained in step 3 in the previous section. See Figure 9.
   
   

   Figure 9: SAE Configuration Screen (Click image for larger view.)

    
   
4. Click Save and then click Back.
   
   
5. Verify that you are still at the Federation tab. If not, click that tab.
   
   
6. Under Entity Providers, click the http://www.sp.com:7777/opensso entity.
   
   
7. In the Request/Response Signing section under Signing and Encryption, verify that Authentication Requests Signed and Assertions Signed are selected. See Figure 10.
   
   

   Figure 10: Signing and Encryption Screen for the SP (Click image for larger view.)

    
   
8. Click Save at the top-right corner.

Specifying the SP's OpenSSO Service Endpoint

1. Click the Advanced tab.
   
   
2. Under SAE Configuration, do the following:
   
   
   1. Type http://www.sp.com:7777/opensso/spsaehandler/metaAlias/sp in the SP URL text field.
      
      The URL points to an SP's OpenSSO service endpoint that can process virtual federation requests.
      
      
   2. Type http://www.sp.com:7777/opensso/samples/saml2/sae/saeSPApp.jsp in the SP Logout URL text field. Click Save. See Figure 11.
      
      

      Figure 11: SAE Configuration Screen for the IdP (Click image for larger view.)

       
      
3. Log out of the OpenSSO Administration Console.

Configuring the SP for Virtual Federation
This section shows you how to configure the SP for virtual federation.

Setting the Realm Attributes

1. Log in to the OpenSSO Administration Console at http://www.sp.com:7777/opensso/UI/Login as amAdmin.
   
   
2. Set the Ignore Profile service attribute:
   
   
   1. Click the Access Control tab.
      
      
   2. Under Realms, click / (Top Level Realm) and then click the Authentication tab, followed by Advanced Properties.
      
      The Core screen for Realm Attributes is displayed.
      
      
   3. Under User Profile, select Ignored.
      
      
   4. Click Save at the top-right corner. See Figure 7.
      
      
   5. Click Back to Authentication.
      
      
   6. Click Back to Access Control.
      
      
3. Click the Federation tab. Under Entity Providers, click the http://www.sp.com:7777/opensso entity.
   
   
4. In the Request/Response Signing section under Signing and Encryption, verify that Authentication Requests Signed and Assertions Signed are selected. Click Save.
   
   
5. Click the Assertion Processing tab.
   
   
6. Under Attribute Mapper, type mail=mail in the New Value text field. Click Add.
   
   
7. Repeat steps 5 and 6 with branch=branch for the New Value text field.
   
   
8. Under Auto Federation, select Enabled and type mail in the Attribute text field. Click Save. See Figure 12.
   
   

   Figure 12: Attribute Mapper Screen (Click image for larger view.)

    

Generating the Encoded Password on the SP

1. Open a new browser window and go to http://www.sp.com:7777/opensso/encode.jsp.
   
   
2. Type my-sp-secret in the "Enter the password to encode" text field. Click Encode. See Figure 8.
   
   OpenSSO displays the encoded password.
   
   
3. Copy the encoded password and save it for later use.
   
   In our case, that password is AQICiEMNe+8E+OsDOH2/eihQa1dWgvn5vstV. The one you generate will be different.

Configuring SAE on the SP

1. Navigate back to the SAE Configuration tab of the IdP by clicking the Federation tab, followed by www.sp.com and Advanced.
   
   
2. Verify that the SP URL reads http://www.sp.com:7777/opensso/spsaehandler/metaAlias/sp.
   
   
3. Type http://www.sp.com:7777/opensso/samples/saml2/sae/saeSPApp.jsp in the SP Logout URL text field.
   
   
4. Under Per Application Security Configuration, type the following string in the New Value text field and then click Add:
   
   url=http://www.sp.com:7777/opensso/samples/saml2/sae/ saeSPApp.jsp|type=symmetric|secret=AQICiEMNe+8E+OsDOH2/ eihQa1dWgvn5vstV
   
   In this string, replace AQICiEMNe+8E+OsDOH2/eihQa1dWgvn5vstV with the encoded password you obtained in step 3 in the previous section. See Figure 13.
   
   

   Figure 13: SAE Configuration Screen for the SP (Click image for larger view.)

    
   
5. Click Save and log out of the OpenSSO Administration Console.

Now modify the OpenSSO application's shared secret on the SP. Later, you'll test the virtual federation-SAE configuration with the SAE sample application in OpenSSO.

To change the secret shared between the SP's OpenSSO instance with the SP application (in this case, saeSPApp.jsp), do the following:

1. On the SP instance, edit the file at deployed-WAR-file-dir/opensso/samples/saml2/sae/saeSPApp.jsp.
   
   
2. Change line 62 from String secret = "secret12"; to String secret = "my-sp-secret";
   
   
3. Save the file.
   
   
4. Restart the application container.

Note: In real-world deployments, be sure to secure and protect the shared secret. For example, store that string in a secured or encrypted text file, or retrieve it from a database on the fly.

For the purposes of the bundled sample, you need not perform the preceding procedure on the IdP's application (saeIDPApp.jsp) because you input the shared secret directly on the Web form.

To test virtual federation with OpenSSO's SAE sample application:

1. Close all your browser instances.
   
   
2. Open a new browser, clear the cookies, and go to http://www.idp.com:8888/opensso/samples/saml2/sae/saeIDPApp.jsp.
   
   
3. Configure the form settings:
   
   
   1. Type http://www.sp.com:7777/opensso/samples/saml2/sae/saeSPApp.jsp in the SP App URL text field.
      
      
   2. Type http://www.idp.com:8888/opensso/idpsaehandler/metaAlias/idp in the "SAE URL on IDP end" text field.
      
      The URL must be in the form of protocol://FQDN:portnumber/contextroot/idpsaehandler/metaAlias/idp for your IdP instance.
      
      
   3. Verify that the "This application's identity" text field reflects the correct URL: http://www.idp.com:8888/opensso/samples/saml2/sae/saeIDPApp.jsp.
      
      The URL must be in the form of protocol://FQDN:portnumber/contextroot/samples/saml2/sae/saeIDPApp.jsp for your IdP instance.
      
      
   4. Choose symmetric from the Crypto Type drop-down menu.
      
      
   5. Type my-idp-secret in the Shared Secret/Private Key Alias text field.
      
      
   6. Deselect the "Use Cached SecureAttrs" instance. See Figure 14.
      
      

      Figure 14: Settings for the SAE Sample Application (Click image for larger view.)

       
   
   
4. Click Generate URL.
   
   OpenSSO confirms the settings. See Figure 15.
   
   

   Figure 15: Confirmation of Settings for the SAE Sample Application (Click image for larger view.)

    
5. Click ssourl.
   
   
6. Verify that your browser URL now reads http://www.sp.com:7777/opensso/samples/saml2/sae/saeSPApp.jsp and that the attributes (Secure Attrs) for the SAE sample are listed, as shown in Figure 16.
   
   

   Figure 16: Attributes in the SAE Sample Application (Click image for larger view.)

    
7. Optional. To capture and view the resulting SAML assertion, increase the logging level:
   
   
   1. Log in to the SP instance as amAdmin.
      
      
   2. Click Configuration, followed by System and Logging.
      
      
   3. Under Logging Level, select the radio box FINE and click Save.
      
      
   4. Repeat steps 1-6 to run the SAE demo application again.
   
   The log file in question is called SAML.access in the OpenSSO-installation-dir/opensso/log directory. In the body of the SAML assertion are the SAE attributes passed from the IdP to the SP. See this example:
   
   

   <saml:AttributeStatement> <saml:Attribute Name=""branch""> <saml:AttributeValue xmlns:xs=""http://www.w3.org/2001/XMLSchema"" xmlns:xsi=""http://www.w3.org/2001/XMLSchema-instance"" xsi:type=""xs:string"">mainbranch</saml:AttributeValue> </saml:Attribute> <saml:Attribute Name=""mail""> <saml:AttributeValue xmlns:xs=""http://www.w3.org/2001/XMLSchema"" xmlns:xsi=""http://www.w3.org/2001/XMLSchema-instance"" xsi:type=""xs:string"">testuser@foo.com</saml:AttributeValue> </saml:Attribute> </saml:AttributeStatement>

    
   

This section describes advanced configurations.

Configuring the IdP to Use the SAML 2 Browser POST Profile
To configure the IdP so that it uses the SAML 2 browser POST profile:

1. On the IdP instance, edit the file deployed-WAR-file-dir/opensso/saml2/jsp/SA_IDP.jsp.
   
   
2. Change line 465 from—
   
   + "&" + SAML2Constants.BINDING + "=" + SAML2Constants.HTTP_ARTIFACT
   
   to—
   
   + "&" + SAML2Constants.BINDING + "=" + SAML2Constants.HTTP_POST
   
   The boldfaced string denotes the original and the revised code.
   
   
3. Save the file.
   
   
4. Restart the application container.
   
   
5. Run the tests in the section Testing Virtual Federation With OpenSSO's SAE Sample again to validate federation with the browser's POST profile.

Extending the SAE Sample Patterns to Your Own Applications
The bundled SAE sample is a good way to verify that you have correctly configured the IdP and SP instances for virtual federation and SAE. However, realization of the true benefits of those capabilities mandates some form of integration with the legacy application to be federated. Integration requires only one step: Simply include the OpenSSO client SDK and import any required classes, such as com.sun.identity.sae.api.SecureAttrs and com.sun.identity.sae.api.Utils. From there, you can code the SAE validation and encode/decode logic right into your federated application!

To customize the IdP:

1. Follow the code in the saeIDPApp.jsp file at deployed-WAR-file-dir/opensso/samples/saml2/sae to package the additional attributes to be secured.
   
   
2. Post to OpenSSO's SAE service URL.

To customize the SP, follow the code in the saeSPApp.jsp file, also at deployed-WAR-filedir/opensso/samples/saml2/sae. That code explains how to retrieve and unpack the secure attributes handed off from OpenSSO after it has validated and consumed the SAML 2 assertion.

OpenSSO's virtual federation capability delivers the ability to federate applications to multiple providers using SAML 2.0 and a single OpenSSO instance. Not only does virtual federation ease first-mile and last-mile integration efforts, it also does so securely with the use of secure attributes exchange. OpenSSO Build 6 will additionally provide encryption support for virtual federation attributes.

• Sun OpenSSO Enterprise
  • Main page
  • Support: Sun OpenSSO Express
  • Project OpenSSO Resource Center
  
  
• Related articles
  • Enabling Virtual Federation With OpenSSO, Part 1: Introduction
  • The Basics of Identity Federation (PDF)
  • From the Trenches at Sun Identity, Part 4: Virtual Federation, a Pioneering Way for Exchanging Data
  • The Fundamentals of Identity Federation
  
  
• Sun developer services
  • Support
  • Training and certification

We welcome your participation in our community. Please keep your comments civil and on point. You can optionally provide your email address to be notified of replies—your information is not used for any other purpose. By submitting a comment, you agree to these Terms of Use.