싱글사인온
Libre WebUI는 GitHub와 Hugging Face를 통한 OAuth 로그인 및 범용 OIDC 통합을 통한 모든 OpenID Connect 제공자를 지원합니다. OAuth 사용자도 로컬 Libre WebUI 사용자로 저장되며 기본적으로 user 역할을 받습니다. OIDC는 선택적으로 클레임에서 역할과 그룹을 매핑할 수 있습니다.
GitHub OAuth
GitHub Developer Settings에서 OAuth 앱을 만드세요.
로컬 콜백 URL:
http://localhost:3001/api/auth/oauth/github/callback
프로덕션 콜백 URL:
https://your-domain.example/api/auth/oauth/github/callback
백엔드 .env:
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
GITHUB_CALLBACK_URL=https://your-domain.example/api/auth/oauth/github/callback
GitHub OAuth는 user:email 범위를 요청합니다. 새 사용자의 사용자 이름에는 gh_ 접두사가 붙습니다.
Hugging Face OAuth
Hugging Face 설정에서 OAuth 앱을 만드세요.
로컬 콜백 URL:
http://localhost:3001/api/auth/oauth/huggingface/callback
프로덕션 콜백 URL:
https://your-domain.example/api/auth/oauth/huggingface/callback
백엔드 .env:
HUGGINGFACE_CLIENT_ID=...
HUGGINGFACE_CLIENT_SECRET=...
HUGGINGFACE_CALLBACK_URL=https://your-domain.example/api/auth/oauth/huggingface/callback
새 사용자의 사용자 이름에는 hf_ 접두사가 붙습니다.
범용 OIDC
OpenID Connect 검색 문서를 제공하는 Keycloak, Authentik, Authelia, Okta, Entra ID, Google Workspace 등의 모든 제공자를 사용할 수 있습니다. 흐름은 PKCE(S256), CSRF state 및 서명이 확인된 ID 토큰 안에서 검증하는 nonce를 사용합니다. 서명 키는 제공자의 JWKS에서 가져옵니다.
다음 콜백 URL을 사용하는 기밀 클라이언트를 등록하세요.
https://your-domain.example/api/auth/oauth/oidc/callback
백엔드 .env:
OIDC_ISSUER_URL=https://id.example.com/realms/main
OIDC_CLIENT_ID=libre-webui
OIDC_CLIENT_SECRET=...
OIDC_DISPLAY_NAME=Example SSO
선택적 정책:
# Require a verified email in one of these domains
OIDC_ALLOWED_EMAIL_DOMAINS=example.com,example.org
# Grant/remove the admin role based on a group claim on every login
OIDC_GROUP_CLAIM=groups
OIDC_ADMIN_GROUPS=libre-admins
# Reconcile Libre group memberships with the group claim on every login
OIDC_SYNC_GROUPS=true
ID는 안정적인 sub 클레임에 연결되므로 제공자 계정 이름이 바뀌어도 Libre 계정은 유지됩니다. 가입이 허용될 때 새 사용자의 사용자 이름에는 oidc_ 접두사가 붙습니다. 이미 연결되지 않은 로컬 계정이 소유한 이메일은 조용히 병합하지 않고 거부합니다. OIDC_SYNC_GROUPS=true이면 클레임 값과 이름이 일치하는 모든 Libre 그룹의 OIDC 사용자 멤버십이 클레임에 따라 결정됩니다. 먼저 설정의 사용자 관리 탭에서 이름이 일치하는 그룹을 만드세요.
공통 설정
공개 백엔드 URL을 설정하세요.
BASE_URL=https://your-domain.example
CORS_ORIGIN=https://your-domain.example
콜백 URL을 명시적으로 설정하지 않으면 Libre WebUI는 BASE_URL을 기준으로 기본값을 만듭니다.
제한 사항
Libre WebUI는 현재 SAML 또는 SCIM 프로비저닝을 제공하지 않습니다. 도메인 허용 목록과 역할/그룹 매핑은 범용 OIDC 제공자에만 사용할 수 있습니다. GitHub 및 Hugging Face 사용자는 항상 user 역할로 생성되며 관리자 UI에서 관리합니다.
문제 해결
OAuth 버튼이 아무 동작도 하지 않습니다
제공자 클라이언트 ID와 비밀이 설정되어 있고 백엔드를 다시 시작했는지 확인하세요.
제공자가 콜백을 거부합니다
제공자 대시보드의 콜백 URL은 Libre WebUI에서 사용하는 URL과 정확히 일치해야 합니다.
사용자가 일반 권한을 받습니다
OAuth 사용자는 기본적으로 user로 생성됩니다. 필요하면 관리자 UI에서 사용자를 승격하세요.