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:

System Daemon

sudo journalctl -u pomerium.service

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

Docker

docker logs pomerium

The container name will depend on your configuration. The -f flag can also be provided to show new logs as they are generated.

Kubernetes

kubectl logs -f deploy/pomerium-authorize

The deployment name will depend on your configuration. 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:

System Daemon

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

Docker

docker logs pomerium | grep '"service":"authorize"'

Kubernetes

kubectl logs -f deploy/pomerium-authorize | 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": [],
  "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:

Key	Description
#allow	If true, at least one allow rule passed. As long as deny is false, the request will be allowed.
#allow-why-false & allow-why-true	The 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.
#deny	If true it means that at least one deny rule passed, and the request will be denied.
#deny-why-false & deny-why-true	The short reason strings why access was denied (or not denied).
#databroker_server_version & databroker_record_version	These 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.