# Policy Evaluation and Authorization Information in Logs

{% hint style="info" %}
This feature is part of the Enterprise plan. If it is not enabled for your organization, please contact StrongDM at the [StrongDM Help Center](https://help.strongdm.com/hc/en-us).
{% endhint %}

The `authz` object contains policy evaluation information for a given request made by a StrongDM user to a resource. The `authz` object can be found in StrongDM logs that pertain to user queries against resources. Specifically, it is located in either in the [Start](/admin/audit/logs/references/node-start.md) event type generated by nodes (gateways and relays), or in the [Query](/admin/audit/logs/references/logstream-queries.md) event type that can be consumed via Log Stream. It is only present if the query in question was evaluated by policies within your StrongDM organization.

The object is generally formatted as follows:

```json
{ 
    "formatVersion": "v1.0.0", 
    "entities": [], 
    "context": {}, 
    "requests": [], 
    "requirements": {},
    "decision": "allow" 
}
```

The fields that the `authz` object can contain are detailed in the following table.

| Field                            | Description                                                                                        |
| -------------------------------- | -------------------------------------------------------------------------------------------------- |
| [formatVersion](#format-version) | String containing the version number of the schema of the JSON `authz` object                      |
| [entities](#entities)            | JSON array of entities used to process the request                                                 |
| [context](#context)              | JSON object describing the context the evaluation was based on                                     |
| [requests](#requests)            | JSON array of Cedar requests evaluated for this query                                              |
| [requirements](#requirements)    | JSON object showing the requirements to complete this authorization                                |
| [decision](#decision)            | String containing "allow" or "deny" denoting the authorization decision from the policy evaluation |

### Format Version

The `formatVersion` field is the version number of the schema of the JSON `authz` object. This can be used to verify the version of the schema for scripts that depend on the particular schema of the object.

**Example formatVersion value:**

`v1.0.0`

### Entities

The `entities` field is a JSON array of entities that were used to process the request. The entities are stored here using the syntax provided in the [Cedar Entities JSON Specification](https://docs.cedarpolicy.com/auth/entities-syntax.html).

**Example entities value:**

```json
"entities": [
    {
        "uid": {
            "type": "Postgres::Database",
            "id": "rs-735d634e6690718e/web"
        },
        "parents": [
            {
                "type": "StrongDM::Resource",
                "id": "rs-735d634e6690718e"
            }
        ],
        "attrs": {
            "database": "web",
            "sdm": {
                "__entity": {
                    "type": "StrongDM::Resource",
                    "id": "rs-735d634e6690718e"
                }
            }
        }
    },
    {
        "uid": {
            "type": "StrongDM::Account",
            "id": "a-66c1524e6690718e"
        },
        "parents": [
            {
                "type": "StrongDM::Role",
                "id": "r-77ed01576690718e"
            }
        ],
        "attrs": {
            "accountType": "user",
            "email": "test@example.com",
            "externalId": "",
            "isManagedUser": false,
            "permissionLevel": "admin",
            "tags": {}
        }
    },
    {
        "uid": {
            "type": "StrongDM::Resource",
            "id": "rs-735d634e6690718e"
        },
        "attrs": {
            "tags": {
                "essential": "true"
            }
        }
    }
]
```

### Context

The `context` field is a JSON object describing the context of the request that the policy evaluation was based on. This context is stored here using the syntax provided in the [Cedar Context JSON Specification](https://docs.cedarpolicy.com/auth/entities-syntax.html). For more information on the individual context elements available in policies at StrongDM, see the [Policies](/admin/access/policies/policy-creation.md#context) section.

**Example context value:**

```json
"context": {
    "network": {
        "clientIp": {
            "__extn": {
                "fn": "ip",
                "arg": "::1"
            }
        },
        "destinationIp": {
            "__extn": {
                "fn": "ip",
                "arg": "127.0.0.1"
            }
        },
        "requestIp": {
            "__extn": {
                "fn": "ip",
                "arg": "127.0.0.1"
            }
        },
        "target": {
            "hostname": "db.example.com",
            "port": 5432
        }
    },
    "trust": {
        "ok": false,
        "status": "unknown"
    }
}
```

### Requests

The `requests` field is a JSON array of Cedar requests regarding this query. Each query log event may contain one or more requests.

* Each request contains the specific Principal, Action Resource, and Context (PARC) request elements as separate objects.
* The `context` object may contain information specific to that request which goes beyond the context supplied in the authz `context` field.
* Each request contains the `diagnostic` object which contains:
  * An array of `reasons` indicate which policies were relevant, and their position.
  * An array of `errors` indicate which policies had errors, their position, and error message.
  * If applicable, a list of `annotations` is also included, showing the annotations that were on any of the policies listed in `reasons`. Multiple policies can have the same annotation name, so each of the values will be in the array.
* Lastly each request contains a `decision` that is either "allow" or "deny".

**Example requests value:**

```json
"requests": [
    {
        "request": {
            "principal": {
                "type": "StrongDM::Account",
                "id": "a-66c1524e6690718e"
            },
            "action": {
                "type": "SQL::Action",
                "id": "select"
            },
            "resource": {
                "type": "Postgres::Database",
                "id": "rs-735d634e6690718e/web"
            },
            "context": {
                "network": {
                    "clientIp": {
                        "__extn": {
                            "fn": "ip",
                            "arg": "::1"
                        }
                    },
                    "destinationIp": {
                        "__extn": {
                            "fn": "ip",
                            "arg": "127.0.0.1"
                        }
                    },
                    "requestIp": {
                        "__extn": {
                            "fn": "ip",
                            "arg": "127.0.0.1"
                        }
                    },
                    "target": {
                        "hostname": "db.example.com",
                        "port": 5433
                    }
                },
                "sql": {
                    "qualifiedTables": [
                        "users",
                        "photos",
                        "albums",
                        "tags",
                        "photo_tags",
                        "comments"
                    ],
                    "qualifiedWriteTables": [],
                    "tables": [
                        "users",
                        "photos",
                        "albums",
                        "tags",
                        "photo_tags",
                        "comments"
                    ],
                    "writeTables": []
                },
                "trust": {
                    "ok": false,
                    "status": "unknown"
                }
            }
        },
        "diagnostic": {
            "reasons": [
                {
                    "policyId": "0",
                    "position": {
                        "filename": "po-460eac7b66e8af40.permit.cedar",
                        "offset": 2,
                        "line": 3,
                        "column": 1
                    }
                }
            ],
            "errors": [
                {
                    "policyId": "1",
                    "position": {
                        "filename": "po-7849329877843982.permit.cedar",
                        "offset": 56,
                        "line": 7,
                        "column": 1
                    },
                    "message": "error parsing ip value",
                }
            ],
            "annotations": {
                "justify": [
                    "?prompt=Justify.\u0026cache=15m"
                ]
            },
        },
        "decision": "allow"
    }
]
```

### Requirements

The `requirements` field is a JSON object showing the requirements to complete this authorization. This contains two fields:

* `requirements` is an array of requirements. Each requirement object contains:
  * A PARC `request` is included, made up of the four PARC elements (principal, action, resource, context).
  * The `values` shows the values of any annotations that were included.
  * The `ok` value indicates whether the request was successful.
  * In some cases a `reason` is supplied by the user in response to a justification request.
  * An `error` string may be captured here, explaining why the requirement was unfulfilled if it was not.
  * A `skipped` Boolean may be captured here. The requirement could be "skipped" if a previous requirement had an error, for example.
  * A `cached` Boolean may be captured here. A request can only be `"cached":true` if there was success, so there would never be an `error` alongside a value of `"cached":true`.
* The second field after the `requirements` array is an `error` string, which may be captured here if a higher level fatal error occurred.

**Example requirements value:**

```json
"requirements": {
    "requirements": [
        {
            "requests": [
                {
                    "principal": {
                        "type": "StrongDM::Account",
                        "id": "a-66c1524e6690718e"
                    },
                    "action": {
                        "type": "SQL::Action",
                        "id": "select"
                    },
                    "resource": {
                        "type": "Postgres::Database",
                        "id": "rs-735d634e6690718e/web"
                    },
                    "context": {}
                }
            ],
            "values": [
                "justify?prompt=Justify.\u0026cache=15m"
            ],
            "ok": true,
            "reason": "I need access."
        }
    ]
},
```

### Decision

The `decision` field is a string that represents the policy evaluation decision for an individual query based on all of the preceding data. The value is either "allow" or "deny".

**Example decision value**

```json
"decision": "allow"
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.strongdm.com/admin/audit/logs/references/authz-logs-object.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.