Implementation:BerriAI Litellm Custom SSO Template

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

• BerriAI_Litellm_Custom_Auth_Template - Custom API key authentication template
• BerriAI_Litellm_Proxy_Auth_Credentials - OAuth2/JWT credential management