Authentication & Permissions
Relevant source files
The following files were used as context for generating this wiki page:
The Authentication & Permissions system provides a structured framework for securing service operations and managing access control through typed requirements. It integrates identity verification with fine-grained authorization, allowing services to define what permissions a principal must hold on specific resources before executing an operation.
The system uses a declarative approach where operations name their requirements in the service model. This information is propagated through code generation to provide runtime enforcement, client SDK support, and automated documentation.
Authentication Mechanisms
The system supports multiple authentication schemes to verify the identity of the caller. The primary method for client-initiated requests is Bearer token authentication, while service-to-service communication may utilize specialized signing mechanisms.
Authentication Schemes
Authentication is defined at the service and operation level. Requests typically carry credentials in HTTP headers.
| Scheme Kind | Header Format | Description |
|---|---|---|
| Bearer | Authorization: Bearer <token> | Verified for operations requiring client credentials. |
| Sender-Signed | Variable (e.g., Payment-Signature) | Used when a third party signs requests instead of clients. |
Sources: crates/crucible-codegen-docs/src/markdown.rs:94-100, crates/crucible-codegen-docs/tests/golden/permissions-external/describe.json:1155-1159, crates/crucible-codegen-openapi/tests/generate.rs:136-140
Sender-Signed Operations
Certain operations are designated as "sender-signed," meaning they are called by specific third-party entities rather than standard API clients. In these cases, the service verifies a signature in a custom header provided by the sender.
The diagram shows the flow for sender-signed operations where verification relies on a specific header rather than a standard Bearer token.
Sources: crates/crucible-codegen-docs/src/markdown.rs:596-608, crates/crucible-codegen-openapi/tests/generate.rs:136-140
Permission Registry and Tiers
Permissions are organized by resource type and categorized into tiers that define how they are granted and exposed.
Resource Types and Identifiers
Every grant names a resource type and a permission value. Resources are identified by specific ID fields defined in the model.
| Resource Type | Identifiers |
|---|---|
graph | organizationId, graphId |
history | organizationId, graphId, historyId |
org | organizationId |
Sources: crates/crucible-codegen-docs/tests/golden/permissions-external/describe.json:1169-1224
Permission Tiers
Permissions are classified into four tiers that control visibility and grantability.
- Public: Standard permissions required by operations and visible to clients.
- Permission-only: Required by no specific operation but checked by service policy.
- Bundles (Not Grantable): Permissions conferred whole by service policy rather than individual grants.
- Internal: Server-specific vocabulary never exposed in public references or refusals.
Sources: crates/crucible-codegen-docs/src/markdown.rs:658-675, e2e/weather-service/tests/permissions.rs:68-75
Authorization Logic
Authorization determines if a principal holding a specific set of grants is permitted to perform a requested action. This is handled through requirements and checks.
Requirement Kinds
Operations declare their authorization needs using different requirement kinds:
- None: The operation is authenticated but requires no specific permission.
- Pending: Requirements are not yet declared; the service performs manual checks.
- Internal: Requires permissions internal to the service.
- List: A structured list of permission clauses with resource bindings.
Sources: crates/crucible-codegen-docs/src/markdown.rs:619-631, e2e/weather-service/tests/permissions.rs:92-108
Check Bindings and Conditions
Clauses in a requirement list define the permission needed and bind model identifiers to specific resources. Clauses can be conditional, using when expressions to determine if the check applies based on request data.
This flowchart illustrates the evaluation logic for authorization requirements, including authentication, condition checking, and grant verification.
Sources: crates/crucible-codegen-docs/src/markdown.rs:633-653, e2e/weather-service/tests/permissions.rs:242-263
Enforcement Modes
Requirements specify how they are enforced during request processing:
- Check: A standard verification performed by the framework before the handler runs.
- Filter: Used for listing operations to return only resources the caller may read.
- Handler: An obligation that the operation handler must discharge or declare not applicable.
Sources: crates/crucible-codegen-docs/src/markdown.rs:645-653, e2e/weather-service/tests/permissions.rs:188-202
Runtime Enforcement and Authorizer
The Authorizer is the core runtime component responsible for deciding verdicts.
The Authorizer Interface
The Authorizer must implement two primary methods:
- decide: Returns a list of
Verdictobjects (Allowed,Denied, orHidden) for a set of checks. - visible: Determines which instances of a resource are visible for a listing operation.
Sources: e2e/weather-service/tests/permissions.rs:309-354
Verdicts and Responses
Authorization failures result in specific HTTP responses based on the verdict:
| Verdict | HTTP Status | Description |
|---|---|---|
Allowed | 200 (or success) | Execution proceeds. |
Denied | 403 Forbidden | Principal lacks permission; message names the missing grant. |
Hidden | 404 Not Found | Principal lacks membership or knowledge; indistinguishable from absence. |
Sources: e2e/weather-service/tests/permissions.rs:414-443
Summary
The Authentication & Permissions system ensures secure access to Crucible services by combining flexible authentication schemes with a robust, tiered permission model. By declaring requirements directly in the service model, the system enables automated documentation and reliable runtime enforcement. This architecture maintains security through pre-handler checks and filtered listings while supporting complex authorization scenarios through conditional clauses and handler-discharged obligations.