Federation Guides › Legacy Federation Guide › Overview of a CA SiteMinder® Federation Setup › Set Up Relying Party Components

Set Up Relying Party Components

Many of the steps for setting up a Policy Server and Web Agent at the relying party are similar to the steps for the asserting party, with the following exceptions:

• you do not configure consumers, Service Providers, or Resource Partners
• you configure a SAML or WS-Federation authentication scheme at the Policy Server

The following illustration shows the required tasks for the SAML 1.x Consumer, the SAML 2.0 Service Provider, or the WS-Federation Resource Partner.

Note: This procedure assumes that the target resources exist at the relying party website.

Install the Relying Party Policy Server

Install the Policy Server at the relying party site. The Policy Server provides functions such as the federation authentication schemes and the Assertion Generator.

For more information, see the Policy Server Installation Guide and the Policy Server Configuration Guide.

At the relying party, do the following:

1. Install the Policy Server.
2. Set up a policy store.

   Important! If you initialize a new policy store, the Policy Server installer automatically imports the affiliate objects in the ampolicy.smdif file. These objects are necessary for federation. If you use an existing policy store, import the affiliate objects manually. To verify that the import is successful, log in to the Administrative UI and navigate to Policy, Domain, Domains. If the import is successful, you can see the FederationWebServices domain object in the list.

3. Set up a user store and add users permitted to access target resources.

Configure a SAML or WS-Federation Authentication Scheme

At the relying party Policy Server, configure an authentication scheme (artifact, POST profile, SAML 2.0, WS-Federation) for each asserting party.

Important! The name of the partner that you specify for the authentication scheme must match the name of the relying party that you specify at the asserting party.

Specifically:

• For SAML 1.x authentication schemes, the Affiliate Name field of the scheme configuration must match an Affiliate Name for an affiliate object at the producer site.
• For SAML 2.0, the equivalent field is the SP ID, which must match the SP ID at the Identity Provider.
• For WS-Federation, the Resource Partner ID for the scheme configuration must match the Resource Partner ID at the Account Partner.

More Information:

Configure as a SAML 1.x Consumer

Configure a SAML 2.0 Service Provider

Configure CA SiteMinder® as a WS-Federation Resource Partner

Protect Target Resources at the Relying Party

After creating a SAML or WS-Federation authentication scheme, assign the scheme to a unique realm or a single custom realm. The realm is the collection of target resources at the relying party that require an assertion for user access. The relying party identifies target resources in one of the following ways:

• TARGET variable in the intersite transfer URLs (SAML 1.x).
• AuthnRequest URL (SAML 2.0 and WS-Federation).
• Authentication scheme configuration (SAML 2.0 and WS-Federation).

After you create a realm and assign a SAML or WS-Federation authentication scheme to it, create a rule for the realm, then add the rule to a policy that protects the resource.

Install a Web Agent or SPS Federation Gateway (Relying Party)

The Web Agent is a required component in a CA SiteMinder® legacy federation network. You can either install a Web Agent on a web server or install an SPS federation gateway, which has an embedded web agent.

At the relying party, set up the following components:

1. Install one of the following components:
   • Web Agent

     For instructions, see the Web Agent Installation Guide.

   • SPS federation gateway

     For instructions, see the Secure Proxy Server Administration Guide.

2. Configure the Web Agent or SPS federation gateway.

Install a Web or Application Server for the Web Agent Option Pack (Relying Party)

If you are implementing legacy federation with a Web Agent and Web Agent Option Pack (not with an SPS federation gateway), install the Web Agent Option Pack. Install this component on a web or application server.

At the relying party:

1. Install one of the following servers to run Federation Web Services, the application that is installed with the Web Agent Option Pack.
   • Web server running ServletExec
   • WebLogic Application Server
   • WebSphere Application Server
   • JBOSS Application Server
   • Tomcat Application Server
2. Deploy Federation Web Services on these systems.

Install the Web Agent Option Pack at the Relying Party

The Web Agent Option Pack supplies the Federation Web Services application, which is a required component for legacy federation.

At the relying party:

1. Install the Web Agent Option Pack.

   For instructions, see the Web Agent Option Pack Guide.

2. Verify that you install a JDK. The Web Agent Option Pack requires this JDK.

   To determine the required JDK version, go to the Technical Support site and search for CA SiteMinder® Platform Matrix.

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.

Configure Federation Web Services at the Relying Party

These steps enable you to set up the Federation Web Services application. The Federation Web Services application is installed on the server with the Web Agent Option Pack or the SPS federation gateway.

To configure Federation Web Services at the relying party

1. Configure one of the supported application servers to use the Web Agent Option Pack. Refer to the Web Agent Option Pack deployment instructions.

   If you are using the SPS federation gateway, the Federation Web Services application is already deployed.

2. Set the AgentConfigLocation parameter in the AffWebServices.properties file to the full path to the WebAgent.conf file. Verify that the syntax is correct and the path appears on one line in the file.

   The AffWebServices.properties file contains the initialization parameters for Federation Web Services. This file is located in the one of the following directories:

   • web_agent_home/affwebservices/WEB-INF/classes
   • sps_home/secure-proxy/Tomcat/webapps/affwebservices/WEB-INF/classes

   web_agent_home

   Represents the installed location of the Web Agent

   sps_home

   Represents the installed location of the SPS federation gateway

3. Enable error and trace logging for Federation Web Services application. Logging is enabled in the LoggerConfig.properties file. The logs enable you to see the communication between the asserting party and the relying party.
   • Error logging is recorded in the affwebserv.log file, the default error log file.
   • Trace logging is recorded in the FWSTrace.log, the default trace log file.
4. Test Federation Web Services by opening a web browser and entering the following link:

   http://fqhn:port_number/affwebservices/assertionretriever

   fqhn

   Defines the fully qualified host name.

   port_number

   Defines the port number of the server where the Federation Web Services application is installed.

   For example:

   http://myhost.ca.com:81/affwebservices/assertionretriever

   If Federation Web Services is operating correctly, the following message appears:

   Assertion Retrieval Service has been successfully initialized.
   The requested servlet accepts only HTTP POST requests.
   

   This message indicates that Federation Web Services is listening for data activity. If Federation Web Services is not operating correctly, you see a message that the Assertion Retrieval Service has failed. If the test fails, look at the Federation Web Services log.

More Information:

Configure Federation Web Services (Asserting Party)

Allow Access to Federation Web Services (asserting party)

When you install the Policy Server, CA SiteMinder® creates policies for the Federation Web Services (FWS) application. The FWS application is installed with the Web Agent Option Pack. For a few federation features, the relying party needs permission to access the protected FWS service. Adding a relying partner to a policy is a task you do only at the asserting party.

For example, for HTTP-Artifact binding for single sign-on, a policy protects the service from which CA SiteMinder® retrieves an assertion. For CA SiteMinder® to retrieve the assertion for a specific relying partner, that partner must be added as a user to the policy that protects the service.

Grant access to specific FWS policies that apply to features configured for your federation partnership.

Modify the Certificate Data Store for Artifact Single Sign-on (optional)

The certificate data store holds keys and certificates for PKI operations, such as encryption, decryption, signing, verification and client authentication.

If you are implementing artifact single sign-on, the certificate data store at the asserting party holds the certificate authority certificate for establishing an SSL connection. This SSL connection is between the relying party and the asserting party. This SSL connection secures the back channel that the assertion is sent across for artifact single sign-on.

A set of common root CAs is shipped in the certificate data store. To use root CAs for web servers that are not in the data store, import these root CAs.

For detailed information about the certificate data store, see the Policy Server Configuration Guide.

Create Links to Initiate Single Sign-on (optional)

For SAML 2.0 and WS-Federation, if a user visits the relying party before visiting the asserting party, establish hard-coded links. The hard-coded links redirect the user to the asserting party to fetch the authentication context. This authentication context consists of the characteristics that enable the relying party to understand how the user was authenticated.

More Information:

Initiate SAML 2.0 Single Sign-on at the SP (optional)

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

Initiate SAML 2.0 Single Sign-on at the SP (optional)

If a user visits the Service Provider before visiting the Identity Provider, the Service Provider must redirect the user to the Identity Provider. At the Service Provider, create an HTML page that contains hard-coded links to the AuthnRequest Service. The AuthnRequest service, in turn, redirects the user to the Identity Provider to fetch the authentication context.

Note: The HTML page has to reside in an unprotected realm.

The hard-coded link that the user clicks at the Service Provider must contain certain query parameters. These parameters become part of an HTTP GET request to the AuthnRequest service. The AuthnRequest service is on the Policy Server at the Service Provider.

For SAML 2.0 (artifact or profile), the syntax for the link is:

http://sp_server:port/affwebservices/public/saml2authnrequest?ProviderID=IdP_ID

sp_server:port

Specifies the server and port number of the Service Provider hosting the Web Agent Option Pack or the SPS federation gateway.

IdP_ID

Specifies the Identity Provider ID.

You can add the ProtocolBinding query parameter to this link depending on which bindings are enabled. For more information about configuring links at the Service Provider, see Set Up Links at the IdP or SP to Initiate Single Sign-on.

Note: You do not need to HTTP-encode the query parameters.

You can also create links at the Identity Provider.

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

If a user visits the Resource Partner before visiting the Account Partner, the Resource Partner must redirect the user to the Account Partner. Create an HTML page, such as a site selection page that contains links to Account Partners with which to authenticate. Upon selecting a link, the user is directed to the single sign-on service at the Account Partner.

Note: The site selection page has to reside in an unprotected realm.

The hard-coded link that the user clicks at the Resource Partner must contain certain query parameters. These parameters are part of an HTTP GET request to the Single Sign-on Service at the Policy Server of the Account Partner.

The syntax for the link is:

https://host:port/affwebservices/public/wsfedsso?wa=wsignin1.0&wtrealm=RP_ID

host:port

Indicates the server and port number where the single sign-on service resides

RP_ID

Specifies the Resource Partner identity

Note: You do not need to HTTP-encode the query parameters.