OpenID Connect 토큰 재사용

LibreChat은 사용자 인증 상태를 관리하기 위해 OpenID Connect 공급자(Azure Entra ID 또는 Auth0 등)가 발급한 액세스 토큰 및 리프레시 토큰 재사용을 지원합니다. 이 기능이 활성화되면, 쿠키로 사용자에게 전달되는 리프레시 토큰은 LibreChat이 아닌 OpenID 공급자가 발급하게 되며, 이를 통해 LibreChat 서버가 해당 토큰을 갱신하고 공급자에게 액세스 토큰을 요청할 수 있게 됩니다.

필수 조건

• 구성된 OpenID Connect 공급자 (Azure Entra ID, Auth0 등)
• 기본 OpenID Connect 설정이 완료되었습니다

구성 단계

1. 환경 변수에 OPENID_REUSE_TOKENS=true를 설정하세요.

공급자별 구성 (Provider-Specific Configuration)

Auth0 구성

Auth0의 경우, 다음을 수행해야 합니다:

1. Auth0에서 API 생성 (JWT 액세스 토큰에 필요):

   • Auth0 Dashboard → Applications → APIs로 이동하세요.
   • **"Create API"**를 클릭하세요
   • Identifier(예: https://api.librechat.com)를 설정하세요.
   • API 설정에서 **"Allow Offline Access"**를 활성화하세요.

2. 필수 환경 변수를 설정하세요:

   # Required for Auth0
   OPENID_AUDIENCE=https://api.librechat.com  # Your API identifier from Auth0
   OPENID_SCOPE=openid profile email offline_access

자세한 Auth0 구성은 다음을 참조하세요: Auth0 OpenID Connect Configuration

Azure Entra ID 구성

2. OpenID 공급자를 구성합니다 (Azure Entra ID를 예시로 사용):
   • Azure Portal로 이동하여 앱 등록(app registration)으로 이동하세요.
   • 왼쪽 메뉴에서 "Expose API"를 클릭하세요
   • "Application ID URI" 옆의 "Add"를 클릭하세요
   • API URI(예: "api://librechat")를 입력하고 저장하세요.

3. API 스코프 생성:
   • "Expose API" 섹션에서 "Add a scope"를 클릭하세요.
   • 적절한 권한으로 범위를 구성하세요
   • 범위 구성을 저장합니다

4. API 권한 구성:
   • 왼쪽 메뉴에서 "API permissions"로 이동하세요
   • "Add a permission"을 클릭하세요
   • "APIs my organization uses" 아래에서 앱을 검색하세요
   • "Delegated permissions"을 선택하고 적절한 범위(예: "access_user")를 선택하세요.

5. 환경에서 필요한 scope를 설정하세요:

   OPENID_SCOPE=api://librechat/.default openid profile email offline_access

   참고: 재사용을 위한 리프레시 토큰을 얻으려면 offline_access 스코프가 필요합니다.

6. 관리자 동의 부여:

   • Azure Portal에서 Enterprise Applications로 이동하세요
   • LibreChat 애플리케이션 찾기
   • Security > Permissions로 이동하세요
   • "Grant admin consent"을 클릭하세요

7. 팝업에서 요청된 권한을 수락하세요

8. LibreChat 캐시를 삭제하고 서비스를 재시작하세요.

환경 변수

# OpenID Token Reuse Configuration
OPENID_REUSE_TOKENS=true
OPENID_SCOPE=api://librechat/.default openid profile email offline_access
OPENID_REUSE_MAX_SESSION_AGE_MS=900000  # 15 minutes in milliseconds

# Required for Auth0 (use your API identifier)
# OPENID_AUDIENCE=https://api.librechat.com

# Caching Configuration
OPENID_JWKS_URL_CACHE_ENABLED=true
OPENID_JWKS_URL_CACHE_TIME=600000  # 10 minutes in milliseconds

# Azure-specific Configuration
OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED=true
OPENID_ON_BEHALF_FLOW_USERINFO_SCOPE=user.read

# Logout Configuration
OPENID_USE_END_SESSION_ENDPOINT=true

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

추가 구성 옵션

• OPENID_AUDIENCE: JWT 검증 및 권한 부여 요청을 위한 Audience 값입니다. Auth0의 경우, 불투명(opaque) 토큰 대신 JWT 액세스 토큰을 받기 위해 필수입니다. JWT 검증 시 쉼표로 구분된 값을 사용할 수 있으며, 권한 부여 요청 시에는 비어 있지 않은 첫 번째 값을 사용합니다.
• OPENID_REUSE_MAX_SESSION_AGE_MS: LibreChat이 IdP 새로고침을 강제하기 전까지 재사용된 OpenID 세션 토큰이 유지되는 최대 시간(기본값: 900000 ms / 15분). 60 * 60 * 24 * 1000과 같은 산술 표현식을 사용할 수 있습니다. 공급자가 액세스 토큰을 새로 고칠 때마다 이전 액세스 토큰을 취소하는 경우, 이 값을 IdP 액세스 토큰 수명에 맞춰 늘리십시오.
• OPENID_JWKS_URL_CACHE_ENABLED: JWKS endpoint에 대한 과도한 HTTP 요청을 방지하기 위해 서명 키 검증 결과의 캐싱을 활성화합니다.
• OPENID_JWKS_URL_CACHE_TIME: 캐시 지속 시간(밀리초 단위, 기본값: 600000 ms / 10분)
• OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED: 사용자 정보에 대한 on-behalf-of 흐름을 활성화합니다 (Azure 전용)
• OPENID_ON_BEHALF_FLOW_USERINFO_SCOPE: on-behalf-of 흐름에서 사용자 정보를 위한 스코프 (Azure 전용)
• OPENID_USE_END_SESSION_ENDPOINT: 로그아웃을 위해 end session endpoint 사용을 활성화합니다
• OPENID_MAX_LOGOUT_URL_LENGTH: URI가 너무 길어지는 오류를 방지하기 위해 id_token_hint 대신 logout_hint를 사용하기 전의 최대 URL 길이 (기본값: 2000)

보안 고려 사항

• 적절한 토큰 저장 및 처리 보장
• 적절한 토큰 갱신 메커니즘을 구현하세요
• 토큰 사용량을 모니터링하고 필요한 경우 속도 제한(rate limiting)을 구현하세요.
• 정기적으로 클라이언트 비밀(client secrets)을 교체하세요
• 토큰 저장을 위해 보안 쿠키 설정을 사용하세요

문제 해결

토큰 재사용과 관련하여 문제가 발생하는 경우:

1. 모든 필수 스코프가 올바르게 구성되었는지 확인하세요
2. 관리자 동의가 부여되었는지 확인하세요
3. API 권한이 올바르게 설정되었는지 확인하세요
4. 토큰 캐시가 예상대로 작동하는지 확인하세요
5. 애플리케이션 로그에서 인증 오류가 있는지 확인하세요
6. 환경 변수에 DEBUG_OPENID_REQUESTS=true를 설정하여 상세 OpenID 요청 헤더 로깅을 활성화하면, URL 외에도 요청 헤더를 확인할 수 있습니다(민감한 데이터는 마스킹 처리됨).