Previous Topic: Internationalization in Federation Security ServicesNext Topic: SiteMinder Administrative User Interfaces

Federation Security Services Guide › Federation Security Services Overview › Federation Use Cases

Federation Use Cases

There are probably as many use cases for federated networks as there are business arrangements between partners. This section presents use cases that demonstrate different ways of handling user identities to provide single sign-on and single logout between partners.

Use Case 1: Single Sign-on Based on Account Linking

In Use Case 1, smcompany.com contracts with a partner company, ahealthco.com to manage employee health benefits.

An employee of smcompany.com authenticates at an employee portal at his company’s site, www.smcompany.com and clicks a link to view her health benefits at ahealthco.com. The employee is taken to the ahealthco.com web site and is presented with her health benefit information without having to sign on to the website.

The following illustration shows this use case.

Graphic showing SSO based on account linking

The company, ahealthco.com, maintains all health-related information for employees at smcompany.com. To do this, ahealthco.com maintains user identities for every employee of smcompany.com. When an employee of smcompany.com accesses ahealthco.com, an identifier for the employee is passed from smcompany.com to ahealthco.com in a secure manner. This identifier allows ahealthco.com to determine who the user is and the level of access to allow for that user.

Solution 1: Single Sign-on based on Account Linking

Solution 1 illustrates how Federation Security Services can be deployed at smcompany.com and ahealthco.com to solve Use Case 1: Single Sign-on Based on Account Linking.

Graphic showing federation security services deployed at two sites for single sign-on based on account linking

SiteMinder is deployed at both sites. The Web Agent with the Web Agent Option Pack are installed on a webserver system and the Policy Server is installed on another system. The installations are the same for smcompany.com and ahealthco.com.

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.

Solution 1 Using SAML 1.x Artifact Authentication

In this example, smcompany.com is acting as the producer site. When an employee of smcompany.com accesses an employee portal at www.smcompany.com, the sequence of events is as follows:

  1. The Web Agent provides the initial authentication.
  2. When the employee clicks a link at smcompany.com to view the health benefits at ahealthco.com, the link makes a request to the Intersite Transfer Service at www.smcompany.com.
  3. The Intersite Transfer Service calls the assertion generator, which creates a SAML assertion, puts the assertion into the SiteMinder session store. The service returns a SAML artifact.
  4. The Web Agent redirects the user to www.ahealthco.com with the SAML artifact, in accordance with the SAML browser artifact protocol.

Ahealthco.com is acting as the consumer site. The SAML credential collector service handles the redirect request of the SAML artifact. The credential collector is part of the Federation Web Services application at ahealthco.com.

The sequence of events is as follows:

  1. The SAML credential collector calls the SAML artifact authentication scheme to obtain the location of the assertion retrieval service at smcompany.com.
  2. The SAML credential collector calls the assertion retrieval service at www.smcompany.com.
  3. The assertion retrieval service at www.smcompany.com retrieves the assertion from the SiteMinder session store and returns it to the SAML credential collector at ahealthco.com.
  4. The SAML credential collector then passes the assertion to the SAML artifact authentication scheme for validation and session creation. Also, it issues a SiteMinder session cookie to the browser.
  5. The user is allowed access to resources at ahealthco.com based on the policies that are defined at the Policy Server at ahealthco.com. The Web Agent at ahealthco.com enforces the policies.

In this example, the administrator at smcompany.com configures an affiliate for ahealthco.com. The affiliate is configured with an attribute that is a unique ID for the user. This action causes the assertion generator to include that attribute as part of the user profile in a SAML assertion that is created for ahealthco.com.

The administrator at ahealthco.com configures a SAML artifact authentication scheme for smcompany.com. The authentication scheme specifies the location of the assertion retriever service at smcompany.com. The scheme also extracts the unique user ID from the SAML assertion, determines how to search the ahealthco.com user directory for the user record that matches the value from the assertion.

Solution 1 Using SAML 1.x POST Profile

In this example, smcompany.com is acting as the producer site. When an employee of smcompany.com accesses an employee portal at www.smcompany.com, the sequence of events is as follows:

  1. The Web Agent provides the initial authentication.
  2. When the employee clicks a link at www.smcompany.com to view the health benefits at ahealthco.com, the link makes a request to the Intersite Transfer Service at www.smcompany.com.
  3. The Intersite Transfer Service calls the assertion generator, which creates a SAML assertion and signs the SAML response.
  4. The signed response is then placed in an auto-POST HTML form and sent to the browser of the user.
  5. The browser automatically POSTs a form to the Assertion Consumer URL (which is the SAML credential collector), at ahealthco.com. The form contains a SAML response as a form variable.

Ahealthco.com is acting as the consumer site. The SAML credential collector service handles the redirect request with the SAML response. The SAML credential collector that is part of the Federation Web Services at ahealthco.com.

The sequence of events is as follows:

  1. The SAML credential collector calls for the requested target resource at ahealthco.com. The SAML POST profile authentication scheme protects the target resource.
  2. Because the SAML POST profile scheme is protecting the resource, the SAML credential collector decodes the SAML response message.
  3. Using the digitally signed SAML response message as credentials, the SAML credential collector calls the Policy Server at ahealthco.com.
  4. The Policy Server verifies the signature and then authenticates the user using the SAML assertion embedded in the decoded SAML response message. Based on the assertion, the Policy Server lets the user log in.
  5. After the user logs in, the SAML credential collector creates an SMSESSION cookie, places it in the browser of the user, and redirects the user to the target resource at ahealthco.com.
  6. The user is allowed access to resources at ahealthco.com based on policies that are defined at the Policy Serve. The Web Agent enforces the policies.

In this example, the administrator at smcompany.com uses the UI to configure an affiliate object for ahealthco.com. The affiliate is configured with an attribute that is a unique ID for the user. This action causes the assertion generator to include that attribute as part of the user profile in a SAML assertion that is created for ahealthco.com.

The administrator at ahealthco.com configures a SAML POST profile authentication scheme for smcompany.com. The authentication scheme specifies how to extract the unique user ID from the SAML assertion. The scheme also defines how to search the user directory at ahealthco.com for the user record that matches the value from the assertion.

Solution 1 Using SAML 2.0 Artifact Authentication

In this example, smcompany.com is acting as the Identity Provider. When an employee of smcompany.com accesses an employee portal at www.smcompany.com, the sequence of events is as follows:

  1. The Web Agent provides the initial authentication. When the user clicks a link at the Identity Provider, this action is referred to as an unsolicited response at the Identity Provider.
  2. When the employee clicks a link at www.smcompany.com to view the health benefits at ahealthco.com, the link makes a request to the Single Sign-on Service at www.smcompany.com.
  3. The single sign-on service calls the assertion generator creates a SAML assertion, stores the assertion in the SiteMinder session store, and returns a SAML artifact.
  4. The Web Agent redirects the user to ahealthco.com with the SAML artifact, in accordance with the SAML browser artifact protocol.

Ahealthco.com is acting as the Service Provider. One of the components of the Service provider is the Assertion Consumer Service. The Assertion Consumer Service handles the redirect request containing the SAML artifact.

The sequence of events is as follows:

  1. The Assertion Consumer Service calls the SAML 2.0 authentication scheme with HTTP-artifact binding to obtain the location of the artifact resolution service at smcompany.com.
  2. The Assertion Consumer Service calls the artifact resolution service at www.smcompany.com.
  3. The artifact resolution service at www.smcompany.com retrieves the assertion from the session store at smcompany.com and returns it to the artifact resolution service at ahealthco.com.
  4. The Assertion Consumer Service passes the assertion to the SAML 2.0 authentication scheme for validation and session creation. The service issues a SiteMinder session cookie to the browser.
  5. The user is allowed access to resources at ahealthco.com based on policies that are defined at the Policy Server at ahealthco.com. The Web Agent at ahealthco.com enforces the policies.

In this example, the administrator at smcompany.com configures a Service Provider object for ahealthco.com. The Service Provider is configured with an attribute that is a unique ID for the user. This action causes the assertion generator to include that attribute as part of the user profile in an assertion that is created for ahealthco.com.

The administrator at ahealthco.com configures a SAML 2.0 authentication scheme that uses the artifact binding for smcompany.com. The authentication scheme has the following information:

Solution 1 Using SAML 2.0 POST Binding

In this example, smcompany.com is acting as the Identity Provider. When an employee of smcompany.com accesses an employee portal at www.smcompany.com, the sequence of events is as follows:

  1. The Web Agent provides the initial authentication. When the user clicks a link at the Identity Provider, this action is referred to as an unsolicited response at the Identity Provider.
  2. When the employee clicks a link at www.smcompany.com to view the health benefits at ahealthco.com, the link makes a request to the Single Sign-on Service at www.smcompany.com.
  3. The Single Sign-on Service passes calls the assertion generator, which creates a SAML assertion and signs the SAML response.
  4. The signed response is then placed in an auto-POST HTML form and sent to the browser of the user.
  5. The browser automatically POSTs a form to the Assertion Consumer URL at ahealthco.com. The form contains a SAML response as a form variable.

Ahealthco.com is acting as the Service Provider. The Assertion Consumer Service handles the redirect request with the SAML response. The service is part of the Federation Web Services at ahealthco.com.

The sequence of events is as follows:

  1. The Assertion Consumer Service calls for the requested target resource at ahealthco.com. The SAML 2.0 authentication scheme protects this resource using the HTTP-POST binding.
  2. Because the SAML 2.0 authentication scheme is protecting the resource, the Assertion Consumer Service passes the digitally signed SAML response message as credentials, to the Policy Server at ahealthco.com.
  3. The Policy Server verifies the signature and then authenticates the user using the SAML assertion embedded in the decoded SAML response message. Based on the assertion, the Policy Server lets the user log in.
  4. After the user logs in, the Assertion Consumer Service creates an SMSESSION cookie, places it in the browser of the user, and redirects the user to the target resource at ahealthco.com.
  5. The user is allowed access to resources at ahealthco.com based on policies that are defined at the Policy Server. The Web Agent enforces the policies.

In this example, the administrator at smcompany.com configures a Service Provider object for ahealthco.com. The Service Provider is configured with an attribute that is a unique ID for the user. This action causes the assertion generator to include that attribute as part of the user profile in a SAML assertion that is created for ahealthco.com.

The administrator at ahealthco.com configures a SAML 2.0 authentication scheme with the HTTP-POST binding for smcompany.com. The authentication scheme has the following information:

Solution 1 Using WS-Federation Passive Requestor Profile

In this example, smcompany.com is acting as the Account Partner. When an employee of smcompany.com accesses an employee portal at www.smcompany.com, the sequence of events is as follows:

  1. The user visits an unprotected site selection page at ahealthco.com.
  2. This link points to the Single Sign-on Service at the Account Partner, www.smcompany.com. The Web Agent provides the initial authentication.
  3. The Single Sign-on Service calls the WS-Federation Assertion Generator, which creates a SAML 1.1 assertion. WS-Federation Assertion Generator signs the assertion and wraps the assertion in a security token response message.
  4. The response is then placed in an auto-POST HTML form as a form variable and sent to the browser of the user.
  5. The browser automatically POSTs a form to the Security Token Consumer Service URL at ahealthco.com.

Ahealthco.com is acting as the Resource Partner. The Security Token Consumer Service handles the redirect request with the SAML response. The service is part of the Federation Web Services application.

The sequence of events is as follows:

  1. The Security Token Consumer Service calls for the requested target resource at ahealthco.com. The WS-Federation authentication scheme protects this resource.
  2. Because the WS-Federation authentication scheme is protecting the resource, the Security Token Consumer Service passes the signed assertion as credentials to the Policy Server at ahealthco.com.
  3. The Policy Server verifies the signature and then authenticates the user using the SAML assertion embedded in the decoded SAML response message. Based on the assertion, the Policy Server lets the user log in.
  4. After the user logs in, the Security Token Consumer Service creates an SMSESSION cookie. The service then places the cookie in the browser and redirects the user to the target resource at ahealthco.com.
  5. The user is allowed access to resources at ahealthco.com based on policies that are defined at the Policy Server. The Web Agent enforces the policies.

In this example, the administrator at smcompany.com configures a Resource Partner object for ahealthco.com. The Resource Partner is configured to include an attribute in the assertion that is a unique ID for the user. The assertion generator includes that attribute in the SAML assertion for ahealthco.com.

The administrator at ahealthco.com configures a WS-Federation authentication scheme for smcompany.com. The authentication scheme has the following information:

Use Case 2: Single Sign-on Based on User Attribute Profiles

In Use Case 2, smcompany.com buys parts from a partner named partsco.com.

An engineer authenticates at the employee portal, smcompany.com and clicks a link to access information at partsco.com. Being an engineer at smcompany.com, the user is taken directly to the Specifications portion of the partsco.com website without having to log in.

Graphic of single sign-on based on user attributes

When a buyer for smcompany.com authenticates and clicks a link for partsco.com, the buyer is taken directly to the Parts List portion of the partsco.com website. The buyer does not have to log in.

Additional attributes, such as the user name are passed from smcompany.com to partsco.com to personalize the interface for the individual user.

Partsco.com does not want to maintain user identities for all employees at smcompany.com, but the company wants to control access to sensitive portions of the website. To control the access, partsco.com maintains a limited number of profile identities for users at smcompany.com. One profile identity is maintained for engineers and one profile identity is maintained for buyers.

When an employee of smcompany.com accesses partsco.com, smcompany.com sends user attributes in a secure manner to partsco.com. Partsco.com uses the attributes to determine what profile identity controls access.

Solution 2: Single Sign-on based on User Attribute Profiles

Solution 2 shows how Federation Security Services can be deployed at smcompany.com and partsco.com to solve Use Case 2: Single Sign-on Based on User Attribute Profiles.

Graphic showing a SSO Solution Based on User Attribute Profiles

SiteMinder is deployed at both sites. The interactions between the user and each site is similar, where partsco.com is acting as the relying party.

The following illustration is similar for SAML 1.x, SAML 2.0, and WS-Federation; however, the Federation Web Services components are different as follows:

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 configuration is similar to Solution 1: Single Sign-on based on Account Linking, except for the following items:

Use Case 3: Single Sign-on with No Local User Account

In Use Case 3, smcompany.com offers employee discounts by establishing a partnership with discounts.com.

An employee of smcompany.com authenticates at smcompany.com and clicks a link to access discounts.com. The employee is taken to the discounts.com website and presented with the discounts available for smcompany.com employees, without logging in to the discounts.com website.

The following illustration shows this use case.

Graphic of single sign-on with no local user account

Discounts.com does not maintain any identities for smcompany.com. The company allows all employees of smcompany.com to access discounts .com as long as long as they have been authenticated at smcompany.com. When an employee of smcompany.com accesses discounts.com, authentication information is sent in a secure manner from smcompany.com to discounts.com. This information is used to allow access to discounts.com.

Additional attributes, such as the user name are passed from smcompany.com to discounts.com to personalize the interface for the individual user.

Solution 3: Single Sign-on with no Local User Account

Solution 3 shows how SiteMinder Federation Security Services can be deployed at smcompany.com and discounts.com to solve Use Case 3: Single Sign-on with No Local User Account.

SiteMinder is deployed at smcompany.com by installing the Web Agent with the Web Agent Option pack on one system, and installing the Policy Server on another system. The SAML Affiliate Agent is installed at discounts.com.

Note: The SAML Affiliate Agent only supports SAML 1.0 and is not FIPS-compatible.

The following figure shows single sign-on with no local user account.

Graphic showing a SSO solution with No Local User Account

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.

Smcompany.com is acting as a SAML 1.x producer. When an employee of smcompany.com accesses an employee portal at www.smcompany.com, the following process occurs:

  1. The Web Agent provides the initial authentication.
  2. When the employee clicks a link at www.smcompany.com to access deals at discounts.com, the link makes a request to the Web Agent at www.smcompany.com.
  3. The Web Agent at www.smcompany.com calls the assertion generator. The assertion generator creates a SAML assertion and stores the assertion in the SiteMinder session store. Finally, smcompany.com returns a SAML artifact to discounts.com.
  4. The Web Agent redirects the user to www.discounts.com with the SAML artifact in accordance with the SAML browser artifact protocol.

Discounts.com is acting as the consumer site. The SAML Affiliate Agent at www.discounts.com handles the redirect request with the SAML artifact, as follows:

  1. The SAML Affiliate Agent obtains the location of the assertion retrieval service at www.smcompany.com from a configuration file.
  2. The SAML Affiliate Agent calls the assertion retrieval service at www.smcompany.com.
  3. The assertion retrieval service at www.smcompany.com retrieves the assertion from the SiteMinder session store and returns it to the SAML affiliate agent at www.discounts.com.
  4. The SAML Affiliate Agent then validates the SAML assertion and issues a SiteMinder affiliate session cookie to the browser.
  5. The user is allowed access to resources at discounts.com.

The administrator at smcompany.com uses the Policy Server User Interface to configure an affiliate for discounts.com. The affiliate is configured to include attributes in the assertion. The assertion generator includes the attributes in the SAML assertion it creates for discounts.com.

The administrator at discounts.com configures the SAML Affiliate Agent with information about the discounts.com site, the location of the assertion retriever service at smcompany.com, and the resources the affiliate protects.

Use Case 4: Extended Networks

In Use Case 4, smcompany.com, ahealthco.com, and discounts.com all participate in an extended federated network. This case is an extension of the previous use cases.

Graphic showing an example of an extended federated network

In this network, not all customers of ahealthco.com work at smcompany.com. Ahealthco.com provides discounts only to its customers by establishing a relationship between themselves and discounts.com. Ahealthco.com maintains user identities for every customer so ahealthco.com manages local credentials, such as a password for each user. By managing local credentials, ahealthco.com can authenticate users and can provide single sign-on access to its partners.

In this extended network, the users access each website differently:

Solution 4: Extended Networks

Solution 4 illustrates how Federation Security Services can be deployed at smcompany.com, ahealthco.com, and discounts.com to solve Use Case 4: Extended Networks.

The following illustration shows an extended network. SAML 1.x is the protocol in use.

Graphic showing an Extended Network Solution

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.

SiteMinder is deployed at smcompany.com and ahealthco.com. At each site, the Web Agent and Web Agent Option Pack is installed on one system and the Policy Server on another system. The SAML Affiliate Agent is installed at discounts.com.

In Solution 4:

The administrator for smcompany.com has configured two entities in an affiliate domain, which represents ahealthco.com and discounts.com. These sites are configured in a similar manner as in Examples 1 and 3 described previously, but the configurations have been extended as follows:

Use Case 5: Single Logout

In Use Case 5, an employee of smcompany.com authenticates at an employee portal, smcompany.com, and selects a link to view the health benefits at ahealthco.com. The employee is taken to the ahealthco.com website and presented with the health benefit information without logging in to the site.

After the employee logs out from ahealthco.com, the site wants to verify the termination of the user session at ahealthco.com and at smcompany.com. Terminating both sessions prevents an unauthorized employee from using the existing session to access resources at smcompany.com or to view benefits of the authorized employee.

Note: The initial logout can occur at smcompany.com and result in both sessions being terminated.

The following illustration shows the use case.

Graphic of how a single logout ends the user session at two websites

Solution 5: Single Logout (SAML 2.0)

Solution 5 illustrates how federation can be employed to solve Use Case 5: Single Logout.

In this solution:

The following figure shows the SiteMinder solution for single logout.

Graphic showing the solution for single logout

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 sequence of events is as follows:

  1. Employee performs single sign-on between smcompany.com and ahealthco.com. Smcompany.com places information about ahealthco.com in its session store. Ahealthco.com places information about smcompany.com in its session store.
  2. After the employee has finished reviewing health benefits, the employee clicks a log out link at the Service Provider. The browser accesses the single logout servlet at the Service Provider.
  3. The user session is terminated from the session store at the Service Provider.

    Note: The termination does not remove the session from the session store; it sets the state to LogoutInProgress.

  4. Based on information in the session store, the session is identified as one that an assertion from the Identity Provider, smcompany.com creates.
  5. The browser is forwarded to the single logout servlet at smcompany.com, the Identity Provider, with the logout request message as a query parameter.
  6. The Identity Provider invalidates the user session from all Service Providers that are associated with that user session, other than ahealthco.com, who initiated the logout request. After all Service Providers confirm the logout, the Identity Provider removes the user session from its session store.

    Note: Other Service Providers are not identified in the illustration.

  7. The Identity Provider returns a logout response message to ahealthco.com, the initiating Service Provider, and the user session is removed from the session store.
  8. The user is finally sent to a logout confirmation page at ahealthco.com.

Terminating both sessions prevents an unauthorized employee from using the existing session to view benefits of the authorized employee.

Use Case 6: WS-Federation Signout

In Use Case 6, an employee of smcompany.com authenticates at the employee portal. The employee then selects a link to view health benefits at ahealthco.com. The employee is taken to the ahealthco.com website and presented with the health benefit information without having to sign on to the site.

When the employee logs out from ahealthco.com, ahealthco.com wants the user session at ahealthco.com and the session at smcompany.com terminated. Terminating both sessions helps ensure that an unauthorized employee cannot use the existing sessions to access resources at smcompany.com or to view benefits of the authorized employee.

The following illustration shows the use case.

usecase_single_logout

Solution 6: WS-Federation Signout

Solution 6 illustrates how federation solves Use Case 6: WS-Federation Signout.

In this solution:

WS-Federation signout is enabled at the Account Partner and the Resource Partner.

The following figure illustrates WS-Federation sign-out.

Graphic showing a WS-Federation signout solution

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 sequence of events is as follows:

  1. An employee authenticates at smcompany.com and then access their health benefits at ahealthco.com without having to log in. Federated single sign-on is configured between smcompany.com and ahealthco.com. During the transaction, smcompany.com places information about ahealthco.com in its session store. Ahealthco.com places information about smcompany.com in its session store.
  2. The employee the health benefit information and clicks a logout link at ahealthco.com. The link calls the signout servlet at smcompany.com.
  3. The session of the user is terminated from the session store of the Account Partner. All references to Resource Partners for that user are also removed from the session store.
  4. The Account Provider retrieves a SignoutConfirm JSP page, which includes a Signout Cleanup URLs for each Resource Partner.

    The SignoutConfirm page generates a frame-based HTML page with each frame containing a signoutcleanup URL for each Resource Partner that is associated with the user session.

  5. The browser of the user then accesses the signout Cleanup URL at ahealthco.com and the session of the user is removed from the session store.
  6. The browser of the user is finally sent back to the Account Partner.

Steps 4-6 are repeated for each Resource Partner simultaneously for complete signout for that user session.

Use Case 7: Identity Provider Discovery Profile

In Use Case 7, several companies contract health benefits from ahealthco.com. When a user requests logs on to ahealthco.com to view their health benefits, ahealthco.com must determine which Identity Provider it sends an authentication request to for a particular user.

IdP discovery is useful in federated networks that have more than one partner providing assertions. It provides a dynamic way for a Service Provider to determine which Identity Provider it sends authentication requests for a particular user.

The following illustration shows a network with the Identity Provider Discovery profile in use.

Graphic showing an IdP discovery use case

A user arrives at ahealthco.com. This health provider determines where to send the authentication request. For User1, smcompany.com is where this user authenticates, so this company is set in the common domain cookie at ahealthco.com. For another user, forwardinc.com is an Identity Provider where a user authenticates. Forwardinc.com is set in the common domain cookie at ahealthco.com also.

A prior business agreement between the sites in this network exists so that all sites interact with the Identity Provider Discovery service.

Solution 7: Identity Provider Discovery Profile (SAML 2.0)

Solution 7 illustrates how SiteMinder Federation Security Services can solve Use Case 7: Identity Provider Discovery Profile.

In this solution:

The following illustration shows the federated network for this solution.

Graphic showing an Identity Provider Discovery Solution

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 sequence of events is as follows:

  1. User 1 initially authenticates at smcompany.com and then logs in to ahealthco.com without having to reauthenticate.

    An agreement exists between smcompany.com and ahealthcoIPD.com to use ahealthcoIPD.com as the IPD service. During the initial authentication process, the Identity Provider URL of smcompany.com is written to the common domain cookie at the IPD service.

  2. User 1, now successfully logged on to ahealthco.com, can look at the health benefits.
  3. User 1 then comes to a site selection page at ahealthco.com. A common domain cookie is set for smcompany.com and ahealthco.com is configured to use the IPD service. As a result, ahealthco.com knows that the user previously logged in to smcompany.com. Therefore, ahealthco.com makes the appropriate links available to the user so that user can go back to smcompany.com to log in.

Use Case 8: Multi-protocol Support

In Use Case 8, smcompany.com issues assertions for ahealthco.com and discounts.com. Ahealthco.com uses SAML 2.0 for User1 to communicate between smcompany.com and ahealthco.com. Discounts.com uses SAML 1.0 for User2 to communicate between smcompany.com and discounts.com. The assertions must be suitable for the protocol that the SP uses to consume the assertion.

The following illustration shows the multiprotocol use case.

Graphic showing how a user can communicate with three websites with multi-protocol support

Solution 8: Multi-protocol Network

Solution 8 illustrates how SiteMinder Federation Security Services can solve Use Case 8: Multi-protocol Support.

In this solution:

The following illustration shows a SiteMinder federated network that implements multiprotocol support.

Graphic showing a multi-protocol network solution

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.

In this multiprotocol solution, smcompany.com can issue a SAML 2.0 assertion for User 1 to access resources at ahealthco.com. Additionally, smcompany.com can issue a SAML 1.0 assertion for User 2 to authenticate at discounts.com. Smcompany.com issues an assertion that is based on the session cookie that is set during initial authentication and determines the appropriate protocol for the assertion.

Configure the SAML Affiliate Agent at discounts.com. The smcompany.com is added to its producer information settings in its AffiliateConfig.xml configuration file so that it accepts SAML 1.0 assertions from this site.

Use Case 9: SAML 2.0 User Authorization Based on a User Attribute

In Use Case 9, sitemindercars.com is a car rental service.

A customer of sitemindercars.com logs in and authenticates at sitemindercars.com, then clicks a link to get a quote for a car rental. The customer has a customer profile at this site that includes the frequent flyer number of the customer with exampleair.com. The frequent flyer number of the customer miles determine a certain status level at sitemindercars.com, which offers the customer discounts on car rentals.

The following illustration shows this use case.

Graphic showing an authorization with user attributes

SiteMindercars.com wants to authorize its customers and present the appropriate discount information. The discount information is based on the frequent flyer number of the customer. The company does not want customers having to log in and authenticate at exampleair.com.

Solution 9: SAML 2.0 User Authorization Based on a User Attribute

Solution 9 shows how SiteMinder Federation Security Services can be deployed at sitemindercars.com and exampleair.com to solve Use Case 9: SAML 2.0 User Authorization Based on a User Attribute.

Note: This solution is only for SAML 2.0.

Graphic showing user authorization based on a user attribute

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.

SiteMinder is deployed at both sites. The Web Agent with the Web Agent Option Pack is installed on one system and the Policy Server with Federation Security Services on another system. The installations are the same for both sites.

Sitemindercars.com is a Service Provider acting as a SAML Requester. When a customer logs in at this site, the sequence of events is as follows:

  1. The user logs in to sitemindercars.com and the Web Agent provides the authentication.
  2. When the user clicks a link to rent a car, the Web Agent first makes a request to the Policy Server at the local site.
  3. The Policy Server evaluates the policy expression and identifies unresolved federation attribute variables. The Policy Server tries to resolve the variable by looking up the user in the user directory. The Policy Server looks in the directory associated with the policy protecting the requested URL.
  4. The local Policy Server cannot resolve the user attribute variable. The Policy Server locates the NameID configuration for the Attribute Authority, Exampleair.com.
  5. The Policy Server sends an <AttributeQuery> containing the NameID and the frequent flyer attribute to the Exampleair.com, which is acting as the Attribute Authority.
  6. Exampleair.com returns a response to sitemindercars.com that contains an attribute assertion which includes the requested attribute.
  7. The SAML Requester resolves the variables and evaluates the policy expression, returning authorization status to the Web Agent.
  8. The Web Agent allows access to the appropriate resource.

Use Case 10: SAML 2.0 Single Sign-on with No Name ID at the IdP

In Use Case 10, discounts.com purchases widgets from smwidgets.com.

A buyer for discounts.com clicks on a link to access the latest widget price list at smwidgets.com. The buyer is taken to the smwidgets.com website and presented with the price list without having to log in to the discounts.com website.

The following illustration shows this use case.

Graphic showing SSO when there is no User ID at IdP

A buyer at discounts.com wants the price list at smwidgets.com There are no buyer identities stored locally, so discounts.com wants to obtain an identity for the buyer at smwidgets.com. Discounts.com sends an authentication request to smwidgets.com. When smwidgets.com receives the request, it generates a unique persistent identity for the buyer and adds this identity to the assertion. Discounts.com uses this unique identifier to authenticate the user and allow the buyer access to the requested resource.

Solution 10: Single Sign-on with No Name ID at the IdP

Solution 10 shows how SiteMinder Federation Security Services can be deployed at smcompany.com and discounts.com to solve Use Case 10: SAML 2.0 Single Sign-on with No Name ID at the IdP.

SiteMinder is deployed at discounts.com and smwidgets.com. A Web Agent and Web Agent Option pack is installed on one system, and the Policy Server with Federation Security Services is installed on another system.

In the following illustration, smwidgets.com is acting as the Identity Provider and discounts.com is acting as the Service Provider.

Graphic showing a SSO solution with no user ID at the Identity Provider

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.

For single sign-on between the two sites, where there is no federated user identity at the Identity Provider, the sequence of events is as follows:

  1. The user clicks on a link at discounts.com to proceed to the target site. This link initiates a call to the local Policy Server to generate an authentication request. In this request, an optional attribute named AllowCreate has been included, based on the configuration of the SAML 2.0 authentication scheme at the Service Provider.
  2. The Federation Web Services application at the local Web Agent redirects the request to the Single Sign-on service at the IdP, smwidgets.com.
  3. The request is then forwarded to the IdP Policy Server, which generates an assertion. During assertion generation, the Policy Server searches for the attribute associated with the user requesting access. For example, the telephone number attribute can be requested as the value of the Name ID.

    If the Policy Server cannot find a value for the telephone number attribute, it verifies its configuration for the AllowCreate option. If this option is configured, the Policy Server searches the authentication request from the Service Provider to see if the AllowCreate option exists.

    If the Allow/Create feature is enabled at both sites, the Policy Server generates a new identifier for the user attribute. The Policy Server places that identifier in its user store.

    Note: The identifier is the value of the user attribute.

  4. The assertion is returned in a response message to the IdP Web Agent (FWS). The IdP returns a form to the browser containing the response, the Assertion Consumer URL, and the javascript to submit the form.
  5. The form is posted to the Assertion Consumer Service at the Service Provider. The Service Provider uses the response message to log in to the Policy Server, using the response as credentials.
  6. The Service Provider at smwidgets.com validates the credential by looking for the attribute in its user store. Assuming that it finds the user, the user is logged in by the SAML authentication scheme.
  7. The SP Web Agent creates an SMSESSION cookie for the smwidgets.com domain. The Agent places the cookie in the browser and redirects the user to the target destination.

Use Case 11: SAML Artifact SSO Using Security Zones

In use case 11, CompanyA, the producer site, wants to protect Web Agent applications and federated partner resources. The protocols that CompanyA uses for federated single sign-on are the SAML 2.0 artifact profile and SAML 2.0 single logoff.

For federated resources, a persistent user session is required because the SAML artifact profile stores assertions in the session store at the producer-side Policy Server. Consequently, calls are made to the session store to retrieve the assertion, impacting performance.

The following illustration shows a producer site that combines a federated environment and a web application environment.

Graphic showing a producer site that combines a federated environment and a web application environment

Solution 11: SAML Artifact SSO Using Security Zones

Solution 11 illustrates how you can set up a parallel web application and federation environments to solve Use Case 11.

A security zone is a segment of a single cookie domain, which is used as a method of partitioning applications. You can assign different security requirements to each zone. Producer-side Web Agents that protect requested federated resources enforce security zones. SiteMinder security zones eliminate the need for a persistent user session to be associated with every request for HTTP-Artifact protected applications.

The following figure illustrates a deployment that uses two different SiteMinder environments at a single asserting party. One SiteMinder environment is for federation functionality and the other is for web application protection.

Graphic showing the Federation Solution with SiteMinder Security Zones

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 figure reflects the following set up:

Web application environment

Agent Configuration Object or Local Configuration File

Trusted Security Zones

Cookies Read by the Web Agent for the Zone

DefaultAgent

SM (default)--primary zone

The DefaultAgent configuration enables the Web Agent to read and write the default session cookie, SMSESSION.

Federation Environment

Agent Configuration Object or Local Configuration File

Trusted Security Zones

Cookies Read by the Web Agent for the Zone

FedWA

used by the Web Agent

FED--primary zone

SM--additionally accepted zone

The FedWA configuration enables the Web Agent to read and write SESSIONSIGNOUT cookies, and read SMSESSION cookies.

FedFWS

used by the FWS application

FED--primary zone only

Configures the FWS to read and write SESSIONSIGNOUT cookies.

All resources protected in the web application environment use non-persistent user sessions. As a result, when users are authenticated and authorized, the SMSESSION cookie contains a non-persistent user session specification. The non-persistent session specification helps ensure that requests to web applications do not incur the performance penalty of calling the session store.

When the Web Agent in the federation environment receives a request, this request is directed to the Authentication URL to establish a user session. The user making the request already has an SMSESSION cookie from the prior authentication in the web application environment. However, the user has no SESSIONSIGNOUT cookie.

The Web Agent in the federation environment writes a SESSIONSIGNOUT cookie. The SESSIONSIGNOUT cookie has a persistent user session specification and it uses the same session ID as the SMSESSION cookie. This persistent user session protects the Authentication URL, which authenticates users federating to a partner site.

The Web Agent in the federation environment reads the SMSESSION cookie and writes a SESSIONSIGNOUT cookie in accordance with the security zones associated with the FedWA configuration.

The Federation Web Services application in the federation environment reads the SESSIONSIGNOUT cookie. Because the cookie contains a persistent user session, a call to the session store is not necessary. The Federation Web Services application successfully processes the federation request that requires a persistent user session.

Use Case 12: SAML 2.0 SSO Using Attributes from a Web Application

In use case 12, an Identity Provider, IdPA.com, wants to include web application attributes in an assertion. This use case is only applicable to SAML 2.0 deployments.

For this use case, single sign-on can be initiated at the Identity Provider or the Service Provider. The profiles that IdPA.com uses is SAML 2.0 (POST and Artifact) and WS-Federation.

The following figure shows an example of this use case.

Graphic showing an attribute extracted from a web application and used for single sign-on

IdP-initiated Single Sign-on with Web Application Attributes

IdPA.com has a web application that allows access to protected resources at its business partner SPB.com. When the customer logs in at IdPA.com, they select a link for the business partner. The user is sent to the web application, where they are prompted to enter a customer ID. IdPA.com must send this information to SPB.com so that the customer is permitted access to the requested resource.

SP-initiated Single Sign-on with Web Application Attributes

A customer selects a link at SPB.com, the Service Provider. This link is for protected resources, so the customer is redirected to IdpA.com to be authenticated. After the customer successfully authenticates at IdPA.com, the IdP redirects the customer to the web application where the customer provides specific user information. Upon submitting the information, the customer is returned to SPB.com to complete single sign-on for the requested resource.

Solution 12: SSO with Attributes from a Web Application

Solution 12 shows how SiteMinder Federation Security Services can be deployed at IdPA.com and SPB.com to solve Use Case 12.

SiteMinder is deployed at both sites. At each site, the Web Agent and the Web Agent Option pack are installed on one system, and the Policy Server is installed on another system.

In the following illustration, IdPA.com is the Identity Provider and SPB.com is the Service Provider and single sign-on is initiated at the Identity Provider.

Graphic showing a SSO solution with attributes from a web application

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.

For IdP-initiated single sign-on, the sequence of events is

  1. At the IdP, the user clicks the web page link and one of the following actions occurs:

    Note: After the user is locally authenticated at the IdP, the user is never redirected to the Authentication URL if the session is valid.

  2. The web application prompts the user supplies the requested information. These attributes are posted to the SSO Service.

    Important! The web application must maintain and POST the SMPORTALSTATE query parameter and the collected attributes back to the SSO Service.

  3. The SSO service processes the SAML request and unpacks the data from the SMPORTALSTATE parameter. The service takes this data with the attributes from the web application and passes all the POST data to the assertion generator.
  4. The Assertion Generator creates the assertion.

    Important! The SSO Service makes all the attributes available to the Assertion Generator. Write and configure the assertion generator plug-in to add the attributes to the assertion.

  5. After the IdP generates the assertion, the IdP redirects the user to the Assertion Consumer Service at the Service Provider. The Service Provider processes the assertion.
  6. The user gains access to the requested resource at the Service Provider.

For SP-initiated single sign-on:

  1. At the SP, the user clicks on a link and an AuthnRequest is sent to the Single Sign-on (SSO) service at the Identity Provider.

    Note: In the SP-initiated single sign-on, the request must arrive at the SSO service directly from the SP, as the SAML specification requires. The user cannot go directly to the web application.

  2. At the IdP, the SSO service recognizes that the user does not have a session. The user is redirected to the Authentication URL to authenticate and establish a session. After the user establishes a session, the IdP redirects the user back to the SSO service. An application URL defined for the SSO service instructs the SSO service to return the user to a custom web application.

    Important! When the user is directed to the SSO Service, several query parameters (SPID, ProtocolBinding, RelayState) are included with the original request. The SSO service groups this query data into one query parameter named SMPORTALSTATE, and then redirects the user (through a GET) to the web application.

  3. The web application prompts the user to supply the requested information. These attributes are posted to the SSO Service.

    Important! The web application must maintain and POST the SMPORTALSTATE query parameter and the collected attributes back to the SSO Service.

  4. The SSO service processes the SAML request and unpacks the data from the SMPORTALSTATE parameter. The service takes the data and the attributes from the web application and passes all the POST data to the assertion generator.
  5. The IdP generates the assertion and includes all the attributes. The IdP redirects the user to the Assertion Consumer Service at the Service Provider, where the assertion is processed.

    Note: Write and configure an assertion generator plug-in to add the attributes to the assertion.

  6. The user gains access to the requested resource at the Service Provider.
Configure SSO with Attributes from a Web Application

Configuring single sign-on based on attributes from a web application, requires specific steps.

Follow these steps:

  1. Create a custom web application for the IdP in your network. This custom application can prompt the user for as many attributes as required. Conversely, the application can supply standard attributes and not prompt the user for any information. How attributes are gathered is entirely dependent on how the custom application is written.

    Important! For IdP-initiated single sign-on, if the user is directed to the web application before the SSO service, the web application must include the parameter AllowApplicationPost=yes. The SSO service accepts the post as long as the application includes the AllowApplicationPost parameter.

    The SiteMinder Web Agent Option Pack comes with sample JSP applications that you can use as a basis for your custom web application. The path to the sample JSP applications is: web_agent_home/affwebservices/. The sample applications are:

    sample_application.jsp

    This sample application can be used for IdP- or SP-initiated single sign-on. The user is first directed to the SSO Service and then sent to the custom web application. This application can be entered for the Application URL in the Service Provider Properties (SAML 2.0) dialog or the Resource Provider Properties (WS-Federation) dialog.

    unsolicited_application.jsp

    This sample application can be used for IdP-initiated single sign-on. The user is sent directly to the web application and not to the SSO Service. The application assumes that the user is already authenticated at the Identity Provider.

    Note: This file shows how to use the AllowApplicationPost parameter in an application.

  2. (Optional) If the user is initially directed to the IdP SSO service:
    1. Specify an Application URL in the SAML 2.0 authentication scheme.
    2. Configure the Assertion Generator plug-in to add the attributes to the assertion.
  3. (Optional) If the user is sent directly to the custom web application from the IdP, you do not have to provide a value for the Application URL parameter. However, write and configure the assertion generator plug-in to work with SiteMinder. See the Programming Guide for Java for information about creating an assertion generator plug-in.

Note: The order of the procedure steps is provided as a guideline. You can perform these steps in a different order.

More information:

Enable the Assertion Generator Plug-in (SAML 2.0)

Use Case 13: SSO with Dynamic Account Linking at the SP

In Use Case 13, the IdP, discounts.com, includes an attribute named buyerID that identifies a particular user and is included in an assertion. When the assertion is sent to the Service Provider, smwidgets.com, the same attribute does not exist in the user record at the Service Provider. The Service Provider must create an attribute in the appropriate user record so that the user can authenticate and gain access to the protected resource.

An employee of discounts.com selects a link to access the latest price list on widgets at smwidgets.com. The employee logs in with the name and buyer ID.

The following illustration shows this use case.

Graphic of use case for user with no mapped ID

The identity that is based on the buyer ID of the user is created at discounts.com and placed in the assertion. The buyer ID value is entered as the NameID in the assertion. However, there is no mapped identity at smwidgets.com for the buyer ID. The administrator at the Service Provider establishes a mapping. The mapping has to use dynamic account linking so that smwidgets can authenticate the employee and can allow the employee access to the price list.

Solution 13: SAML 2.0 SSO with Dynamic Account Linking at the SP

Solution 13 shows how SiteMinder Federation Security Services can be deployed at IdPA.com and SPB.com to solve Use Case 13.

Note: Dynamic account linking is only supported with SAML 2.0.

SiteMinder is deployed at both sites. Each site has a Web Agent and Web Agent Option Pack installed on one system, and the Policy Server on another system.

The following illustration shows single sign-on with dynamic account linking at the Service Provider.

Graphic of SAML 2.0 SSO with dynamic account linking at the SP

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 order of events for this solution is

  1. The employee initially logs in and authenticates at discounts.com. Discounts.com creates an assertion for the employee. Discounts.com posts the assertion (POST binding) or redirects the user with an artifact (artifact binding) to the Assertion Consumer Service at smwidgets.com. This assertion includes an attribute named buyerID.
  2. The Assertion Consumer Service at smwidgets.com tries to authenticate the user with the SAML authentication scheme. However, the buyerID attribute of the employee does not map to a local user record so the authentication fails.
  3. As part of the SAML authentication scheme at the SP, a redirect URL is defined, which points to the directory web_agent_home/affwebservices/linkaccount.jsp. The employee is redirected to this URL.

    Note: The linkaccount.jsp file must be part of a protected realm. The default location for this file is http://sp_home/affwebservices/public/. Copy the file from this location to a protected realm.

  4. A Web Agent that authenticates the local user with the forms authentication scheme protects this linkaccount.jsp URL. After a successful authentication, a SiteMinder session at smwidgets.com is established and an SMSESSION cookie is placed in the browser of the employee.
  5. The linkacount.jsp gets loaded in the browser and the user sees a message to permit the link to the SP account. Click on the button to permit the account linking.
  6. The user is redirected to the Assertion Consumer Service, where the browser of the employee presents the SMSESSION cookie with the assertion.
  7. The Assertion Consumer Service extracts the NameID from the assertion and inserts the NameID value into a newly created buyerID attribute. The buyerID attribute is in the existing user record of the employee. The Assertion Consumer Service knows which user record to map because the UserDN in the SMSESSION cookie identifies the user.

    The search specification configured in the SAML 2.0 authentication scheme indicates which attribute is mapped to the NameID. In this case, the search specification is buyerID=%s.

  8. After the attribute is mapped, the SAML authentication scheme authenticates the user that is based on the assertion and establishes a new user session.

    The next time that the same user presents an assertion with the buyer ID, the user successfully gains access to the requested resource.

Configure SAML 2.0 SSO with Dynamic Account Linking at the SP

Configure several components at the Service Provider to enable SAML 2.0 single sign-on with dynamic account linking:

Enable dynamic account linking for POST or Artifact single sign-on at the Service Provider

Follow these steps:

  1. For the linkaccount.jsp file, do the following:
  2. Enable the Allow/Create feature at the Service Provider.
  3. For the Web Agent at the Service Provider, set the POST Preservation parameter to yes. This setting enables the POST data from the SAML response to be preserved.
  4. Configure a redirect URL that sends the user to the linkaccount.jsp file if authentication fails. Direct the user only to this file.

    The redirect URL is part of the SAML 2.0 authentication scheme setup at the Service Provider.

    Complete the following fields with the values shown:

    Redirect URL for the User Not Found Status

    http://sp_home/protected_realm/linkaccount.jsp

    Example: http://smwidgets.com/partner_resources/linkaccount.jsp

    The default location of the linkaccount.jsp file is http://sp_home/affwebservices/public/. Copy the file from this directory to a directory that is configured as a protected realm.

    Mode

    HTTP POST

  5. Configure a search specification for the SAML authentication scheme. For example, if the Name ID from the assertion replaces buyerID, the search specification would be buyerID=%s.

More information:

Use Case 13: SSO with Dynamic Account Linking at the SP

Allow the Identity Provider to Assign a Value for the NameID

Permit the Creation of a Name Identifier for SSO

Look Up User Records for SAML 2.0 Authentication

Locate User Records for Authentication