APERTURE IS NOW AVAILABLE - START BUILDING WITH AI SAFELY IN MINUTES, NO WAITLIST.Read more →

Integrate Cerbos with Aperture

Last validated:

Aperture by Tailscale is currently in alpha.

Cerbos is a policy engine that provides fine-grained, context-aware authorization. By connecting Aperture to Cerbos, you can send LLM request data to Cerbos so it can enforce authorization policies on AI usage, such as controlling which users can access specific models or tools.

Aperture sends data to Cerbos using the hooks system. You configure a hook endpoint for your Cerbos deployment and a grant that specifies which requests trigger the hook and what data to include.

Prerequisites

Before you begin, ensure you have the following:

  • A running Aperture instance accessible from your device.
  • A Cerbos deployment (self-hosted or Cerbos Hub) with an API endpoint that can receive webhook data.

Configure the Cerbos endpoint

To integrate Cerbos with Aperture, configure the Cerbos endpoint so you can use it as a hook in Aperture and set up a grant to send request data to that hook. This allows Cerbos to receive real-time data about LLM requests for authorization decisions.

  1. In your Cerbos deployment, identify or create an endpoint that can receive HTTP POST requests from Aperture.
  2. Note the endpoint URL and any API key or authentication token. You'll use these when configuring the hook in Aperture.

For details on setting up Cerbos, refer to the Cerbos documentation.

Configure the Aperture hook

Configure a hook in Aperture that points to your Cerbos endpoint. This lets you send request data to Cerbos for authorization decisions.

  1. Open the Aperture dashboard at http://ai/ui/.

  2. Navigate to the Settings page and open the JSON editor.

  3. Add a cerbos entry in the hooks section with the endpoint URL from your Cerbos deployment.

    "hooks": {
    "cerbos": {
        "url": "YOUR_CERBOS_ENDPOINT_URL",
        "apikey": "YOUR_CERBOS_API_KEY"
    }
}

    Replace YOUR_CERBOS_ENDPOINT_URL with the URL of your Cerbos endpoint and YOUR_CERBOS_API_KEY with the API key from your Cerbos deployment.

  4. Add a grant with a send_hooks entry that references the cerbos hook. The grant controls which requests trigger the hook and what data Aperture sends.

    "grants": [
    {
        "src": ["*"],
        "app": {
            "tailscale.com/cap/aperture": [
                {
                    "send_hooks": [
                        {
                            "name": "cerbos",
                            "events": ["entire_request"],
                            "send": ["tools", "user_message", "grants"]
                        }
                    ]
                }
            ]
        }
    }
]

    This configuration sends request data for all users. The grants send type includes the user's custom capabilities, which Cerbos can use for authorization decisions. To limit which users' requests trigger the hook, replace "*" in the src field with specific user identities or tags.

  5. Save the configuration.

For details on hook events and send types, refer to the hooks configuration reference.

Verify the integration

After configuring the Cerbos hook, verify that Aperture is sending data to Cerbos and that Cerbos is evaluating it against your policies.

  1. Send a request through Aperture that matches your grant conditions.
  2. Check your Cerbos deployment to confirm the request data arrives.
  3. Verify that Cerbos evaluates the data against your authorization policies.

If data doesn't appear, check that the send_hooks name matches the key in your hooks section and that the grant's src field includes the user who made the request.

Next steps