LibreChat is joining ClickHouse to power the open-source Agentic Data Stack 🎉 Learn more
LibreChat

Auth0

配置 Auth0 作为 LibreChat 的 OpenID Connect 提供商

本指南将引导您完成将 Auth0 配置为 LibreChat 的 OpenID Connect 提供商的步骤。

概述

Auth0 可以作为 LibreChat 的 OpenID Connect 提供商。当在启用令牌重用（OPENID_REUSE_TOKENS=true）的情况下使用 Auth0 时，必须配置 OPENID_AUDIENCE 环境变量以防止身份验证问题。

先决条件

  • 一个拥有活跃租户的 Auth0 账户
  • 在 Auth0 中创建应用程序和 API 的管理员权限
  • LibreChat 实例已准备好进行配置

配置步骤

第一步：创建 Auth0 应用程序

  1. 前往 Auth0 Dashboard → Applications → Applications
  2. 点击 "Create Application"
  3. 配置应用程序：
    • 名称: LibreChat (或您偏好的名称)
    • Application Type: 选择 "Single Page Application"
  4. 点击 "Create"

第 2 步：配置应用程序设置

需要 HTTPS

Auth0 不允许在生产环境应用中使用 http://localhost URL。对于本地开发/测试，你需要使用 HTTPS。你可以使用以下服务：

  • ngrok: ngrok http 3080 (提供指向 localhost 的 HTTPS 隧道)
  • Caddy: 本地 HTTPS 代理服务器
  • localtunnel: 类似于 ngrok

使用 ngrok 的示例：

ngrok http 3080
# This will give you a URL like: https://abc123.ngrok.io
  1. 在您应用程序的 Settings 选项卡中：
  2. 设置 Allowed Callback URLs： 
    https://your-domain.ngrok.io/oauth/openid/callback
    （请使用您的 ngrok URL 进行测试，或使用您的生产环境 HTTPS URL）
  3. 设置 Allowed Logout URLs（如果使用结束会话功能）： 
    https://your-domain.ngrok.io
  4. 设置 Allowed Web Origins： 
    https://your-domain.ngrok.io
  5. 保存更改

第 3 步：创建 Auth0 API（令牌重用所必需）

令牌重用的重要注意事项

当使用 OPENID_REUSE_TOKENS=true 时，此步骤是必需的。否则，Auth0 将返回 LibreChat 无法验证的不透明令牌，从而导致无限刷新循环。

  1. 前往 Auth0 Dashboard → Applications → APIs
  2. 点击“Create API”
  3. 配置 API：
    • 名称: LibreChat API (或您偏好的名称)
    • 标识符: https://api.librechat.ai (或您偏好的标识符)
      • 注意：这只是一个唯一标识符，并非实际的 URL。它不需要是可访问的。
      • 常见模式：https://api.yourdomain.com，https://librechat.yourdomain.com 等。
    • 签名算法: RS256 (推荐)
  4. 点击“Create”

第 4 步：配置离线访问

  1. 前往您的 API 设置 → 访问设置
  2. 启用 "Allow Offline Access"
  3. 保存更改

第 5 步：收集配置值

在您的 Auth0 应用程序的 Basic Information 部分，您将找到：

  • Domain: 显示为 dev-example.us.auth0.com（你需要添加 https:// 前缀）
  • Client ID: 一个长字母数字字符串
  • Client Secret: 默认隐藏（点击以显示）

重要

Auth0 中显示的 Domain 不包含 https:// 前缀。在配置 OPENID_ISSUER 时，您必须加上该前缀。

示例：如果 Auth0 显示 dev-abc123.us.auth0.com，请使用 https://dev-abc123.us.auth0.com

第 6 步：配置 LibreChat 环境变量

将以下环境变量添加到您的 .env 文件中：

# OpenID Connect Configuration
# Domain from Basic Information (add https:// prefix)
OPENID_ISSUER=https://dev-abc123.us.auth0.com
 
# Client ID from Basic Information
OPENID_CLIENT_ID=your_long_alphanumeric_client_id
 
# Client Secret from Basic Information (click to reveal)
OPENID_CLIENT_SECRET=your_client_secret_from_basic_information
 
# Callback URL (must match what's configured in Auth0)
OPENID_CALLBACK_URL=/oauth/openid/callback
 
# Token Configuration
OPENID_REUSE_TOKENS=true
OPENID_SCOPE=openid profile email offline_access
 
# IMPORTANT: Your Auth0 API identifier (from Step 3)
OPENID_AUDIENCE=https://api.librechat.ai
 
# Security Settings (recommended)
OPENID_USE_PKCE=true
 
# Session Configuration (generate a secure random string)
OPENID_SESSION_SECRET=your-secure-session-secret-32-chars-or-more
 
# Optional: Custom button appearance
OPENID_BUTTON_LABEL=Continue with Auth0
# OPENID_IMAGE_URL=https://path-to-auth0-logo.png
 
# If using ngrok for testing, also update:
# DOMAIN_CLIENT=https://your-domain.ngrok.io
# DOMAIN_SERVER=https://your-domain.ngrok.io

理解 OPENID_AUDIENCE

问题所在

当在 OPENID_REUSE_TOKENS=true 的情况下使用 Auth0 时：

  • Auth0 默认返回 不透明访问令牌 (JWE 格式)
  • LibreChat 要求提供可验证的 签名 JWT 令牌（JWS 格式）
  • 如果没有进行正确的配置，这种不匹配会导致身份验证失败和无限刷新循环。

解决方案

OPENID_AUDIENCE 环境变量：

  • 必须设置为您的 Auth0 API 标识符（在第 3 步中创建）
  • 强制 Auth0 签发已签名的 JWT 访问令牌，而不是不透明令牌
  • 使 LibreChat 能够使用 Auth0 的 JWKS endpoint 验证令牌
  • 可能包含用于 JWT 验证的逗号分隔的受众（audiences）；Auth0 授权请求将使用第一个非空值

工作原理

当配置了 OPENID_AUDIENCE 时：

  1. LibreChat 在授权请求中包含 audience 参数，当配置了多个以逗号分隔的 audience 时，将使用第一个非空值。
  2. Auth0 将受众识别为已注册的 API
  3. Auth0 签发的 JWT 访问令牌可以进行验证
  4. LibreChat 已成功验证令牌，身份验证工作正常

环境变量参考

KeyTypeDescriptionExample
OPENID_AUDIENCEstring您的 Auth0 API 标识符。当使用 OPENID_REUSE_TOKENS=true 配合 Auth0 以防止不透明令牌问题时，此项为必填项。支持使用逗号分隔的值进行 JWT 验证；授权请求将使用第一个非空值。OPENID_AUDIENCE=https://api.librechat.ai

故障排除

无限刷新循环

症状：点击“Continue with OpenID”后页面持续重新加载

解决方案:

  1. 请确保 OPENID_AUDIENCE 已设置为您的 Auth0 API 标识符
  2. 验证 API 已在 Auth0 中创建且已启用离线访问 (offline access)
  3. 检查 audience 值是否完全匹配

无效令牌错误

症状：身份验证因令牌验证错误而失败

解决方案:

  1. 启用调试日志：DEBUG_OPENID_REQUESTS=true
  2. 验证 Auth0 是否返回 JWT 令牌（而非不透明令牌）
  3. 检查 JWKS endpoint 是否可访问

缺少 Refresh Token

症状：身份验证响应中没有刷新令牌 (refresh token)

解决方案:

  1. 确保 offline_access 包含在 OPENID_SCOPE 中
  2. 请在 Auth0 API 设置中确认已启用 "Allow Offline Access"。

最佳实践

  1. 始终使用 HTTPS - Auth0 要求所有回调 URL 必须使用 HTTPS
  2. 本地测试 - 使用 ngrok 或类似服务创建指向 localhost 的 HTTPS 隧道
  3. 保护您的会话密钥 - 请为 OPENID_SESSION_SECRET 使用一个强且随机的值
  4. 启用 PKCE - 设置 OPENID_USE_PKCE=true 以增强安全性
  5. 限制回调 URL - 仅允许在 Auth0 设置中使用您的实际域名
  6. 监控日志 - 在设置期间使用 DEBUG_OPENID_REQUESTS=true
  7. API Identifier - 请记住，这只是一个标识符，并非必须存在的实际 endpoint。

更多资源

这篇指南怎么样？

在 GitHub 上编辑