API

Contextual Authorization Query (CAQ) provides a REST API that can be used for evaluating reverse queries against an authorization policy and its respective attributes defined in the authorization domain.

CAQ API uses attribute identifiers to evaluate policies under question, in both the requests and responses.

Attribute identifiers

Αn attribute identifier is a sequence of case-sensitive string elements, separated by the . character.

All these string elements in an attribute identifier, up to the last dot (if any), form the namespace; the last string element in the sequence is the name. An attribute identifier with a single string element (no dots), has a name, but no namespace (or it has an ‘empty’ namespace).

Example of an attribute identifier:

company.resource.classification

Attributes dictionary

To associate the attribute identifiers of a request or response with the attributes used in the policy of an authorization domain, CAQ uses the attributes dictionary.

The attributes dictionary is located under the attributes section of an authorization domain.

The CAQ scans the authorization domain dictionary in order to associate each attribute identifier with its respective attribute (xacmlId , category, datatype, issuer) used in the policy and to evaluate requests and respond accordingly.

Example of attributes dictionary:

attributes:
  abcbank.role:
    xacmlId: abcbank.role
    category: 'urn:oasis:names:tc:xacml:1.0:subject-category:access-subject'
    datatype: 'http://www.w3.org/2001/XMLSchema#string'
    issuer: 'test-user'

note

If the attribute value is provided by an attribute connector, the attribute should be listed in the attributes dictionary of the domain. An authorization domain with no attribute connectors is still valid even if the attributes dictionary is empty or missing.

Axiomatics recommends using a fully defined dictionary, listing all the attributes used in the policy, in order for CAQ to work properly.

Attribute identifiers in requests and responses that do not have a corresponding mapping in the dictionary are handled by the API in the following ways:

• Request: When a CAQ query contains an attribute identifier that is missing from the dictionary, then CAQ API ignores that attribute and proceeds with evaluating the query.

• Response: If a CAQ response contains an attribute identifier for which there is no corresponding mapping in the dictionary, then CAQ service API generates an attribute identifier for this attribute used in the policy under question.

  The CAQ service generates these attribute identifiers from the policy's attributes using the following rules:

  • For unique attributes, the service generates an attribute identifier name using the attribute xacmlId and category.
  • For attributes having the same xacmlId , the service differentiates them by generating an attribute identifier name using their attribute category.
  • For attributes having the same xacmlId and Category, the service differentiates them by generating an attribute identifier name using their attribute datatype.
  • For attributes having the same xacmlId , category and datatype the service differentiates them by generating an attribute identifier name using their attribute issuer-id.

CAQ REST API documentation

Swagger UI API

CAQ REST API interactive documentation is available in the Swagger UI API.

Τo access the Swagger UI API, you first need to start the service. Then, you can access the interactive documentation using the following URL:

http(s)://<your host>:<your port>/authorization/swagger-ui/index.html

OpenAPI

You can access the OpenAPI/Swagger documentation in CAQ by using the following path:

http(s)://<your host>:<your port>/authorization/api-docs