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

Auth0

LibreChatのOpenID ConnectプロバイダーとしてAuth0を設定する

このガイドでは、LibreChatのOpenID ConnectプロバイダーとしてAuth0を設定する手順を説明します。

概要

Auth0は、LibreChatのOpenID Connectプロバイダーとして使用できます。トークンの再利用を有効にした状態（OPENID_REUSE_TOKENS=true）でAuth0を使用する場合は、認証の問題を防ぐためにOPENID_AUDIENCE環境変数を設定する必要があります。

前提条件

  • アクティブなテナントを持つAuth0アカウント
  • Auth0でアプリケーションやAPIを作成するための管理者アクセス権
  • 設定準備が完了したLibreChatインスタンス

設定手順

ステップ 1: 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 ダッシュボードに移動 → Applications → APIs
  2. 「Create API」をクリック
  3. APIの設定:
    • 名前: LibreChat API (またはお好みの名前)
    • Identifier: https://api.librechat.ai (または任意の識別子)
      • 注: これは単なる一意の識別子であり、実際のURLではありません。アクセス可能である必要はありません。
      • 一般的なパターン: https://api.yourdomain.com、https://librechat.yourdomain.com など。
    • 署名アルゴリズム: RS256 (推奨)
  4. 「Create」をクリック

ステップ 4: オフラインアクセスの設定

  1. APIの「Settings」 → **「Access Settings」**に移動します
  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 を使用してください。

Step 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 の理解

問題点

Auth0を OPENID_REUSE_TOKENS=true で使用する場合：

  • Auth0はデフォルトで不透明アクセストークン（JWE形式）を返します。
  • LibreChatは、検証可能な署名付きJWTトークン（JWS形式）を想定しています。
  • 適切な設定を行わないと、この不一致により認証エラーや無限リフレッシュループが発生します。

解決策

OPENID_AUDIENCE 環境変数:

  • （ステップ3で作成した）Auth0 API識別子に設定する必要があります。
  • Auth0が不透明なトークンではなく、署名付きJWTアクセストークンを発行するように強制します。
  • LibreChatがAuth0のJWKS endpointを使用してトークンを検証できるようにします
  • JWT検証用のカンマ区切りオーディエンスを含めることができます。Auth0認可リクエストは、空ではない最初の値を使用します。

仕組み

OPENID_AUDIENCE が設定されている場合：

  1. LibreChatは認可リクエストに audience パラメータを含めており、カンマ区切りで複数のaudienceが設定されている場合は、空ではない最初の値を使用します。
  2. Auth0は、audienceを登録済みAPIとして認識します。
  3. Auth0は検証可能なJWTアクセストークンを発行します
  4. LibreChatはトークンを正常に検証し、認証は正しく機能しています

環境変数リファレンス

KeyTypeDescriptionExample
OPENID_AUDIENCEstringAuth0 APIの識別子。OPENID_REUSE_TOKENS=trueをAuth0で使用する際、不透明トークンの問題を回避するために必須です。JWT検証にはカンマ区切りの値が使用でき、認可リクエストには最初の空でない値が使用されます。OPENID_AUDIENCE=https://api.librechat.ai

トラブルシューティング

無限リフレッシュループ

症状: 「Continue with OpenID」をクリックした後、ページが継続的にリロードされる

解決策:

  1. OPENID_AUDIENCE が Auth0 API 識別子に設定されていることを確認してください。
  2. Auth0でAPIが作成され、オフラインアクセスが有効になっていることを確認してください
  3. audience の値が完全に一致していることを確認してください

Invalid Token Errors

症状: トークン検証エラーにより認証が失敗する

解決策:

  1. デバッグログを有効にする: DEBUG_OPENID_REQUESTS=true
  2. Auth0が（不透明なトークンではなく）JWTトークンを返していることを確認してください
  3. JWKS endpoint がアクセス可能であることを確認してください

リフレッシュトークンの欠落

症状: 認証レスポンスにリフレッシュトークンが含まれていない

解決策:

  1. OPENID_SCOPE に offline_access が含まれていることを確認してください。
  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 で編集