ADI retrieval from the WebSEAL client request

In a WebSEAL environment, authorization rules can be written to require authorization decision information (ADI) contained in the client HTTP/HTTPS request. ADI can be contained in the request header, the request query string, and the request POST body. Authorization decision information is referred to by an XML container name in authorization rules. A special WebSEAL-specific prefix in the container name is used to alert the authorization rules evaluation process that WebSEAL can interpret this parameter correctly and return a value. Prefixes can be specific to any resource manager. Accordingly, the resource manager must be designed to respond appropriately to a request for ADI.

The following container names contain prefixes that are appropriate for WebSEAL:

Container name	Description	Value derived from
AMWS_hd_name	Request header container name	HTTP header called name in the HTTP request.
AMWS_qs_name	Request query string container name	name value in the request query string.
AMWS_pb_name	Request POST body container name	name in the request POST body.

In each case, the value is returned to the authorization rules evaluator as ADI.

The following process flow helps illustrate how prefixes enable the extraction of ADI from client requests:

1. An authorization rule is written that requires ADI from the client request (for example, a specific HTTP header in the request).

   In this example, the AMWS_hd_ prefix is used in the container name specified in the rule. The prefix is specified by the resource-manager-provided-adi stanza entry in the [aznapi-configuration] stanza of the WebSEAL configuration file. The authorization service incorporates this configuration information during its initialization. This WebSEAL-specific prefix alerts the authorization evaluation process the required ADI is available in the client request and that WebSEAL knows how to find, extract, and return this ADI.

2. The authorization rules evaluation process tries to evaluate, for example, the AMWS_hd_host container name in a rule.

   The AMWS_hd_ prefix alerts the authorization evaluation process that WebSEAL can interpret this container name correctly and return a value.

3. The AMWS_hd_host container name is sent to WebSEAL.

   WebSEAL is designed to recognize and interpret the AMWS_hd_ prefix.

4. WebSEAL responds to the AMWS_hd_host container name by looking for the "host" header in the client request and extracting the value associated with that header.

5. WebSEAL returns the "host" header value (as an XML container) to the authorization rules evaluation process.

6. The authorization rules evaluation process uses the value as ADI in its evaluation of the rule.

The resource-manager-provided-adi stanza entry in the [aznapi-configuration] stanza of the WebSEAL configuration file specifies—to the authorization rules evaluation process— the prefixes that can be used in container names specified by authorization rules. To specify multiple prefixes, use multiple entries of the resource-manager-provided-adi stanza entry:

[aznapi-configuration]
resource-manager-provided-adi = AMWS_qs_
resource-manager-provided-adi = AMWS_pb_
resource-manager-provided-adi = AMWS_hd_

The permission-info-returned stanza entry in the [aznapi-configuration] stanza of the WebSEAL configuration file appears by default. This stanza entry specifies the permission information returned to the resource manager (for example, WebSEAL) from the authorization service.

[aznapi-configuration]
permission-info-rned = azn_perminfo_rules_adi_request azn_perminfo_reason_rule_failed

The azn_perminfo_rules_adi_request setting allows the authorization service to request ADI from the current WebSEAL client request. The azn_perminfo_reason_rule_failed setting specifies that rule failure reasons be returned to the resource manager (this setting is required for -R junctions—see Supply a failure reason across a junction).

• Example: Retrieving ADI from the request header
  
• Example: Retrieving ADI from the request query string
  
• Example: Retrieving ADI from the request POST body
  

Related concepts

• Overview of ADI retrieval
• ADI retrieval from the user credential
• Dynamic ADI retrieval

Related tasks

• Supply a failure reason across a junction
• Configure WebSEAL to use the attribute retrieval service

Parent topic

Authorization decision information retrieval