การลงชื่อเข้าใช้ครั้งเดียว
Libre WebUI รองรับการเข้าสู่ระบบ OAuth ด้วย GitHub และ Hugging Face รวมถึงผู้ให้บริการ OpenID Connect ใด ๆ ผ่านการเชื่อมต่อ OIDC ทั่วไป ผู้ใช้ OAuth ยังคงถูกจัดเก็บเป็นผู้ใช้ Libre WebUI ในเครื่องและได้รับบทบาท user ตามค่าเริ่มต้น (OIDC สามารถแมปบทบาทและกลุ่มจาก claim ได้ตามต้องการ)
GitHub OAuth
สร้างแอป OAuth ใน GitHub Developer Settings
URL callback ในเครื่อง:
http://localhost:3001/api/auth/oauth/github/callback
URL callback สำหรับระบบใช้งานจริง:
https://your-domain.example/api/auth/oauth/github/callback
ไฟล์ .env ของ backend:
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
GITHUB_CALLBACK_URL=https://your-domain.example/api/auth/oauth/github/callback
GitHub OAuth ขอ scope user:email ผู้ใช้ใหม่จะได้รับชื่อผู้ใช้ที่ขึ้นต้นด้วย gh_
Hugging Face OAuth
สร้างแอป OAuth ในการตั้งค่า Hugging Face
URL callback ในเครื่อง:
http://localhost:3001/api/auth/oauth/huggingface/callback
URL callback สำหรับระบบใช้งานจริง:
https://your-domain.example/api/auth/oauth/huggingface/callback
ไฟล์ .env ของ backend:
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 และ nonce ซึ่งตรวจสอบภายใน ID token ที่ผ่านการตรวจลายเซ็น โดยรับ signing key จาก JWKS ของผู้ให้บริการ
ลงทะเบียน confidential client ด้วย URL callback นี้:
https://your-domain.example/api/auth/oauth/oidc/callback
ไฟล์ .env ของ backend:
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
ตัวตนจะเชื่อมโยงด้วย claim sub ที่คงที่ ดังนั้นบัญชีผู้ให้บริการที่เปลี่ยนชื่อยังคงใช้บัญชี Libre เดิม ผู้ใช้ใหม่จะได้รับชื่อผู้ใช้ที่ขึ้นต้นด้วย oidc_ เมื่ออนุญาตการลงทะเบียน อีเมลที่เป็นของบัญชีในเครื่องซึ่งยังไม่เชื่อมโยงจะถูกปฏิเสธแทนการรวมอย่างเงียบ ๆ เมื่อใช้ OIDC_SYNC_GROUPS=true สมาชิกของทุกกลุ่ม Libre ที่ชื่อตรงกับค่า claim จะถูกควบคุมจาก claim สำหรับผู้ใช้ OIDC ให้สร้างกลุ่มชื่อเดียวกันในแท็บ User Management ใน Settings ก่อน
การตั้งค่าร่วม
กำหนด URL สาธารณะของ backend:
BASE_URL=https://your-domain.example
CORS_ORIGIN=https://your-domain.example
หากไม่ได้ตั้ง URL callback อย่างชัดเจน Libre WebUI จะสร้างค่าเริ่มต้นจาก BASE_URL
ข้อจำกัด
ปัจจุบัน Libre WebUI ยังไม่รองรับ SAML หรือการจัดเตรียมผู้ใช้ด้วย SCIM รายการโดเมนที่อนุญาตและการแมปบทบาท/กลุ่มมีเฉพาะผู้ให้บริการ OIDC ทั่วไป ผู้ใช้ GitHub และ Hugging Face จะถูกสร้างด้วยบทบาท user เสมอ และจัดการจากอินเทอร์เฟซผู้ดูแลระบบ
การแก้ปัญหา
ปุ่ม OAuth ไม่ทำงาน
ยืนยันว่าได้ตั้ง client ID และ secret ของผู้ให้บริการแล้ว และได้รีสตาร์ต backend
ผู้ให้บริการปฏิเสธ callback
URL callback ในแดชบอร์ดของผู้ให้บริการต้องตรงกับ URL ที่ Libre WebUI ใช้ทุกตัวอักษร
ผู้ใช้ได้รับสิทธิ์ปกติ
ผู้ใช้ OAuth ถูกสร้างเป็น user ตามค่าเริ่มต้น หากจำเป็น ให้เลื่อนสิทธิ์ผู้ใช้จากอินเทอร์เฟซผู้ดูแลระบบ