Audit Logging

Audit Logging is functionality exclusive to AuthZed products that publishes logs of SpiceDB API operations to a log sink.

Log Format

Logs contain the full details related to a request including:

API Token hash
Request Method
Request Body
Request IP
Response Body
Errors (if any)

Example

CheckPermission

{
 "specversion": "1.0",
 "id": "819b4d52db4797491e31d0228f381543",
 "source": "/ps/dev-ps/rc/us-east-1/p/dev-ps-abcd1234",
 "type": "/authzed.api.v1.PermissionsService/CheckPermission",
 "datacontenttype": "application/json",
 "time": "2023-12-18T17:33:11.783093248Z",
 "data": {
   "request": {
     "@type": "type.googleapis.com/authzed.api.v1.CheckPermissionRequest",
     "consistency": {
       "minimizeLatency": true
     },
     "resource": {
       "objectType": "resource",
       "objectId": "firstdoc",
       "permission": "read"
     },
     "subject": {
       "object": {
         "objectType": "user",
         "objectId": "tom"
       }
     },
     "response": {
       "@type": "type.googleapis.com/authzed.api.v1.CheckPermissionResponse",
       "checkedAt": {
         "token": "GgoKCENKcmt4QTA9"
       },
       "permissionship": "PERMISSIONSHIP_HAS_PERMISSION"
     },
     "metadata": {
       "token_hash": "c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2",
       "user-agent": "grpc-go/1.58.3",
       "x-request-id": "819b4d52db4797491e31d0228f381543"
     }
   }
 }
}

ReadSchema

{
  "specversion": "1.0",
  "id": "35cdd6662882bd387292ef78a650d18b",
  "source": "/ps/dev-ps/rc/us-east-1/p/dev-ps-abcd1234",
  "type": "/authzed.api.v1.SchemaService/ReadSchema",
  "datacontenttype": "application/json",
  "time": "2023-12-18T17:32:47.234247Z",
  "data": {
    "request": {
      "@type": "type.googleapis.com/authzed.api.v1.ReadSchemaRequest"
    },
    "response": {
      "@type": "type.googleapis.com/authzed.api.v1.ReadSchemaResponse",
      "schemaText": "definition folder {\n\trelation reader: user | service\n\tpermission read = reader\n}\n\ndefinition resource {\n\trelation reader: user | service\n\tpermission read = reader\n}\n\ndefinition service {}\n\ndefinition user {}",
      "readAt": {
        "token": "GhUKEzE3MDI5MjA0MjcxMjM2MDIwMDA="
      }
    },
    "metadata": {
      "token_hash": "c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2",
      "user-agent": "grpc-go/1.58.3",
      "x-request-id": "35cdd6662882bd387292ef78a650d18b"
    }
  }
}

Log Sinks

Log Sinks are the targets where logs will be shipped in order to be persisted.

Info: We're exploring additional Log Sinks.

Please reach out to your success team with any requests.

AWS Kinesis and Kinesis Firehose

As a prerequisite to use Kinesis (opens in a new tab) or Kinesis Firehose (opens in a new tab) as a log sink, an IAM role must exist in the AWS account with the necessary permissions to write to the Kinesis stream or Firehose delivery stream.

This is an example policy that grants the necessary permissions to write to a Firehose delivery stream:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "",
            "Effect": "Allow",
            "Action": [
                "firehose:PutRecord"
            ],
            "Resource": "EXAMPLE_FIREHOSE_ARN"
        }
    ]
}

Dedicated

For Dedicated customers, this role will also need a trust policy which allows the role to be assumed by the AuthZed account in order to deliver logs to the stream.

To find the Dedicated AWS account ID, navigate to the Permission System's settings page, find the Audit Log settings, and choose "AWS Kinesis" or "AWS Kinesis Firehose" as the log sink. The account ID will be displayed in the configuration.

This is an example trust policy that allows the AuthZed account to assume the role:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "EXAMPLE_AUTHZED_ACCOUNT_ID"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "sts:ExternalId": "EXAMPLE_EXTERNAL_ID"
                }
            }
        }
    ]
}

Configuration

The process for setting up audit logging varies depending on the AuthZed product you're using.

Dedicated & Cloud

Using the web dashboard, navigate to the Permission System's settings page to find the Audit Log settings.

Self-Hosted

Use the following command-line flags:

Flag	Description	Default
--extender-enabled	must be set to`authzed-audit`
--extender-audit-batch-size-limit	defines the maximum number of audit events to be processed as a unit	`10000`
--extender-audit-buffer-size	defines the size of the audit log buffer that holds events to be processed by workers	`1000000`
--extender-audit-buffer-window	defines maximum amount of time events are buffered before being pushed	`1s`
--extender-audit-disabled-on-methods strings	list of comma-separated, fully-qualified API methods to disable events for. Watch API is always excluded (e.g. `/authzed.api.v1.PermissionsService/CheckPermission`)
--extender-audit-initial-retry-interval duration	sets the first retry backoff in case of a failure to push audit events to the backend	`1s`
--extender-audit-max-retry-interval duration	sets the maximum backoff duration in case of failure to push events	`30s`
--extender-audit-retry-randomizer-factor	sets the randomization factor for the backoff duration - this helps prevent thundering herds on event push errors	`0.5`
--extender-audit-stream-name	defines the name of the target stream/topic (e.g. Kafka Topic, Kinesis Stream...)	`spicedb`
--extender-audit-target-configuration	target-type specific configuration	`[]`
--extender-audit-target-endpoint-url string	defines the URL of target endpoint to ingest audit events. If left unspecified, some types will try to determine automatically (e.g. AWS SDK)
--extender-audit-target-type	defines the type of target to ingest audit events	`noop`
--extender-audit-worker-count	defines the number of worker goroutines to process audit events (default 5)

Tokens in Audit Logs

To identify which token was used for a request, look up its SHA-256 hash in the audit log's metadata. Each request's token_hash field contains the hashed value of the original token used.

Example of generating a SHA-256 hash:

$ python3 -c "import hashlib; print(hashlib.sha256('<authzed-token>'.encode()).hexdigest())"
> 2ffb5caf16962e4371bc036d8de2a99dfcea1ae70091ef2953d633a88d05321a

Setting up Private Networking Authzed Materialize