PingOne

Logging for Authorize gateway instances

Configure decision and service logging to help manage, troubleshoot, and optimize your Authorize gateway policies.

Decision logging

Decision logging provides detailed insights into how an Authorize gateway instance evaluates requests and makes decisions.

By default, decision log entries are written to the Docker container’s console and include high-level details about attributes, services, and policy elements evaluated in the decision.

For example:

2025-01-15T19:20:50.374Z [auditLog]
{
  "id":"2e1cba8f-a4a7-41a8-8a50-301930c3e720",
  "authorizationVersion":{"id":"b60fbd90-85e3-11ef-9451-b72251ed6dd8"},
  "timestamp":"2025-01-15T19:20:49.972105346Z",
  "elapsedMicroseconds":239714,
  "decision":"PERMIT",
  "authorized":true,
  "statements":[],
  "status":{"code":"OKAY","messages":[], "errors":[]}
  "evaluationLog":[{"id":"91d191af-e0ec-422f-a7f7-fce227ed60b7","type":"Attribute","name":"Amount","outcome":{"value":"Resolved","isSuccess":true},"parent":"e2e47b75-8d9d-417b-a652-cc5d604c22da","elapsedTime":8700},{"id":"e2e47b75-8d9d-417b-a652-cc5d604c22da","type":"Rule","name":"Permit payments up to 10000 USD","outcome":{"value":"PERMIT","isSuccess":true},"parent":"622eadcc-e87e-4109-a7e9-9c229bb14e61","elapsedTime":13935},{"id":"28272483-72ec-4f00-bc91-6f90aa0159ad","type":"Rule","name":"Deny payments above 1000 USD","outcome":{"value":"NOT_APPLICABLE","isSuccess":true},"parent":"622eadcc-e87e-4109-a7e9-9c229bb14e61","elapsedTime":1053},{"id":"622eadcc-e87e-4109-a7e9-9c229bb14e61","type":"Policy","name":"Payment checks","outcome":{"value":"PERMIT","isSuccess":true},"parent":"b0c75c6b-3212-4042-b0a0-e3005d557b4f","elapsedTime":16008},{"id":"b0c75c6b-3212-4042-b0a0-e3005d557b4f","type":"PolicySet","name":"Policies","outcome":{"value":"PERMIT","isSuccess":true},"elapsedTime":21815}]
}

To more easily consume logs, you can stream log data from the gateway instance to external destinations like Kafka or Splunk.

When developing and testing authorization policies published to gateway instances, you can configure the granularity of decision log views for enhanced visibility into which policies and rules were evaluated and which attributes or services were consumed in the process.

Decision logging configuration

Using one of the available configuration methods, pass the decision-logging JSON object into your gateway instance and override the default logging configuration.

Example decision-logging configuration object:

{
  "decision-logging": [
    {
      "name": "auditLog",
      "details": ["evaluationLog", "services", "request"],
      "logged-attributes": ["Amount","Payment.consentId"],
      "logFormat": "%date{yyyy-MM-dd'T'HH:mm:ss.SSSXXX,UTC} [%logger] %msg%n"
    }
  ]
}

Configuration properties for the decision-logging object:

  • name (required): A unique name for the logger.

    Add this name to each log entry by including the %logger tag in the log-format configuration property.

  • details (required): An array of logging views. Logging views determine the granularity of log entry data.

    You can include the following logging views in this array:

    Logging view Description

    request

    Includes the full decision request object.

    statements

    Includes any statements attached to the decision response.

    errors

    Includes any errors returned in the status field of the decision response.

    attributes

    Includes detailed resolution and value processing information for any attributes evaluated in the decision.

    By including this view, you can see attribute data after clicking the Attributes tab in the Decision Visualizer. Learn more in Visualizing decisions made by Authorize gateway instances.

    services

    Includes details for services invoked during policy evaluation.

    By including this view, you can see service data after clicking the Services tab in the Decision Visualizer. Learn more in Visualizing decisions made by Authorize gateway instances.

    evaluationLog

    Includes a list of policy elements evaluated in the decision.

    decisionTree

    Includes details for the evaluation flow of the policy tree.

    Selecting the request, attributes, or services logging views might log sensitive and personally identifiable information (PII). Enable these views only during testing and disable them afterward.

  • logged-attributes (optional): An array of full names of attributes whose data type and value you want to be logged.

    If included, this property overrides configuration of the attributes logging view.

    To obtain an attribute’s full name, click the hamburger menu next to the attribute and select Copy full name to clipboard.

  • log-format (optional): A string defining the format for log entries.

    If no format is specified, the log format defaults to "%date{yyyy-MM-dd’T’HH:mm:ss.SSSXXX,UTC} [%logger] %msg%n".

    For example:

    2024-10-08-T22:16:51.239Z

    Learn more about customizing the log format in the logback documentation.

Examples

The following request asks whether the client is authorized to deposit 990 USD into a basic checking account:

curl --location 'http://localhost:8080/api/authorize' \
  --header 'Authorization: Bearer example-secret' \
  --header 'Content-Type: application/json' \
  --data '
{
  "parameters": {
    "Amount": "990",
    "Account": "Basic checking",
    "Payment.consentId": "{{consentID}}"
  }
}'

Given the sample configuration defined in step 2 and the above request, debugLog produces the following entry:

[2024-08-13 15:29:56,748]
{
  "id": "cda6fd43-e9ae-49de-b822-7479ef2f2b35",
  "deploymentPackageId": "42b99394-cbb0-46f9-8b9d-bca15cde330e",
  "timestamp": "2024-08-13T10:48:45.344117Z",
  "elapsedTime": 649161,
  "decision": "PERMIT",
  "authorised": true,
  "statements": [],
  "decisionTree": {
    "id": "9cf53282-0443-44a3-895a-1c413e190177",
    "nodeType": "PolicySet",
    "name": "Policies",
    "targets": [],
    "elapsedTime": 19914,
    "combiningAlgorithm": "FirstApplicable{}",
    "decision": "PERMIT",
    "attributes": {
        "Amount": {
            "id": "1a89a7b2-6034-48fa-ad45-6bb68e454bb5",
            "name": "Amount",
            "successful": "true",
            "elapsedTime": 0,
            "value": "permit",
            "type": "NUMBER"
        }
    }
    "applicableChildren": {
      "Payment checks": {
        "id": "014fa703-b5a4-4820-8744-2cb0c715fcfd",
        "nodeType": "Policy",
        "name": "Payment checks",
        "sequence": 1,
        "targets": [],
        "elapsedTime": 14765,
        "combiningAlgorithm": "FirstApplicable{}",
        "decision": "PERMIT",
        "applicableChildren": {
          "Permit payments up to 1000 USD": {
            "id": "1b9fd38e-5713-48f4-9bf1-5ea8d7b98493",
            "nodeType": "Rule",
            "name": "Permit payments up to 1000 USD",
            "sequence": 1,
            "targets": [],
            "elapsedTime": 13637,
            "decision": "PERMIT",
            "condition": {
              "less than or equal": {
                "lhs": {
                  "id": "1a89a7b2-6034-48fa-ad45-6bb68e454bb5",
                  "name": "Amount",
                  "value": 990,
                  "type": "NUMBER"
                },
                "rhs": {
                  "value": 1000,
                  "type": "NUMBER"
                }
              },
              "result": {
                "value": "true",
                "type": "BOOLEAN"
              }
            },
            "statements": []
          }
        },
        "statements": []
      }
    },
    "statements": []
  }
}

Using decision log entries, you can visualize the decision flow and other details about recent decisions to make sure the gateway instance is evaluating policies according to your expectations. Learn more in Visualizing decisions made by Authorize gateway instances.

Although you can define multiple decision loggers, this isn’t recommended for performance reasons.

Service call logging

When information points are slow to respond, it can lead to delays in evaluating policies or incorrect access decisions. Service call logs can help diagnose information point degradation by providing insight into service latency and availability.

By default, the Authorize gateway instance logs external service calls in the SERVICE_AUDIT component. The gateway instance will produce an additional log entry if the service response value is retrieved from a cache.

Examples

The following examples show SERVICE_AUDIT log entries for different types of service call results.

HTTP 200; level=INFO

The following example shows a SERVICE_AUDIT log entry for a successful HTTP service call:

2024-10-03T11:42:13.204Z level=INFO  thread=DefaultServiceExecution-Http Service-0 component=SERVICE_AUDIT decisionRequestId=0e70aec0-ba0d-42a5-bfd9-673538b0a8be exchangeId=J9ggyeMm8utrLivF9fj-dw |  HTTP service call: name=Payment Service, host=192.168.7.106, duration=14ms, configuredTimeout=2000ms, status=HTTP/1.1 200 OK

HTTP 4XX, 5XX; level=INFO

The following example shows a SERVICE_AUDIT log entry for an unsuccessful HTTP service call, due to a lack of authorization:

2024-10-03T11:47:48.280Z level=INFO  thread=DefaultServiceExecution-Http Service-0 component=SERVICE_AUDIT decisionRequestId=a2bbdc25-5d15-4cfc-84b0-0ccf9378ce68 exchangeId=Yvg-p4Lyq2CKD2fsSHE7eQ |  Error invoking HTTP service: name=Payment Service, host=192.168.7.106, duration=5ms, configuredTimeout=2000ms, error=com.pingidentity.authorize.serviceexecution.ClientServiceExecutionException: Got unsuccessful status code: 401, with body: {
  "message": "Unauthorized"
}

HTTP 429; level=WARN

The following example shows a SERVICE_AUDIT log entry for an unsuccessful HTTP service call, due to rate limits:

2024-10-03T11:45:50.598Z level=WARN  thread=DefaultServiceExecution-Http Service-0 component=SERVICE_AUDIT decisionRequestId=d63629cc-d61f-41e7-8e68-52298a83b533 exchangeId=Wx-T-oESN6uxNRYeu158Tg |  Error invoking HTTP service: name=Payment Service, host=192.168.7.106, duration=14ms, configuredTimeout=2000ms, error=com.pingidentity.authorize.serviceexecution.ClientServiceExecutionException: Got unsuccessful status code: 429, with body: {
  "message": "Too Many"
}

level=WARN

The following example shows a SERVICE_AUDIT log entry for an unsuccessful service call, due to the service timing out:

2024-10-03T11:50:19.540Z level=WARN  thread=DefaultServiceExecution-Payment Service-0 component=SERVICE_AUDIT decisionRequestId=0c907d84-f70d-4c82-893c-a8d0810bae37 exchangeId=jRPBjiXKEFoL06BuOjGieg |  Error invoking HTTP service: name=Payment Service, host=192.168.7.106, duration=2004ms, configuredTimeout

Service cache hit

The following example shows a SERVICE_AUDIT log entry for a successful service cache hit:

2024-10-04T11:58:19.540Z level=INFO thread=DefaultServiceExecution-RandomUserService-0 component=SERVICE_AUDIT decisionRequestId=b7034567-08da-499g-9b1a-926b8571d565 exchangeId=85sC5rqIn_bPfvnU2u5Mgg | Cache hit for Payment Service: name=PaymentService, cacheKey=3c21d32a-c432-4cf4-99e1-f9e04f32134a_E02083C34EBC29E4A2CD378F4755728, host=localhost