Logging for Authorize gateway instances

Configure logging to help manage, troubleshoot, and optimize your gateway instances.

Log filtering

To enhance security, gateway instances filter certain keywords from logs by default. This prevents credentials and other sensitive information from being exposed in log entries.

Gateway instances omit log entries that contain the following case-insensitive keywords:

defaultSharedSecret
sharedSecret
ASN1
password

For debugging, you can disable filtering to include sensitive data in the logs. To override the default behavior, add the logging.allowSensitiveMaterial property to your gateway instance configuration and set it to true:

{
  "logging": [
    {
      "allowSensitiveMaterial": true
    }
  ]
}

Decision logging

Decision logging provides detailed insights into how a 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 invoked 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

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.

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.

Example

The following decision 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}}"
  }
}'

With the above decision request and the decisionTree logging view enabled, debugLog records 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 evaluates 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

Slow responses from information points can delay policy evaluations or lead to incorrect access decisions. Service call logs help diagnose information point degradation by providing insight into service latency and availability.

By default, gateway instances log:

External service calls in the SERVICE_AUDIT component
PingOne service calls in the PINGONE_SERVICE_AUDIT component
The gateway instance logs PingOne service calls when policies use:
- Attributes resolved from the built-in PingOne.User attribute
- Is Member Of and Is Not Member Of condition comparators

The gateway instance records an additional log entry if it uses a cached service value in an authorization decision.

Examples

External service call logs

The following examples show SERVICE_AUDIT log entries generated for various service call results.

HTTP 200; level=INFO (successful 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 (authorization failure)

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 (rate limit exceeded)

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 (service unresponsive)

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

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

PingOne service call logs

The following examples show PINGONE_SERVICE_AUDIT log entries generated by PingOne service calls for group membership checks.

HTTP 200; level=INFO (successful call)

2025-06-16T14:58:33.651Z level=INFO  thread=DefaultServiceExecution-IS_MEMBER_OF0-0 component=PINGONE_SERVICE_AUDIT decisionRequestId=5ef633c4-1271-4a35-acaf-10faa1ef891b exchangeId=_490Jq7opXV0DARGr4eJmA |  HTTP service call: name=IS_MEMBER_OF0, method=GET, host=api.pingone.com, duration=358ms, configuredTimeout=1000ms, status=HTTP/2 200

HTTP 4XX, 5XX; level=INFO (authorization failure)

2025-06-16T14:30:28.770Z level=INFO  thread=DefaultServiceExecution-IS_MEMBER_OF0-0 component=PINGONE_SERVICE_AUDIT decisionRequestId=02e41d1b-cd69-4a26-9f7e-bc1434fed11a exchangeId=FWNNUYSYL5toYfmFFXTHEw |  Error invoking HTTP service: name=IS_MEMBER_OF0, method=GET, host=api.pingone.com, duration=288ms, configuredTimeout=1000ms, error=Got unsuccessful client error code: 403 body: {
  "id" : "4614c4fa-b7b1-4977-8134-5dbecffeb494",
  "code" : "ACCESS_FAILED",
  "message" : "The actor attempting to perform the request is not authorized."
}

HTTP 429; level=WARN (rate limit exceeded)

2026-06-16T11:45:50.598Z level=WARN  thread=DefaultServiceExecution-IS_MEMBER_OF0-0 component=PINGONE_SERVICE_AUDIT decisionRequestId=d63629cc-d61f-41e7-8e68-52298a83b533 exchangeId=Wx-T-oESN6uxNRYeu158Tg |  HTTP service call: name=IS_MEMBER_OF0, method=GET, host=api.pingone.com, duration=358ms, configuredTimeout=1000ms, error=com.pingidentity.authorize.serviceexecution.ClientServiceExecutionException: Got unsuccessful status code: 429, with body: {
  "message": "Rate limit exceeded"
}

level=WARN (service unresponsive)

2024-10-03T11:50:19.540Z level=WARN  thread=DefaultServiceExecution-IS_MEMBER_OF0-0 component=PINGONE_SERVICE_AUDIT decisionRequestId=0c907d84-f70d-4c82-893c-a8d0810bae37 exchangeId=jRPBjiXKEFoL06BuOjGieg |  Error invoking HTTP service: name=IS_MEMBER_OF0, method=GET, host=api.pingone.com, duration=358ms, configuredTimeout=1000ms

PingOne service cache hit

2025-06-17T15:15:43.095Z level=INFO  thread=DefaultServiceExecution-IS_MEMBER_OF0-0 component=PINGONE_SERVICE_AUDIT decisionRequestId=21891fbe-1789-4704-a414-25750392d3b0 exchangeId=3zGbrjik4BgSYEFk4g1SsA |  Cache hit for PingOne service: name=IS_MEMBER_OF0, cacheKey=B8153ECDBA957D9C36447FDCEC53CEC9, host=api.pingone.com

PingOne connection logging

Gateway instances maintain a WebSocket Secure connection with the PingOne platform. When this connection fails, the gateway instance logs error messages describing the issue.

Connection failures can occur when:

The network is unavailable, blocked by a firewall, or otherwise misconfigured on the client side.
The Authorize gateway associated with the gateway instance has been deleted.
The gateway credential associated with the gateway instance has been deleted.

When the gateway instance loses connection, it logs an initial message like the following:

2025-07-23T17:22:36.340Z level=WARN
thread=Ensure connected to all regions daemon thread.
component=c.p.l.s.g.WebSocketClientManager  |
Failed to send 'gatewayConnectionConfiguration' message over the websocket
org.eclipse.jetty.websocket.api.exceptions.WebSocketException:
Could not connect to websocket server after 146 ms, location=us-east-2

If the connection isn’t restored, the gateway instance periodically logs messages like the following:

Caused by: java.util.concurrent.CompletionException: org.eclipse.jetty.websocket.api.exceptions.UpgradeException: org.eclipse.jetty.websocket.core.exception.UpgradeException: Failed to upgrade to websocket: Unexpected HTTP Response Status Code: 403 Forbidden

To restore connectivity:

Verify that your network configuration allows outbound WebSocket connections to the relevant PingOne region endpoint. Learn more in Gateway access.

Verify that the associated Authorize gateway still exists and that the gateway credential hasn’t been deleted.

If the gateway has been deleted, create a new Authorize gateway, generate a new gateway credential, and restart the gateway instance with the new credential.

When you restart a gateway instance, it uses the authorization policy version configured for the associated Authorize gateway. If this version differs from the one currently published to the gateway instance, the published version is replaced.

If the gateway instance can’t establish a connection to PingOne at startup, you must restart the gateway instance after resolving the underlying issue.

The gateway instance can automatically restore its connection without manual intervention after temporary network interruptions.