Authorize Log Fields
Summary
The Authorize Log Fields setting controls which fields will be included in the authorize logs. For each incoming request, the authorize service will emit a log entry with the message authorize check
containing the policy evaluation result and these additional log fields.
The default log fields should be appropriate for most deployments.
How to configure
- Core
- Enterprise
- Kubernetes
Config file key | Environment variable | Type | Default |
---|---|---|---|
authorize_log_fields | AUTHORIZE_LOG_FIELDS | Array of strings | See Authorize Fields and Defaults |
Examples
authorize_log_fields:
- request-id
- path
- ip
AUTHORIZE_LOG_FIELDS=request-id,path,ip
Headers examples:
# List all HTTP headers
authorize_log_fields:
- headers
AUTHORIZE_LOG_FIELDS=headers
# List custom HTTP headers
authorize_log_fields:
- headers.cookie
- headers.content-type
AUTHORIZE_LOG_FIELDS=headers.cookie,headers.content-type
Configure Authorize Log Fields in the Console:
Add Custom Headers in the Console:
Parameter name | Type | Default |
---|---|---|
authorizeLogFields | Array of strings | See Authorize Fields and Defaults |
Examples
authorizeLogFields:
- request-id
- path
- ip
Authorize log fields and defaults
The table below lists all available authorize log fields:
Field name | Description | Default field |
---|---|---|
check-request-id | The request ID of the gRPC check call | Yes |
email | The logged-in user's email address | Yes |
headers | The complete set of HTTP request headers | No |
* headers.{CustomHeaderName} | An HTTP Request Header identified by the HeaderName | No |
host | The HTTP request :authority or Host header value. Can be a domain name or IP address and may contain a port number (for example, www.example.com ) | Yes |
id-token | The user's ID token | No |
id-token-claims | The user's ID token claims | No |
impersonate-email | If impersonating, the impersonated email | Yes |
impersonate-session-id | If impersonating, the impersonated session ID | Yes |
impersonate-user-id | If impersonating, the impersonated user ID | Yes |
ip | The IP address of the direct downstream client. If Pomerium is deployed behind a load balancer or other proxy, this will not be the IP address of the end user. | Yes |
method | The HTTP request method, such as GET , POST , or PUT | Yes |
path | The HTTP request path (for example, /some/path ) | Yes |
query | The HTTP request query (for example, ?test=one&other=13 ) | No |
request-id | The request's unique identifier as assigned by Pomerium | Yes |
service-account-id | if using a service account, the service account ID | Yes |
session-id | the session ID | Yes |
user | The user's ID | Yes |
* The headers.{CustomHeaderName}
field is only available in Core and Enterprise, not Kubernetes.
Query parameters often contain sensitive information. Do not enable the query
log field without careful consideration.
Authorize log behavior
Find authorize logs
To find logs from the authorize service, filter your Pomerium logs for entries containing "message": "authorize check"
:
{
"level":"info",
"service":"authorize",
"request-id":"f55d5fd5-2d6c-42d1-a7f6-007ad7ec3a85",
"check-request-id":"f55d5fd5-2d6c-42d1-a7f6-007ad7ec3a85",
"method":"POST","path":"/pomerium.dashboard.KeyChainService/ListKeyPairs",
"host":"console.localhost.pomerium.io",
"ip":"127.0.0.1",
"session-id":"45445311-b287-4476-b17e-d5a8965ff3f4",
"user":"google-oauth2|XXXXXXXXXXXXXXXXXXXXX",\
"email":"example@pomerium.com",
"allow":true,
"allow-why-true":["domain-ok"],
"deny":false,"deny-why-false":[],
"time":"2023-08-07T09:48:03-04:00",
"message":"authorize check"
}
Display specific logs
If authorize_log_fields
is not defined, all the available default fields will be logged.
To log only a specific field, or multiple fields, add the desired field(s) to your configuration file.
For example, if you add the following fields to authorize_log_fields
:
authorize_log_fields:
- request-id
- method
- path
Your logs would look similar to the below example:
{
"level": "info",
"service": "authorize",
"request-id": "c9afae5a-ec5a-4242-864f-df4189f20e99",
"method": "GET",
"path": "/index.css",
"allow": true,
"allow-why-true": ["domain-ok"],
"deny": false,
"deny-why-false": [],
"time": "2023-08-07T10:26:33-04:00",
"message": "authorize check"
}
Log authorize HTTP headers
To get a list of all authorize HTTP headers, add the headers
option:
authorize_log_fields:
- headers
Your logs would look similar to the example below:
{
"level": "info",
"service": "authorize",
"headers": {
":authority": "verify.localhost.pomerium.io",
":method": "GET",
":path": "/api/verify-info",
":scheme": "https",
"Accept": "*/*",
"Accept-Encoding": "gzip, deflate, br",
"Accept-Language": "en-US,en;q=0.9",
"Content-Type": "application/json",
"Cookie": "_pomerium=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhYnJva2VyX3JlY29yZF92ZXJzaW9uIjozMTQwLCJkYXRhYnJva2VyX3NlcnZlcl92ZXJzaW9uIjo3OTM4MDg0ODcsImlhdCI6MTY5MTQxODM5MiwianRpIjoiMTcyZTQ1NTEtZTllYi00ZmUwLWE2Y2UtMjQ0NWM3NjA0MGJkIiwic3ViIjoiZ29vZ2xlLW9hdXRoMnwxMTU0MjA2NjQ3MjYxODMzMjM3NTgifQ.ktq6oFtiBiGwNsU-5DQzLNTszexFhyNl1Iz4kc_Uq2M",
"Referer": "https://verify.localhost.pomerium.io/",
"Sec-Ch-Ua": "\"Not/A)Brand\";v=\"99\", \"Google Chrome\";v=\"115\", \"Chromium\";v=\"115\"",
"Sec-Ch-Ua-Mobile": "?0",
"Sec-Ch-Ua-Platform": "\"macOS\"",
"Sec-Fetch-Dest": "empty",
"Sec-Fetch-Mode": "cors",
"Sec-Fetch-Site": "same-origin",
"User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36",
"X-Envoy-Internal": "true",
"X-Forwarded-For": "XXX.XXX.X.XXX",
"X-Forwarded-Proto": "https",
"X-Request-Id": "d6c95dd6-9f3c-4653-94d1-62ea54b11328"
},
"allow": true,
"allow-why-true": ["domain-ok"],
"deny": false,
"deny-why-false": [],
"time": "2023-08-07T10:32:03-04:00",
"message": "authorize check"
}
Log custom headers fields
The headers.{CustomHeaderName}
field allows you to enter custom headers. Adding one or multiple custom headers will display only those headers.
For example, if you add the following custom headers to authorize_field_logs
:
authorize_log_fields:
- headers.Cookie
- headers.content-type
The custom headers will appear in the headers
field:
{
"level": "info",
"service": "authorize",
"headers": {
"Content-Type": "application/json",
"Cookie": "_pomerium=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhYnJva2VyX3JlY29yZF92ZXJzaW9uIjozMTQwLCJkYXRhYnJva2VyX3NlcnZlcl92ZXJzaW9uIjo3OTM4MDg0ODcsImlhdCI6MTY5MTQxODM5MiwianRpIjoiMTcyZTQ1NTEtZTllYi00ZmUwLWE2Y2UtMjQ0NWM3NjA0MGJkIiwic3ViIjoiZ29vZ2xlLW9hdXRoMnwxMTU0MjA2NjQ3MjYxODMzMjM3NTgifQ.ktq6oFtiBiGwNsU-5DQzLNTszexFhyNl1Iz4kc_Uq2M"
},
"allow": true,
"allow-why-true": ["domain-ok"],
"deny": false,
"deny-why-false": [],
"time": "2023-08-07T10:40:38-04:00",
"message": "authorize check"
}
Log ID tokens and claims
Adding id-token
or id-token-claims
will print these values to stdout.
If specified, the id-token
option displays the user's ID token received from the identity provider. id-token-claims
displays the claims contained in the ID token.
For example, if you add id-token
and id-token-claims
:
authorize_log_fields:
- id-token
- id-token-claims
Your logs would look similar to the below example:
{
"level": "info",
"service": "authorize",
"id-token": "<ID-TOKEN>",
"id-token-claims": {
"aud": "XmDTct9PHNsMRxKxCIObqWnmnEJLguPQ",
"email": "example@pomerium.com",
"email_verified": true,
"exp": 1691452058,
"family_name": "Painter",
"given_name": "Zachary",
"iat": 1691416058,
"iss": "https://dev-XXXXXXXXXXXXXXXX.us.auth0.com/",
"locale": "en",
"name": "Zachary Painter",
"nickname": "XXXXXXXX",
"picture": "https://lh3.googleusercontent.com/a/XXX=s96-c",
"pomerium.io/groups": ["admin"],
"sid": "L_tMPjzHdHKd6q1NjGdHERgSdWUUZF1b",
"sub": "google-oauth2|XXXXXXXXXXXXXXXXXXXXX",
"updated_at": "2023-08-03T17:44:00.171Z"
},
"allow": true,
"allow-why-true": ["domain-ok"],
"deny": false,
"deny-why-false": [],
"time": "2023-08-07T10:43:36-04:00",
"message": "authorize check"
}