OAuth 允许您使用第三方服务来验证您的用户。

要激活 OAuth 提供商，您需要在代码中定义 OAuth 回调，并设置提供商的环境变量。

​
提供商

请按照以下指南为您选择的提供商创建 OAuth 应用。然后将信息复制到相应的环境变量中以激活提供商。

如果您的应用部署在反向代理后（例如 Cloud Run），您需要设置 CHAINLIT_URL 环境变量。例如，如果您的应用托管在 https://mydomain.com，CHAINLIT_URL 应设置为 https://mydomain.com。

​
GitHub

转到此页面创建新的 GitHub OAuth 应用。

回调 URL 应为：CHAINLIT_URL/auth/oauth/github/callback。如果您的 Chainlit 应用托管在 localhost:8000，您应使用 http://localhost:8000/auth/oauth/github/callback。

您需要设置以下环境变量

  • OAUTH_GITHUB_CLIENT_ID：客户端 ID
  • OAUTH_GITHUB_CLIENT_SECRET：客户端密钥

​
Gitlab

转到此页面创建新的 GitLab OAuth 应用。创建应用时，您需要允许 openid、profile 和 email 范围。

回调 URL 应为：CHAINLIT_URL/auth/oauth/gitlab/callback。如果您的 Chainlit 应用托管在 localhost:8000，您应使用 http://localhost:8000/auth/oauth/gitlab/callback。

您需要设置以下环境变量

  • OAUTH_GITLAB_CLIENT_ID：客户端 ID
  • OAUTH_GITLAB_CLIENT_SECRET：客户端密钥
  • OAUTH_GITLAB_DOMAIN：域名（不含协议）

​
Google

转到此页面创建新的 Google OAuth 应用。

回调 URL 应为：CHAINLIT_URL/auth/oauth/google/callback。如果您的 Chainlit 应用托管在 localhost:8000，您应使用 http://localhost:8000/auth/oauth/google/callback。

您需要设置以下环境变量

  • OAUTH_GOOGLE_CLIENT_ID：客户端 ID
  • OAUTH_GOOGLE_CLIENT_SECRET：客户端密钥

​
Azure Active Directory

按照本指南创建新的 Azure Active Directory OAuth 应用。

回调 URL 应为：CHAINLIT_URL/auth/oauth/azure-ad/callback。如果您的 Chainlit 应用托管在 localhost:8000，您应使用 http://localhost:8000/auth/oauth/azure-ad/callback。

您需要设置以下环境变量

  • OAUTH_AZURE_AD_CLIENT_ID：客户端 ID
  • OAUTH_AZURE_AD_CLIENT_SECRET：客户端密钥
  • OAUTH_AZURE_AD_TENANT_ID：Azure 租户 ID

如果您的应用支持“仅限此组织目录中的帐户”（单租户），您需要明确设置：OAUTH_AZURE_AD_ENABLE_SINGLE_TENANT=true。否则，完全无需设置此环境变量。

​
Okta

按照本指南创建 OIDC 应用集成。

回调 URL 应为：CHAINLIT_URL/auth/oauth/okta/callback。如果您的 Chainlit 应用托管在 localhost:8000，您应使用 http://localhost:8000/auth/oauth/okta/callback。

您需要设置以下环境变量

  • OAUTH_OKTA_CLIENT_ID：客户端 ID
  • OAUTH_OKTA_CLIENT_SECRET：客户端密钥
  • OAUTH_OKTA_DOMAIN：Okta 设置的域名 - 例如 https://company.okta.com

配置 Okta OAuth 路由有几种方法

  • 使用 Okta 单点登录 设置时，您需要将 OAUTH_OKTA_AUTHORIZATION_SERVER_ID 环境变量设置为 false。
  • 将 Okta 用作您的应用或 API 的身份平台时，您可以
    • 如果您有开发者帐户，将 OAUTH_OKTA_AUTHORIZATION_SERVER_ID 环境变量设置为 default，
    • 或将其设置为您的自定义授权服务器的授权服务器 ID。

​
Descope

前往 Descope 注册页面，开始创建您的帐户并设置您的认证。

回调 URL 应为：CHAINLIT_URL/auth/oauth/descope/callback。如果您的 Chainlit 应用托管在 localhost:8000，您应使用 http://localhost:8000/auth/oauth/descope/callback。

您需要设置以下环境变量

  • OAUTH_DESCOPE_CLIENT_ID：Descope 项目 ID，可在控制台的项目设置下找到。
  • OAUTH_DESCOPE_CLIENT_SECRET：Descope 访问密钥，可在控制台的访问密钥下创建。

​
Auth0

按照本指南创建 Auth0 应用。

回调 URL 应为：CHAINLIT_URL/auth/oauth/auth0/callback。如果您的 Chainlit 应用托管在 localhost:8000，您应使用 http://localhost:8000/auth/oauth/auth0/callback。

您需要设置以下环境变量

  • OAUTH_AUTH0_CLIENT_ID：客户端 ID
  • OAUTH_AUTH0_CLIENT_SECRET：客户端密钥
  • OAUTH_AUTH0_DOMAIN：Auth0 设置的域名

可选环境变量

  • OAUTH_AUTH0_ORIGINAL_DOMAIN：Auth0 设置的原始域名（如果您使用自定义域名）

​
Amazon Cognito

按照本指南创建新的 Amazon Cognito 用户池。

回调 URL 应为：CHAINLIT_URL/auth/oauth/aws-cognito/callback。如果您的 Chainlit 应用托管在 localhost:8000，您应使用 http://localhost:8000/auth/oauth/aws-cognito/callback。

您需要设置以下环境变量

  • OAUTH_COGNITO_CLIENT_ID：客户端 ID
  • OAUTH_COGNITO_CLIENT_SECRET：客户端密钥
  • OAUTH_COGNITO_DOMAIN：Cognito 域名

​
Keycloak

按照此文档在您的 realm 中创建新客户端。

您可以选择更改 Keycloak 提供商的 id，默认 ID 为 keycloak。如果您想在登录页面上显示更合适的名称，这将非常有用。使用 OAUTH_KEYCLOAK_NAME 环境变量来设置名称。不要选择与任何其他 OAuth 提供商冲突的 ID。

客户端的回调 URL 应为：CHAINLIT_URL/auth/oauth/${OAUTH_KEYCLOAK_NAME}/callback。如果您的 Chainlit 应用托管在 localhost:8000，您应使用 http://localhost:8000/auth/oauth/${OAUTH_KEYCLOAK_NAME}/callback。

您需要设置以下环境变量

  • OAUTH_KEYCLOAK_CLIENT_ID：客户端 ID
  • OAUTH_KEYCLOAK_CLIENT_SECRET：客户端密钥
  • OAUTH_KEYCLOAK_REALM：包含您的客户端的 realm。
  • OAUTH_KEYCLOAK_BASE_URL：您的 Keycloak URL。
  • OAUTH_KEYCLOAK_NAME：可选，见上文。

​
自定义提供商

使用 Chainlit 可以接入任何 OAuth 提供商。所需步骤是

  • 在运行时修改 providers 变量
  • 实现带有方法和字段的 CustomOAuthProvider(OAuthProvider) 类
    • get_token(self, code, url)
    • get_user_info(self, token)
    • authorize_params
    • env
  • 提供 env 中描述的环境变量，例如
    • YOUR_PROVIDER_CLIENT_ID
    • YOUR_PROVIDER_CLIENT_SECRET

本 cookbook 示例描述了如何实现，也可查看基类作为参考。

​
Prompt 配置

从 1.3.0 版本开始，Chainlit 允许您通过 prompt 参数配置 OAuth 提供商如何处理重新认证。这对于控制用户退出登录时的行为特别有用。

您可以使用以下两个环境变量来配置此行为

  • OAUTH_PROMPT：设置所有 OAuth 提供商的默认 prompt 行为
  • OAUTH_<PROVIDER>_PROMPT：设置特定提供商的 prompt 行为（例如，OAUTH_GITHUB_PROMPT）

这些变量支持的值包括

  • none：无需交互（未设置时的默认值）
  • login：强制重新认证
  • consent：请求批准所需的范围
  • select_account：允许用户选择不同的帐户

例如

# Force consent prompt for all providers
OAUTH_PROMPT=consent

# Override specific provider to force login
OAUTH_GITHUB_PROMPT=login

注意：不同 OAuth 提供商对不同 prompt 值的行为和支持可能有所不同。例如

  • GitHub 对 prompt=consent 响应良好
  • 某些提供商（如 Descope）仅支持 prompt=login

此功能在您想要实现以下目的时特别有用

  • 允许用户正确退出登录并切换帐户
  • 出于安全目的强制重新认证
  • 允许用户选择他们批准的范围
  • 阻止退出登录后自动重新认证

prompt 参数在 OpenID Connect Core 1.0 规范中定义。更多技术细节，请参考 OpenID Connect 文档。

​
示例

​
允许所有通过 OAuth 认证的用户。

from typing import Dict, Optional
import chainlit as cl


@cl.oauth_callback
def oauth_callback(
  provider_id: str,
  token: str,
  raw_user_data: Dict[str, str],
  default_user: cl.User,
) -> Optional[cl.User]:
  return default_user

​
仅允许来自特定 Google 域的用户。

from typing import Dict, Optional
import chainlit as cl


@cl.oauth_callback
def oauth_callback(
  provider_id: str,
  token: str,
  raw_user_data: Dict[str, str],
  default_user: cl.User,
) -> Optional[cl.User]:
  if provider_id == "google":
    if raw_user_data["hd"] == "example.org":
      return default_user
  return None