Macros are predefined, specially formatted strings that are used to dynamically add information to static HTML server response pages.
When WebSEAL responds with a static HTML 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 HTML 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.html 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. |
| CERTAUTHN | Used to control the display of information in the certlogin.html 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. |
| 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.html 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. |
| ERROR | The hard-coded error message returned from Security Access Manager. 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. |
| EXPIRE_SECS | Contains the numbers of seconds before the password expires. This can be submitted into the password warning form (passwd_warn.html) 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. |
| 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 | 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 |
| 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.) |