Configure Web Agent Single Sign-On Settings

CA Single Sign-On provides single sign-on functionality across single and multiple cookie domains. To provide single sign-on across multiple cookie domains, you configure a web agent to act as a cookie provider. There can only be one cookie provider per deployment. This topic explains how to configure a Web Agent as a cookie provider to implement single sign-on.
casso128
CA Single Sign-On provides single sign-on functionality across single and multiple cookie domains. To provide single sign-on across multiple cookie domains, you configure a web agent to act as a 
cookie provider.
 There can only be one cookie provider per deployment. This topic explains how to configure a Web Agent as a cookie provider to implement single sign-on.
Note:
 The video references the product name as CA SiteMinder, the former name of CA Single Sign-On (CA SSO).

The web agent single sign-on settings covered in this topic include:
Configure the Web Agent Settings for 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
      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 Single Sign-On
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 Single Sign-On
 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.
Example: Your SSO environment contains the following domains:
The following table describes the agent configuration settings for each domain:
(Cookie Provider Domain)
CCCExt
= .ccc
CookieProvider
=
http://server1.example.com:80/
siteminderagent/SmMakeCookie.ccc
CookieProvider
=
http://server1.example.com:80/
siteminderagent/SmMakeCookie.ccc
IgnoreExt
= (list of extensions,
which must include .ccc)
CCCExt
= .ccc
CCCExt
= .ccc
EnableCookieProvider
= yes
IgnoreExt
= (list of extensions,
which must include .ccc)
IgnoreExt
= (list of extensions,
which must include .ccc)
LimitCookieProvider
= yes
EnableCookieProvider
= no
EnableCookieProvider
= no
TrackSessionDomain
= yes
TrackSessionDomain
= yes
TrackSessionDomain
= yes
TrackCPSessionDomain
= yes
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 Single Sign-On
 requires cookies with the following parameter:
RequireCookies
Specifies whether 
CA Single Sign-On
 requires cookies. 
CA Single Sign-On
 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.
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 Single Sign-On
    , but end their browser sessions before the 
    CA Single Sign-On
     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:
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.
Special Values
When the parameter is set to the value "none", the agent generates cookies only for its own server. For example, myserver.example.com.
If the parameter value is left empty (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.
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 Single Sign-On
 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 using the 
SessionUpdatePeriod 
parameter.
This parameter 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  session. The default is 60 seconds.
To modify the session update period:
  1. Log in to the Administrative UI.
  2. In the ACO for your Agent, verify that the CookieProvider parameter is defined.
  3. Change the number of seconds in the 
    SessionUpdatePeriod
     parameter to reflect the interval you want.
  4. Save your changes.
Setting this parameter to 0 disables the setting. A session update period of 0 disables the periodic updates of sessions at the cookie provider. Sessions are updated for other reasons, but only the periodic forced updates are disabled.
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.
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.
Prevent Non-Get Requests from Being Sent to Cookie Providers
The 
LegacyCookieProvider
 parameter enables the following behaviors:
  • Allows traditional agents to act as cookie providers.
  • Can prevent requests other than GET requests from being sent to cookie providers (in all environments)
The 
LegacyCookieProvider
 parameter controls whether an agent redirects a resource request to a traditional agent operating as a cookie provider. Whether the agent redirects the request to the cookie provider depends on the request method and the setting of this parameter. If you are using central agent configuration, add this parameter to your agent configuration object. This parameter exists in local configuration files.
If 
LegacyCookieProvider=No
 (the default):
  • For GET and non-GET requests, such as POST or HEAD the agent redirects the requests to the cookie provider. The cookie provider then redirects the request back to the agent with the same request method. For example, a POST request remains a POST request when the cookie provider redirects the request back to the agent.
 If 
LegacyCookieProvider=Yes
  • For GET requests, the agent redirects the request to the cookie provider. The cookie provider redirects the request back to the agent as a GET request.
  • For Non-GET requests, such as POST or HEAD, the agent 
    does not
     redirect the request to the cookie provider. The request remains a Non-GET request.
Default: 
No
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.
All Web Agents in a single sign-on environment must have the SecureUrls parameter set to the same value.
CA Single Sign-On
does not support interoperability between Web Agents with the SecureUrls parameter set to different values.
Note:
When the ACO parameter SecureURLs=yes, all the query related is encrypted and put into SMQUERYDATA.
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 Single Sign-On
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:
Set the configuration parameters of all agents to the following values:
EnableCookieProvider = no
Allow Automatic Access to Resources that use the OPTIONS Method
The Web Agent challenges authenticated users who attempt to access resources that use the OPTIONS method. Some examples of resources that use the OPTIONS method include but are not limited to the following:
  • Microsoft® Word documents
  • Microsoft® Excel® spreadsheet documents
This challenge occurs because the application associated with the resource sends a request using the OPTIONS method to the web server. Because this request does
not
include a
CA Single Sign-On
cookie, the Web Agent issues a challenge. You can prevent users from being challenged for these resources using the
AutoAuthorizeOptions
parameter.
Follow these steps:
  1. Set the value of the following parameter to yes:
    • autoauthorizeoptions
      Automatically authorizes any requests for resources which use the HTTP OPTIONS method.
      If you set the value of this parameter to yes, also set the value of the PersistentCookies parameter to no.
      Default: 
      No default
      Limits
      : yes, no
  2. Set the PersistentCookies parameter to no.
You can also configure a Web Agent not to challenge requests for resources that use HTTP methods other than OPTIONS.
Follow these steps:
  1. Set the
    AutoAuthorizeHttpMethod
    parameter to a comma-separated list of HTTP method names. If set, requests for resources that use the specified HTTP methods are authorized without being challenged for credentials. There is no default value.
  2. Set the
    AutoAuthorizeOptions
    parameter to yes.
  3. Set the the PersistentCookies parameter to no.