PingAuthorize

Configuring policy request header mappings

With the Policy Decision Service set to embedded policy decision point (PDP) mode, you can configure the PingAuthorize Server to apply policy request header mappings to 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 policies to use header data in making authorization decisions. In embedded PDP mode, the PingAuthorize server only applies these mappings to individual (/governance-engine) and batch (/governance-engine/batch) JSON PDP API requests.

Header mappings support both single-valued and multivalued headers.

  • You can define multivalued headers with either comma-separated values or duplicate header names.

    The Policy Decision Service treats comma-separated 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 multiple header names map to the same attribute, the Policy Decision Service uses the value of the header that appears last in the PingAuthorize admin console’s alphabetically ordered list, as shown below:

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

If a decision request includes different values for a mapped header and attribute, the Policy Decision Service overwrites the attribute value with the header value.

You can also configure policy request header mappings when developing and testing policies in the Policy Editor. Learn more in Configuring Policy Editor policy request header mappings.

  • Admin console

  • dsconfig

Steps

  1. Go to Configuration > 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 isn’t 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.

  5. Click Save.

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.

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 checkbox under 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": []
  }
}