mirror of
https://github.com/snapotter-hq/SnapOtter.git
synced 2026-08-03 07:46:42 +02:00
SnapOtterandGitHub
4963ab3bbd
All 181 docs markdown files translated into 20 languages (apps/docs/<locale>/**). Companion to the i18n code PR; admin-merged because the file count exceeds GitHub's per-PR CI trigger limit. Validated by pnpm i18n:check (all surfaces, 0 stale/missing) and a clean all-locale docs build.
171 lines
8.5 KiB
Markdown
171 lines
8.5 KiB
Markdown
---
|
|
description: "Configure o Single Sign-On com OpenID Connect. Guias passo a passo para Keycloak, Authentik, Google e outros provedores OIDC."
|
|
i18n_source_hash: 4296343b3cc5
|
|
i18n_provenance: human
|
|
i18n_output_hash: d91e31e0728d
|
|
---
|
|
|
|
# OIDC / Single Sign-On {#oidc-single-sign-on}
|
|
|
|
O SnapOtter oferece suporte a OpenID Connect (OIDC) para single sign-on. Os usuários podem fazer login com um provedor de identidade externo, como Keycloak, Authentik ou Google, em vez de (ou junto com) a autenticação local por usuário/senha.
|
|
|
|
::: tip Veja também
|
|
[SAML SSO](/pt-BR/guide/saml) | [Provisionamento SCIM](/pt-BR/guide/scim) | [Usuários, Papéis e Permissões](/pt-BR/guide/users-roles)
|
|
:::
|
|
|
|
## Início rápido {#quick-start}
|
|
|
|
Adicione estas variáveis de ambiente ao seu `docker-compose.yml`:
|
|
|
|
```yaml
|
|
services:
|
|
SnapOtter:
|
|
image: snapotter/snapotter:latest
|
|
environment:
|
|
EXTERNAL_URL: "https://photos.example.com"
|
|
OIDC_ENABLED: "true"
|
|
OIDC_ISSUER_URL: "https://auth.example.com/realms/myrealm"
|
|
OIDC_CLIENT_ID: "snapotter"
|
|
OIDC_CLIENT_SECRET: "your-secret-here"
|
|
```
|
|
|
|
A URI de redirecionamento do seu provedor é sempre:
|
|
|
|
```
|
|
${EXTERNAL_URL}/api/auth/oidc/callback
|
|
```
|
|
|
|
Por exemplo, se `EXTERNAL_URL` for `https://photos.example.com`, configure a URI de redirecionamento do seu provedor como `https://photos.example.com/api/auth/oidc/callback`.
|
|
|
|
## Referência de configuração {#configuration-reference}
|
|
|
|
| Variável | Padrão | Descrição |
|
|
|---|---|---|
|
|
| `OIDC_ENABLED` | `false` | Habilita o login OIDC. Um botão "Entrar com SSO" aparece na página de login. |
|
|
| `OIDC_ISSUER_URL` | | URL do issuer do provedor. Deve suportar OIDC Discovery (`/.well-known/openid-configuration`). |
|
|
| `OIDC_CLIENT_ID` | | ID do cliente OAuth registrado com seu provedor. |
|
|
| `OIDC_CLIENT_SECRET` | | Segredo do cliente OAuth. |
|
|
| `OIDC_SCOPES` | `openid profile email` | Lista de escopos a solicitar, separados por espaço. |
|
|
| `OIDC_AUTO_CREATE_USERS` | `true` | Cria automaticamente uma conta de usuário local no primeiro login OIDC. |
|
|
| `OIDC_DEFAULT_ROLE` | `user` | Papel atribuído a usuários OIDC criados automaticamente. Um de `admin`, `editor` ou `user`. |
|
|
| `OIDC_AUTO_LINK_USERS` | `false` | Vincula uma identidade OIDC a um usuário local existente se o endereço de e-mail corresponder. |
|
|
| `OIDC_PROVIDER_NAME` | | Nome de exibição mostrado no botão de login (por exemplo, "Keycloak", "Google"). Se vazio, o botão diz "SSO". |
|
|
| `OIDC_CLOCK_TOLERANCE` | `30` | Tolerância de desvio de relógio em segundos para validação de token. |
|
|
| `OIDC_USERNAME_CLAIM` | `preferred_username` | Claim do token de ID usada como nome de usuário para novas contas. |
|
|
| `EXTERNAL_URL` | | A URL pública onde o SnapOtter está acessível. Obrigatória para que o OIDC construa a URI de redirecionamento correta. |
|
|
| `COOKIE_SECRET` | gerado automaticamente | Segredo para assinar os cookies de sessão. Defina isto explicitamente ao executar várias réplicas. |
|
|
|
|
## Guias de provedores {#provider-guides}
|
|
|
|
### Keycloak {#keycloak}
|
|
|
|
1. Crie um novo realm (ou use um existente).
|
|
2. Vá para **Clients** e crie um novo cliente:
|
|
- **Client ID**: `snapotter`
|
|
- **Client authentication**: On (confidential)
|
|
- **Authentication flow**: Standard flow (Authorization Code)
|
|
3. Na aba **Settings** do cliente, defina **Valid redirect URIs** como sua URL de callback (por exemplo, `https://photos.example.com/api/auth/oidc/callback`).
|
|
4. Copie o **Client secret** da aba **Credentials**.
|
|
5. Defina `OIDC_ISSUER_URL` como `https://keycloak.example.com/realms/your-realm`.
|
|
|
|
### Authentik {#authentik}
|
|
|
|
1. Na interface de administração, vá para **Applications > Providers** e crie um novo **OAuth2/OpenID Provider**.
|
|
- **Client type**: Confidential
|
|
- **Redirect URIs**: Sua URL de callback
|
|
- **Signing key**: Selecione uma chave existente ou crie uma
|
|
2. Crie uma **Application** e vincule-a ao provedor.
|
|
3. Copie o **Client ID** e o **Client Secret** das configurações do provedor.
|
|
4. Defina `OIDC_ISSUER_URL` como `https://authentik.example.com/application/o/snapotter/` (a barra final importa).
|
|
|
|
### Google {#google}
|
|
|
|
1. Acesse o [Google Cloud Console](https://console.cloud.google.com/).
|
|
2. Crie um projeto (ou selecione um existente).
|
|
3. Navegue até **APIs & Services > OAuth consent screen** e configure-o.
|
|
4. Vá para **APIs & Services > Credentials** e crie um **OAuth 2.0 Client ID**:
|
|
- **Application type**: Web application
|
|
- **Authorized redirect URIs**: Sua URL de callback
|
|
5. Copie o **Client ID** e o **Client secret**.
|
|
6. Defina `OIDC_ISSUER_URL` como `https://accounts.google.com`.
|
|
7. Defina `OIDC_USERNAME_CLAIM` como `email` (o Google não fornece `preferred_username`).
|
|
|
|
## Provisionamento de usuários {#user-provisioning}
|
|
|
|
### Criação automática {#auto-create}
|
|
|
|
Quando `OIDC_AUTO_CREATE_USERS` é `true` (o padrão), uma conta de usuário local é criada na primeira vez que alguém faz login via OIDC. O nome de usuário é obtido da claim especificada por `OIDC_USERNAME_CLAIM`, e o papel é definido como `OIDC_DEFAULT_ROLE`.
|
|
|
|
Se ocorrer uma colisão de nome de usuário, um sufixo numérico é anexado (por exemplo, `jane` vira `jane_2`).
|
|
|
|
### Vinculação automática {#auto-link}
|
|
|
|
Quando `OIDC_AUTO_LINK_USERS` é `true`, o SnapOtter vincula uma identidade OIDC a uma conta local existente se os endereços de e-mail corresponderem. Isso é útil quando você tem contas de usuário pré-criadas e quer que elas comecem a usar SSO sem perder seus dados.
|
|
|
|
::: warning
|
|
Habilite a vinculação automática apenas se você confiar que seu provedor OIDC verifica os endereços de e-mail. Um e-mail não verificado poderia permitir que alguém assumisse a conta de outro usuário.
|
|
:::
|
|
|
|
### Desabilitando o login local {#disabling-local-login}
|
|
|
|
O OIDC não desabilita o login local por usuário/senha. Ambos os métodos permanecem disponíveis. Os administradores ainda podem fazer login com credenciais locais caso o provedor OIDC esteja inacessível.
|
|
|
|
## Certificados autoassinados {#self-signed-certificates}
|
|
|
|
Se o seu provedor OIDC usa um certificado autoassinado ou de uma CA privada, monte o pacote da CA no contêiner e aponte `NODE_EXTRA_CA_CERTS` para ele:
|
|
|
|
```yaml
|
|
services:
|
|
SnapOtter:
|
|
image: snapotter/snapotter:latest
|
|
volumes:
|
|
- ./my-ca.pem:/etc/ssl/certs/custom-ca.pem:ro
|
|
environment:
|
|
NODE_EXTRA_CA_CERTS: /etc/ssl/certs/custom-ca.pem
|
|
OIDC_ENABLED: "true"
|
|
OIDC_ISSUER_URL: "https://auth.internal.example.com/realms/myrealm"
|
|
OIDC_CLIENT_ID: "snapotter"
|
|
OIDC_CLIENT_SECRET: "your-secret-here"
|
|
```
|
|
|
|
::: danger
|
|
Não defina `NODE_TLS_REJECT_UNAUTHORIZED=0`. Isso desabilita toda a verificação TLS e é um risco de segurança.
|
|
:::
|
|
|
|
## Solução de problemas {#troubleshooting}
|
|
|
|
### Incompatibilidade de URI de redirecionamento {#redirect-uri-mismatch}
|
|
|
|
O erro mais comum. Verifique estas diferenças entre o que seu provedor espera e o que o SnapOtter envia:
|
|
|
|
- `http` vs `https` - o esquema deve corresponder exatamente
|
|
- Barra final - alguns provedores são rigorosos quanto a isso
|
|
- Número da porta - inclua a porta se ela não for padrão
|
|
- Caminho - deve ser `/api/auth/oidc/callback`
|
|
|
|
Confira novamente `EXTERNAL_URL`. Ele deve corresponder à URL que os usuários digitam no navegador.
|
|
|
|
### UNABLE_TO_VERIFY_LEAF_SIGNATURE {#unable-to-verify-leaf-signature}
|
|
|
|
O provedor OIDC está usando um certificado no qual o Node.js não confia. Veja [Certificados autoassinados](#self-signed-certificates) acima.
|
|
|
|
### Erros de desvio de relógio {#clock-skew-errors}
|
|
|
|
Se o relógio do seu servidor e o relógio do provedor OIDC estiverem fora de sincronia, a validação do token pode falhar. Aumente `OIDC_CLOCK_TOLERANCE` (o padrão é 30 segundos). Uma solução melhor é rodar NTP em ambas as máquinas.
|
|
|
|
### "OIDC provider unreachable" {#oidc-provider-unreachable}
|
|
|
|
O SnapOtter busca o documento de discovery do provedor na inicialização e durante o login. Verifique:
|
|
|
|
- Resolução de DNS de dentro do contêiner Docker (`docker exec snapotter nslookup auth.example.com`)
|
|
- Regras de firewall entre o contêiner e o provedor
|
|
- O valor de `OIDC_ISSUER_URL` - ele deve ser acessível a partir do servidor, não apenas do seu navegador
|
|
|
|
### Claims ausentes {#missing-claims}
|
|
|
|
Se os nomes de usuário ou e-mails estiverem vazios após o login, seu provedor pode não estar retornando as claims esperadas. Verifique:
|
|
|
|
- Os escopos configurados em `OIDC_SCOPES` incluem `profile` e `email`
|
|
- O provedor está configurado para incluir a claim especificada em `OIDC_USERNAME_CLAIM` no token de ID
|
|
- Alguns provedores exigem configuração explícita de mapper/escopo para liberar as claims
|