Authentication & Identity
Relevant source files
The following files were used as context for generating this wiki page:
The Authentication and Identity system in Hoop provides a robust framework for managing secure access to production infrastructure for diverse entities, including human engineers, AI agents, and service accounts. It functions as a Layer 7 gateway that federates identity from external providers while maintaining local authentication capabilities for initial setup and specific environments.
The system is designed to handle multiple authentication methods, including OIDC, SAML, and local email/password auth. It supports advanced identity concepts such as machine identities, SPIFFE-based agent authentication, and OAuth 2.1 for MCP (Model Context Protocol) clients. By sitting between the user and the infrastructure, it ensures that every action is attributed to a specific, verified identity.
Sources: README.md, webapp_v2/README.md, gateway/api/server.go:127-145
Authentication Methods
Hoop supports two primary categories of authentication for users and services. The system automatically detects the required method based on the gateway's configuration.
Local Authentication
Local authentication utilizes email and password combinations. It is primarily used for the initial server setup (where the first registered user becomes an administrator) and in environments where external identity providers are not configured.
OAuth/IDP (SSO)
The system supports Single Sign-On (SSO) through integration with major identity providers (IdPs) like Okta, Azure AD (Microsoft Entra ID), JumpCloud, and Google Workspace using OIDC or SAML 2.0.
| Component | Description |
|---|---|
| OIDC Config | Includes Client ID, Client Secret, Issuer URL, and Audience. |
| SAML Config | Includes IDP Metadata URL and groups claim mapping. |
| Groups Claim | Used to propagate user group memberships from the IdP to Hoop. |
Sources: webapp_v2/README.md:83-89, gateway/api/openapi/openapiv3.json, gateway/api/server.go:131-140
Authentication Flow
The following diagram illustrates the high-level authentication flow for a user session:
The diagram shows the logic for selecting an authentication method based on server configuration and the subsequent token issuance.
Sources: webapp_v2/README.md:92-98, webapp_v2/CONTEXT_MIGRATION.md:144-150, gateway/api/server.go:127-145
Identity Types
Hoop distinguishes between various types of identities to apply appropriate security policies and audit controls.
Human Users
Standard users who authenticate via the Web UI or CLI. Their identities are typically derived from OIDC/SAML claims (email and name).
AI Agent Identities
Specific identities for AI tools like Claude Code or Cursor. These allow AI agents to inherit permissions from a human user or operate with dedicated restricted scopes. They use generated keys (prefixed with hpk_) for authentication.
Machine & Service Accounts
Non-human identities used for automation and service-to-service communication.
- Service Accounts: Mapped from identity provider clients.
- Machine Identities: Provisioned with native credentials for specific connections.
SPIFFE Mappings
Allows Hoop agents to authenticate using SPIFFE SVIDs (JWT-SVID) instead of static DSN tokens. This is often used in Kubernetes environments where SPIRE is present.
Sources: gateway/api/openapi/openapiv3.json, webapp_v2/src/pages/AiAgentsIdentities/Created/index.jsx:39-45, gateway/api/server.go:303-318
Token Management & Security
Security tokens are the primary mechanism for maintaining session state and authorizing API requests.
- Storage: In the web application, the JWT is stored in
localStorageunder the keyjwt-token. - Transmission: Tokens are sent in the
Authorization: Bearer <token>header for API requests. - Detection: The React shell can extract tokens from cookies (
hoop_access_token) or query parameters (?token=xxx) to facilitate seamless transitions between legacy and modern UI routes. - Handling 401s: On receiving a 401 Unauthorized response, the application saves the current URL for post-login redirection and triggers a logout/login flow.
Sources: webapp_v2/README.md:92-98, webapp_v2/CONTEXT_MIGRATION.md:144-150, webapp_v2/CONTEXT_MIGRATION.md:214-220
API Endpoints for Identity Management
The following table summarizes key API endpoints used for managing authentication and identities:
| Endpoint | Method | Description |
|---|---|---|
/api/login | GET | Returns the OIDC login URL. |
/api/callback | GET | OIDC login callback handler. |
/api/localauth/login | POST | Authenticates local users. |
/api/userinfo | GET | Returns details about the currently authenticated user. |
/api/api-keys | POST | Generates new API keys for programmatic access. |
/api/ai-agents | POST | Creates identities for AI coding agents. |
/api/spiffe-mappings | POST | Maps SPIFFE IDs to Hoop agents. |
Sources: gateway/api/server.go:127-318, gateway/api/openapi/openapiv3.json
Implementation: AI Agent Identity Creation
When an AI Agent identity is created, the system generates a unique key. This key is displayed only once to the user.
// Example of how the client configures usage for an AI identity
function buildMcpSnippet(apiUrl, key) {
const config = {
mcpServers: {
hoop: {
type: 'http',
url: `${apiUrl}/api/mcp`,
headers: {
Authorization: `Bearer ${key}`,
},
},
},
}
return JSON.stringify(config, null, 2)
}
Sources: webapp_v2/src/pages/AiAgentsIdentities/Created/index.jsx:13-25
Conclusion
The Authentication & Identity system in Hoop provides a unified layer for securing infrastructure access. By supporting local, federated, and machine-based identities, it ensures that every connection—whether initiated by a developer, a script, or an AI agent—is strictly authenticated and auditable. This centralized approach allows organizations to implement consistent security policies across all protocols and backends.