Explain on PDP methods

Explain can be enabled in the PDP to provide context to why a user received a DENY decision when adjudicating an operation or routine.

To enable explain in the PDP:

pdp.setExplain(true);

Response objects will populate the explain field if an UnauthorizedException is thrown:

AdminAdjudicationResponse response = pdp.adjudicateAdminRoutine(new UserContext("u1"), new RoutineRequest("routine1", Map.of("a", "test")));
Explain explain = response.getExplain();

• If explain is not enabled, response.getExplain() will return null.

Here is an annotated example of the output of getExplain() in JSON format:

{
  "privileges": [ <- The privileges the user has on the object
    "read"
  ],
  "policyClasses": [ <- For each policy class in which the object has one or more paths to the policy class node
    {
      "pc": "pc1", <- The policy class
      "arset": [   <- The access rights the user has under the policy class
        "read",
        "write"
      ],
      "paths": [ <- The paths from the object to the policy class node
        [
          {
            "node": "o1",
            "associations": []
          },
          {
            "node": "oa1",
            "associations": [ <- The associations in which this node is the target of
              {
                "ua": "ua1",
                "arset": [
                  "read",
                  "write"
                ],
                "userPaths": [ <- The paths (if any) that make this association reachable by the user
                  [
                    "u1",
                    "ua1"
                  ]
                ]
              }
            ]
          },
          {
            "node": "pc1",
            "associations": []
          }
        ]
      ]
    },
    {
      "pc": "pc2",
      "arset": [
        "read",
        "write"
      ],
      "paths": [
        [
          {
            "node": "o1",
            "associations": []
          },
          {
            "node": "oa3",
            "associations": []
          },
          {
            "node": "oa2",
            "associations": [
              {
                "ua": "ua2",
                "arset": [
                  "read",
                  "write"
                ],
                "userPaths": [
                  [
                    "u1",
                    "ua2"
                  ]
                ]
              }
            ]
          },
          {
            "node": "pc2",
            "associations": []
          }
        ]
      ]
    }
  ],
  "deniedPrivileges": [ <- Any privileges that are denied through prohibitions
    "write"
  ],
  "prohibitions": [ <- The prohibitions that have been satisfied
    {
      "name": "p1",
      "subject": {
        "name": "u1",
        "type": "USER"
      },
      "containers": [
        {
          "name": "oa1",
          "complement": false
        }
      ],
      "accessRightSet": [
        "write"
      ],
      "intersection": false
    }
  ]
}