Macro resources for customizing response pages
Macros are predefined, specially formatted strings 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). 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. 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. 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}.
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. 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.
PROTOCOL 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.)
Parent topic: HTML server response page modification