Default HTTP Headers Used by the Product

This content describes the default HTTP headers that stmndr uses.
casso1283
This content describes the default HTTP headers that
SiteMinder
uses.
2
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
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
SiteMinder
default HTTP headers are available for Web Agents:
  • HTTP_SM_AUTHDIRNAME
    Indicates the name of the directory against which the Policy Server authenticates the user. The administrator specifies this directory with the Administrative UI.
  • HTTP_SM_AUTHDIRNAMESPACE
    Identifies the directory namespace against which the Policy Server authenticates the user. The administrator specifies this namespace with the Administrative UI.
  • HTTP_SM_AUTHDIROID
    Indicates the directory object identifier (OID) from the Policy Server database.
  • HTTP_SM_AUTHDIRSERVER
    Indicates the directory server against which the Policy Server authenticates the user. The administrator specifies this directory server with the Administrative UI.
  • HTTP_SM_AUTHREASON
    Indicates the code the Web Agent returns to the user after a failed authentication attempt or secondary authentication challenge.
  • HTTP_SM_AUTHTYPE
    Indicates the type of authentication scheme the Policy Server uses to verify the user’s identity.
  • HTTP_SM_DOMINOCN
    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."
  • HTTP_SM_REALM
    Indicates the
    SiteMinder
    realm in which the resource exists.
  • HTTP_SM_REALMOID
    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.
  • HTTP_SM_SDOMAIN
    Indicates the Agent’s local cookie domain.
  • HTTP_SM_SERVERIDENTITYSPEC
    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.
  • HTTP_SM_SERVERSESSIONID
    Indicates a unique string that identifies a user session.
  • HTTP_SM_SERVERSESSIONSPEC
    Indicates the ticket that contains user session information. Only the Policy Server knows how to decode this information.
  • HTTP_SM_SESSIONDRIFT
    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.
  • HTTP_SM_TIMETOEXPIRE
    Indicates the amount of time remaining for a session.
  • HTTP_SM_TRANSACTIONID
    Indicates the agent-generated unique ID for each user request.
  • HTTP_SM_UNIVERSALID
    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.
  • HTTP_SM_USER
    Indicates the login name of the authenticated user. If a user does not provide the user name at log in, such as in the case of certificate-based authentication, then this variable is not set. For JWT authentication, this header is populated with the full DN (
    Example:
    cn=user123,dc=abc,dc=com). If you have any integrations based on the
    HTTP_SM_USER
    header, add a response header to pass the right attribute to be picked up for the user name. For more information, see JSON Web Token (JWT) Authentication Scheme.
  • HTTP_SM_USERDN
    Identifies an authenticated user’s distinguished name as determined by the Policy Server.
    For anonymous authentication schemes, this returns a Globally Unique Identifier (GUID).
  • HTTP_SM_USERMSG
    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.
HTTP Header and Cookie-Variables
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.
The server may convert any dash (-) in the attribute name to an underscore (_), and all alphabetic characters to uppercase.
Header Variables and End-User IP Address Validation
When a
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.
How Custom Headers Validate IP Addresses
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.
Configure IP Address Validation
You can implement IP-address checking using the following parameters:
CustomIpHeader
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
ProxyDefinition
Specifies the IP addresses of a list of trusted proxies in a network. Agent uses the value of ProxyDefinition along with other ACO parameters such as CustomIpHeader to determine whether a request originates from a user directly or proxy server. If you define the value of ProxyDefinition, Agent expects that all the requests coming from a proxy to have an IP address that can be found in the ProxyDefinition list. If a request includes an IP address that cannot be found in the list, Agent does not consult the CustomIPHeader list to resolve the client IP address for the request and leaves the client IP address as unresolved.
Add the AUTO keyword to the ProxyDefinition list to perform the following actions:
  • Let Agent allow requests through proxies and HTTP clients to access the same applications.
  • If the CustomIpHeader header value is not present in a request, let Agent fall back to the REMOTE_ADDR IP address.
The following tables describe how the requests are processed:
When requests are accessed through proxy:
ProxyDefinition List
CustomIPHeader
RequireClient IP
Behavior to End User
List of IP address of Proxy
X-forwarded-for
YES
Page accessed with IP resolved to x-forwarded-for
IP address of proxy with AUTO keyword
X-forwarded-for
YES
Page accessed with IP resolved to x-forwarded-for
Only AUTO keyword
X-forwarded-for
YES
Page accessed with IP resolved to x-forwarded-for
When requests are accessed directly with Agent:
ProxyDefinition List
CustomIPHeader
RequireClientIP
Behavior to End User
List of IP address of Proxy
X-forwarded-for
YES
403 forbidden request
IP address of proxy with AUTO keyword
X-forwarded-for
YES
Page accessed with IP resolved from REMOTE_ADDR
Only AUTO Key word
X-forwarded-for
YES
Page accessed with IP resolved from REMOTE_ADDR
RequireClientIP
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).
These settings are independent of the TransientIPCheck and PersistentIPCheck parameters.
IP Address Validation with Previous Web Agent Releases
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
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.
Preserve HTTP Headers
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
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.
Control How HTTP Header Resources are Cached
You can control how the Web Agent handles cache-related request headers by setting the
AllowCacheHeaders
setting. This setting specifies whether the web agent removes the following cache-related HTTP headers from protected resource requests
before
passing those requests to the web server:
  • if-modified-since
  • if-none-match
The AllowCacheHeaders 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.
For terminated sessions, the browser does
not
use cached content. The value of the AllowCacheHeaders parameter is ignored.
The following options are valid for the AllowCacheHeaders setting:
  • Yes
    —The agent does
    not
    remove any cache-related HTTP headers. The SMSESSION cookies are still tracked to validate the session. When the session expires, the web agent sends an updated SMSESSION cookie with a 304 "not modified" response. This response is applied to the unmodified resources that are stored in the cache. The time indicated in the if-modified-since HTTP header determines when this behavior occurs.
    If this parameter is set to yes, pages of personalized applications lacking the appropriate cache control headers might be cached. This situation introduces unexpected behavior and allows a browser to save sensitive data to the disk.
  • No
    —(default value). The agent removes the cache-related HTTP headers only from
    protected
    resource-requests only. The web server treats the request as unconditional. The contents of the cache are not validated.
  • None
    —The Web agent removes all cache-related headers for protected
    and
    unprotected resources.
If you configure the LogOffUri parameter, set the value of the AllowCacheHeaders parameter to
no
. Otherwise, the browser sessions do not terminate properly. A cached logout page might be served to a user.
For more information about HTTP 1.1 caching mechanisms, see RFC 2616, Section 13 "Caching in HTTP."
Set the HTTP Header Encoding Specification
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.
If your chosen encoding puts characters into cookies that HTTP traffic considers illegal, specify the encoding specification with a wrapping specification. The wrapping specification is useful for custom HTTP cookie responses that contain double-byte encoded data. The recommended wrapping specification is RFC-2047. For example, some Shift-JIS characters can cause undesirable results unless the characters are further encoded by a wrapping specification. You can set the HTTPheaderEncodingSpec setting to Shift-JIS,RFC-2047. The wrapping also tells the receiving application the type and nature of the encoding so the application can better interpret the encoded text.
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.
If you specify a wrapping specification, first the data is encoded according to the HTTPHeaderEncodingSpec, then the data is further encoded by the wrapping specification.
Set the HTTPheaderEncodingSpec setting using the following syntax:
encoding_specification
,
wrapping_specification
encoding_specification
is a text string representing one of the following values: UTF-8, Shift-JIS, EUC-J, or ISO-2022 JP.
wrapping_specification
must be
RFC-2047
. Although this variable is optional, we strongly recommend that you include it. The encoding type you select might generate byte codes that are not compatible with the HTTP protocol.
Example:
Shift-JIS,RFC-2047
If you leave the HTTPHeaderEncodingSpec setting blank, the default is UTF-8 with no wrapping.
For a proxy system with an agent installed, set the HTTPHeaderEncodingSpec to UTF-8,RFC-2047, if either of the following conditions applies:
  • You protect the Administrative UI with an agent.
  • The DN values for administrators have non-English characters.
Disable Conformance to 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.
Use Lower Case HTTP in Headers (for Oracle iPlanet and Domino web servers)
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.
IIS, Apache, and IHS web servers do not benefit from this feature, as these web servers do not honor the character case of headers set by Web Agent.
To use lower case headers, set the LowerCaseHTTP parameter to
Yes
. If you require upper-case header variables, set LowerCaseHTTP to
No
.
Enable Legacy Variables for HTTP Headers
You can specify which naming convention the Web Agent uses for the HTTP headers with the following parameter:
LegacyVariables
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.
For Apache 2.4.x web servers, set the LegacyVariables parameter to No to see the default headers such as SMUSER, SMUSERDN.
Disable Default HTTP Header Variables
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
SiteMinder
’s default HTTP header variables.
The default variables are grouped into the following categories:
You cannot disable individual variables. You can only disable a category of several variables.
  • Authentication source variables
    • SM_AUTHDIRNAME
    • SM_AUTHDIRSERVER
    • SM_AUTHDIRNAMESPACE
    • SM_AUTHDIROID
  • User Session variables
    • SM_SERVERSESSIONID
    • SM_SERVERSESSIONSPEC
    • SM_SERVERIDENTITYSPEC
    • SM_SESSIONDRIFT
    • SM_TIMETOEXPIRE
  • User Name variables
    • SM_USER
    • SM_USERDN
    • SM_DOMINOCN
To disable the default use of HTTP header variables, complete any of the following tasks:
  • Disable authentication source variables by setting the DisableAuthSrcVars parameter to yes.
  • Disable user session variables by setting the value of the DisableSessionVars parameter to yes. The default is no.
    If you are using
    SiteMinder
    Federation, leave the DisableSessionVars parameter set to no. If you change the value, the agent will not set the sessionID and sessionspec headers. Without these headers, the agent ignores the session and the following types of errors are written in FWS trace log: [Request doesn't contain session ID header. Session cookie[SMSESSION]is not valid.]
  • Disable user name variables by setting the DisableUserNameVars parameter to yes. To disable Universal ID (UID) generation when DisableUserNameVars is set to yes, set the disableuniversalid ACO parameter to yes.
    If you are using CA Identity Manager, or any application that might use the variables in this category, ensure the value of the DisableUserNameVars  parameter is set to no (enabled).