Login único
O Libre WebUI oferece suporte a login OAuth com GitHub e Hugging Face, além de qualquer provedor OpenID Connect por meio da integração OIDC genérica. Os usuários OAuth continuam armazenados como usuários locais do Libre WebUI e recebem o papel user por padrão (o OIDC pode, opcionalmente, mapear papéis e grupos a partir de claims).
OAuth do GitHub
Crie um aplicativo OAuth nas configurações de desenvolvedor do GitHub.
URL de callback local:
http://localhost:3001/api/auth/oauth/github/callback
URL de callback de produção:
https://your-domain.example/api/auth/oauth/github/callback
.env do backend:
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
GITHUB_CALLBACK_URL=https://your-domain.example/api/auth/oauth/github/callback
O OAuth do GitHub solicita o escopo user:email. Novos usuários são criados com nomes de usuário prefixados por gh_.
OAuth do Hugging Face
Crie um aplicativo OAuth nas configurações do Hugging Face.
URL de callback local:
http://localhost:3001/api/auth/oauth/huggingface/callback
URL de callback de produção:
https://your-domain.example/api/auth/oauth/huggingface/callback
.env do backend:
HUGGINGFACE_CLIENT_ID=...
HUGGINGFACE_CLIENT_SECRET=...
HUGGINGFACE_CALLBACK_URL=https://your-domain.example/api/auth/oauth/huggingface/callback
Novos usuários são criados com nomes de usuário prefixados por hf_.
OIDC genérico
Qualquer provedor com um documento de descoberta OpenID Connect funciona: Keycloak, Authentik, Authelia, Okta, Entra ID, Google Workspace e outros. O fluxo usa PKCE (S256), estado CSRF e um nonce verificado dentro do token de ID cuja assinatura é conferida; as chaves de assinatura vêm do JWKS do provedor.
Registre um cliente confidencial com esta URL de callback:
https://your-domain.example/api/auth/oauth/oidc/callback
.env do backend:
OIDC_ISSUER_URL=https://id.example.com/realms/main
OIDC_CLIENT_ID=libre-webui
OIDC_CLIENT_SECRET=...
OIDC_DISPLAY_NAME=Example SSO
Políticas opcionais:
# 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
As identidades são vinculadas pela claim estável sub; assim, uma conta renomeada no provedor
mantém sua conta do Libre. Novos usuários são criados com nomes de usuário prefixados por oidc_
quando o cadastro os permite. Um email que já pertença a uma conta local não vinculada
é rejeitado em vez de ser mesclado silenciosamente. Com
OIDC_SYNC_GROUPS=true, a associação a todo grupo do Libre cujo nome corresponda a um
valor da claim é orientada por claims para usuários OIDC — primeiro, crie os grupos correspondentes na aba
Gerenciamento de Usuários em Configurações.
Configurações compartilhadas
Defina a URL pública do backend:
BASE_URL=https://your-domain.example
CORS_ORIGIN=https://your-domain.example
Se as URLs de callback não forem definidas explicitamente, o Libre WebUI cria os padrões com base em BASE_URL.
Limites
Atualmente, o Libre WebUI não oferece SAML nem provisionamento SCIM. As listas de domínios permitidos e o mapeamento de papéis/grupos estão disponíveis apenas para o provedor OIDC genérico; os usuários do GitHub e do Hugging Face sempre são criados com o papel user e gerenciados pela interface administrativa.
Solução de problemas
O botão OAuth não faz nada
Confirme que o ID e o segredo do cliente do provedor estão definidos e que o backend foi reiniciado.
O provedor rejeita o callback
A URL de callback no painel do provedor deve corresponder exatamente à URL usada pelo Libre WebUI.
O usuário recebe permissões normais
Os usuários OAuth são criados como user por padrão. Promova-os pela interface administrativa, se necessário.