Dual-Layer Authentication
Relevant source files
The following files were used as context for generating this wiki page:
Dual-Layer Authentication is a security architecture that secures the Infrahub MCP server by separating credential extraction from policy enforcement. The system operates across the ASGI transport layer and the MCP middleware layer to ensure that AI assistants operate under specific user identities rather than shared service accounts. This approach preserves Infrahub's existing permission models and maintains a clear audit trail for all infrastructure modifications.
Sources: dev/adr/0003-dual-layer-authentication.md, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:61-64
Architecture Overview
The authentication stack functions in two distinct stages. The outer ASGI layer extracts credentials from incoming HTTP headers before the MCP protocol logic begins. The inner MCP middleware layer then enforces the presence of these credentials and applies access control policies during tool execution.
Authentication Flow
This diagram illustrates the sequence of credential handling from the initial request to the final Infrahub SDK call:
Authentication Modes
The server supports four primary authentication modes, validated at startup via ServerConfig.
| Mode | Implementation Detail | Use Case |
|---|---|---|
none | Uses shared environment variable credentials. | Local development and testing. |
oidc | Full OAuth 2.0 / OIDC flow via OIDCProxy. | Production deployments with SSO. |
token-passthrough | Extracts Bearer token from configurable header. | Clients with personal API tokens. |
basic-passthrough | Extracts Username/Password from Basic auth. | Legacy credential delegation. |
Sources: specs/archive/20260421-144953-production-ready-mcp-server/spec.md:144-150, dev/constitution.md:Principle VI
Component Roles
ASGI Extraction Layer
The _CredentialsPassthroughASGI component acts as the entry point for HTTP transport. It inspects incoming requests for authentication headers based on the server configuration. When it identifies credentials, it stores them in ContextVar containers. This mechanism ensures per-request isolation in asynchronous environments where shared thread pools are utilized.
Key elements include:
- ContextVar Storage:
_passthrough_tokenand_passthrough_basicvariables provide task-level isolation. - Header Mapping: The server allows mapping custom HTTP headers to specific credential types.
Sources: src/infrahub_mcp/middleware.py:100-115, specs/archive/20260421-144953-production-ready-mcp-server/research.md:R2
MCP Enforcement Layer
Once the request reaches the MCP protocol layer, specific middleware classes enforce security policies:
- AuthMiddleware: Manages OIDC scope enforcement. It ensures that write operations are only permitted if the authenticated identity possesses the necessary scopes.
- TokenPassthroughMiddleware: Implements a fail-closed policy. If the
ContextVaris empty in a passthrough mode, the middleware rejects the tool call before any interaction with the Infrahub API occurs.
Sources: src/infrahub_mcp/middleware.py:175-190, specs/archive/20260421-144953-production-ready-mcp-server/research.md:R2
Security Standards
The implementation follows strict security guidelines defined in the project constitution:
- Fail-Closed Behavior: Requests in passthrough modes are rejected by default if no credentials are provided.
- Credential Isolation: Credentials reside only in
ContextVarand are never stored in global state. - Zero Leakage: The system ensures that secrets, API keys, and credentials do not appear in logs, exceptions, or error responses.
- Startup Validation: OIDC configurations are validated as a complete set; partial configurations cause immediate startup failure to prevent insecure states.
Sources: dev/constitution.md:Principle VI, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:154-159
Middleware Ordering
Authentication middleware is strategically positioned within a 17-layer stack to ensure proper lifecycle management:
Conclusion
Dual-Layer Authentication provides a robust trust boundary between AI assistants and production infrastructure. By leveraging ASGI-level extraction and MCP-level enforcement, the system maintains strict per-user identity, fulfills audit requirements, and prevents unauthorized access through a fail-closed design.