Autenticação SSO
Configure o Single Sign-On para o rtCloud auto-alojado usando Keycloak incorporado, um fornecedor OIDC externo ou Azure Active Directory.
O rtCloud suporta três abordagens para Single Sign-On (SSO):
| Opção | Ideal Para |
|---|---|
| Keycloak Incorporado | Organizações que querem um servidor SSO totalmente autónomo integrado com o rtCloud |
| Fornecedor OIDC Externo | Organizações que já executam um fornecedor de identidade (Auth0, Authentik, Okta, Supabase, etc.) |
| Azure Active Directory | Organizações que usam Microsoft 365 ou Azure AD |
Sem SSO configurado, os utilizadores iniciam sessão com contas rtCloud locais geridas através do painel de administração.
Keycloak Incorporado
A implantação inclui um contentor Keycloak opcional que corre junto com o rtCloud. O Keycloak é pré-configurado com um realm rtSurvey e pronto a usar.
Requisitos
- Um nome de domínio com HTTPS (o Keycloak requer HTTPS em produção)
- Pelo menos 4 GB RAM no servidor (o Keycloak adiciona ~512 MB de uso de memória)
Configuração
1. Configure as variáveis de ambiente em .env:
# Ativar o contentor Keycloak incorporado
EMBED_KEYCLOAK=true
# URLs Keycloak — use o seu domínio real
KEYCLOAK_URL=https://rtcloud.example.com/auth
KC_HOSTNAME=https://rtcloud.example.com/auth
KC_HOSTNAME_STRICT=false
# Configurações de realm e cliente (correspondem ao JSON de realm importado)
KEYCLOAK_REALM=rtsurvey
KEYCLOAK_CLIENT_ID=rtsurvey-app
KEYCLOAK_CLIENT_SECRET=your-client-secret-here
# Credenciais de admin Keycloak
KEYCLOAK_ADMIN_USER=admin
KEYCLOAK_ADMIN_PASSWORD=change_me_keycloak_admin_password
# Base de dados Keycloak (criada automaticamente)
KEYCLOAK_DB=keycloak
KEYCLOAK_DB_USER=keycloak
KEYCLOAK_DB_PASSWORD=change_me_keycloak_db_password
# Porta em que o Keycloak escuta (lado do host, proxiado pelo Nginx)
KEYCLOAK_PORT=8091
2. Inicie com o perfil Keycloak incorporado:
docker compose -f docker-compose.production.yml --profile embed-keycloak up -d
3. Verifique se o Keycloak está saudável:
docker compose -f docker-compose.production.yml ps
O contentor rtcloud-keycloak deve mostrar Up (healthy) após 2–3 minutos.
4. Aceda à consola de admin Keycloak:
https://rtcloud.example.com/auth/admin
Inicie sessão com KEYCLOAK_ADMIN_USER e KEYCLOAK_ADMIN_PASSWORD.
O que Está Pré-Configurado
O Keycloak incorporado inicia com um realm rtsurvey pré-importado que inclui:
- Configuração de cliente para a aplicação web
- Funções de utilizador predefinidas (
admin,project_manager,enumerator,analyst) - Configurações de sessão e token otimizadas para o rtSurvey
Pode adicionar utilizadores diretamente na consola de admin Keycloak ou ligar o Keycloak a um fornecedor de identidade upstream (LDAP, SAML).
Encaminhamento Nginx
Ao usar os scripts de implantação na cloud, o Nginx é configurado para fazer proxy de ambos os serviços:
| Caminho | Backend |
|---|---|
/ | Aplicação rtCloud em 127.0.0.1:8080 |
/auth/ | Keycloak em 127.0.0.1:8090 |
Fornecedor OIDC Externo
Ligue o rtCloud a qualquer fornecedor de identidade compatível com OpenID Connect. Esta abordagem não requer o contentor Keycloak.
Fornecedores Suportados
Qualquer fornecedor compatível com OIDC funciona, incluindo:
- Authentik
- Auth0
- Okta
- Keycloak (instância externa)
- Supabase
- Google (para organizações Google Workspace)
- GitHub (via aplicações OAuth com extensão OIDC)
Configuração
1. Registe o rtCloud como cliente OIDC no seu fornecedor de identidade.
Vai precisar de:
- Um ID de cliente e segredo de cliente
- Registar o URI de redirecionamento:
https://rtcloud.example.com/auth/callback - Para suporte a aplicações móveis, registe também:
vn.rta.rtsurvey.auth://callback
2. Configure as variáveis de ambiente em .env:
# URL de descoberta OIDC (específico do fornecedor — consulte a documentação do seu IdP)
OIDC_ISSUER_URL=https://your-identity-provider.com
# Credenciais de cliente do seu fornecedor de identidade
OIDC_CLIENT_ID=rtcloud-app
OIDC_CLIENT_SECRET=your-client-secret-here
# Scopes a solicitar (openid, profile e email são tipicamente suficientes)
OIDC_SCOPE=openid profile email
# URI de redirecionamento registado no seu fornecedor de identidade
OIDC_REDIRECT_URI=https://rtcloud.example.com/auth/callback
# Opcional: cliente separado para a aplicação móvel
OIDC_MOBILE_CLIENT_ID=rtcloud-mobile
OIDC_MOBILE_REDIRECT_URI=vn.rta.rtsurvey.auth://callback
# Defina como true para criar automaticamente contas rtCloud para novos utilizadores OIDC
OPEN_REGISTRATION=false
3. Reinicie o contentor da aplicação para aplicar as alterações:
docker compose -f docker-compose.production.yml up -d --force-recreate rtcloud
Provisionamento Automático de Utilizadores
Quando OPEN_REGISTRATION=true, o rtCloud cria automaticamente uma conta local na primeira vez que um utilizador inicia sessão via OIDC. A conta é preenchida com o nome e email do utilizador provenientes do token de ID.
Quando OPEN_REGISTRATION=false (predefinição), um administrador do rtCloud deve criar primeiro a conta de utilizador e a identidade OIDC é ligada no primeiro início de sessão.
Endpoints Personalizados
Se o seu fornecedor não suportar descoberta OIDC (.well-known/openid-configuration), pode definir endpoints manualmente:
OIDC_AUTHORIZATION_ENDPOINT=https://your-provider.com/oauth2/authorize
OIDC_TOKEN_ENDPOINT=https://your-provider.com/oauth2/token
OIDC_USERINFO_ENDPOINT=https://your-provider.com/oauth2/userinfo
Azure Active Directory
Integre o rtCloud com o tenant Microsoft Azure AD da sua organização.
Configuração
1. Registe uma nova aplicação no Portal Azure:
- Vá a Azure Active Directory → Registos de aplicações → Novo registo
- Nome:
rtCloud - URI de redirecionamento:
https://rtcloud.example.com/auth/callback(tipo Web) - Após a criação, anote o ID da Aplicação (cliente) e o ID do Diretório (inquilino)
- Em Certificados e segredos, crie um novo segredo de cliente
2. Configure as variáveis de ambiente em .env:
AZURE_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AZURE_TENANT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
3. Reinicie o contentor da aplicação:
docker compose -f docker-compose.production.yml up -d --force-recreate rtcloud
Os utilizadores no seu tenant Azure AD podem agora iniciar sessão no rtCloud usando as suas credenciais Microsoft.
Desativar SSO
Para reverter para autenticação local, remova ou comente todas as variáveis relacionadas com SSO em .env, depois reinicie o contentor da aplicação:
docker compose -f docker-compose.production.yml up -d --force-recreate rtcloud
Se estava a usar o Keycloak incorporado, pare-o omitindo o sinalizador --profile embed-keycloak e executando docker compose down seguido de up -d sem o perfil.