Skip to main content

The most recent patch for this version is 2.1.1.  Learn more  

Version: 2.1

Audit logging

Audit logs in Access Decision Service (ADS) are detailed records that capture and store information about every authorization request processed by the service. These logs are essential for monitoring, security, and compliance purposes. You can customize the audit logs to suit your deployment's needs. This includes adjusting the level of detail recorded, specifying which types of events to log, and determining how long logs should be retained.

Audit logging is disabled by default. You can enable it in the deployment.yaml configuration file, following the instructions in the Enable audit logging section.

By default, audit logs are generated in JSON file format, but you can opt for XML, which was used in ADS 1.x. Read the Audit logging format and mode section for details.

Even though audit logging is part of the basic configuration options for logs in ADS, you can enable additional logging configurations:

  • Basic logging options can be found in the Logging section under Basic configuration.
  • Additional logging options are available in the Additional logging properties section under Additional configuration.

Logging events​

The audit logs produced by ADS contain two types of logging events:

  • Evaluation Events: These events cover the specifics of access requests, including the queries made and the system's responses.
  • Administrative Events: These focus on modifications made to the ADS configuration during runtime.

You can configure the inclusion of either event type in the audit logs. You can find detailed instructions on separating these event types within the audit log output in Separate event types in the audit log output.

By default, the log output for evaluation events is presented in a concise layout, that is, information not essential to auditing is excluded from the evaluation events. To configure logging to use the verbose mode for the output refer to the Audit logging format and mode section.

Audit log message character encoding​

Audit log messages are recorded one per line in US-ASCII character encoding. Parameter values within these messages utilize a variant of the RFC 3986 URL encoding scheme (%) to represent special and reserved characters.

Parameter values are UTF-8 encoded to octet streams that are subsequently percent-encoded as needed.

Basically, the logger will do a URL encoding of the value of every parameter but will exclude the following characters from the encoding:

"|", "~", "!", "#", "$", "&", "'", "(", ")", "*", "+", "/", ":", ";", "?", "@", "[", "]", "-", ".", "<", ">", "\", "^", "_", "`"

Audit log samples​

Evaluation event log - concise mode​

This snippet showcases a sample log entry in the default concise mode while the table below explains each line in detail.

{
  "DomainId": "4f1c96e8-9749-4233-b170-9560c5905904",
  "ClientIdentity": "Username%3A+ads-user",
  "ClientSource": "172.0.0.1:53633",
  "Request": {
    "Category": [
      {
        "CategoryId": "AccessSubject",
        "Attribute": [
          {
            "AttributeId": "urn:oasis:names:tc:xacml:1.0:subject:subject-id",
            "Value": "Alice"
          }
        ]
      }
    ],
    "XPathVersion": "http://www.w3.org/TR/1999/REC-xpath-19991116"
  },
  "Response": [
    {
      "Decision": "Permit",
      "Call": [
        {
          "attribute": {
            "Id": "location",
            "Category": "AccessSubject",
            "Datatype": "string"
          },
          "Values": [
            "Stockholm"
          ]
        },
        {
          "attribute": {
            "Id": "role",
            "Category": "AccessSubject",
            "Datatype": "string"
          },
          "Values": [
            "QA"
          ]
        },
        {
          "attribute": {
            "Id": "department",
            "Category": "AccessSubject",
            "Datatype": "string"
          },
          "Values": [
            "Engineering"
          ]
        }
      ]
    }
  ]
}
LineDescription
2The ID of the Authorization Domain.
3The identity of the caller. If ADS is started without authentication, this line will be excluded.
4IP address and port number of the calling PEP.
5-18The XACML request evaluated by ADS.
21The XACML decision (Permit, Deny, Not applicable, Indeterminate)
22-53Details regarding attribute Values, fetched from an Attribute Connector and utilized in the evaluation. The attribute object specifies the ID, category, and datatype of the attributes to which these values correspond to, where:
Id - the id of the attribute
Category - the XACML category of the attribute
Datatype - the XACML datatype

Evaluation event log - verbose mode​

The following snippet showcases a sample log entry in verbose mode while the table below explains each line in detail.

{
  "DomainId": "4f1c96e8-9749-4233-b170-9560c5905904",
  "GroupVersion": "0",
  "ClientIdentity": "Username%3A+ads-user",
  "ClientSource": "172.0.0.1:53633",
  "EvaluationTimeMillis": 343,
  "InterfaceType": "REST",
  "PdpIdentity": "",
  "Request": {
    "Category": [
      {
        "CategoryId": "AccessSubject",
        "Attribute": [
          {
            "AttributeId": "urn:oasis:names:tc:xacml:1.0:subject:subject-id",
            "Value": "Alice"
          }
        ]
      }
    ],
    "XPathVersion": "http://www.w3.org/TR/1999/REC-xpath-19991116"
  },
  "Pips": [
    {
      "refId": "P1",
      "Id": "318ce3f1-c4dd-4540-be17-73766fe9afed",
      "Type": "com.axiomatics.attributeconnector.ldap.LDAPAttributeFinder",
      "Version": "0"
    },
    {
      "refId": "P2",
      "Id": "13371bff-a2db-4e17-9dba-166747dfd047",
      "Type": "com.axiomatics.attributeconnector.jdbc.SQLAttributeFinder",
      "Version": "0"
    },
    {
      "refId": "P3",
      "Id": "3c629267-2cda-4c91-bb14-ccc272c1d94e",
      "Type": "com.axiomatics.attributeconnector.table.TableAttributeFinder",
      "Version": "0"
    }
  ],
  "Attributes": [
    {
      "refId": "A3",
      "Id": "department",
      "Category": "urn:oasis:names:tc:xacml:1.0:subject-category:access-subject",
      "Datatype": "http://www.w3.org/2001/XMLSchema#string"
    },
    {
      "refId": "A1",
      "Id": "location",
      "Category": "urn:oasis:names:tc:xacml:1.0:subject-category:access-subject",
      "Datatype": "http://www.w3.org/2001/XMLSchema#string"
    },
    {
      "refId": "A2",
      "Id": "role",
      "Category": "urn:oasis:names:tc:xacml:1.0:subject-category:access-subject",
      "Datatype": "http://www.w3.org/2001/XMLSchema#string"
    }
  ],
  "Response": [
    {
      "Decision": "Permit",
      "Call": [
        {
          "attribute": {
            "Id": "location",
            "Category": "AccessSubject",
            "Datatype": "string"
          },
          "pipRef": "P1",
          "cachedValue": false,
          "Values": [
            "Stockholm"
          ]
        },
        {
          "attribute": {
            "Id": "role",
            "Category": "AccessSubject",
            "Datatype": "string"
          },
          "pipRef": "P2",
          "cachedValue": false,
          "Values": [
            "QA"
          ]
        },
        {
          "attribute": {
            "Id": "department",
            "Category": "AccessSubject",
            "Datatype": "string"
          },
          "pipRef": "P3",
          "cachedValue": false,
          "Values": [
            "Engineering"
          ]
        }
      ],
      "EvaluationComplexity": 26
    }
  ]
}
LineDescription
2The ID of the Authorization Domain.
3The object version of the Authorization Domain.
4The identity of the caller. If ADS is started without authentication, this line will be excluded.
5IP address and port number of the calling PEP.
6Evaluation time in milliseconds for this request.
7The interface by which the client contacts ADS for authorization services.
8Identity of the PDP as registered in ASM. For ADS this is always an empty string.
23-42The definition of an Attribute Connector that was called during evaluation, where:
refId - The evaluation unique identifier as referenced by the Call element in this evaluation to denote this Attribute Finder
Id - The unique identifier of the Attribute Connector object
Type - The Attribute Connector Type
Version - The object version of the Attribute Connector
43-62The definition of an external Attribute that was used during evaluation and for which values were fetched from an Attribute Finder (PIP), where
refId - The evaluation unique identifier as referenced by the Call element in this evaluation to denote this attribute
Id - the id of the attribute
Category - the XACML category of the attribute
Datatype - the XACML datatype
63-94The XACML result of the evaluation.
65The XACML Decision (Permit, Deny, Not applicable, Indeterminate)
66-103Details regarding attribute Values, fetched from an Attribute Connector and utilized in the evaluation.
The attribute object specifies the ID, category, and datatype of the attributes to which these values correspond to, where:
Id - the id of the attribute
Category - the XACML category of the attribute
Datatype - the XACML datatype
The attribute pipRef refers to the Attribute Connector these values were fetched from.
The attribute cachedValue indicates whether these values were obtained from the cache.
104A metric indicating the complexity of the evaluation process, measured by the number of steps required.

Administrative event log example​

The following text is a sample log entry for an administrative event, with explanations provided in the table below:

"thread":"main","message":"Domain with id 08922b78-48f7-4147-b9eb-ae0034b6ccd0 was loaded","level":"INFO","timestamp":1629726715756,"logger":"com.axiomatics.audit.ads.admin"
ItemDescription
threadWhich thread of the log stream this entry belongs to.
messageThe event that was logged.
levelThe severity level set for the logging configuration.
timestampThe time of the event.
loggerThe logger that produced the event.

Administrative event log description

note

There is only one version of the output, the concise/verbose option is only relevant for evaluation events.