Apply CA Single Sign-On Behavior to a Web Application Client

Contents
casso127
Contents
2
Some web applications use script engines, which execute in the context of a Web browser, to request resources and display content. Similar to requests standard web browsers send, the requests originating from the script engine can trigger Agent-generated behavior, such as HTTP redirects or challenges.
Unless properly integrated with the web application, this behavior can result in the web application client reaching an indeterminate state.
The web application client response (WebAppClientResponse) ACO parameter lets you:
  • Configure
    CA Single Sign-On
    to identify requests originating from the script engine that is executing in the context of the Web browser.
  • Use a customized response to integrate
    CA Single Sign-On
    -generated behavior, including a challenge, with the functionality of the web application client.
  • Configure the response format for requests from Web 2.0 resources (AJAX and other API-based calls) at the global level. 
  • Configure a global response to the web application clients to reduce the need to configure request/responses at each Web Agent level manually.
If you are using the WebAppClientResponse parameter to integrate the session management features, such as idle or session timeouts, configure the OverLookSessionFor ACO parameter also. While the OverLookSessionFor parameters prevent web application client requests from keeping user sessions active indefinitely, the WebAppClientResponse parameter lets you integrate the required functionality to redirect users after a session timeout.
Web Application Client Response Introduced
Use the WebAppClientResponse ACO parameter to implement the functionality of the web application client, while maintaining
CA Single Sign-On
security.
The parameter has the following default attributes:
Resource=|Method=|Status=|Body=|Content-Type=|Charset=|RequestHeader=|RequestHeaderValue=|ResponseFormat=|RedirectURL=
Consider the following factors:
  • This ACO parameter requires at least one attribute with a valid value.
  • Provide Body or ResponseFormat for a valid response.
  • All additional attributes are optional.
  • If both Body and ResponseFormat attributes are configured, Body takes the precedence.
  • If you must identify requests from multiple web applications, a single ACO parameter can include multiple values for each attribute.
  • Web Application Client Response functionality does not work with Basic authentication schemes.
Example: WebAppClientResponse ACO parameter
The example shows the parameter with a valid value for each attribute. A description of each attribute follows the example:
WebAppClientResponse:Resource=/web20/dir/*|Method=GET,POST|Status=403
|Body=C:\location\custombody_1.txt|Content-Type=application/xml|Charset=us-ascii|RequestHeader=X-REQUESTED- WITH|RequestHeaderValue=XML_HTTPREQUEST|ResponseFormat=Application/xml|RedirectURL=http://www.google.com
  • Resource
    Specifies the protected URI to which the web application client is making requests. If the URI of a request matches this value,
    CA Single Sign-On
    identifies the request as originating from the web application client. The resource can contain a wildcard (*) for prefix and suffix matching.
    Default:
    No value: if this value is omitted, all resources that the Web Agent is protecting apply to the parameter.
    Value:
    Regular expressions are not supported.
    Example:
    Resource=/web20/dir/*
    Example:
    Resource=/web20/dir/*.xml
  • Method
    Specifies the HTTP method with which the web application client is making the request. If the HTTP method of a request matches this value,
    CA Single Sign-On
    identifies the request as originating from the web application client.
    Default:
    No value: if this value is omitted, the parameter applies all HTTP methods.
    Separate multiple methods with a comma (,).
    Example:
    GET, POST
  • Status
    Specifies the HTTP status that
    CA Single Sign-On
    must send back to the web application client request.
    Default:
    No value: if this value is omitted, an HTTP status of 200 applies to the parameter.
    You can customize the Status codes. If the Status attribute is set to 403, the application client receives the global response and custom response with the status code 403.
  • Body
    Specifies the fully qualified name of the file containing the custom body that is to function as the response to the web application client request. This file resides on the Web Agent host system and can:
    • Be text-based or contain binary data.
    • Contain any custom body that is designed by the application owner.
    • Contain a custom body that can be used to forward a reason and redirect URL.
    Default:
    No value: if this value is omitted,
    CA Single Sign-On
    forwards the response to the web application client without a body.
  • Content-Type
    Specifies the MIME type of the data present in the file that contains the response.
    Default:
    No value: if this value is omitted, a MIME type of text/plain applies to the parameter.
    If the custom body contains
    CA Single Sign-On
    generated responses, the content type of the data must be one of the following types:
    • text/*
    • application/xml
    • application/*+xml
  • Charset
    Specifies the character set of the data present in the body file.
    Default:
    No value: if this value is omitted, the parameter applies a character set type of us–ascii.
  • RequestHeader
    Specifies the header name of the HTTP request.
    Example:
     RequestHeader=X-REQUESTED-WITH 
  • RequestHeaderValue
    Specifies the header value of the HTTP request.
    Example:
     RequestHeaderValue=XML-HTTPREQUEST
  • ResponseFormat
    Specifies the format of the response that is sent to the web application making the request. The response format can be xml or json.
    Example: 
    ResponseFormat=Application/json
    Example:
     ResponseFormat=Application/xml
  • RedirectURL
    Specifies the URL that the user is automatically redirected to. RedirectURL attribute uses the status code that is defined in the ACO parameter.
Cookie Providers and the Web Application Client Response
Considering the following factors when setting the WebAppClientResponse parameter:
  • If a user accesses a Web 2.0 resource,
    CA Single Sign-On
    does not update the session cookie on the cookie provider.
  • When a user accesses a non-Web 2.0 resource, such as .html, .jsp, .asp, and .cgi,
    CA Single Sign-On
    update the session cookie on the cookie provider as normal.
How to Apply the Web Application Client Response to a Web Application
Applying the web application client response with a web application lets you implement the functionality of the web application client, while maintaining
CA Single Sign-On
security. Complete the following steps to apply the web application client response:
  1. Configure the web application client response (WebAppClientResponse) ACO parameter.
  2. Configure a custom response.
  3. Configure the web application to handle a custom response.
Configure a Web Application Client Response
Configure the Web Application Client Response to implement the functionality of the web application client.
Follow these steps:
  1. Do one of the following tasks:
    • Open the Agent Configuration Object (ACO) in the Administrative UI and uncomment WebAppClientResponse.
    • Open the local agent configuration file and uncomment WebAppClientResponse.
  2. Enter a value for one or more of the following default attributes. The ACO parameter requires a valid value in at least one attribute. All additional attributes are optional. To identify requests from multiple web applications, a single ACO parameter can include multiple values for each attribute.
    • Resource
    • Method
    • Status
    • Body
    • Content-Type
    • Charset
    • RequestHeader
    • ReuqestHeaderValue
    • ResponseFormat
  3. Do one of the following tasks:
    • Save the ACO in Administrative UI.
    • Save the local agent configuration file.
Configure a Customized Response
The application owner configures a customized response in the body of a file that resides on the Web Agent host system. When a web application client request triggers
CA Single Sign-On
functionality, the Web Agent returns the body as a response to the web application client.
Consider the following factors:
  • The file can contain any custom body as designed by the application owner.
  • The file can be text-based. If the file is text-based,
    CA Single Sign-On
    parse the body of the file for $$Reason$$ and $$URL$$ before sending the response to the web application client.
    If the response is to include a
    CA Single Sign-On
    -generated behavior:
    • The content MIME type of the data must be one of the following types:
      • text/*
      • application/xml
      • application/*+xml
    • The following placeholder values must appear in the body:
      SiteminderReason=$$Reason$$ SiteminderRedirectURL=$$URL$$
      CA Single Sign-On
      parses the body for these values and inserts the triggered
      CA Single Sign-On
      functionality and redirect URL. The following parameters or policy response types define the functions and URLs:
      • IdleTimeoutURL
      • MaximumTimeoutURL
      • ExpiredCookieURL
      • OnAccessAcceptRedirect
      • OnAccessRejectRedirect
      • Challenge
      Example:
      A web application client request triggers an idle timeout.
      CA Single Sign-On
      replaces the placeholder values with the URL in the IdleTimeoutURL parameter.
  • The file can contain binary data. If the file contains binary data,
    CA Single Sign-On
    forward the body of the file to the web application client without parsing it.
Configure a Global Response
You can also configure response formats for request types that are unidentified or not configured. The following attributes can be configured:
RequestHeader, RequestHeaderValue, and ResponseFormat
Example:
RequestHeader=X-REQUESTED- WITH|RequestHeaderValue=XML_HTTPREQUEST|ResponseFormat=Application/xml
RequestHeader=Accept|RequestHeaderValue=Application/json|ResponseFormat=Application/json
If the RequestHeader is configured and a valid Body, RequestHeaderValue, or ResponeFormat attributes are not configured, then CA Single Sign On verifies the RequestHeader. Depending on the value of the RequestHeader, the response is returned in xml or json format as defined in the configuration.
Configure the Web Application to Handle a Custom Response
If the custom response includes a reason and redirect URL, configure the web application separately to handle the custom response.
The Web Agent installation wizard installs sample applications in
web_agent_home
/samples. Extrapolate from the samples for your specific environment and situation.
  • web_agent_home
    specifies the Web Agent installation path.