Federation Guides › Legacy Federation Guide › Configure SiteMinder as a WS-Federation Resource Partner

Configure SiteMinder as a WS-Federation Resource Partner

This section contains the following topics:

Prerequisites for a Relying Partner

How to Configure a Resource Partner

WS-Federation Authentication Scheme Overview

Select the WS-Federation Authentication Scheme Type

Specify the General Information for the WS-Fed Auth Scheme

Locate User Records for Authentication

Configure WS-Federation Single Sign-on at the Resource Partner

Implement WS-Federation Signout

Create a Custom WS-Federation Authentication Scheme

Customize Assertion Processing with the Message Consumer Plug-in

Redirect Users After Failed WS-Federation Authentication Attempts

Supply SAML Attributes as HTTP Headers

How To Protect a Target Resource with a WS-Federation Authentication Scheme

Prerequisites for a Relying Partner

For SiteMinder to act as the relying partner, complete following tasks:

• Install the Policy Server.
• Install one of the following components:
  • The Web Agent and the Web Agent Option Pack. The Web Agent authenticates users and establishes a session. The Option Pack provides the Federation Web Services application. Be sure to deploy the FWS application on the appropriate system in your network.
  • The SPS federation gateway, which has an embedded Web Agent and has the Federation Web Services application on the embedded Tomcat web server.

  For more information, see the Web Agent Option Pack Guide.

• Private keys and certificates are imported for functions that require verification and encrypting of messages.
• An asserting partner is set up within the federated network.

How to Configure a Resource Partner

Configuring a WS-Federation Resource Partner requires the following tasks:

1. Complete the SAML 1.x authentication scheme prerequisites.
2. Select the authentication scheme type and assign it a name.
3. Specify the namespace for users being authenticated with the SAML 1.x authentication scheme.
4. Select the single sign-on profile that this consumer supports (artifact or POST).

Configure a SAML authentication scheme for each Account Partner that is a federation partner and generates assertions. Bind each scheme to a realm, which includes the URLs of the target resources that users request. You can do this task on a per Account Partner basis or can create a single custom authentication scheme and single realm. Protect these resources with a SiteMinder policy.

Tips:

• Certain parameter values at the Account Partner and Resource Partner must match for the configuration to work. A list of those parameters is available in Configuration Settings that Must Use the Same Values.
• Verify that you are using the correct URLs for the Federation Web Services servlets. The URLs are listed in Federation Web Services URLs Used in SiteMinder Configuration.

Optional Configuration Tasks for a Resource Partner

The optional tasks for configuring a Resource Partner include:

• Customize assertions using the Message Consumer Plug-in.
• Redirect failed authentication attempts.

Navigating Legacy Federation Dialogs

The Administrative UI provides two ways to navigate to the legacy federation configuration dialogs.

You can navigate in one of two ways:

• Following a wizard to configure a new legacy federation object.

  When you create an object, a page displays with a configuration wizard. Follow the steps in the configuration wizard to create the object.

  

• Selecting tabs to modify an existing legacy federation object.

  When you modify an existing object, a page displays with a series of tabs. Modify the configuration from these tabs. These tabs are the same as the steps in the configuration wizard.

  

WS-Federation Authentication Scheme Overview

Any SiteMinder site, or SPS Federation Gateway, can consume a <RequestSecurityTokenResponse> message and can use the assertion in the response to authenticate and authorize users. If sites in your federated network have user stores, you can use WS-Federation authentication.

The WS-Federation authentication scheme lets a Resource Partner authenticate a user. The authentication scheme enables cross-domain single sign-on by consuming a SAML assertion and establishing a SiteMinder session. After the user is identified, the Resource Partner site can authorize the user for specific resources.

A site can be both a WS-Federation Resource Partner and Account Partner.

Note: The SPS federation gateway can replace the Web Agent and Web Agent Option Pack to provide the Federation Web Services application functions. For information about installing and configuring the SPS federation gateway, see the Secure Proxy Server Administration Guide.

The WS-Federation authentication scheme is configured at the Resource Partner-side Policy Server. The WS-Federation Security Token Consumer Service invokes the authentication scheme. The Security Token Consumer Service is a component of the Federation Web Services application and is installed on the Resource Partner-side Web Agent. This service obtains information from the WS-Federation authentication scheme at the Policy Server. FWS uses that information to extract the necessary information from the assertion to authenticate a user.

The SAML assertion becomes the user credentials to log in to the Policy Server at the Resource Partner site. The user is authenticated and authorized, and if authorization is successful, the user is redirected to the target resource.

Select the WS-Federation Authentication Scheme Type

The WS-Federation authentication scheme provides information about the Account Partner that generates the assertion for the Resource Partner. The authentication scheme specifies how the Resource Partner supports the authentication process.

After you configure an authentication scheme, associate the scheme with a realm that contains the resource you want to protect.

To configure a WS-Federation authentication scheme

1. Navigate to Infrastructure, Authentication, Authentication Schemes.

   The Create Authentication Scheme dialog opens.

2. From the Authentication Scheme Type drop-down list, select WS-Federation Template.

   The contents of the Authentication Scheme dialog change for the scheme.

   Note: Click Help for descriptions of settings and controls, including their respective requirements and limits.

After you select the authentication scheme template, you can configure the details of the authentication scheme. You access the rest of the configuration dialogs by clicking WS-Federation Configuration.

More Information:

How To Protect a Target Resource with a WS-Federation Authentication Scheme

Specify the General Information for the WS-Fed Auth Scheme

Identity the Resource Partner and the Account Partner in the General settings for the WS-Federation authentication schemes.

Follow these steps:

1. From the main authentication scheme page, click WS-Federation Configuration.

   If you are modifying an existing scheme, click Modify then WS-Federation Configuration.

   The detailed settings for the scheme display.

2. In the General settings, complete the required fields.
3. Verify that the Disable Signature Processing option is set appropriately for single sign-on.

   Important! For debugging purposes only, you can temporarily disable all signature processing (both signing and verification of signatures) by enabling the Disable Signature Processing option.

The general configuration is complete.

Locate User Records for Authentication

When you configure an authentication scheme, you define a way for the authentication scheme to look up a user in the local user store. After the correct user is located, the system generates a session for that user. Locating the user in the user store is the process of disambiguation. How SiteMinder disambiguates a user depends on the configuration of the authentication scheme.

For successful disambiguation, the authentication scheme first determines a LoginID from the assertion. By default, the LoginID is extracted from the Name ID value in the assertion. You can also obtain the LoginID by specifying an Xpath query.

After the authentication scheme determines the LoginID, SiteMinder checks if a search specification is configured for the authentication scheme. If no search specification is defined for the authentication scheme, the LoginID is passed to the Policy Server. The Policy Server uses the LoginID together with the user store search specification to locate the user. For example, imagine that the LoginID value is Username and the LDAP search specification is set to the uid attribute. The Policy Server uses the uid value (Username=uid) to search for the user.

If a search specification is configured for the authentication scheme, the LoginID is not passed to the Policy Server. Instead, the search specification is used to locate a user.

The disambiguation process involves two steps:

1. Obtain the LoginID by the default behavior or by using an Xpath query.
2. Locate the user in the user store by the default behavior or with a search specification.

Note: The use of Xpath and the search specification are optional.

Obtain a LoginID for a WS-Federation User

You can find the LoginID in two ways:

• Relying on the default behavior, where the LoginID is extracted from the NameID in the assertion. This option requires no configuration.
• Using an Xpath query to find the LoginID in place of the default behavior.

To specify an Xpath query

1. Navigate to the authentication scheme for the Resource Partner you are configuring.
2. Select WS-Federation Configuration, SAML Profiles. Click Modify first if you are modifying an existing scheme.

   The SAML Profiles dialog opens.

3. In the User Disambiguation section, enter an Xpath query that the authentication scheme uses to obtain a LoginID, then click OK.

   Xpath queries must not contain namespace prefixes. The following example is an invalid Xpath query:

   /saml:Response/saml:Assertion/saml:AuthenticationStatement/
   saml:Subject/saml:NameIdentifier/text()
   

   The valid Xpath query is:

   //Response/Assertion/AuthenticationStatement/Subject/
   

   NameIdentifier/text()

Use a Search Specification to Locate a WS-Federation User

You can use a search specification to locate the user in place of the default behavior, where the LoginID is passed to the Policy Server.

To locate a user with a search specification

1. Navigate to the authentication scheme for the Resource Partner you are configuring.
2. Select WS-Federation Configuration, SAML Profiles. Click Modify first if you are modifying an existing scheme.

   The SAML Profiles dialog opens.

3. In the User Disambiguation section, enter a search specification in the appropriate namespace field. The search specification defines the attribute that the authentication scheme uses to search a namespace. Use %s in the entry as a variable representing the LoginID.

   For example, the LoginID has a value of user1. If you specify Username=%s in the Search Specification field, the resulting string is Username=user1. This string is verified against the user store to find the correct record for authentication.

4. Click OK.