How Response Attributes Work with Web Agents

Response attributes provide a means of delivering data to applications and customizing the user experience. This content describes how response attributes work with Web Agents.
sm1252sp1
Response attributes provide a means of delivering data to applications and customizing the user experience. This content describes how response attributes work with Web Agents.
You configure responses using the Administrative UI, and then associate them with specific rules in a policy. When a request triggers a rule with a configured response, the Policy Server sends the response data to the Agent, which interprets the information and makes it available to web applications.
When you configure a response, you associate the response with an Agent action. You can associate HTTP header and cookie response attributes with the actions GET and POST. These attributes can also be tied to Authentication or Authorization events. If the user is accepted or rejected for either of these events, the Policy Server can send a response.
When configuring response attributes, the maximum web server buffer size for agent responses is 32 KB. Response attributes have no length limit other than the total buffer size.
Response attributes other than the header and cookie attributes can
only
be used when an authentication or authorization event occurs (whether the user is accepted or rejected for either of these events). For example, you can select an
Authorization event
action for a rule and then configure a
WebAgent-OnReject-Redirect
response attribute. If a user is rejected during the authorization process, the Agent redirects the user to another page that could display a message indicating why that user was rejected.
The following illustration shows how response attributes are sent from the Policy Server to the web server:
SM--SSO--Response Overview
SM--SSO--Response Overview
To simplify the task of maintaining responses, define a separate response for each type of event. For example, define one response for an OnAccept event and another response for an OnReject event. Creating a separate response makes it easier to find attributes when you must modify response values.
Return a Customized Response for a Forms Challenge
When the Web Agent challenges a user to authenticate using a forms authentication scheme, the SM_AGENTAPI_ATTR_USERMSG response enables developers to return custom text to their client applications.
If you configure 
CA Single Sign-On
 password policies, the Web Agent can convert the text from the SM_AGENTAPI_ATTR_USERMSG response to an SMUSRMSG cookie during a forms challenge. Password policies are required to generate the SMUSRMSG cookie. 
The Agent converts the response to the SMUSRMSG cookie only under the following conditions:
  • The user password expires.
  • You enable the force password change flow when the provided password does not match against password policy.
The cookie contains text that explains why the new password failed to be set against the password policy. The cookie also contains text indicating why a password expired.
To ensure that the SMUSRMSG cookie is removed after the challenge is complete, the FCC consumes the cookie (deletes it from the browser) after a successful POST request, as follows:
  • In native mode, the Agent deletes the cookie after a successful login, while redirecting back to the target URL.
  • In 4.x compatibility mode, the Agent deletes the cookie after generating the FORMCRED cookie, while redirecting back to the target URL.
The SMUSRMSG cookie is stored for a period of time in the browser, and can be transmitted over nonsecure HTTP connections. As a result, sensitive data should be avoided.
Web Agents URL-encode text that is placed in the SMUSRMSG cookie during a forms challenge, to make it safe for HTTP transmission, eliminating spaces and other harmful characters. The FCC decodes this text before making it available to the environment for use in custom FCC functionality. URL encoding is only implemented if the text is placed in the SMUSRMSG cookie.
To implement the new functionality, custom authentication scheme developers must generate custom forms-based authentication schemes. When an Sm_AgentApi_Login() call returns SM_AGENTAPI_CHALLENGE, the Agent challenges the requesting user by redirecting to the authentication scheme URL provided by the response to Sm_AgentApi_IsProtected().
When the Web Agent handles an authentication scheme that uses the HTML Forms authentication scheme template, the Agent looks for a SM_AGENTAPI_ATTR_STATUS_MESSAGE response attribute. If the attribute is found, the Agent generates the appropriate SMUSRMSG cookie, while redirecting to the authentication scheme URL. The FCC might then use this cookie during form generation, if appropriate directives are placed in the desired .FCC source file.
For more information about the FCC, see the Policy Server documentation.
Cache Response Attributes
You can instruct an agent to cache response attributes or expire attributes that contain dynamic data, forcing the Agent to contact the Policy Server and update the information. If you configure a static response attribute, the Policy Server only allows you to cache the value. By definition, static values do not change, so there is no need to recalculate them. If you configure user, DN, or active attributes, you can either cache the value or you can recalculate the value at specific intervals to ensure that the data is current.
Configure an Agent to Use Fully Qualified URLs in Redirect Responses
Set the
EnforceFQResponseRedirectUrl
agent configuration parameter to instruct an agent to use fully qualified domain names (FQDNs) in responses that redirect the user to another URL.
When the EnforceFQResponseRedirectUrl parameter is enabled, the agent checks that the value of any redirect response attribute (for example, WebAgent-OnAccept-Redirect) is a fully qualified URL. If the URL is not fully qualified, the agent prepends the original target host address to the relative redirect URL. This allows you to define a relative response URL that is applicable to all web sites.  
Values:
Yes, No
Default
: No
Example
: If EnforceFQResponseRedirectUrl is set and the value of a WebAgent-OnAccept-Redirect attribute is "/response/redirect.html" the final redirect URLs depend on the original target addresses as follows:
  • www.example.com – http://www.example.com/response/redirect.html
  • www.example.net – http://www.example.net/response/redirect.html
  • www.example.org – http://www.example.org/response/redirect.html