PingAuthorize

Configuring policy request header mappings

With the Policy Decision Service set to external or embedded policy decision point (PDP) mode, you can configure the PingAuthorize server to enforce policy request header mappings on JSON PDP API requests.

By defining a policy request header mapping, you can map a decision request header to a Trust Framework attribute. The PingAuthorize server uses this mapping to dynamically populate the attribute’s value with the value of an incoming request header, enabling you to leverage header data in the decision request body. In embedded PDP mode, the PingAuthorize server applies these mappings to individual and batch JSON PDP API requests only.

  • If a decision request includes different values for a header and attribute that are mapped to each other, the Policy Decision Service replaces the attribute value with the header value.

  • You can define multivalued headers with either comma-separated values or with duplicate header names. If the header’s values are comma-separated, the Policy Decision Service treats these values as a single string. If there are duplicate header names with different values, the Policy Decision Service uses the first value specified in the request.

  • If a decision request includes different header names mapped to the same attribute, the Policy Decision Service uses the value of the header that appears last in the administrative console list. This list is ordered alphabetically.

Screen capture of the Policy Request Header Mappings list in the admin console

You can configure policy request header mappings for development and testing in the Policy Editor. Learn more in Configuring Policy Editor policy request header mappings.

  • Administrative console

  • Dsconfig

Configuring policy request header mappings using the administrative console

Steps

  1. On the Configuration page of the PingAuthorize administrative console, go to Authorization and Policies → Policy Decision Service.

  2. In the Policy Request Header Mappings section, click New Policy Request Header Mapping.

  3. In the Name field, enter the name of the header.

    The request header name is not case sensitive.

  4. In the Attribute Name field, enter the full name of the attribute that you want to map to the relevant header.

    Screen capture of the New Policy Request Header Mapping page, with sample values included in the Name and Attribute Name fields

    The full name of an attribute represents that attribute’s full path in the Trust Framework hierarchy. For example, a Param1 attribute with parent attributes Request and Header would have a full name of Request.Header.Param1. To quickly obtain an attribute’s full name, click the hamburger menu of that attribute and select Copy full name to clipboard.

    Screen capture of the Param1 attribute’s hamburger menu selected, and the Copy full name to clipboard option highlighted

  5. Click Save to PingAuthorize server cluster.

Example

Suppose you want to add a request correlation ID so that your logging and monitoring services have full visibility of a decision request’s processing journey. This correlation ID is represented by the x-correlation-id authorization attribute, which has a parent Request attribute. The following policy request header mapping creates a mapping between the x-correlation-id header and the x-correlation-id attribute:

Screen capture of the New Policy Request Header Mapping page with an example x-correlation-id mapping defined

To include the modified decision request body in the JSON PDP API response, select the request view in the Decision Response View.

Screen capture of the Decision Response View in the Policy Request Configuration section of the admin console, with the request view selected

Selecting the request view causes the Policy Decision Logger to record potentially sensitive data in API requests and responses.

Suppose a decision request includes a sample Attribute1 attribute and a header value of x-correlation-id:abc. The relevant authorization policy produces a PERMIT decision if the Request.x-correlation-id attribute equals "abc" and a DENY decision otherwise:

{
"domain": "example.Domain",
"action": "example.Action",
"service": "example.Service",
"identityProvider": "example.Identity Provider",
"attributes": {
"Attribute1": "A request body attribute"
  }
}

The following decision response includes the modified request body, which now includes the Request.x-correlation-id attribute set to the x-correlation-id header’s value:

{
"id": "18e98969-3915-4096-b437-71100ac1d70f",
"deploymentPackageId": "502bdfdf-da19-47c9-b474-0047f77d18de",
"timestamp": "2024-05-23T15:29:30.115879Z",
"elapsedTime": 193449,
"request": {
"domain": "example.Domain",
"service": "example.Service",
"action": "example.Action",
"attributes": {
"Attribute1": "A request body attribute",
"Request.x-correlation-id": "abc"
    }
  },
"decision": "PERMIT",
"authorised": true,
"statements": [],
"status": {
"code": "OKAY",
"messages": [],
"errors": []
  }
}

Configuring policy request header mappings using dsconfig

Steps

  • To create a new policy request header mapping, use the dsconfig create-policy-request-header-mapping command and supply the mapping-name and set attribute-name arguments.

    dsconfig create-policy-request-header-mapping \
--mapping-name x-param-1 \
--set attribute-name: Request.Header.param1

    The mapping-name should match the name of the request header, and the attribute-name should match the full name of the attribute defined in the Trust Framework.

    The full name of an attribute represents that attribute’s full path in the Trust Framework hierarchy. For example, a Param1 attribute with parent attributes Request and Header would have a full name of Request.Header.Param1. To quickly obtain an attribute’s full name, click the hamburger menu of that attribute and select Copy full name to clipboard.

    Screen capture of the Param1 attribute, with the hamburger menu selected and the Copy full name to clipboard option highlighted