Skip to main content

Audit logs

Pomerium provides verbose logging to help users audit, manage, and troubleshoot their configurations. The amount of logs output can be overwhelming, so on this page we'll cover how to sort for and understand logs from the authorization service. These logs often provide the most helpful information when first configuring Pomerium.

Find Logs​

The command to display Pomerium's logs will depend on your installation method:

sudo journalctl -u pomerium.service

The -f flag can also be provided to show new logs as they are generated.

Filter Logs​

To filter log output to just the Authorize service logs, we can pipe (|) the output through grep:

sudo journalctl -u pomerium.service | grep '"service":"authorize"'

Formatted Logs​

To better parse the logs, you can install jq and use another pipe to pass the content through it:

kubectl logs -f deploy/pomerium-authorize | grep '"service":"authorize"' | jq
{
  "level": "info",
  "service": "authorize",
  "request-id": "46747f58-...",
  "check-request-id": "7700fe70-a166-406c-a326-48f433029f98",
  "method": "GET",
  "path": "/",
  "host": "grafana.example.com",
  "query": "",
  "session-id": "46b36e11...",
  "allow": false,
  "allow-why-false": ["claim-unauthorized", "non-pomerium-route"],
  "deny": false,
  "deny-why-false": ["valid-client-certificate-or-none-required"],
  "user": "941b0719-...",
  "email": "alex@example.com",
  "databroker_server_version": ...,
  "databroker_record_version": ...,
  "time": "2022-05-16T18:18:55Z",
  "message": "authorize check"
}

Authorization Log Keys​

The keys described below usually contain the relevant information when debugging an authorization issue:

KeyDescription
#allowIf true, at least one allow rule passed. As long as deny is false, the request will be allowed.
#allow-why-false & allow-why-trueThe short reason strings why access was allowed (or not allowed).

In the example output above, claim-unauthorized means that there was a policy rule on a claim that didn't pass.

non-pomerium-route means that it was not a request to /.pomerium/, which is allowed for any authenticated user.
#denyIf true it means that at least one deny rule passed, and the request will be denied.
#deny-why-false & deny-why-trueThe short reason strings why access was denied (or not denied).

In the example above, valid-client-certificate-or-none-required means that either a valid client certificate was provided, or the policy didn't require one. By default pomerium policies have this PPL rule added to them. It's how we implement client certificates.
#databroker_server_version & databroker_record_versionThese values are used for auditing. With these version numbers and a complete history of all changes in the databroker, you can determine what data was used for policy evaluation.

Understanding Authorization Logs​

The most confusing keys for new users to understand are likely allow-why-false and deny-why-false. To better understand them, we should first discuss how Pomerium Policy Language (PPL) works.

PPL allows a request to a route if the claim matches at least one allow policy rule, and matches zero deny policy rules. With that in mind, allow-why-false and allow-why-true will describe a situation where the request either does or not not meet the requirements of an allow block a policy applied to that route. Conversely, deny-why-true and deny-why-false will describe why a request did or did not match a deny block for a policy assigned to the route.