Ligar o Keycloak ao diretório da organização (LDAP ou Active Directory) para que os utilizadores entrem no iGRP com as credenciais que já usam.
Muitas organizações já têm os utilizadores num diretório LDAP ou num Active Directory (AD). Em vez de criar contas novas, o Keycloak pode ler esse diretório através da federação de utilizadores (User Federation): o utilizador entra com o nome e a palavra-passe do diretório, o Keycloak valida-os no LDAP e o iGRP recebe a identidade como recebe qualquer outra.
A integração faz-se só no Keycloak. O Access Management continua configurado com o Keycloak como IdP a montante (variáveis IGRP_OAUTH_EXTERNAL_IDP_*, ver Configuração), e as aplicações não mudam nada.
Pré-requisitos
- O Keycloak usado pelo iGRP está instalado, acessível e tens uma conta de administrador do realm.
- A rede deixa o Keycloak chegar ao servidor LDAP (porta
389para LDAP/StartTLS,636para LDAPS). - A equipa que gere o diretório deu-te os dados de ligação: URL, a conta de serviço (Bind DN) e a palavra-passe, o DN onde estão os utilizadores e, se for o caso, o certificado do servidor.
Os valores dos exemplos desta página (dc=example,dc=org, ldap.example.org) são ilustrativos. Substitui-os pelos do teu diretório.
Os prints foram tirados no Keycloak 26, ligado a um servidor OpenLDAP de teste (Vendor Other). Com Active Directory, os campos são os mesmos e mudam só os valores indicados na coluna "Active Directory".
Criar o fornecedor LDAP
Abrir a federação de utilizadores
Na consola de administração do Keycloak, escolhe o realm do iGRP e abre User federation no menu lateral.
Adicionar o fornecedor
Clica em Add Ldap providers (ou Add new provider → Ldap, se já existir outro fornecedor).

Preencher as secções
Preenche as secções descritas abaixo, por ordem. Usa os botões Test connection e Test authentication antes de guardar.
Guardar e sincronizar
Clica em Save. Depois, em Action → Sync all users, importa os utilizadores pela primeira vez.
Opções gerais
| Campo | Valor recomendado | Notas |
|---|---|---|
| UI display name | ldap ou active-directory | Nome que aparece na consola. Só serve para o identificares. |
| Vendor | Active Directory, ou o produto LDAP usado | Ao escolher o fornecedor, o Keycloak preenche valores típicos nos campos seguintes. Confirma-os na mesma. |

Ligação e autenticação
| Campo | Valor recomendado | Notas |
|---|---|---|
| Connection URL | ldaps://ldap.example.org:636 | Endereço e porta do servidor. Prefere ldaps://. Com ldap:// (porta 389), ativa StartTLS. |
| Enable StartTLS | On com ldap:// | Cifra a ligação sobre a porta normal. Não se usa com ldaps://. |
| Use Truststore SPI | Always | Com ldaps:// ou StartTLS, o Keycloak valida o certificado do servidor com a truststore configurada. Se o certificado for de uma CA interna, ela tem de estar nessa truststore. |
| Connection pooling | On | Reaproveita ligações. Útil com muitos logins. |
| Connection timeout | 5000 (ms) | Tempo máximo para abrir a ligação. Vazio = sem limite. |
| Bind type | simple | O Keycloak autentica-se no diretório com uma conta de serviço. none só serve para diretórios com leitura anónima. |
| Bind DN | cn=svc-keycloak,ou=service,dc=example,dc=org | DN da conta de serviço. No AD também aceita o formato svc-keycloak@example.org. |
| Bind credentials | palavra-passe da conta de serviço | Fica guardada no Keycloak. |

Os dois botões devem responder Successfully connected to LDAP. O primeiro testa só a ligação; o segundo testa também o Bind DN e a palavra-passe.
Uma conta de serviço só de leitura
Pede uma conta dedicada ao Keycloak, sem expiração de palavra-passe e só com permissão de leitura sobre os utilizadores. Se a palavra-passe expirar, todos os logins falham.
Pesquisa e atualização
Esta secção diz ao Keycloak onde estão os utilizadores e que atributos usar.
| Campo | Active Directory | OpenLDAP / outros | Notas |
|---|---|---|---|
| Edit mode | READ_ONLY | READ_ONLY | O diretório é a fonte de verdade. O Keycloak não altera nada nele. |
| Users DN | ou=Utilizadores,dc=example,dc=org | ou=users,dc=example,dc=org | Ramo de onde a pesquisa parte. |
| Username LDAP attribute | sAMAccountName (ou userPrincipalName) | uid | O que o utilizador escreve no login. |
| RDN LDAP attribute | cn | uid ou cn | Primeiro componente do DN de cada utilizador. |
| UUID LDAP attribute | objectGUID | entryUUID | Identificador imutável de cada utilizador. Não uses um atributo que mude. |
| User object classes | person, organizationalPerson, user | inetOrgPerson, organizationalPerson | Classes que identificam um utilizador. |
| User LDAP filter | ver abaixo | opcional | Restringe os utilizadores aceites. |
| Search scope | Subtree | One Level ou Subtree | One Level só lê o nível imediato do Users DN. Subtree inclui as sub-OUs. |
| Read timeout | 30000 (ms) | 30000 (ms) | Tempo máximo à espera de resposta. |
| Pagination | On | On se o servidor suportar | Necessário com muitos utilizadores. O AD limita cada resposta a 1000 entradas. |

No Active Directory, este filtro aceita apenas pessoas e exclui as contas desativadas:
(&(objectCategory=person)(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))Para restringir o acesso a um grupo do diretório, acrescenta (memberOf=CN=iGRP,OU=Grupos,DC=example,DC=org) dentro do &.
Sincronização
| Campo | Valor recomendado | Notas |
|---|---|---|
| Import users | On | Cria no Keycloak uma cópia local de cada utilizador do diretório. Ver o aviso abaixo. |
| Sync Registrations | Off | Com On, as contas criadas no Keycloak seriam escritas no diretório. Com READ_ONLY, deixa Off. |
| Batch size | 1000 | Utilizadores por lote em cada sincronização. |
| Periodic full sync | On, p. ex. a cada 86400 s | Volta a ler todo o diretório (uma vez por dia). |
| Periodic changed users sync | On, p. ex. a cada 900 s | Lê só os utilizadores alterados desde a última sincronização. |
| Remove invalid users during searches | On (valor por omissão) | Remove do Keycloak um utilizador importado que já não exista no diretório quando é pesquisado. |

A identidade no iGRP depende do ID do Keycloak
O Access Management liga cada utilizador do iGRP ao sub que o Keycloak emite, e esse sub é o ID do utilizador no Keycloak, não o nome no diretório. Escolhe o modo de importação antes de pôr o iGRP em uso e não o mudes depois. Também não uses Remove imported nem apagues e recries o fornecedor. Qualquer destas ações gera IDs novos no Keycloak, e o iGRP passa a ver cada pessoa como um utilizador novo, sem os perfis e departamentos que tinha.
Kerberos
| Campo | Valor recomendado | Notas |
|---|---|---|
| Allow Kerberos authentication | Off | Só se o domínio tiver Kerberos/SPNEGO configurado para login sem palavra-passe nos postos do domínio. |
| Use Kerberos for password authentication | Off | Valida a palavra-passe por Kerberos em vez de LDAP. Mesma condição. |

Cache
| Campo | Valor recomendado | Notas |
|---|---|---|
| Cache policy | DEFAULT | O Keycloak guarda em cache os utilizadores lidos do diretório. NO_CACHE força a leitura no diretório em cada pedido. |

Definições avançadas
| Campo | Valor recomendado | Notas |
|---|---|---|
| Enable the LDAPv3 password modify extended operation | Off | Só faz sentido em modo WRITABLE, se o servidor suportar. |
| Validate password policy | Off | Com o diretório como fonte de verdade, quem aplica as regras de palavra-passe é o diretório. |
| Trust email | On | Obrigatório para o iGRP. Ver a secção seguinte. |
| Connection trace | Off | Regista no log o tráfego LDAP. Só para diagnóstico. |

Depois clica em Save. O fornecedor aparece em User federation como Enabled.
O que o iGRP exige
O email vem verificado
Por omissão, o Access Management recusa logins em que o ID Token do Keycloak não traga email_verified: true (variável IGRP_OAUTH_REQUIRE_EMAIL_VERIFIED, ver Configuração). Os utilizadores importados do diretório não têm o email verificado, a menos que se ative o Trust email no fornecedor LDAP.
Com Trust email em Off, o login no Keycloak funciona, mas o regresso ao iGRP falha com unverified_email.
Não desligues a verificação no Access Management
Pôr IGRP_OAUTH_REQUIRE_EMAIL_VERIFIED=false também resolve o sintoma, mas aceita emails de qualquer origem. Ativa o Trust email no fornecedor, que confia apenas no diretório da organização.
Cada utilizador tem email
O iGRP identifica e contacta as pessoas pelo email. O atributo mail tem de estar preenchido no diretório para quem vai usar o iGRP, e o mapper email (ver abaixo) tem de apontar para ele. Se definires IGRP_OAUTH_ALLOWED_EMAIL_DOMAINS, o domínio do email do diretório tem de constar da lista.
Primeiro login e permissões
No primeiro login, o Access Management cria o utilizador automaticamente com o estado temporário, a partir das claims preferred_username, email e name. Os grupos do diretório não se convertem em permissões do iGRP: departamentos, perfis e acessos atribuem-se no Application Center (ver Utilizadores).
O superadministrador
Se o superadministrador vier do diretório, o valor de IGRP_SUPERADMIN_USER_EXTERNAL_ID é o ID do utilizador no Keycloak (em Users → utilizador → ID, depois da primeira sincronização), e não o nome no diretório. O IGRP_SUPERADMIN_EMAIL tem de coincidir com o mail dessa pessoa.
Mappers
Depois de guardar o fornecedor, o separador Mappers mostra a correspondência entre atributos do diretório e campos do Keycloak. Os mappers vêm criados conforme o Vendor escolhido. Confirma estes:

| Mapper | Atributo no Keycloak | Atributo LDAP (AD) | Claim que o iGRP lê |
|---|---|---|---|
| username | username | sAMAccountName | preferred_username |
email | mail | email | |
| first name | firstName | givenName | given_name / name |
| last name | lastName | sn | family_name / name |
O mapper email tem de estar presente, e os nomes devem vir preenchidos para o iGRP mostrar o nome da pessoa.
Com o Vendor Other, o mapper first name vem ligado a cn, que costuma ter o nome completo. Abre-o e muda LDAP Attribute para givenName; depois corre Sync all users para atualizar os utilizadores já importados.
Verificação
-
Em User federation → o fornecedor → Action → Sync all users, confirma que a mensagem indica utilizadores importados e nenhuma falha (
0 users failed).

-
Em Users, os utilizadores do diretório aparecem com nome de utilizador, email e nomes preenchidos.

-
Abre um utilizador. Deve ter Federation link a apontar para o fornecedor e Email verified em
On. O ID desta página é osubque o iGRP recebe.
-
Abre o Application Center do iGRP, faz login com as credenciais do diretório e confirma que a sessão abre.
-
No Application Center, o utilizador aparece na lista com estado temporário, pronto para receber departamento e perfil.
Resolução de problemas
| Sintoma | Causa provável | O que fazer |
|---|---|---|
| Test connection falha | DNS, firewall ou porta errada | Confirma o host e a porta a partir da rede do Keycloak. Com ldaps://, a porta é 636. |
| Test connection falha com erro de certificado | A CA do servidor não está na truststore do Keycloak | Importa o certificado da CA para a truststore configurada no Keycloak e reinicia-o. |
| Test authentication falha | Bind DN ou palavra-passe errados, ou conta bloqueada/expirada | Valida a conta de serviço com a equipa do diretório. |
| A sincronização importa 0 utilizadores | Users DN, object classes ou filtro errados, ou One Level com utilizadores em sub-OUs | Revê a secção de pesquisa e experimenta Subtree. |
| A sincronização para nas 1000 entradas | Paginação desligada no AD | Ativa Pagination. |
O login no Keycloak funciona mas o iGRP devolve unverified_email | Trust email em Off | Ativa Trust email no fornecedor e volta a sincronizar. |
| O iGRP recusa o login de alguns utilizadores | Email vazio no diretório, ou domínio fora de IGRP_OAUTH_ALLOWED_EMAIL_DOMAINS | Preenche mail no diretório, ou acrescenta o domínio à lista. |
| Um utilizador antigo aparece no iGRP como novo, sem acessos | O ID no Keycloak mudou (fornecedor recriado, Remove imported, mudança do modo de importação) | Evita estas ações. Reatribui os acessos ao utilizador novo e desativa o antigo no Application Center. |
| Uma conta desativada no AD continua a entrar | Filtro sem a exclusão de contas desativadas, ou cache | Usa o filtro com userAccountControl acima e sincroniza. Para efeito imediato, termina as sessões do utilizador no Application Center. |
Última atualização:
