CA SiteMinder® default HTTP headers instruct applications how to collect user data and apply that information to display personalized content for each user.
As part of the Web application environment, the CA SiteMinder® Agent submits default HTTP headers to the web server, and the web server makes them available for Web applications. You can use these headers to include functions and enable your Web applications to personalize content. Headers can store information such as a user’s name and the type of action a user is authorized to perform.
The Agent sends these headers regardless of whether or not they are called from a Web application; however, you can disable some of these headers so that they do not use up header space.
The following CA SiteMinder® default HTTP headers are available for Web Agents:
Indicates the name of the directory against which the Policy Server authenticates the user. The administrator specifies this directory with the Administrative UI.
Identifies the directory namespace against which the Policy Server authenticates the user. The administrator specifies this namespace with the Administrative UI.
Indicates the directory object identifier (OID) from the Policy Server database.
Indicates the directory server against which the Policy Server authenticates the user. The administrator specifies this directory server with the Administrative UI.
Indicates the code the Web Agent returns to the user after a failed authentication attempt or secondary authentication challenge.
Indicates the type of authentication scheme the Policy Server uses to verify the user’s identity.
Identifies the user’s Domino canonical name if a Domino LDAP directory is used to authenticate users.
Example: HTTP_SM_DOMINOCN="CN=jsmith/O=netegrity."
Indicates the CA SiteMinder® realm in which the resource exists.
Indicates the realm object ID that identifies the realm where the resource exists. This ID is may be used by third party applications to make calls to the Policy Server.
Indicates the Agent’s local cookie domain.
Indicates the Policy Server identity ticket that keeps track of the user identity. The Web Agent uses this to access content protected by anonymous authentication schemes so that it can personalize the content for the user.
Indicates a unique string that identifies a user session.
Indicates the ticket that contains user session information. Only the Policy Server knows how to decode this information.
Indicates the amount of time the Web Agent can keep a session active using the information in its cache before validating the session with the Policy Server. The session server at the Policy Server must be enabled and a session validation period must be configured for this header to be set.
Indicates the amount of time remaining for a CA SiteMinder® session.
Indicates the agent-generated unique ID for each user request.
Identifies the Policy Server-generated universal user ID. This ID is specific to the customer and identifies the user to the application, but it is not the same as the user login.
Indicates the login name of the authenticated user. If a user does not provide a user name at log in, such as certificate-based authentication, then this variable is not set.
Identifies an authenticated user’s distinguished name as determined by the Policy Server.
For anonymous authentication schemes, this returns a Globally Unique Identifier (GUID).
Identifies the text that the Agent presents to the user after an authentication attempt. Some authentication schemes supply challenge text or a reason why an authentication has failed.
The HTTP-Header-Variable and HTTP-Cookie-Variable attributes enable a Web Agent to pass a static or dynamic list of name/value pairs to a Web application. The name/value pairs are specific to the user requesting a resource, which enables the application to customize what the user sees.
For example, an administrator configures the WebAgent-HTTP-Header-Variable response attribute to store the full name of the user. When the user is authorized to access the protected resource, the Web Agent passes the user’s full name to the Web application. The user’s name is then displayed by the application, which helps to establish a relationship with the customer.
Be aware that in a Web application environment, the HTTP-Header-Variable response attribute appears as an HTTP_attribute_name variable, where attribute_name is the name of the HTTP variable, for example USERFULLNAME. You do not have to have an underscore in the name as the underscores cause problems with some application servers.
Note: The server may convert any dash (-) in the attribute name to an underscore (_), and all alphabetic characters to uppercase.
When a CA SiteMinder® Web Agent receives a request that follows an initial request by that same user, the Agent validates the session cookie sent with the subsequent request by comparing the IP address of the requesting user with the IP address encrypted inside the session cookie. The address inside the cookie is generated by the Agent during the user’s initial request.
Mechanisms used to balance and manage incoming network traffic, such as firewalls, load balancers, cache devices, and proxies can alter the user’s IP address or make it appear as if all incoming requests are coming from a single or small group of IP addresses. As a result, the Web Agent’s IP checking becomes ineffective. The Web Agent can now perform IP checking in these network environments using a custom HTTP header and a configurable list of safe proxy IP addresses.
The following table lists the terminology for new IP checking functionality.
|
Term |
Definition |
|---|---|
|
HTTP Request Header |
A name/value pair that describes a single element of an HTTP request. |
|
Custom IP Header |
A user-defined HTTP request header used by intermediate HTTP network applications or hardware devices to store the requestor’s IP address. |
|
IP Checking |
Feature that enables the Web Agent to check requests for authenticity by comparing the REMOTE_ADDR in the request with the REMOTE_ADDR value stored in the SMSESSION cookie, after an initial request. This feature is also known as IP validation. |
|
REMOTE_ADDR |
web server variable representing the IP address of the HTTP client making a request to the web server. Also known as REMOTE_IP or CLIENT_IP. This differs from the Requestor IP Address when a proxy server, NAT firewall, or other network service or device sits between the requestor and the target web server. |
|
Requestor |
The initiator of an HTTP request, typically a user at a browser. |
|
Requestor IP Address |
The IP address of the user making the original HTTP request. |
|
Single Sign-on |
Feature that requires a user to enter credentials for secure access to a protected Web site only once during a session. |
|
SMSESSION cookie |
HTTP mechanism used by Web Agents to track single sign-on state. |
The Web Agent can now use a custom HTTP header to determine a user’s IP address instead of using the REMOTE_ADDR variable. If a proxy or other device sets a custom client IP header and the Web Agent is configured to look for that header on an incoming request, the Agent uses that header as the source of the client IP information.
In addition to configuring a custom header, you can set up a list of proxy IP addresses. If the REMOTE_ADDR matches an address in the proxy list, the Web Agent retrieves the user’s IP address from the custom header. Otherwise, the user’s IP address is obtained from the REMOTE_ADDR.
After the Web Agent resolves the requestor’s IP address, the address is stored and used for request processing. If an address cannot be resolved, the IP address is set to unknown.
The Web Agent logs where the client IP address was resolved from to facilitate any debugging that may be necessary.
You can implement IP‑address checking using the following parameters:
Specifies an HTTP header for which the agent searches to find the IP address of the requestor. If no value is specified for this parameter, the default is an empty string. No maximum length is enforced and the value can be any string that contains a valid HTTP header value.
Default: No
Example: HTTP_ORIGINAL_IP
Specifies the IP address of a proxy (such as a cache device) that requires the use of a custom HTTP header. This custom header helps the agent resolve the IP addresses of the requester.
Default: No default
Limits: The string must contain an IP address. Do not use server names or fully qualified DNS host names.
Specifies if the agent validates the IP address of the client. When this value is set to yes, the agent validates that the IP address in the browser cookie matches the IP address of the client. If the addresses do not match, a 403 error message appears in the browser of the user. If the cookie does not contain an IP address, then users are prompted for their credentials.
Default: No (client IP addresses not validated).
Note: These settings are independent of the TransientIPCheck and PersistentIPCheck parameters.
In an environment of 6.x QMR 2 or 3 Web Agents and older Agents, single sign-on may be affected if IP checking is configured.
Web Agents prior to v6.x QMR 2 and 5.x QMR 7 will not be able to resolve the requestor IP address and as a result, SMSESSION cookies created by those Web Agents may be discarded by 6.x QMR 2 or 3 Web Agents. This includes custom Agents using the SDK to generate SMSESSION cookies, Application Server Agents, and any other CA SiteMinder® Agents in a single sign-on environment that use SMSESSION cookies.
Conversely, 6.x QMR 2 and 3 Web Agents may resolve a requestor’s IP address, which then differs from the address resolved by an older Agent.
You can configure the Web Agent to save existing HTTP headers instead of replacing them when new headers are created. This feature is useful for applications that generate multiple CA SiteMinder® responses with the same name but with different values, and need to be included in headers. If there are multiple instances of the same HTTP header, the web server handles this by generating a single header with all the relevant header values separated by commas.
By default, the Web Agent does not preserve headers as a precaution against applications using the wrong header values. For Oracle iPlanet, Domino, and Apache Web Agents to preserve HTTP headers, set the PreserveHeaders parameter to yes. The default value is no.
You can control how the Web Agent handles cache-related request headers by setting the following parameter:
Specifies whether the web agent removes the following cache-related HTTP headers from protected-resource requests before passing those requests to the web server:
This setting affects whether a browser uses cached pages. This setting does not affect auto-authorized resources (including values in the IgnoreExt parameter). The settings of the web server and browser determine whether auto-authorized resources are cached.
This parameter uses the following values:
Important! When this parameter is set to yes, pages of personalized applications lacking the appropriate cache control headers could possibly be cached. This situation introduces unexpected behavior and allows a browser to save sensitive data to the disk.
For terminated sessions, the browser does not use cached content. The value of the AllowCacheHeaders parameter is ignored.
The settings of this parameter affect the following parameters:
Default: No
Limits: Yes, No, None
To remove all cache related headers from protected and unprotected resources, set the value of the AllowCacheHeaders parameter to none.
Note: For more information about HTTP 1.1 caching mechanisms, see RFC 2616, Section 13 "Caching in HTTP."
The HTTPHeaderEncodingSpec setting affects the encoding of all HTTP header values and all custom HTTP-COOKIE responses.
Use this parameter to support the web applications expecting localized text in specific encodings. Since the cookies pass back and forth between the browser and portal through the HTTP protocol, use the RFC-2047 HTTPWrapSpec if your chosen encoding puts characters that HTTP traffic considers illegal into the cookies.
For example, some Shift-JIS characters can cause undesirable results if not further encoded by RFC-2047.
For the Kanji characters, you can use SECP932, which is a superset of SHIFT-JIS. Though SHIFT-JIS can be used for most Kanji encoding and decoding, CP932 covers an even larger character set.
When HTTPWrapSpec is used, first the data is encoded according to the HTTPHeaderEncodingSpec, then the data is further encoded following the RFC-2047 specification.
The syntax for the parameter is:
encoding_spec, wrapping_spec
The encoding_spec is a text string that represents one of the following encoding types: UTF-8, Shift-JIS, EUC-J, or ISO-2022 JP. Specify the encoding type that you want the Agent to use.
The wrapping_spec is the wrapping specification, which must be RFC-2047. Although this variable is optional, we strongly recommend that you include the wrapping specification because the encoding type you select may generate byte codes that are not compatible with the HTTP protocol.
This is especially true if you use custom HTTP Cookie responses that contain double-byte encoded data. For example, some Shift-JIS characters cause undesirable results if they are not further encoded by RFC-2047. The wrapping also tells the receiving application that the type and nature of the encoding so the application can better interpret the encoded text. For example, set the parameter to Shift-JIS,RFC-2047.
When RFC-2047 is used, the Agent first encodes the data based on the chosen encoding specification and then further encodes the data following the RFC-2047 specification.
Note: If you leave the HTTPHeaderEncodingSpec setting blank, the default is UTF-8 with no wrapping.
Important! Set the following value for the HTTPHeaderEncodingSpec ACO parameter in the proxy computer in which the agent is installed, in the following cases:
UTF-8,RFC-2047
By default, the Web Agent conforms to RFC 2047. However, you can disable this conformance by setting the ConformToRFC2047 parameter to no.
If this parameter does not exist or is set to yes, the Web Agent conforms to RFC 2047.
If you have server applications that are case-sensitive, you can specify the case of the Agent’s HTTP headers. The Web Agent defaults to lower case headers.
For example, Oracle iPlanet web servers, by default, provide the HTTP header variables in lower-case, such as http_sm_user.
Note: IIS Web Agents do not benefit from this feature, because IIS forces all headers to an upper case format.
To use lower case headers, set the LowerCaseHTTP parameter to yes. If you require upper-case header variables, set LowerCaseHTTP to no.
You can specify which naming convention the Web Agent uses for the HTTP headers with the following parameter:
Specifies if the Web Agent uses underscores in HTTP header names. With some web servers (such as the Sun Java System), using the underscore character in the HTTP headers causes problems with some applications.
When this parameter is set to no, the HTTP headers will not have underscores, as shown in the following example:
SMHeaderName
When this parameter is set to yes, the HTTP headers will use underscores, as shown in the following example:
SM_HeaderName
Default: (traditional agents) Yes
Default: (framework agents) No
To enable legacy variables and have the Web Agent use underscores in the HTTP header names, set value of the LegacyVariables parameter to yes.
Note: For Apache 2.4.x web servers, set the LegacyVariables parameter to No to see the CA SiteMinder® default headers such as SMUSER, SMUSERDN.
Many system platforms have an HTTP header limit of 4096 bytes. To avoid exceeding this limit and to allow space for custom response variables, you can disable some of CA SiteMinder®’s default HTTP header variables.
The default variables are grouped into the following categories:
Note: You cannot disable individual variables. You can only disable a category of several variables.
To disable the default use of HTTP header variables do any of the following tasks:
Default: No
Note: If you are using CA IdentityMinder, or any application that might use the variables in this category, ensure the value of this parameter is set to no (enabled).
Custom error handling allows you to make error information relevant to your application. To customize applications for users, you can add the HTML text displayed by HTTP 500, HTTP 401, and HTTP 403 error pages or, with the exception of 401 errors, you can redirect the user to a URL that points to a custom error page or application.
You can configure customized handling for the following types of errors:
Specifies the customized HTML page to display when users receive a 401 (insufficient privileges) browser error. These errors occur when a user does not have the appropriate privileges to access a resource.
Note: Some web servers append text of their own to the custom text that you choose. So the response pages for these servers are not customizable.
Default: No default (blank).
After you create these HTML files or applications, direct the Web Agent to the custom error pages or URLs.
Note: For an Apache server being used as a proxy or reverse proxy server, the Apache Agent will not return custom CA SiteMinder® error pages, but will return the standard Apache HTTP 500 and 403 error pages.
To customize how your applications display error messages for users, do any of the following tasks:
For HTTP 500 and 403 errors only: If you configure the agent to redirect the user to a URL, the agent appends the error code to the URL. See the following example of an appended URL:
?SMError=error_code,
If you add standard HTML error text, you can only specify HTML code between the following tags:
<body> </body>
To direct the agent to the custom error pages or URLs, do one of the following tasks:
Enter the URL in the value of the respective agent configuration parameter.
Errors and other events and the respective agent configuration parameters are listed in the following table:
|
Set a custom response for this type of error: |
With the value of this configuration parameter: |
|
Server errors |
ServerErrorFile |
|
Access denied errors |
Custom401ErrorFile |
|
Cookie required errors |
ReqCookieErrorFile |
|
CSS characters errors |
CSSErrorFile |
The error files can reside anywhere in your application.
Important! Leave any URL you configure as a custom error page unprotected.
Note: If the URLs of your applications require HTML tags, encode the characters in the tags. For information about encoding HTML characters, see: http://www.cert.org/tech_tips/.
The following examples show a file path and a URL to an error file. The syntax in the example is for a local configuration file. You can also set these parameters in an agent configuration object.
File Path:
CSSErrorFile="C:\error\error.txt"
ReqCookieErrorFile="C:\custompages\error.txt"
ServerErrorFile="C:\error\error.txt"
Custom401ErrorFile="C:\error\accessdenied.txt"
URL:
CSSErrorFile="http://www.mycompany.com/error.jsp"
ReqCookieErrorFile="http://www.myorg.com/error.asp"
ServerErrorFile="http://www.mycompany.com/error.jsp"
Because re-checking is triggered by the existence of the Custom401errorfile value rather than its usability, you can correct an error without restarting the agent. The correction will be picked up on the next check.
|
Copyright © 2013 CA.
All rights reserved.
|
|