Authentication and SSO
Relevant source files
The following files were used as context for generating this wiki page:
Authentication and Single Sign-On (SSO) in LiteLLM provide secure access control for the proxy server and management dashboard. The system supports multiple authentication mechanisms including virtual API keys, OAuth2 hooks, and specialized SSO providers like Microsoft (Azure AD). These mechanisms ensure that only authorized users, teams, or applications can interact with the LLM gateway.
The authentication architecture is designed to handle various client types, ranging from programmatic SDK access using Bearer tokens to interactive browser-based logins for the admin UI and CLI tools. It integrates with database-backed user management to enforce budgets, rate limits, and model-level access permissions.
Virtual API Key Authentication
The primary method for programmatic access to the LiteLLM proxy is through virtual API keys. These keys are validated against a database or cache to determine the permissions and limits associated with the requester.
Authentication Logic
The core logic resides in user_api_key_auth.py, which implements a user_api_key_auth function. This function intercepts incoming FastAPI requests to validate the Authorization header. It supports both standard Bearer tokens and custom header names if configured.
The diagram shows the extraction and validation flow for virtual keys.
Sources: litellm/proxy/auth/user_api_key_auth.py
Key Validation Features
- Team-Based Access: Keys can be tied to specific
team_ids, allowing for granular control over which models a team can use. - Budget Enforcement: The authentication layer checks if the key has exceeded its
max_budget. - Dynamic Scoping: Permissions can be restricted to specific models or API endpoints.
Sources: litellm/proxy/auth/user_api_key_auth.py, litellm/proxy/client/README.md
Single Sign-On (SSO) and OAuth2
LiteLLM supports SSO to enable enterprise-grade security for the Admin UI and CLI. This is handled via OAuth2 flows and specialized provider implementations.
Microsoft SSO (Azure AD)
The MicrosoftSSO class manages the interaction with Microsoft's OAuth2 endpoints. It handles the initial redirect to the login page, token exchange, and user profile retrieval.
| Function | Description |
|---|---|
microsoft_sso_login | Generates the redirect URL for the Microsoft login page using client_id and scope. |
microsoft_sso_callback | Processes the authorization code from Microsoft and exchanges it for an access token. |
get_user_info | Uses the access token to call the Microsoft Graph API (/me) to retrieve user details like email and name. |
Sources: litellm/proxy/management_endpoints/sso/custom_microsoft_sso.py:10-80
OAuth2 Proxy Hook
LiteLLM can integrate with external OAuth2 proxies (e.g., oauth2-proxy). The OAuth2ProxyHook class extracts user identity information directly from headers injected by the proxy, such as X-Forwarded-User or X-Forwarded-Email.
Sources: litellm/proxy/auth/oauth2_proxy_hook.py
CLI Authentication Flow
The LiteLLM CLI utilizes a polling-based SSO mechanism to authenticate users without requiring them to manually copy-paste long-lived API keys.
The diagram illustrates the secure polling mechanism used by the CLI to obtain credentials.
Sources: litellm/proxy/client/README.md:214-245
Dashboard Authentication and Session Management
The LiteLLM Dashboard manages user sessions via cookies and interaction with the Proxy's SSO endpoints.
Session Expiration
The UI includes logic to handle expired sessions. If a network request returns an authentication error (e.g., "Expired Key"), the dashboard triggers a logout sequence.
// Example of session handling in the UI
if (errorData.includes("Authentication Error - Expired Key")) {
NotificationsManager.info("UI Session Expired. Logging out.");
clearTokenCookies();
}
Sources: ui/litellm-dashboard/src/components/networking.test.ts:25-35
SSO Configuration Management
Administrators can update SSO settings through management endpoints. These updates require high-level permissions and are subject to environment variable checks (e.g., STORE_MODEL_IN_DB).
Sources: ui/litellm-dashboard/src/components/networking.test.ts:47-60
ChatGPT Subscription OAuth
LiteLLM provides helper utilities for managing OAuth sessions specifically for ChatGPT subscription-based access (Codex). This includes managing device codes and access tokens.
| Constant | Value / Purpose |
|---|---|
CHATGPT_AUTH_BASE | https://auth.openai.com |
CHATGPT_DEVICE_CODE_URL | Endpoint to request a device code for user verification. |
CHATGPT_OAUTH_TOKEN_URL | Endpoint to exchange codes for access tokens. |
CHATGPT_CLIENT_ID | Fixed client ID used for ChatGPT authentication. |
Sources: litellm/llms/chatgpt/common_utils.py:10-25
Conclusion
LiteLLM provides a flexible authentication framework that spans simple API key validation to complex SSO flows. By supporting standard OAuth2 protocols and enterprise providers like Microsoft, it ensures that LLM usage can be securely governed across both automated services and human administrators. Memory-based caching and database verification allow the system to scale while maintaining strict security boundaries for every request.