Authentication & Credentials
Relevant source files
The following files were used as context for generating this wiki page:
Coral manages service credentials for agents to ensure security and policy compliance. The system isolates agents from raw secrets by running programs in a sandbox where Coral injects the necessary tokens only at the moment of execution.
This module provides a unified interface for various authentication protocols, including OAuth 2.0, Basic Auth, and custom header or query parameter injection. Owners configure these credentials through Provider Recipes or manual setup, while Coral handles the lifecycle, storage, and injection of sensitive values.
Authentication Methods
Coral supports eight distinct authentication methods for connecting to upstream services. These methods are defined in the provider recipe schema and presented to users during provider setup.
| Method | Description |
|---|---|
none | Public access without credentials. |
bearer | Bearer token sent in the Authorization header. |
header | API keys or tokens sent in specific, named HTTP headers. |
basic | HTTP Basic authentication using a username and password. |
query | API keys sent as URL query parameters. |
oauth | OAuth 2.0 authorization code flow. |
device | OAuth 2.0 device code flow for terminal-based or restricted devices. |
discovery | MCP-only method that discovers endpoints via OIDC/OAuth discovery. |
Sources: apps/reef/app/views/providers/configuration-details.tsx:13-23, apps/reef/app/lib/provider-recipes/recipe-format.ts:191-267
Execution Flow with Credentials
The following diagram illustrates how Coral intercepts agent requests to inject credentials after performing policy checks.
Sources: README.md:62-72
Credential Management and Binding
Coral uses a binding system to map user-entered credential fields to specific locations in HTTP requests. This allows the system to handle complex authentication requirements like custom header prefixes or multiple API keys.
Credential Fields
Users enter sensitive values into defined fields. Coral masks these values during entry if marked as sensitive in the recipe.
Sources: apps/reef/app/lib/provider-recipes/recipe-format.ts:153-162
Binding Types
- Header Bindings: Map a field to a header (e.g.,
x-api-key). Supports optional prefixes likeToken. - Query Bindings: Map a field to a query parameter.
- Basic Auth Bindings: Map fields to the username and password slots of a Basic Auth header.
Sources: apps/reef/app/views/providers/types.ts:122-132, apps/reef/app/views/providers/configuration-step.tsx:644-654
Table: Credential Configuration Types
| Type | Description |
|---|---|
field | A dynamic value provided by the user per account. |
literal | A fixed protocol constant (non-secret) defined by the recipe. |
Sources: apps/reef/app/views/providers/types.ts:122-132
OAuth Implementation
Coral implements OAuth 2.0 with a focus on security and ease of use. It handles complex tasks like PKCE (Proof Key for Code Exchange) and scope formatting automatically.
OAuth Configuration Options
For the oauth_authorization_code and oauth_device_code flows, the system manages:
- Authorization and Token URLs: The endpoints used for the OAuth handshake.
- Client Identification: Supports both "automatic" (Coral-managed) and "manual" (user-provided) client IDs and secrets.
- Scopes: Managed as an array of strings, with configurable formatting (space or comma separated) for the authorization request.
- PKCE: Enabled by default using the S256 method; it can only be disabled for confidential clients.
Sources: apps/reef/app/lib/provider-recipes/recipe-format.ts:222-250, apps/reef/app/views/providers/types.ts:154-156
WorkOS Integration
During local development, Coral integrates with WorkOS to handle authentication kit and organization membership.
- Run
./dev setupto start the configuration wizard. - Provide the
WORKOS_ENVIRONMENT_CLIENT_IDandWORKOS_ORGANIZATION_ID. - Configure a "Connect" OAuth application for the development machine.
- Store the
WORKOS_CONNECT_CLIENT_SECRETin the.dev/directory for secure local access.
Sources: scripts/dev/setup.sh:185-217
Security and Persistence
The system maintains strict boundaries between untrusted code and sensitive credentials.
- Isolation: Program sandboxes have no direct access to the credential store or the network.
- Outbound Control: All outbound traffic must pass through the
coral-outbound::Client, which applies identity and destination policies. - Test Data: Tests using dummy credentials must use filesystem storage. Developers must NOT write test credentials to the OS keychain.
- Redaction: Logs and diagnostic reports are stripped of sensitive values to prevent accidental exposure (e.g., credentials embedded in URLs).
Sources: AGENTS.md:16-19, AGENTS.md:217-219, crates/coral-catalog/tests/provider_configuration.rs:480-484
Summary
Authentication in Coral centers on a zero-trust model for agent programs. By defining authentication via a structured recipe schema and centralizing credential injection in a secure gateway, Coral allows agents to utilize diverse services without ever handling raw secrets. This architecture supports standard protocols like OAuth and Basic Auth while enforcing strict policy controls on every outbound call.