Managed Gateway Login
Relevant source files
The following files were used as context for generating this wiki page:
Managed Gateway Login is an opt-in authentication and policy enforcement system for the shunt gateway. It allows administrators to govern Claude Code client access using the OAuth 2.0 device flow, shifting from shared static tokens to individual user-based sessions. This system supports browser-based approval through local static users or external OIDC providers like Google, issuing short-lived HS256 JWT access tokens and long-lived refresh tokens to clients.
The feature is controlled via the [server.gateway] configuration block. When enabled, it provides an OAuth discovery surface, device/refresh grant handlers, and a managed settings endpoint (/managed/settings) that pushes telemetry and enforces model availability policies. Refresh sessions are persisted to disk by default in an atomically written JSON file to maintain user sessions across gateway restarts.
Sources: README.md:195-207, ARCHITECTURE.md:120-128
System Architecture
Managed Gateway Login integrates into the shunt server by registering a specific set of OAuth and management routes. It relies on a stateful session manager to handle device authorization requests and persistent refresh tokens.
Core Components
| Component | Description |
|---|---|
| Device Flow Manager | Handles device_authorization and device_code grant types. |
| JWT Manager | Issues and validates HS256 encoded Access Tokens. |
| OIDC Provider | Integrates with external identity providers for user authentication. |
| Managed Settings | Serves user-specific configuration and telemetry push parameters. |
| Session Store | Persists refresh sessions to gateway-sessions.json on disk. |
Sources: src/gateway/mod.rs, src/gateway/jwt.rs, README.md:201-204
Authentication Flow
The following sequence diagram illustrates the Device Authorization Flow used by Claude Code to authenticate against a Managed Gateway.
This diagram shows the standard OAuth 2.0 Device Flow implementation where the client polls for a token while the user completes authentication in a browser.
Sources: src/gateway/device.rs, README.md:198-201
Managed Settings and Policy
The gateway provides a specialized endpoint at /managed/settings which is used by managed Claude Code clients to retrieve their operating context.
Telemetry and Model Availability
The response from this endpoint includes:
- ETag Caching: Efficient delivery of configuration.
- Available Models: Enforcement of which model IDs the specific user is permitted to use.
- Telemetry Environment: Pushing specific environment variables to the client for tracking or configuration.
Sources: src/gateway/managed.rs, README.md:198-201
JWT Token Structure
The jwt.rs module manages the creation of signed Access Tokens. These tokens are used as Bearer credentials for inference routes and /v1/models.
The gateway uses HS256 signing for efficiency, relying on a configured secret to validate incoming requests.
Sources: src/gateway/jwt.rs, README.md:198
Configuration Options
Managed Gateway behavior is defined within the [server.gateway] TOML table.
| Key | Type | Default | Description |
|---|---|---|---|
state_path | String | ~/.shunt/gateway-sessions.json | Location for persistent refresh tokens. |
oidc | Table | Optional | Configuration for external OIDC provider (e.g., Google). |
issuer | String | Required | The URL of the gateway for JWT iss claim. |
secret | String | Required | HS256 secret for signing tokens. |
Sources: src/gateway/mod.rs, README.md:204-206
Session Persistence
Shunt implements a cancellation-safe and crash-safe mechanism for storing refresh tokens.
- Hashing: Refresh tokens are stored as SHA-256 hashes to prevent plain-text exposure if the session file is compromised.
- Atomic Writes: The session file is written atomically to prevent corruption during gateway crashes.
- Restoration: At boot, the gateway reads
state_pathto populate its memory-only device grants and restore existing refresh sessions.
Sources: src/gateway/mod.rs, README.md:204-206
Summary
Managed Gateway Login provides a robust, enterprise-ready authentication layer for the shunt project. By implementing the OAuth 2.0 Device Flow and OIDC integration, it allows for individual user accountability and centralized policy enforcement (via /managed/settings) while maintaining a seamless experience for Claude Code users through session persistence and transparent token refreshes.