Web Agent Guides › Web Agent Configuration Guide › Protecting Web Applications › Use SM_AGENT_ATTR_USRMSG Response for a Forms Challenge

Use SM_AGENT_ATTR_USRMSG Response for a Forms Challenge

The SM_AGENTAPI_ATTR_USERMSG response enables developers of custom SiteMinder authentication schemes to return custom text to their client applications, as part of a user challenge or for some other purpose.

Beginning with v5 QMR3, the Web Agent has the ability to convert the text from an SM_AGENTAPI_ATTR_USERMSG response to an SMUSRMSG cookie when performing a forms challenge.

To ensure 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 SiteMinder mode, the Agent deletes the cookie after a successful login, while redirecting back to the target URL.
• In SiteMinder 4.x compatibility mode, the Agent deletes the cookie after generating the FORMCRED cookie, while redirecting back to the target URL.

Note: The SMUSRMSG cookie will be stored for a period of time in the user's browser, and could possibly be transmitted over non-secure HTTP connections. As a result, sensitive data should be avoided.

Web Agents will 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.

Note: URL encoding is not implemented unless 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 may then use this cookie during form generation, if appropriate directives are placed in the desired .FCC source file.

Note: For more information, see the Policy Server documentation.