| Attribute |
Value
|
| Sources |
litellm/proxy/custom_sso.py
|
| Domains |
Proxy, SSO, Authentication, Extensibility, Templates
|
| Last Updated |
2026-02-15 16:00 GMT
|
Overview
custom_sso is an example template demonstrating how to implement a custom SSO (Single Sign-On) handler that processes identity provider (IDP) information after LiteLLM redirects users through the SSO flow.
Description
This module provides a reference implementation of a custom SSO handler via the custom_sso_handler async function. The function is invoked after LiteLLM has completed the SSO redirect flow and retrieved user information from the identity provider. It receives an OpenID object (from fastapi_sso) containing the user's IDP information and must return a SSOUserDefinedValues object that defines the user's access properties within the proxy. The template demonstrates: validating the user ID, querying existing user information from the LiteLLM proxy database via user_info, accessing extra fields from the IDP response (when GENERIC_USER_EXTRA_ATTRIBUTES is configured), and returning user properties including models, user role (LitellmUserRoles.INTERNAL_USER), max budget, and budget duration.
Usage
Copy and modify this template when you need custom post-SSO processing logic for the LiteLLM proxy. Configure it in your proxy's YAML configuration. The handler enables mapping IDP user attributes to LiteLLM proxy user properties like roles, budgets, and model access.
Code Reference
Source Location
litellm/proxy/custom_sso.py
Signature
async def custom_sso_handler(userIDPInfo: OpenID) -> SSOUserDefinedValues
Import
from litellm.proxy.custom_sso import custom_sso_handler
I/O Contract
Inputs
| Parameter |
Type |
Description
|
userIDPInfo |
fastapi_sso.sso.base.OpenID |
The user information retrieved from the identity provider, including id, email, and optional extra_fields.
|
Outputs
| Return Type |
Description
|
SSOUserDefinedValues |
A typed dictionary containing: models (list of allowed models), user_id, user_email, user_role (e.g., LitellmUserRoles.INTERNAL_USER), max_budget, and budget_duration.
|
Exceptions
| Exception |
Description
|
ValueError |
Raised when userIDPInfo.id is None.
|
Exception("Failed custom auth") |
Raised for any other error during SSO processing.
|
Usage Examples
from fastapi_sso.sso.base import OpenID
from litellm.proxy._types import LitellmUserRoles, SSOUserDefinedValues
async def custom_sso_handler(userIDPInfo: OpenID) -> SSOUserDefinedValues:
if userIDPInfo.id is None:
raise ValueError("No ID found for user")
# Map IDP roles to LiteLLM roles
extra_fields = getattr(userIDPInfo, "extra_fields", None) or {}
user_groups = extra_fields.get("group", [])
if "admin" in user_groups:
role = LitellmUserRoles.PROXY_ADMIN.value
max_budget = 1000
else:
role = LitellmUserRoles.INTERNAL_USER.value
max_budget = 10
return SSOUserDefinedValues(
models=[],
user_id=userIDPInfo.id,
user_email=userIDPInfo.email,
user_role=role,
max_budget=max_budget,
budget_duration="1d",
)
Related Pages
Page Connections
Double-click a node to navigate. Hold to expand connections.
