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. Find the instructions for your product below.

Dedicated

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

Self-Hosted

Audit logging is configured using command-line flags. See the full list of flags in the Extenders section.

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