Evaluation endpoints

Contextual authorization REST API allows users to POST reverse queries in JSON format for evaluation.

The response provides information on what constraints need to be satisfied to get an expected PDP decision (as defined in the request). The constraints are logically combined using logical operators that evaluate to true or false.

The Contextual Authorization Query (CAQ) supports two endpoints for reverse query evaluation that define the type of response that is sent back by the service's API:

• Generate programmatic responses by sending requests to the /authorization/constraints endpoint.
• Generate human-readable responses by sending requests to the /authorization/simplified-constraints endpoint.

Request format

The CAQ API enables users to perform requests using the attributes of an authorization policy provided by the authorization domain.

A request is constituted by distinct parts. The most important are the following:

• providedAttributes: Attributes that are provided for CAQ evaluation.

  • A user can define provided attributes with or without initial values (empty bag of values).

  • Provided attribute values should result from user input and/or values resolved by an Attribute connector.

  • When a derived attribute (resolved by an attribute connector) is set as provided, then its respective key attribute should be defined somewhere in the request.

  • The Issuer property is optional and will be set to null, if not provided.

• mockedAttributtes: Attributes that are defined by the user for CAQ evaluation.

  • A user can define mocked attributes with or without initial values.
  • Mocked attribute values are final. Any attribute connectors providing values for these attributes will not be invoked.
  • A derived attribute does not need its respective key to be set.
  • The Issuer property is optional and will be set to null, if not provided.

• pdpDecisionSet: A set of PDP decisions to evaluate the reverse query.

  ​ By default this property is set to PERMIT.

  ​ A pdpDecisionSet can be also DENY, INDETERMINATE, or NOT_APPLICABLE.

• excludeIndeterminate: Indicates whether constraints that refer to an Indeterminate response, should be excluded from the result.

  ​ By default this property is set to false.

• contextType: Returns a pointer to the policy node based on the authorization domain. Can be omitted.

  ​ By default this property is set to NONE.

  • NONE = No policy context information is included in the reverse query response.

  • TIP = ID of the innermost Policy, PolicySet or Rule.

  • PATH = Full path of Policy, PolicySet and Rule Ids.

  • Enum: [ NONE, TIP, PATH ]

note

The same attribute cannot be present in both providedAttributes and mockedAttributtes. In that case the service responds with a “Request is malformed” message.

A detailed description of a request can be found in the Swagger documentation.

How to send a request

The following example is based on cURLOpens in a new tab and its command-line curl:

curl --data @request.json -H Content-Type:application/json http://localhost:8080/authorization/constraints -u admin:secret

When CAQ is configured to use authentication, any request without authentication headers, or with invalid credentials, will return an "HTTP 401 Unauthorized" response.

Examples of requests

Example 1: Who can view the company policy?

{
  "providedAttributes": [
     {
      "attribute": "Action.idaction",
      "values": [
        "view"
      ]
    }
  ],
  "mockedAttributes": [
    {
      "attribute": "resource.documentId",
      "values": [
        "companypolicy"
      ]
    }
  ],
  "pdpDecisionSet": [
    "PERMIT"
  ]
}

Example 2: What can a manager read?

{
  "providedAttributes": [
    {
      "attribute": "AccessSubject.role",
      "values": [
        "manager"
      ]
    }
  ],
  "mockedAttributes": [
    {
      "attribute": "Action.idaction",
      "values": [
        "read"
      ]
    }
  ],
  "pdpDecisionSet": [
    "PERMIT"
  ]
}

Programmatic response

A request to the /authorization/constraints endpoint returns a JSON response that can be consumed by client applications programmatically.

This programmatic CAQ response uses the AST (Abstract Syntax Tree) representation to display the response in a simplified way. Each node of the tree refers to one or more expressions (logical conditions that can be nested or not) that are part of the final PDP decision.

A node can contain one of the following conditions:

Conditions	Description
AttributeDesignator	An AttributeDesignator refers to an external source that is used to extract an attribute.
Constant	A Constant represents a fixed value.
Apply	An Apply represents an application of a function between a set of arguments. An argument can be either an Apply, a Constant, an Attribute Designator or a Function element. You can refer to the Supported Reverse API functions section, for a full list of all supported functions according to the XACML standard and information about their function and return types.
FunctionElement	A FunctionElement represents a function as a final argument of an Apply (nested).
IndeterminateExpression	An IndeterminateExpression represents the result when an answer cannot be determined.

note

The top level of an AST tree is an Apply or a Constant.

However, the API will return a true or false Boolean constant when the response, for the PDPdecisionSet under question, is a definite answer. That means that no constraints apply for the PDP decision.

Representation of an AST response

Example of programmatic response:

{
  "response": {
    "apply": {
      "function": "greaterThan",
      "returnType": "boolean",
      "policyContext": null,
      "arguments": [
        {
          "apply": {
            "function": "size",
            "returnType": "list",
            "listOf": "integer",
            "arguments": [
              {
                "attributeDesignator": {
                  "attributeName": "action",
                  "type": "list",
                  "listOf": "string"
                }
              }
            ]
          }
        },
        {
          "constant": {
            "value": "0",
            "type": "integer"
          }
        }
      ]
    }
  }
}

Example: Decision set for a "greater than" response.

Human-readable response

A request to the /authorization/simplified-constraints endpoint returns a human-readable response that can be easily understood by a user that is not familiar with logical and mathematical terms. Thus, certain details are omitted for the purpose of simplification.

The human-readable response is by default in JSON format. If you set the Accept header to text/plain, then the service returns the human-readable response in TEXT format.

Example of human-readable response in JSON format:

{
    "response": "\t\"group_manager\" == abcbank.role\tAND\tnot(\"investment_banker\" == abcbank.role)\nOR\n\t\"investment_banker\" == abcbank.role\tAND\tabcbank.name == abcbank.documentOwner\tAND\t\"remote\" == abcbank.location\nOR\n\t\"investment_banker\" == abcbank.role\tAND\t\"office\" == abcbank.location"
}

Example of human-readable response in text format:

"group_manager" == abcbank.role AND not("investment_banker" == abcbank.role)
OR
    "investment_banker" == abcbank.role AND abcbank.name == abcbank.documentOwner   AND "remote" == abcbank.location
OR
    "investment_banker" == abcbank.role AND "office" == abcbank.location