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: アプリケーション設定の構成

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を作成する (トークンの再利用に必須)

1. Auth0 ダッシュボードに移動 → Applications → APIs
2. 「Create API」をクリックします
3. APIの設定:
   • 名前: LibreChat API (またはお好みの名前)
   • Identifier: https://api.librechat.ai (または任意の識別子)
     • Note: これは単なる一意の識別子であり、実際の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: デフォルトでは非表示（クリックで表示）

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

# Maximum logout URL length before using logout_hint instead of id_token_hint (default: 2000)
# OPENID_MAX_LOGOUT_URL_LENGTH=2000

# 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はトークンを正常に検証し、認証が正しく機能します

環境変数リファレンス

トラブルシューティング

無限リフレッシュループ

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

解決策:

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

無効なトークンエラー

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

解決策:

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である必要はないことに注意してください。

その他のリソース

• Auth0 Documentation
• Auth0 Access Tokens
• LibreChat OpenID トークンの再利用