Web Agent Guides › Web Agent Configuration Guide › Single Sign-On (SSO) › How to Configure Single Sign-On

How to Configure Single Sign-On

To set up your single sign-on environment, follow these steps:

1. Decide which cookie domains you want in your single sign-on environment.
2. Select a cookie domain within your single sign-on environment (from Step 1) to act as the cookie provider domain.
3. If your agents use central configuration, open the Agent Configuration Object (using the Administrative UI). For agents using local configuration, open the Web Agent configuration file (on each web server).
4. For your agent that is the cookie provider, modify the configuration parameters as shown in the following steps:
   1. Restrict the cookie provider functions for better security.
   2. Prevent cookie provider replay attacks.
   3. Verify that the value of the RequireCookies parameter is yes.
   4. (Optional) If you want the cookies to remain valid until the configured session timeout, enable persistent cookies. Without persistent cookies, the browser cookies are transient. Transient cookies remain valid for only one browser session.
   5. Verify that the value of the CookieDomain parameter specifies the local cookie domain of the system on which the agent is installed.
   6. To validate IP addresses, set one of the following parameters:
      • If you are using persistent cookies, set the PersistentIPCheck parameter.
      • If you are using transient cookies, set the TransientIPCheck parameter.
5. (Optional) Modify any of the following single sign-on parameter settings:
   • Modify the session update period.
   • Set secure cookies across multiple domains.
   • Ignore the cookie provider for unprotected resources.
   • Ignore the cookie provider for POST requests.
   • Configure Secure URLs with single sign-on.
6. For all other agents in your SSO environment that (all agents that are not a cookie provider) set the configuration parameters as shown in the following steps:
   1. Set the value of the CookieProvider parameter to the name of your cookie provider domain. Use the fully qualified domain name of the web server hosting the agent which is acting as the cookie provider.

      Use the syntax shown in the following example:

      http://server.example.com:port/siteminderagent/SmMakeCookie.ccc

      Note: The cookie provider name requires the .ccc extension, as shown in the previous example.

   2. Disable the cookie provider functions for better security.
7. If you edited parameters by modifying the agent configuration file, restart the web server, so that the changes take effect.

Restrict Cookie Provider Functions

All agents have cookie-provider functions that are enabled by default. Unauthorized users with stolen CA SiteMinder® SSO cookies could exploit cookie providers and attempt to use a session cookie from one domain to forge session cookies in another cookie domain. These forged session cookies could allow unauthorized access to protected SSO domains.

You can eliminate the potential for stolen SSO cookies to exploit cookie providers and forge session cookies with the following parameter:

LimitCookieProvider

Specifies how the CA SiteMinder® agent acting as a cookie provider handles cookie provider SET requests (.ccc resources). When the value of this parameter is yes, the SET request is ignored unless a cookie exists in the domain of the cookie provider. The cookie provider redirects the user to the TARGET URL without setting a new cookie. When the value of this parameter is no, the SET request is processed and a new cookie is always set during the redirect back to the TARGET URL.

Default: No.

Default: (after using smpolicy-secure.xml to create your Policy Store) Yes.

Agents acting as cookie providers and the other agents operating in your SSO environment could possibly require specific configuration for optimum security.

For example, suppose that your SSO environment contains three domains. A cookie provider in example.com, and two SSO domains named example.org and example.net. The following table describes the agent configuration settings for each domain:

Prevent Cookie Provider Replay Attacks

You can prevent the cookie provider from being vulnerable to replay attacks with the following parameter:

TrackCPSessionDomain

Validates that the cookie domain of the session cookie matches the cookie domain of the cookie provider. Different cookie domains could indicate a possible replay attack.

Default: No (The domain of cookie provider is not validated).

To prevent cookie provider replay attacks, set the value of the TrackCPSessionDomain parameter to yes.

The agent compares cookie domains and rejects requests when the domains do not match.

Set RequireCookies Parameter for Single Sign-On

You can control whether CA SiteMinder® requires cookies with the following parameter:

RequireCookies

Specifies whether CA SiteMinder® requires cookies. CA SiteMinder® requires cookies for the following functions:

• Securing single sign-on environments.
• Enforcing session timeouts.
• Enforcing idle timeouts.

When the value of this parameter is yes, the agent requires one of the following cookies to process HTTP requests:

• SMCHALLENGE
• SMSESSION

When the value of this parameter is no, the following conditions could occur:

• Users are challenged for credentials unexpectedly.
• Timeouts are not strictly enforced.

Important! If the agent requires cookies, instruct your users to accept HTTP cookies in their browsers. Otherwise, the users are denied access to all protected resources.

Default: Yes

To require cookies, set the value of the RequireCookies parameter to yes.

Enabling Persistent Cookies for Single Sign-On

If you want to use single sign-on for multiple browser sessions, use persistent cookies. The following steps describe one possible use for persistent cookies:

1. Users authenticate with CA SiteMinder®, but end their browser sessions before the CA SiteMinder® session expires.
2. Users start new browser sessions later, but the persistent cookie maintains their single-sign on capability.

Persistent cookies remain valid for the configured maximum session time-out plus seven days. Many browsers delete the cookie file of the web browser after the cookie expires. Some browsers possibly handle persistent cookies differently.

Follow these steps:

1. Set the PersistentCookies parameter to yes.

   The SMSESSION cookies are persistent.

2. Set the TransientIDCookies parameter to no.

   The SMIDENTITY cookies are persistent.

Specify the Cookie Domain

The CookieDomain parameter defines the cookie domain of the server where you installed the agent. You can modify the domain by setting the following parameter:

CookieDomain

Defines the cookie domain of the agent. Use a fully qualified domain name with at least two periods. For example, the setting .example.com cookie domain matches the following servers:

• w1.example.com
• w2.example.com
• w3.sales.example.com

All web servers in this domain can exchange cookies with a browser. Servers in the same cookie domain use cookies to verify the credentials of a user.

When the parameter value is none, the agent generates cookies only for its own server. For example, myserver.example.com.

If the value is blank (or contains "" in a local configuration file), the agent uses the domain information in the HTTP_HOST header. The agent then bases the value using the setting in the CookieDomainScope parameter.

Default: Empty

Example: .example.com

Limits: This value is case-sensitive. This value requires a fully qualified domain name with at least two periods, as shown in the previous example.

Note: This value is case-sensitive.

Follow these steps:

1. Set the value of the CookieDomain parameter.
2. (Optional) Set the value of the CookieDomainScope parameter.

   CookieDomainScope

   Specifies the number of sections (characters with periods between them) in the domain name.

   When the value is set to 0, the default, the agent chooses the most specific cookie domain for the host without making a server-only cookie. This means that the cookie domain myserver.example.com yields a domain of example.com, and myserver.metals.example.org yields a domain of .metals.example.org.

   If the CookieDomainScope parameter is set to 2, the cookie domain would be .example.com and .example.org respectively.

   Default: 0

   Example: Suppose that your cookie domain is division.example.com. To set the scope of the cookie domain for server.division.example.com, set the value of the CookieDomainScope parameter to 3.

Enable IP Address Validation for Single Sign-On Environments

An unauthorized system can monitor packets, steal a cookie, and use that cookie to gain access to another system. To prevent a breach of security by an unauthorized system, you can enable or disable IP checking with persistent and transient cookies.

The IP checking feature requires agent to compare the IP address stored in a cookie from the last request against the IP address contained in the current request. If the IP addresses do not match, the agent rejects the request.

The two parameters that are used to implement IP checking are PersistentIPCheck and TransientIPCheck. Set them as follows:

• If you enabled PersistentCookies, set PersistentIPCheck to yes.
• If you did not enable PersistentCookies, set TransientIPCheck to yes.

CA SiteMinder® identity cookies are unaffected by IP checking.

Modify the Session Update Period

You can specify how often the Web Agent redirects a request to the Cookie Provider to set a new cookie with the following parameter:

SessionUpdatePeriod

Specifies how often (in seconds) a Web Agent redirects a request to the Cookie Provider to set a new cookie. Refreshing the master cookie decreases the possibility that it will expire due to an idle time-out of the CA SiteMinder® session.

Default: 60

To modify the session update period

1. Make sure the CookieProvider parameter is defined.
2. Change the number of seconds in the SessionUpdatePeriod parameter to reflect the interval you want.

   The session update period is changed.

Set Secure Cookies Across Multiple Domains

Setting the UseSecureCookies parameter configures a Web Agent to only return a local cookie to a requesting browser session if the connection between them is secure (HTTPS); if the Web Agent is also configured as a cookie provider, UseSecureCookies does not apply to redirected requests for access to resources in other cookie domains.

To configure a Web Agent acting as a cookie provider to only return cookies to a Web Agent in another cookie domain if that Web Agent is also configured to use secure cookies, you must enable UseSecureCookies and also configure the following parameter:

UseSecureCPCookies

If UseSecureCPCookies is set to Yes, the cookie provider will only send a cookie to a Web Agent in another cookie domain that is also configured to use secure cookies (that is, UseSecureCookies is enabled).

When this setting and UseSecureCookies are both enabled, users in a multiple domain single sign-on environment who move from an SSL web server to a non-SSL web server in another cookie domain will have to reauthenticate. Secure cookies cannot be passed over traditional HTTP connections.

Default: No

To send cookies over SSL connections across multiple domains, set the UseSecureCookies and UseSecureCPCookies to yes on the cookie provider.

More information:

Set Secure Cookies

Ignore the Cookie Provider for Unprotected Resources

Agents forward all requests to the cookie provider by default. If you have unprotected resources, you can reduce network traffic with the following parameter:

IgnoreCPForNotprotected

Prevents the cookie provider from being queried for unprotected resource requests. When this parameter is set to no, all requests are directed to the cookie provider by the Web Agent. For traditional (nonframework) Agents, configure a cookie provider so that value of this parameter appears in the Web Agent log file.

Default: No

To prevent an agent from contacting the cookie provider when unprotected resources are requested, set the value of the IgnoreCPForNotprotected parameter to yes.

Ignore the Cookie Provider for POST Requests

The following parameter enables these behaviors:

• This setting allows traditional agents to act as cookie providers.
• This setting prevents POST requests from being sent to cookie providers (in all environments).

  LegacyCookieProvider

  Controls whether an agent sends a POST request to a cookie provider. When the agents send POST requests to a traditional agent (operating as a cookie provider), the redirected request becomes a GET. This conversion causes errors. When set to no, the agent sends the POST request to the cookie provider. When set to yes, the agent does not send the POST request to the cookie provider.

  If you are using central agent configuration, add this parameter to your agent configuration object. This parameter exists in local configuration files.

  Default: No (POST requests sent)

Set the value of the LegacyCookieProvider parameter to yes to enable the following behaviors:

• Use traditional agents as cookie providers.
• Prevent any POST requests from being sent to cookie providers.

Configure SecureUrls with Single Sign-on

If your single sign-on network has a Web Agent that supports SecureUrls functionality and another Agent that does not, this could result in internal server error messages when a user requests a protected single sign-on resource.

The log for the Web Agent with SecureUrls support shows the reason for the server error, such as the following:

Error. Unable to process request, SecureUrls is disabled.

Note: All Web Agents in a single sign-on environment must have the SecureUrls parameter set to the same value. CA SiteMinder® does not support interoperability between Web Agents with the SecureUrls parameter set to different values.

Specify the Cookie Provider

To have the other agents in your SSO environment use a cookie provider, specify the location of the agent that is acting as a cookie provider with the following parameter:

CookieProvider

Specifies the URL of the web server where the agent that is acting as the cookie provider resides.

A cookie provider is an agent in a single sign-on environment. The cookie provider sets a browser cookie for the local domain in which it exists. After this cookie is set, users can navigate throughout the single sign-on environment without reauthenticating.

The cookie provider name requires a .ccc extension, as shown in the following examples:

• For IIS, Oracle iPlanet, and Domino web servers, the URL syntax is as follows:

  http://server.domain:port/siteminderagent/SmMakeCookie.ccc

• For Apache and Apache-based web servers, the URL syntax is as follows:

  http://server.domain:port/SmMakeCookie.ccc

This parameter also affects the following parameters:

• CCCExt
• SessionUpdatePeriod

Default: No default

Example: (IIS, Oracle iPlanet, and Domino web servers) http://server1.example.com:80/siteminderagent/SmMakeCookie.ccc

Example: (Apache and Apache-based web servers) http://server1.example.com:80/SmMakeCookie.ccc

Limits: This parameter requires a fully qualified domain name.

Follow these steps:

1. Set the CookieProvider parameter to the URL of the web server that is acting as a cookie provider.
2. Verify that the value of the CCCExt parameter is set to .ccc
3. Add the .ccc extension to the values in the IgnoreExt parameter.
4. (Optional) Modify the session update period.
5. Repeat Steps 1 through 4 on all web agents in your SSO environment that are not cookie providers.

   The cookie provider is specified.

Disable Cookie Providers

All CA SiteMinder® agents can act as cookie providers by default. This setting makes configuring an SSO environment easier. For increased security, you can disable the built-in cookie provider functionality with the following parameter:

EnableCookieProvider

Specifies how the agent handles requests from cookie providers (.ccc). When this parameter value is yes, the agent processes the requests. When this parameter value is no, the agent ignores the requests from the cookie provider. The agent denies access to the requested resource. To increase security, set this parameter value to no.

Default: Yes.

Default: (after using smpolicy-secure.xml to create your Policy Store) No.

To prevent an agent from processing requests from cookie providers, set the value of the EnableCookieProvider parameter to no.

If you do not use cookie providers for SSO in your environment, use the agent configuration settings shown in the following table for all of your agents: