Macro support for local response redirection

Macro support for local response redirection

Local response redirection provides support for a subset of the macros provided by WebSEAL to customize static server response pages. Macros allow dynamic substitution of information from WebSEAL.
As with the operation information (provided by the TAM_OP argument), macros are specified as an argument in the query string of the location header. Specific characters in the macro values are URI-encoded (see Encoding of macro contents).
Valid WebSEAL macros for use in local response redirection include:

Macro Description

AUTHNLEVEL Authentication level required by authentication strength policy (step-up).

CREDATTR{name} Used to include the contents of a specified attribute in the user credential. If the specified credential attribute does not exist in the request, the macro contains the text: 'Unknown'.
For example, use the following macro name to include the tagvalue_session_index attribute, which contains the secret token for the session: CREDATTR{tagvalue_session_index}.

ERROR_CODE The hexadecimal value of the error code.

ERROR_TEXT The WebSEAL-supplied error message text associated with an error code in the message catalog.

FAILREASON Error message text associated with a Boolean rules operation.

HOSTNAME Fully qualified host name.

HTTPHDR{name} Used to include the contents of a specified HTTP header. If the specified HTTP header does not exist in the request, the macro contains the text: 'Unknown'.
For example, the macro name to include the "Host" HTTP header is HTTPHDR{Host}.

METHOD The HTTP method requested by the client.

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.

URL The URL requested by the client.

USERNAME The name of the logged in user. For users that are not logged in, the name they used to attempt to log in is the one used. (See also Customization of login forms for reauthentication.)
When using local response redirection, WebSEAL also uses the value "unauthenticated" after an inactivity timeout. This behavior differs from the processing that occurs when WebSEAL serves static pages. We can configure WebSEAL to set the USERNAME macro value to the authenticated username as it does when serving static pages. To achieve this behavior, set the use-existing-username-macro-in-custom-redirects configuration entry in the [server] stanza to yes. Restart WebSEAL for this change to take effect.

For example, the originally requested URL might be required by an external authentication interface server that provides authentication services. The standard WebSEAL URL macro can be included in the query string of the Location header of the HTTP 302 response. The value of the macro is dynamically provided by WebSEAL.
To specify macro-supplied information (to be returned in the Location header query string), uncomment the appropriate macro stanza entries in the [local-response-macros] stanza of the WebSEAL configuration file. For example:
[local-response-macros] macro = TAM_OP #macro = USERNAME #macro = METHOD #macro = REFERER #macro = HOSTNAME #macro = AUTHNLEVEL #macro = FAILREASON #macro = PROTOCOL #macro = ERROR_CODE #macro = ERROR_TEXT #macro = HTTPHDR{header_name}macro = URL

WebSEAL inserts the TAM_OP macro in all local redirect responses regardless of Whether it is included in the configuration file.
The following example header shows a Location URI with the TAM_OP and URL macros (and values) indicated in the query string:
Location: https://webseal/jct/handler-svr/handler?TAM_OP=login& URL=%2FjctB%2Fresource.html

In this example, the forward slash character (/) in the value of the URL macro is encoded as %2F. See Encoding of macro contents.
If a configured macro contains no information, the macro name and the “=” delimiter still appear in the query string. For example
Location: https://webseal/jct/handler-svr/handler?TAM_OP=stepup&USERNAME=eric& FAILREASON=&AUTHNLEVEL=2

The HTTPHDR macro is used to include a specified HTTP header in the query string. The desired header name should be configured in the [local-response-macros] stanza. For example, to insert the Host header into the query string, the following configuration entry should be added to the [local-response-macros] stanza:
macro = HTTPHDR{Host}

This will result in a query string similar to the following:
Location: https://webseal/jct/handler-svr/handler?TAM_OP=login&HTTPHDR_Host=webseal

Customize macro field names

Encoding of macro contents

Macro content length considerations

Parent topic: Local response redirection

Macro	Description
AUTHNLEVEL	Authentication level required by authentication strength policy (step-up).
CREDATTR{name}	Used to include the contents of a specified attribute in the user credential. If the specified credential attribute does not exist in the request, the macro contains the text: 'Unknown'. For example, use the following macro name to include the tagvalue_session_index attribute, which contains the secret token for the session: CREDATTR{tagvalue_session_index}.
ERROR_CODE	The hexadecimal value of the error code.
ERROR_TEXT	The WebSEAL-supplied error message text associated with an error code in the message catalog.
FAILREASON	Error message text associated with a Boolean rules operation.
HOSTNAME	Fully qualified host name.
HTTPHDR{name}	Used to include the contents of a specified HTTP header. If the specified HTTP header does not exist in the request, the macro contains the text: 'Unknown'. For example, the macro name to include the "Host" HTTP header is HTTPHDR{Host}.
METHOD	The HTTP method requested by the client.
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.
URL	The URL requested by the client.
USERNAME	The name of the logged in user. For users that are not logged in, the name they used to attempt to log in is the one used. (See also Customization of login forms for reauthentication.) When using local response redirection, WebSEAL also uses the value "unauthenticated" after an inactivity timeout. This behavior differs from the processing that occurs when WebSEAL serves static pages. We can configure WebSEAL to set the USERNAME macro value to the authenticated username as it does when serving static pages. To achieve this behavior, set the use-existing-username-macro-in-custom-redirects configuration entry in the [server] stanza to yes. Restart WebSEAL for this change to take effect.