Sun OpenSSO Enterprise 8.0 Administration Guide

ID-FF Federation Operations

This section describes Federation operations that are specific to the ID-FF protocol.

The Pre-Login URL

The pre-login process is the entry point for applications participating in Liberty-based single sign-on. The principal would be redirected to the location defined by the pre-login URL if no OpenSSO Enterprise session token is found. This default process, though, can be modified based on the values of query parameters passed to OpenSSO Enterprise by the service provider within a URL.

A query parameter is a name/value pair appended to the end of a URL. The parameter starts with a question mark (?) and takes the form name=value. A number of parameters can be combined in one URL; when more than one parameter exists, they are separated by an ampersand (&). Use the format http://hostname:port/deploy-uri/preLogin?metaAlias=metaAlias. Additional parameters are appended to the URL as &param1=value1&param2=value2 and so on. These parameters and their usage and values are described in the following table.

Table 8–1 Pre-login URL Parameters for Federation

Parameter 

Description 

actionOnNoFedCookie

The actionOnNoFedCookie parameter provides the flexibility to redirect a user when the fedCookie is not present in the browser, and when there is only one identity provider. It takes the following values:

  • commonlogin will redirect to a common login page.

  • locallogin will redirect to the local OpenSSO Enterprise login page.

  • passive will issue a request to the identity provider by setting the isPassive parameter of the AuthnRequest element to true.

  • active will issue a normal single sign-on request to the identity provider.

anonymousOnetime

The anonymousOnetime parameter can be used by service providers that authenticate users with anonymous, one time federation sessions. A value of true enables the service provider to issue a one time federation request and generate an anonymous session after successful verification of the authentication assertion from the identity provider. This feature is useful when the service provider doesn't have a user repository (for example, http://www.weather.com) but would like to depend on an identity provider for authentication. When the service provider receives a successful authentication assertion from an identity provider, they would generate an anonymous, temporary session.

authlevel

The authlevel parameter takes as a value a positive number that maps to an authentication level defined in the OpenSSO Enterprise Authentication Framework. The authentication level indicates how much to trust a method of authentication.

In this framework, each service provider is configured with a default authentication context (preferred method of authentication). However, the provider might like to change the assigned authentication context to one that is based on the defined authentication level. For example, provider B would like to generate a local session with an authentication level of 3 so it requests the identity provider to authenticate the user with an authentication context assigned that level. The value of this query parameter determines the authentication context to be used by the identity provider. 

goto

The goto parameter takes as a value a URL to which the principal will be redirected after a successful SSO. If the value is not specified, default redirection will occur based on the value of the Provider Home Page URL attribute defined in the service provider configuration. The value of this URL can be configured by changing the iplanet-am-provider-homepage-url attribute in the amProviderConfig.xml file.

gotoOnFedCookieNo

The gotoOnFedCookieNo parameter takes as a value a URL to which the principal is redirected if a fedCookie with a value of no is found. The default behavior is to redirect the user to the OpenSSO Enterprise login page.

In order to modify the pre-login URL, edit the relevant properties in either the AMConfig.properties file or the AMAgent.properties file, dependent on your deployment.

ProcedureTo Configure for Pre-login

In a federation setup, OpenSSO Enterprise acts as a service provider and manages an application that runs on a separate instance of Sun Java System Web Server. You must configure the agent that is protecting this application as follows:

  1. Point the com.sun.am.policy.loginURL property in the AMAgent.properties file to the pre-login service URL running on OpenSSO Enterprise.

    For example: com.sun.am.policy.loginURL = http://www.sp1.com:58080/opensso/preLogin?metaAlias=www.sp1.com

  2. Point the com.sun.am.policy.am.library.loginURL in the AMAgent.properties file to the login URL of the instance of OpenSSO Enterprise acting as the service provider.

    For example: com.sun.am.policy.am.library.loginURL = http://www.sp1.com:58080/opensso/UI/Login

ProcedureTo Configure for Global Logout

To implement the logout process for all service providers using the Liberty Logout method, do the following:

  1. Copy the AMClient.properties file to the service provider's web container.

  2. Revise the Logout method, as follows:

    ResourceBundle rsbu =ResourceBundle.getBundle("AMClient"); String logouturl = rsbu.getString ("com.sun.identity.federation.client.samples.logoutURL"); response.sendRedirect(logouturl);

    This revision is equivalent to a redirection to http://www.sp1.com:58080/opensso/liberty-logout?metaAlias=www.sp1.com.

Configuring ID-FF Single Sign-on

To setup single sign-on between two OpenSSO Enterprise instances for ID-FF protocol, one as an identity provider and one as a service provider, follow these steps:

ProcedureTo Configure ID-FF Single Sign-on

  1. Create an ID-FF identity provider. For instructions, see To Create an ID-FF Entity Provider.

  2. Export the standard identity provider metadata into an XML file using the ssoadm command's export-entity subcommand. The example filename for these instructions is IDP.xml.

  3. Create an ID-FF service provider. For instructions, see To Create an ID-FF Entity Provider


    Note –

    If the identity provider and service provider reside in the same domain, you need to modify the cookie name of one instance to be different from the other. To do so, log in to the OpenSSO Enterprise and go to Configuration>Servers and Sites, then choose the server instance. Click the Security>Inheritance Settings, and uncheck the Cookie Name field. Click Save.

    Click Back to Server Profile, go to the Cookie section, and modify the value for Cookie Name. Click Save. Restart the web container.


  4. Export the standard identity provider metadata into an XML file using the ssoadm command's export-entity subcommand. The example filename for these instructions is SP.xml.

  5. Load the remote service provider metadata to the OpenSSO Enterprise instance of the identity provider. To do so:

    1. Copy the SP.xml file to the identity provider instance.

    2. Log in to the console on the identity provider instance and click on the Federation tab.

    3. Click the Import Entity button.

    4. Choose the realm to which the identity provider resides.

    5. Select the File option and click upload to locate the SP.xml file. You can leave the extended metadata field blank.

  6. In the Federation tab, create a circle of trust and add the identity provider and service provider. For instructions, see To Create a New Circle of Trust.

  7. Load the identity provider metadata to the OpenSSO Enterprise instance of the service provider. To do so:

    1. Copy the IDP.xml file to the identity provider instance.

    2. Log in to the console on the identity provider instance and click on the Federation tab.

    3. Click the Import Entity button.

    4. Choose the realm to which the identity provider resides.

    5. Select the File option and click upload to locate the IDP.xml file. You can leave the extended metadata field blank.

  8. In the Federation tab, create a circle of trust and add the identity provider and service provider. For instructions, see To Create a New Circle of Trust.

    Single Sign-on is now established between the OpenSSO Enterprise instances.

ID-FF Auto-Federation

The auto-federation feature in OpenSSO Enterprise will automatically federate a user's disparate provider accounts based on a common attribute. This common attribute will be exchanged in a single sign-on assertion so that the consuming service provider can identify the user and create account federations. If auto-federation is enabled and it is deemed that a user at provider A and a user at provider B have the same value for the defined common attribute (for example, emailaddress), the two accounts will be federated automatically without principal interaction on the service provider side (that is, without login on the service provider side).


Note –

Auto-federating a principal's two distinct accounts at two different providers requires each provider to have agreed to implement support for this functionality beforehand.


ProcedureTo Enable ID-FF Auto Federation

Ensure that single sign-on is properly configured. For more information, see To Configure ID-FF Single Sign-on. Remote providers would not be configured in your deployment.

  1. In the OpenSSO Enterprise Console, click the Federation tab.

  2. Select the name of the identity provider to edit its profile.

  3. Click on the Auto Federation link at the top of the page, or scroll down to the Auto Federation subsection.

  4. Enable Auto Federation by checking the box.

  5. Type a value for the Auto Federation Common Attribute Name attribute.

    For example, enter emailaddress or userID. You should be sure that each participating user profile (at both providers) has a value for this attribute.

  6. Click the Identity Provider Attribute Mapper link, or scroll down to the Identity Provider Attribute Mapper subsection. Enter the following attribute values:

    Attribute Mapper Class

    com.sun.identity.federation.services.FSDefaultRealmAttributeMapper

    Identity Provider Attribute Mapping

    Enter the mapping for the Auto-Federation attribute name.

  7. Click the Plug-ins link, or scroll down to the Plug-ins subsection. Enter the following attribute value:

    Attribute Statement Plug-in

    com.sun.identity.federation.services.FSDefaultRealmAttributePlugin

  8. Click Save to complete the identity provider configuration.

  9. Go back to the Federation tab and select the service provider you wish to edit.

  10. Click on the Auto Federation link at the top of the page, or scroll down to the Auto Federation subsection.

  11. Enable Auto Federation by checking the box.

  12. Type a value for the Auto Federation Common Attribute Name attribute.

    For example, enter emailaddress or userID. You should be sure that each participating user profile (at both providers) has a value for this attribute.

  13. Click the Service Provider Attribute Mapper link, or scroll down to the Service Provider Attribute Mapper subsection. Enter the following attribute values:

    Attribute Mapper Class

    com.sun.identity.federation.services.FSDefaultRealmAttributeMapper

    Identity Provider Attribute Mapping

    Enter the mapping for the Auto-Federation attribute name.

  14. Click Save to complete the configuration.

Enabling ID-FF XML Signing

By default, ID-FF singing is turned off. To enable ID-FF XML signing on OpenSSO Enterprise server, see the following section:

ProcedureTo Enable ID-FF XML Signing

  1. Login to the console as the top-level administrator.

  2. Select the Configuration tab, select Global, and then Liberty ID-FF Service Configuration.

  3. Select YES for the XML Signing On attribute and save the configuration.

  4. Go to the Federation tab and select the service provider and/or identity provider that needs to be enabled.

  5. Under the Common Attributes section, make sure a signing certificate alias is chosen for the provider. Otherwise, you must enter your certification alias.

    If the certificate alias is added or changed, you need to send the new metadata (to be exported using ssoadm CLI) to the remote party to update its metadata.

  6. Click Save.

  7. Restart the server.

Dynamic Identity Provider Proxying

An identity provider that is asked to authenticate a principal that has already been authenticated with another identity provider may proxy the authentication request, on behalf of the requesting service provider, to the authenticating identity provider. This is called dynamic identity provider proxying. When the first identity provider (referred as Proxying Identity Provider) receives an authentication request regarding a principal, it prepares a new authentication assertion on its own behalf by referencing the relevant information from the original assertion and sending the assertion to the authenticating identity provider. After receiving the Assertion from the authenticating identity provider, the proxying identity provider generates a new Assertion based on the information from the original Assertion, and sends to the requesting service provider.


Note –

The service provider requesting authentication may control this proxy behavior by setting a list of preferred identity providers or by defining the amount of times the identity provider can proxy the request.


ProcedureTo Configure and Test Dynamic Identity Provider Proxying

The following steps describe the procedure to enable three machines for identity provider proxying and test the configuration. The procedure assumes the three machines have OpenSSO Enterprise installed and are configured as follows:

Machine 

Authentication Function 

Federation Function 

Machine 1 

Authenticating Identity Provider 

Identity Provider 

Machine 2 

Proxying Identity Provider 

Identity Provider and Service Provider 

Machine 3 

Requesting Service Provider 

Service Provider 

  1. Install and configure three OpenSSO instances.

    If those three instances resides on the same domain, you need to modify the cookie name of all three instances to be different from one another. To do so:

    1. Login to administration console and click the Configuration tab.

    2. Click Servers and Sites and choose your server instance.

    3. Click the Security tab, then click Inheritance Settings.

    4. Uncheck the box for the Cookie Name attribute.

    5. Click Save.

    6. Click the Back to Server Profile button.

    7. Modify the value for the Cookie Name attribute under the Cookie section.

    8. Click Save.

    9. Restart the web container on which the server instance is deployed.

  2. Create hosted ID-FF metadata on the requesting service provider instance on machine 3.

    For more information, see ID-FF Entity Provider. When creating the provider:

    1. Enter the service provider entity ID in the Entity Identifier field

    2. Under the Service Provider section, specify meta alias, signing/encryption cert alias if needed.

  3. Export the requesting Service Provider's standard metadata to a XML file. This could be done using the export-entity option in ssoadm CLI or the ssoadm.jsp. The rest of these steps use the file name sp.xml as an example.

  4. Create hosted metadata on the proxying Identity provider instance, o machine 2.

    1. Login to machine 2 as the top-level administrator, click Federation, then click New under Entity Providers table.

    2. Select IDFF in the pop up window

    3. Save the configuration.

    4. Enter the entity ID in the Entity Identifier field.

    5. Under the Identity Provider section, specify a meta alias, and enter signing/encryption cert alias if needed.

    6. Under the Service Provider section, specify a meta alias different from that entered for Identity Provider section, and enter signing/encryption cert alias if needed.

    7. Click create.

  5. Export the proxying identity provider's standard metadata to a XML file. This is done using the export-entity option in ssoadm CLI or ssoadm.jsp. The rest of these steps use the file name proxy.xml as an example.

  6. Create the hosted metadata on the authenticating Identity provider instance, machine 1.

    For more information, see ID-FF Entity Provider. When creating the provider:

    1. Enter the service provider entity ID in the Entity Identifier field

    2. Under the Service Provider section, specify meta alias, signing/encryption cert alias if needed.

  7. Export the authenticating Identity provider's standard metadata to a XML file using the export-entity option in the ssoadm CLI or by using the ssoadm.jsp. The rest of these steps use the file name idp.xml as an example.

  8. Load the remote proxying identity provider metadata on the requesting service provider instance.

    1. Copy the proxy.xml to machine 3.

    2. In the console of machine 3, click the Federation tab and then the Import Entity button.

    3. Choose the realm to which the requesting service provider belongs.

    4. Under Where Does the Meta Data File Reside field, choose File and click Upload.

    5. Choose proxy.xml. The Where Does the Extended Data File Reside can be left blank.

    6. Click Ok.

  9. Create a circle of trust on the requesting service provider instance to include the proxying IDP and requesting SP entity. For information, see Circle of Trust.

  10. Load the remote authenticating identity provider and requesting service provider metadata to the proxying identity provider instance.

    1. Copy the idp.xml and sp.xml files to machine 2.

    2. In the console of machine 2, click the Federation tab and then the Import Entity button.

    3. Choose the realm to which the requesting service provider belongs.

    4. Under Where Does the Meta Data File Reside field, choose File and click Upload.

    5. Choose idp.xml. The Where Does the Extended Data File Reside field can be left blank.

    6. Click OK.

    7. Repeat the steps for loading the requesting service provider meta data (sp.xml).

  11. Create circles of trust on the proxying identity provider instance, machine 2. For information, see Circle of Trust

    Add the requesting service provider and proxying identity provider to the circle of trust. Repeat this step to create a circle of trust for both the authenticating identity provider and the proxying identity provider. Make sure the circles of trust have different names.

  12. Load the remote proxying identity provider metadata on the authenticating identity provider instance, machine 1.

    1. Copy the proxy.xml to machine 1.

    2. In the console of machine 1, click the Federation tab and then the Import Entity button.

    3. Choose the realm to which the requesting service provider belongs.

    4. Under Where Does the Extended Data File Reside field, choose File and click Upload.

    5. Choose proxy.xml. The Where Does the Extended Data File Reside can be left blank.

    6. Click Ok.

  13. Create a create a circle of trust on the authenticating identity provider instance to include the proxying identity provider and authenticating identity provider entities.

  14. Enable Dynamic Identity provider proxying on the requesting service provider instance.

    1. In the console of machine 3, click the Federation tab.

    2. Select the hosted requesting service provider.

    3. Go to Proxy Authentication Configuration.

    4. Check the box for Proxy Authentication to enable it.

    5. Enter 10 for the value in the Maximum Number of Proxies attribute.

    6. Click Save.

  15. Enable dynamic identity provider proxying on the proxying identity provider instance.

    1. In the console of machine 2, click the Federation tab.

    2. Select the hosted proxying identity provider.

    3. Go to Proxy Authentication Configuration.

    4. Check the box for Proxy Authentication to enable it.

    5. Enter 10 for the value in the Maximum Number of Proxies attribute.

    6. Add the authenticating identity provider's entity ID in the Proxy Identity Providers List file.

    7. Click Save.

  16. Federate a user between machine 3 (acting as a service provider) and machine 2 (acting as an identity provider).

  17. Federate a user between machine 2 (acting as a service provider) and machine 1 (acting as an identity provider).

  18. Close the browser and attempt to perform a single sign-on again from machine 3. You will be redirected to machine 1 rather than machine 2 for authentication.

    Enter the username and password used on machine 1. You will have a successful single sign-on to machine 3.