--- title: Configuring policy request header mappings description: 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. component: pingauthorize version: 10.3 page_id: pingauthorize:pingauthorize_server_administration_guide:paz_policy_request_header_mappings canonical_url: https://docs.pingidentity.com/pingauthorize/11.1/pingauthorize_server_administration_guide/paz_policy_request_header_mappings.html llms_txt: https://docs.pingidentity.com/pingauthorize/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: April 28, 2025 superseded_by: https://docs.pingidentity.com/pingauthorize/11.1/pingauthorize_server_administration_guide/paz_policy_request_header_mappings.html section_ids: configuring-policy-request-header-mappings-using-the-administrative-console: Configuring policy request header mappings using the administrative console steps: Steps example: Example configuring-policy-request-header-mappings-using-dsconfig: Configuring policy request header mappings using dsconfig steps-2: Steps --- # Configuring policy request header mappings With the Policy Decision Service set to [external](paz_config_external_pdp.html) or [embedded policy decision point](paz_config_embedded_pdp.html) (PDP) mode, you can configure the PingAuthorize server to enforce policy request header mappings on [JSON PDP API](paz_json_pdp_api_flow.html) 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](_images/jsa1717779766593.png) | 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](paz_config_pe_request_header_mapping.html). * 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 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](_images/dfe1717779929404.png) | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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](_images/qvj1717780006644.png) | 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](_images/lbb1717780099674.png) To include the modified decision request body in the JSON PDP API response, select the **request** view in the [Decision Response View](paz_config_decision_response_view.html). ![Screen capture of the Decision Response View in the Policy Request Configuration section of the admin console, with the request view selected](_images/nbj1717780176144.png) | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Selecting the **request** view causes the [Policy Decision Logger](paz_enable_detailed_logging.html#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: ```json { "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: ```json { "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](_images/qvj1717780006644.png) |