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 section explains how to configure Web Agent as a cookie provider to implement single sign-on.
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 section explains how to configure Web Agent as a cookie provider to implement single sign-on.
This topic describes the following web agent settings for single sign-on:
To set up your single sign-on environment, follow these steps:
- Decide which cookie domains you want in your single sign-on environment.
- Select a cookie domain within your single sign-on environment (from Step 1) to act as the cookie provider domain.
- 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).
- For your agent that is the cookie provider, modify the configuration parameters as shown in the following steps:
- Restrict the cookie provider functions for better security.
- Prevent cookie provider replay attacks.
- Verify that the value of the RequireCookies parameter is yes.
- (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 onlyonebrowser session.
- Verify that the value of the CookieDomain parameter specifies the local cookie domain of the system on which the agent is installed.
- 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.
- (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.
- 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:
- 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.cccThe cookie provider name requires the .ccc extension, as shown in the previous example.
- Disable the cookie provider functions for better security.
- 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-OnSSO 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:
Specifies how the
CA Single Sign-Onagent 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: (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:
IgnoreExt= (list of extensions,
which must include .ccc)
IgnoreExt= (list of extensions,
which must include .ccc)
IgnoreExt= (list of extensions,
which must include .ccc)
Prevent Cookie Provider Replay Attacks
You can prevent the cookie provider from being vulnerable to replay attacks with the following parameter:
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-Onrequires cookies with the following parameter:
CA Single Sign-Onrequires cookies.
CA Single Sign-Onrequires 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:
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.
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:
- Users authenticate withCA Single Sign-On, but end their browser sessions before theCA Single Sign-Onsession expires.
- 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
plusseven 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:
- Set the PersistentCookies parameter to yes.The SMSESSION cookies are persistent.
- 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:
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:
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.
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:
- Set the value of the CookieDomain parameter.
- (Optional) Set the value of the CookieDomainScope parameter.
- CookieDomainScopeSpecifies the number of sections (characters with periods between them) in the domain name.Default:0
Manage Domain Name When Cookie Domain Parameter is Empty
You can use the
ConformToRFC6265ACO parameter to specify whether a leading dot must be appended to a domain name when the value of CookieDomain is empty. If cookie domain contains a value, this value overrides ConformToRFC6265 value.
If ConformToRFC6265 is set to
YES, the domain name is displayed without a leading dot. If ConformToRFC6265 is set to
NO, the domain name is displayed with a leading dot.
Example: For a domain name example.com, the cookie domain value is example.com. For a domain name example.com, the cookie domain value is .example.com.
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-Onidentity 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
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:
- Log in to the Administrative UI.
- In the ACO for your Agent, verify that the CookieProvider parameter is defined.
- Change the number of seconds in theSessionUpdatePeriodparameter to reflect the interval you want.
- 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
localcookie 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:
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.
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:
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.
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
LegacyCookieProviderparameter enables the following behaviors:
- Allows traditional agents to act as cookie providers.
- Prevents requests other than GET requests from being sent to cookie providers (in all environments).
LegacyCookieProviderparameter 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.
- 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.
- 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 agentdoes notredirect the request to the cookie provider. The request remains a Non-GET request.
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 can 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
SecureUrlsparameter set to the same value.
CA Single Sign-Ondoes 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:
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:
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:
- Set the CookieProvider parameter to the URL of the web server that is acting as a cookie provider.
- Verify that the value of the CCCExt parameter is set to .ccc
- Add the .ccc extension to the values in the IgnoreExt parameter.
- (Optional) Modify the session update period.
- Repeat Steps 1 through 4 on all web agents in your SSO environment that arenotcookie providers.The cookie provider is specified.
Disable Cookie Providers
CA Single Sign-Onagents 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:
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: (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
Prevent Authentication Challenges for Requests Sent Using Specific HTTP Methods
By default, Web Agents challenge authenticated users who attempt to access resources that use HTTP method in headers because the request does
CA Single Sign-Onsession cookie. For example, requests for the following resources use the OPTIONS HTTP method:
- Microsoft® Word documents
- Microsoft® Excel® spreadsheet documents
To prevent authentication challenges for resources that use specific HTTP methods, set the AutoAuthorizeHttpMethod parameter.
If set, requests for resources that use the specified HTTP methods are authorized without being challenged for credentials.
Value: One or more comma-separated HTTP method names.
: The AutoAuthorizeHttpMethod parameter replaces the AutoAuthorizeOptions parameter available in previous releases. However AutoAuthorizeOptions is still supported for backward compatibility reasons. if AutoAuthorizeOptions is set, AutoAuthorizeHttpMethod is ignored and only requests with the OPTIONS HTTP method are given unchallenged access. To use AutoAuthorizeHttpMethod, unset AutoAuthorizeOptions.