Authentication Methods

Relevant source files

The following files were used as context for generating this wiki page:

• dev/knowledge/backend/authentication.md
• backend/infrahub/api/auth.py
• frontend/app/src/entities/authentication/domain/use-cases/login-with-credentials.ts
• dev/guides/frontend/adding-an-auth-method.md
• specs/ifc-2595-login-refactor/spec.md
• backend/AGENTS.md

Infrahub provides a multi-faceted authentication system supporting local credentials, Single Sign-On (SSO), and LDAP integrations. The system is designed to be extensible, allowing for various authentication paths to converge on a unified token-based session management model. Authentication logic is split between a FastAPI backend that handles validation and group resolution, and a React frontend that manages method selection and token persistence.

Sources: backend/AGENTS.md, specs/ifc-2595-login-refactor/spec.md:16-22

Authentication Architecture

The architecture distinguishes between credentials-based methods and redirect-based methods. All methods eventually produce a UserToken which the frontend persists in localStorage.

Data Flow Overview

The following diagram illustrates the flow from a login request to session establishment.

Backend Authentication Types

The backend supports several specific authentication providers and processes.

Local Credentials

Users provide a username and password directly to the Infrahub backend. The backend validates these against the internal user database.
Sources: specs/ifc-2595-login-refactor/spec.md:16-17

Single Sign-On (SSO)

SSO utilizes OAuth2 or OIDC redirect flows. When enabled, the backend handles SSO group resolution and can auto-create groups based on provider attributes.
Sources: backend/AGENTS.md, specs/ifc-2595-login-refactor/spec.md:17

LDAP

LDAP serves as a credentials-based method where the frontend collects a username and password, but the backend validates them against an external LDAP server.
Sources: specs/ifc-2595-login-refactor/spec.md:18-20, dev/guides/frontend/adding-an-auth-method.md:23-42

Method Kind	UI Component	Backend Endpoint
Local	LocalCredentialsForm	/api/auth/login
SSO	LoginSSOButtons	Managed via redirects
LDAP	LdapCredentialsForm	/api/auth/ldap/login

Sources: specs/ifc-2595-login-refactor/spec.md:88-100, dev/guides/frontend/adding-an-auth-method.md:26-38

Frontend Auth Method Registry

The frontend uses a registry pattern to manage available authentication methods. This allows the UI to dynamically render the appropriate login form or button based on the server's configuration.

AuthMethod Type

The AuthMethod is a TypeScript union type that defines the structure for each supported login style.

export type AuthMethod =
  | { kind: "local"; label: string }
  | { kind: "sso"; providers: SSOProvider[] }
  | { kind: "ldap"; displayLabel: string; icon: string };

Sources: specs/ifc-2595-login-refactor/spec.md:58-69, dev/guides/frontend/adding-an-auth-method.md:18-22

Method Selection Logic

The LoginMethodPicker component determines which method to display using the following priority:

1. Last Used: The method stored in localStorage under LAST_USED_METHOD_KEY.
2. Preferred Default: If no preference exists, it defaults to SSO if available.
3. Fallback: The first available method in the registry.

Sources: specs/ifc-2595-login-refactor/spec.md:102-116, specs/ifc-2595-login-refactor/spec.md:137-142

Token Management and Persistence

Infrahub uses a centralized persistence model to ensure consistency and avoid duplicate writes to storage.

Persistence Rules

• Interactive Login: The AuthContext (specifically useAuth.setToken) is the sole writer to localStorage during successful login flows.
• Refresh Flow: refresh-access-token.ts may persist tokens directly because it operates outside the React component lifecycle (e.g., in an API interceptor).
• Domain Functions: Logic in domain/ (like login-with-credentials.ts) must return tokens but must not call saveTokensInLocalStorage.

Sources: specs/ifc-2595-login-refactor/spec.md:112-116, dev/guides/frontend/adding-an-auth-method.md:65-67

Error Handling

The frontend maps backend HTTP status codes to specific LoginError codes to provide actionable feedback.

HTTP Status	Error Code	User Message
401	invalid_credentials	Invalid username or password
5xx	server	Authentication service unavailable
Offline	network	Network error — check your connection
Other	unknown	Could not log in

Sources: specs/ifc-2595-login-refactor/spec.md:82-86

Authentication methods in Infrahub facilitate secure access through a unified frontend registry and specialized backend providers. By centralizing token persistence and standardizing error handling, the system maintains a consistent user experience across local, SSO, and LDAP login paths.