跳至主要内容

✨ Admin UI 的 SSO

信息

自 v1.76.0 版本起，SSO 功能对 5 名以下用户免费开放。

信息

✨ SSO 功能包含在 LiteLLM 企业版中

企业定价

获取 7 天免费试用密钥

使用方法 (Google, Microsoft, Okta 等)​

第 1 步：在 Okta 中创建 OIDC 应用程序​

在您的 Okta 管理控制台中，创建一个新的 OIDC Web 应用程序。详细说明请参阅 Okta 关于创建 OIDC 应用集成的指南。

配置应用程序时

  • 登录重定向 URI: https://<your-proxy-base-url>/sso/callback
  • 登出重定向 URI (可选): https://<your-proxy-base-url>

创建应用后，从应用程序的“常规 (General)”选项卡中复制您的 Client ID 和 Client Secret

第 2 步：将用户分配给应用程序​

确保在 分配 (Assignments) 选项卡中将用户分配给该应用。如果启用了联合代理模式 (Federation Broker Mode)，您可能需要将其禁用才能手动分配用户。

第 3 步：设置环境变量​

设置以下环境变量。两种 Okta 授权服务器之间的唯一区别在于端点 URL

组织授权服务器 (Org Authorization Server)（适用于所有 Okta 计划，无需额外 SKU）

GENERIC_CLIENT_ID="<your-client-id>"
GENERIC_CLIENT_SECRET="<your-client-secret>"
GENERIC_AUTHORIZATION_ENDPOINT="https://<your-okta-domain>/oauth2/v1/authorize"
GENERIC_TOKEN_ENDPOINT="https://<your-okta-domain>/oauth2/v1/token"
GENERIC_USERINFO_ENDPOINT="https://<your-okta-domain>/oauth2/v1/userinfo"
PROXY_BASE_URL="https://<your-proxy-base-url>"

自定义授权服务器 (Custom Authorization Server)（需要 Okta API 访问管理 SKU）

GENERIC_CLIENT_ID="<your-client-id>"
GENERIC_CLIENT_SECRET="<your-client-secret>"
GENERIC_AUTHORIZATION_ENDPOINT="https://<your-okta-domain>/oauth2/default/v1/authorize"
GENERIC_TOKEN_ENDPOINT="https://<your-okta-domain>/oauth2/default/v1/token"
GENERIC_USERINFO_ENDPOINT="https://<your-okta-domain>/oauth2/default/v1/userinfo"
PROXY_BASE_URL="https://<your-proxy-base-url>"
提示

您可以在 https://<your-okta-domain>/.well-known/openid-configuration 找到所有的 OAuth 端点

第 3a 步：配置访问策略（仅限自定义授权服务器）​

如果您使用自定义授权服务器，则必须配置访问策略。否则，用户将收到 no_matching_policy 错误。如果您使用组织授权服务器，请跳过此步骤。

  1. 前往 Security（安全） → API
  1. 选择 default（默认） 授权服务器（或您的自定义服务器）
  1. 点击 Access Policies（访问策略） 选项卡，创建一个分配给您的 LiteLLM 应用的新策略
  2. 添加一条允许 Authorization Code（授权码） 授权类型的规则

更多详情请参阅 Okta 访问策略文档。

第 4 步：配置 Okta 安全设置​

建议为 Okta 设置 GENERIC_CLIENT_STATE 以防止 CSRF 攻击

GENERIC_CLIENT_STATE="random-string"

PKCE (代码交换证明密钥) — 如果您的 Okta 应用程序配置为需要 PKCE，请通过设置启用它

GENERIC_CLIENT_USE_PKCE="true"

LiteLLM 将在 OAuth 流程中自动处理 PKCE 参数的生成和验证。

第 5 步：测试 SSO 流程​

  1. 启动您的 LiteLLM 代理
  2. 导航至 https://<your-proxy-base-url>/ui
  3. 点击 SSO 登录按钮
  4. 使用 Okta 进行身份验证，并验证是否重定向回了 LiteLLM

故障排除​

错误原因解决方案
redirect_uri 错误未配置重定向 URI在 Okta 的登录重定向 URI 中添加 <proxy_base_url>/sso/callback
access_denied用户未分配到应用程序在“分配”选项卡中分配用户
no_matching_policy缺少访问策略（仅限自定义授权服务器）在授权服务器中创建访问策略（请参阅第 3a 步）

默认登录、登出 URL​

某些 SSO 提供商需要特定的登录和登出重定向 URL。您可以输入以下值。

  • 登录: <your-proxy-base-url>/sso/key/generate
  • 登出: <your-proxy-base-url>

这是在代理上设置登出 URL 的环境变量

PROXY_LOGOUT_URL="https://www.google.com"

第 3 步。在 .env 中设置 PROXY_BASE_URL​

在您的 .env 中设置此项（以便代理可以设置正确的重定向 URL）

PROXY_BASE_URL=https://litellm-api.up.railway.app

第 4 步。测试流程​

使用 SSO 限制电子邮件子域​

如果您正在使用 SSO 并希望仅允许具有特定子域的用户（例如 @berri.ai 电子邮件帐户）访问 UI，请执行此操作

export ALLOWED_EMAIL_DOMAINS="berri.ai"

这将在允许访问之前检查从 SSO 收到的用户电子邮件是否包含此域。

设置代理管理员​

启用 SSO 时设置代理管理员。启用 SSO 后，用户的 user_id 将从 SSO 提供商处检索。要设置代理管理员，您需要从 UI 复制 user_id 并将其作为 PROXY_ADMIN_ID 设置在您的 .env 中。

第 1 步：从 UI 复制您的 ID​

第 2 步：在您的 .env 中将其设置为 PROXY_ADMIN_ID​

export PROXY_ADMIN_ID="116544810872468347480"

这会将 LiteLLM_UserTable 中的用户角色更新为 proxy_admin。

如果您打算更改此 ID，请通过 API /user/update 或 UI（内部用户页面）更新用户角色。

第 3 步：查看所有代理密钥​

信息

如果您没有看到所有密钥，这可能是由于令牌缓存。只需重新登录即可生效。

在管理后台禁用 默认团队​

如果您想在管理后台隐藏“默认团队”，请使用此功能

将应用以下逻辑

  • 如果已分配团队，则不显示 默认团队
  • 如果未分配团队，则用户应看到 默认团队

在您的 litellm config.yaml 中设置 default_team_disabled: true

general_settings:
  master_key: sk-1234
  default_team_disabled: true # OR you can set env var PROXY_DEFAULT_TEAM_DISABLED="true"

在启用 SSO 时使用用户名、密码登录​

如果您需要在启用 SSO 时通过用户名/密码访问 UI，请导航至 /fallback/login。此路由允许您使用用户名/密码凭据登录。

限制 UI 访问​

您可以将 UI 访问权限限制为仅管理员——包括您（proxy_admin）以及您授予只读访问权限的人员（proxy_admin_viewer，用于查看全球支出）。

第 1 步。设置 'admin_only' 访问权限

general_settings:
    ui_access_mode: "admin_only"

第 2 步。邀请只读用户

管理后台自定义品牌​

在 LiteLLM 管理后台使用您公司的自定义品牌，我们允许您：

  • 自定义 UI Logo
  • 自定义 UI 配色方案

我们允许您传递本地图像或图像的 http/https URL

在您的 env 中设置 UI_LOGO_PATH。我们建议使用托管图像，这样更容易设置、配置和调试

托管图像设置示例

UI_LOGO_PATH="https://litellm-logo-aws-marketplace.s3.us-west-2.amazonaws.com/berriai-logo-github.png"

本地图像设置示例（在您的容器上）

UI_LOGO_PATH="ui_images/logo.jpg"

或者直接从管理后台设置您的 Logo：​

设置自定义配色主题​

{
    "brand": {
      "DEFAULT": "teal",
      "faint": "teal",
      "muted": "teal",
      "subtle": "teal",
      "emphasis": "teal",
      "inverted": "teal"
    }
}

  • 部署 LiteLLM 代理服务器

故障排除​

“The 'redirect_uri' parameter must be a Login redirect URI in the client app settings” 错误​

当重定向 URI 配置不正确时，此错误通常会出现在 Okta 和其他 SSO 提供商中。

问题​

Your request resulted in an error. The 'redirect_uri' parameter must be a Login redirect URI in the client app settings

解决方案​

1. 确保已在 .env 中设置 PROXY_BASE_URL 且包含协议

确保您的 PROXY_BASE_URL 包含完整的协议 URL (http:// 或 https://)

# ✅ Correct - includes https://
PROXY_BASE_URL=https://litellm.platform.com

# ✅ Correct - includes http://
PROXY_BASE_URL=http://litellm.platform.com

# ❌ Incorrect - missing protocol
PROXY_BASE_URL=litellm.platform.com

2. 对于 Okta，请确保设置了 GENERIC_CLIENT_STATE，并在需要时配置了 PKCE

有关 GENERIC_CLIENT_STATE 和 PKCE 配置的详细信息，请参阅 Okta SSO — 第 4 步：配置 Okta 安全设置。

常见配置问题​

Base URL 中缺少协议​

# This will cause redirect_uri errors
PROXY_BASE_URL=mydomain.com

# Fix: Add the protocol
PROXY_BASE_URL=https://mydomain.com

回退登录​

如果您需要在启用 SSO 时通过用户名/密码访问 UI，请导航至 /fallback/login。此路由允许您使用用户名/密码凭据登录。

调试 SSO JWT 字段​

如果您需要检查 LiteLLM 从 SSO 提供商处收到的 JWT 字段，请遵循这些说明。本指南将引导您完成设置调试回调以在 SSO 过程中查看 JWT 数据。


  1. 将 /sso/debug/callback 添加为您 SSO 提供商中的重定向 URL

在 SSO 提供商的设置中，添加以下 URL 作为新的重定向 (回调) URL

重定向 URL
http://<proxy_base_url>/sso/debug/callback

  1. 在浏览器中导航至调试登录页面

    在浏览器中导航至以下 URL

    要导航到的 URL
    https://<proxy_base_url>/sso/debug/login

    这将启动标准的 SSO 流程。您将被重定向到 SSO 提供商的登录屏幕，身份验证成功后，您将被重定向回 LiteLLM 的调试回调路由。

  2. 查看 JWT 字段

重定向后，您应该会看到一个名为“SSO Debug Information”的页面。此页面显示了从您的 SSO 提供商处收到的 JWT 字段（如上图所示）

高级​

通过 Azure 应用角色管理用户角色​

通过在 Azure Entra ID 中定义用户权限来集中管理角色。当用户登录时，LiteLLM 将根据您的 Azure 配置自动分配角色——无需在 LiteLLM 中手动管理角色。

第 1 步：在 Azure 应用注册上创建应用角色​

  1. 导航至 https://portal.azure.com/ 上的应用注册
  2. 转到 App roles（应用角色） > Create app role（创建应用角色）
  3. 使用 支持的 LiteLLM 角色 之一配置应用角色
    • 显示名称: Admin Viewer（或您喜欢的显示名称）
    • 值: proxy_admin_viewer (必须与 LiteLLM 角色值完全匹配)
  4. 点击 Apply（应用） 保存角色
  5. 对您要使用的每个 LiteLLM 角色重复此操作

支持的 LiteLLM 角色值 (请参阅 完整角色文档)

  • proxy_admin - 完全管理员访问权限
  • proxy_admin_viewer - 只读管理员访问权限
  • internal_user - 可创建/查看/删除自己的密钥
  • internal_user_viewer - 可查看自己的密钥（只读）

第 2 步：将用户分配给应用角色​

  1. 导航至 https://portal.azure.com/ 上的 企业应用程序
  2. 选择您的 LiteLLM 应用程序
  3. 转到 Users and groups（用户和组） > Add user/group（添加用户/组）
  4. 选择用户
  5. 在 Select a role（选择角色） 下，选择您创建的应用角色（例如 proxy_admin_viewer）
  6. 点击 Assign（分配） 保存

第 3 步：登录并验证​

  1. 通过 SSO 登录 LiteLLM UI
  2. LiteLLM 将自动从 JWT 令牌中提取应用角色
  3. 用户将被分配相应的角色（您可以通过检查用户配置文件下拉菜单在 UI 中验证这一点）

注意： 来自 Entra ID 的角色将覆盖 LiteLLM 数据库中的任何现有角色。这确保了您的 SSO 提供商是用户角色的权威来源。

🚅
LiteLLM 企业版
SSO/SAML、审计日志、支出跟踪、多团队管理和护栏 —— 专为生产环境构建。
了解更多 →