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 (또는 선호하는 식별자)
     • 참고: 이는 실제 URL이 아닌 고유 식별자일 뿐입니다. 접근 가능할 필요는 없습니다.
     • 일반적인 패턴: https://api.yourdomain.com, https://librechat.yourdomain.com 등.
   • 서명 알고리즘: RS256 (권장)
4. "Create"를 클릭하세요

4단계: 오프라인 액세스 구성

1. API 설정으로 이동 → 액세스 설정(Access Settings)
2. **"Allow Offline Access"**를 활성화하세요
3. 변경 사항 저장

5단계: 구성 값 수집

Auth0 애플리케이션의 Basic Information 섹션에서 다음을 찾을 수 있습니다:

• Domain: dev-example.us.auth0.com으로 표시됩니다 (https:// 접두사를 추가해야 합니다)
• Client ID: 긴 영숫자 문자열
• Client Secret: 기본적으로 숨겨짐 (클릭하여 표시)

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이 불투명 토큰(opaque tokens) 대신 서명된 JWT 액세스 토큰을 발급하도록 강제합니다.
• LibreChat이 Auth0의 JWKS endpoint를 사용하여 토큰을 검증할 수 있도록 활성화합니다.
• JWT 검증을 위한 쉼표로 구분된 대상(audiences)을 포함할 수 있습니다. 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가 생성되었고 오프라인 액세스(offline access)가 활성화되었는지 확인하세요.
3. audience 값이 정확히 일치하는지 확인하세요

잘못된 토큰 오류 (Invalid Token Errors)

증상: 토큰 유효성 검사 오류로 인해 인증 실패

해결 방법:

1. 디버그 로깅 활성화: DEBUG_OPENID_REQUESTS=true
2. Auth0이 (불투명 토큰이 아닌) JWT 토큰을 반환하는지 확인하세요
3. JWKS endpoint가 액세스 가능한지 확인하세요

새로 고침 토큰 누락 (Missing Refresh Token)

증상: 인증 응답에 리프레시 토큰이 없음

해결 방법:

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 토큰 재사용