Macro resources for customizing response pages

Macros are predefined, specially formatted strings that are used to dynamically add information to static server response pages.

When WebSEAL responds with a static page, it parses the page and searches for occurrences of macros. When a macro is found, the appropriate content is dynamically substituted. Macros are populated only when the value is relevant to that page.

For example, WebSEAL returns a static server response page in response to a request that results in an error. If WebSEAL encounters the ERROR macro in the static server response page, WebSEAL substitutes a string representation of the error code that was generated when handling the request.

The following macros occur in some of the static server response pages provided by WebSEAL, and are available for use in customizing these pages:

Macro	Description
`AUTHNLEVEL`	Substitutes the authentication level used in authentication strength policy (step-up).
`AUTH_URL`	The URL that triggered the request for authentication. This macro is only valid in the login success response. If no URL is known the ‘none’ string will be used.
`BACK_NAME`	Substitutes the value "BACK" if a referer header is present in the request, or "NONE" if no referer header is present in the request.
`BACK_URL`	Substitutes the value of the referer header from the request, or "/" if none.
`BASICAUTHN`	Used to control the display of information in the `certlogin` and `stepuplogin.html` login forms. When the authentication method (indicated by the macro name) is valid, the section in the form governed by the macro is displayed. When the authentication method is not valid, the macro is replaced by a start comment delimiter (<!--). All subsequent information in the form is commented out until a comment closing delimiter (-->) is reached. Note: This macro is only appropriate for HTML responses.
`CERTAUTHN`	Used to control the display of information in the `certlogin` and `stepuplogin` login forms. When the authentication method (indicated by the macro name) is valid, the section in the form governed by the macro is displayed. When the authentication method is not valid, the macro is replaced by a start comment delimiter (<!--). All subsequent information in the form is commented out until a comment closing delimiter (-->) is reached.
`CREDATTR{name}`	The value of the user credential attribute that has the specified `name`. For example, CREDATTR{tagvalue_session_index} returns the session token.
`EAIAUTHN`	Used to control the display of information in the `certlogin` and `stepuplogin` login forms. When the authentication method (indicated by the macro name) is valid, the section in the form governed by the macro is displayed. When the authentication method is not valid, the macro is replaced by a start comment delimiter (<!--). All subsequent information in the form is commented out until a comment closing delimiter (-->) is reached. Note: This macro is only appropriate for HTML responses.
`ERROR`	The hard-coded error message returned from Security Verify Access. Same as ERROR_TEXT. Both macros exist for compatibility with prior versions of WebSEAL.
`ERROR_CODE`	The numeric value of the error code.
`ERROR_TEXT`	The text associated with an error code in the message catalog. Same as ERROR. Both macros exist for compatibility with prior versions of WebSEAL.
`ERROR_URL`	The URI of a Web page which provides additional information on the error. This macro is only used for OIDC error responses.
`EXPIRE_SECS`	Contains the numbers of seconds before the password expires. This can be included into the password warning form (passwd_warn) to display the time left the user has to change their password.
`FAILREASON`	Error message.
`HOSTNAME`	Fully qualified host name.
`HTTP_BASE`	Base HTTP URL of the server "http://host:tcpport/".
`HTTPS_BASE`	Base HTTPS URL of the server, "https://host:sslport/".
`HTTPHDR{name}`	Used to include the contents of a specified HTTP header. If the specified HTTP header does not exist within the request, the macro will contain the text: ’Unknown’. For example, the macro name to include the ’Host’ HTTP header would be `HTTPHDR{Host}`.
`HTTPRSPHDR{name}`	Used to include the contents of a specified HTTP response header. If the specified HTTP header does not exist within the response, the macro will contain the text: ’Unknown’. For example, the macro name to include the ‘Content-Type’ HTTP response header would be HTTPRSPHDR{Content-Type}.
`LOCATION`	Contains the URL to which the client is being redirected. Sent only in redirects.
`METHOD`	The HTTP method requested by the client.
`OIDCAUTHN`	Used to control the display of information in the `login`, `certlogin` and `stepuplogin` login forms. When the authentication method (indicated by the macro name) is valid, the section in the form governed by the macro is displayed. When the authentication method is not valid, the macro is replaced by a start comment delimiter (`<!--`). All subsequent information in the form is commented out until a comment closing delimiter (`-->`) is reached. Note: This macro is only appropriate for HTML responses.
`OLDSESSION`	When WebSEAL receives a user request that contains an old ("stale") session cookie that no longer matches any existing entry in the WebSEAL session cache, the macro (normally set to "0") is set to the value of "1". The macro is set whenever WebSEAL sees a session cookie that is not recognized. Unrecognized session cookies can occur, for example, during session timeouts, session displacement, and when a user switches WebSEAL servers. Used in the standard WebSEAL login form to provide a trigger mechanism for a customized response to the user. This custom response could more accurately explain to the user why the session is not valid anymore. See Customized responses for old session cookies.
`PROTOCOL`	The client connection protocol used. Can be HTTP or HTTPS.
`REFERER`	The value of the HTTP referer header from the request, or "Unknown", if none.
`REFERER_ENCODED`	A URI encoded version of the HTTP referer header and macro.
`STEPUP`	A message specifying the step-up level required. Only sent when returning a step-up login form
`TAM_OP`	The operation code for the response. The values for this macro are identical to the values for local response redirects. See Operation for local response redirection.
`URL`	The URL requested by the client.
`URL_ENCODED`	A URI encoded version of the URI and macro.
`USERNAME`	The name of the user responsible for the request. (See also Customization of login forms for reauthentication.)