iGRPIGRP 3.0Documentation

Keycloak com LDAP / Active Directory

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.

IGRPKEYCLOAKrealm do iGRPORGANIZAÇÃOAplicações iGRPApp Center · appsAccess ManagementAuthorization ServerUser Federationfornecedor LDAPActive Directoryou servidor LDAPloginOIDCLDAPSigrp-authcria o utilizadorno primeiro loginTrust email = Onsincronização periódicaconta de serviçosó de leitura
A ligação ao diretório configura-se só no Keycloak (User Federation). O Access Management e as aplicações não mudam.

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 389 para LDAP/StartTLS, 636 para 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).

User federation no Keycloak, com os cartões Add Kerberos providers e Add Ldap providers

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

CampoValor recomendadoNotas
UI display nameldap ou active-directoryNome que aparece na consola. Só serve para o identificares.
VendorActive Directory, ou o produto LDAP usadoAo escolher o fornecedor, o Keycloak preenche valores típicos nos campos seguintes. Confirma-os na mesma.

Opções gerais do fornecedor LDAP: UI display name e Vendor


Ligação e autenticação

CampoValor recomendadoNotas
Connection URLldaps://ldap.example.org:636Endereço e porta do servidor. Prefere ldaps://. Com ldap:// (porta 389), ativa StartTLS.
Enable StartTLSOn com ldap://Cifra a ligação sobre a porta normal. Não se usa com ldaps://.
Use Truststore SPIAlwaysCom 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 poolingOnReaproveita ligações. Útil com muitos logins.
Connection timeout5000 (ms)Tempo máximo para abrir a ligação. Vazio = sem limite.
Bind typesimpleO Keycloak autentica-se no diretório com uma conta de serviço. none só serve para diretórios com leitura anónima.
Bind DNcn=svc-keycloak,ou=service,dc=example,dc=orgDN da conta de serviço. No AD também aceita o formato svc-keycloak@example.org.
Bind credentialspalavra-passe da conta de serviçoFica guardada no Keycloak.

Ligação e autenticação: Connection URL, StartTLS, Truststore SPI, pooling, timeout, Bind type, Bind DN e Bind credentials, com os botões Test connection e Test authentication

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.

CampoActive DirectoryOpenLDAP / outrosNotas
Edit modeREAD_ONLYREAD_ONLYO diretório é a fonte de verdade. O Keycloak não altera nada nele.
Users DNou=Utilizadores,dc=example,dc=orgou=users,dc=example,dc=orgRamo de onde a pesquisa parte.
Username LDAP attributesAMAccountName (ou userPrincipalName)uidO que o utilizador escreve no login.
RDN LDAP attributecnuid ou cnPrimeiro componente do DN de cada utilizador.
UUID LDAP attributeobjectGUIDentryUUIDIdentificador imutável de cada utilizador. Não uses um atributo que mude.
User object classesperson, organizationalPerson, userinetOrgPerson, organizationalPersonClasses que identificam um utilizador.
User LDAP filterver abaixoopcionalRestringe os utilizadores aceites.
Search scopeSubtreeOne Level ou SubtreeOne Level só lê o nível imediato do Users DN. Subtree inclui as sub-OUs.
Read timeout30000 (ms)30000 (ms)Tempo máximo à espera de resposta.
PaginationOnOn se o servidor suportarNecessário com muitos utilizadores. O AD limita cada resposta a 1000 entradas.

Pesquisa e atualização preenchida para OpenLDAP: READ_ONLY, Users DN, uid, entryUUID, inetOrgPerson e filtro

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

CampoValor recomendadoNotas
Import usersOnCria no Keycloak uma cópia local de cada utilizador do diretório. Ver o aviso abaixo.
Sync RegistrationsOffCom On, as contas criadas no Keycloak seriam escritas no diretório. Com READ_ONLY, deixa Off.
Batch size1000Utilizadores por lote em cada sincronização.
Periodic full syncOn, p. ex. a cada 86400 sVolta a ler todo o diretório (uma vez por dia).
Periodic changed users syncOn, p. ex. a cada 900 sLê só os utilizadores alterados desde a última sincronização.
Remove invalid users during searchesOn (valor por omissão)Remove do Keycloak um utilizador importado que já não exista no diretório quando é pesquisado.

Sincronização: Import users On, Sync Registrations Off, Batch size 1000, sincronização completa diária e de alterados a cada 900 segundos

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

CampoValor recomendadoNotas
Allow Kerberos authenticationOffSó se o domínio tiver Kerberos/SPNEGO configurado para login sem palavra-passe nos postos do domínio.
Use Kerberos for password authenticationOffValida a palavra-passe por Kerberos em vez de LDAP. Mesma condição.

Integração Kerberos com as duas opções desligadas


Cache

CampoValor recomendadoNotas
Cache policyDEFAULTO Keycloak guarda em cache os utilizadores lidos do diretório. NO_CACHE força a leitura no diretório em cada pedido.

Cache policy DEFAULT


Definições avançadas

CampoValor recomendadoNotas
Enable the LDAPv3 password modify extended operationOffSó faz sentido em modo WRITABLE, se o servidor suportar.
Validate password policyOffCom o diretório como fonte de verdade, quem aplica as regras de palavra-passe é o diretório.
Trust emailOnObrigatório para o iGRP. Ver a secção seguinte.
Connection traceOffRegista no log o tráfego LDAP. Só para diagnóstico.

Definições avançadas com Trust Email ligado

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:

Separador Mappers do fornecedor LDAP com os mappers creation date, email, first name, Kerberos principal, last name, modify date e username

MapperAtributo no KeycloakAtributo LDAP (AD)Claim que o iGRP lê
usernameusernamesAMAccountNamepreferred_username
emailemailmailemail
first namefirstNamegivenNamegiven_name / name
last namelastNamesnfamily_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

  1. Em User federation → o fornecedor → Action → Sync all users, confirma que a mensagem indica utilizadores importados e nenhuma falha (0 users failed).

    Menu Action do fornecedor: Sync changed users, Sync all users, Unlink users, Remove imported e Delete provider

    Mensagem Sync of users finished successfully, com 0 users failed

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

    Lista de utilizadores do realm com quatro utilizadores importados do diretório

  3. Abre um utilizador. Deve ter Federation link a apontar para o fornecedor e Email verified em On. O ID desta página é o sub que o iGRP recebe.

    Detalhe de um utilizador importado: ID, Federation link ldap e Email verified On

  4. Abre o Application Center do iGRP, faz login com as credenciais do diretório e confirma que a sessão abre.

  5. No Application Center, o utilizador aparece na lista com estado temporário, pronto para receber departamento e perfil.


Resolução de problemas

SintomaCausa provávelO que fazer
Test connection falhaDNS, firewall ou porta erradaConfirma o host e a porta a partir da rede do Keycloak. Com ldaps://, a porta é 636.
Test connection falha com erro de certificadoA CA do servidor não está na truststore do KeycloakImporta o certificado da CA para a truststore configurada no Keycloak e reinicia-o.
Test authentication falhaBind DN ou palavra-passe errados, ou conta bloqueada/expiradaValida a conta de serviço com a equipa do diretório.
A sincronização importa 0 utilizadoresUsers DN, object classes ou filtro errados, ou One Level com utilizadores em sub-OUsRevê a secção de pesquisa e experimenta Subtree.
A sincronização para nas 1000 entradasPaginação desligada no ADAtiva Pagination.
O login no Keycloak funciona mas o iGRP devolve unverified_emailTrust email em OffAtiva Trust email no fornecedor e volta a sincronizar.
O iGRP recusa o login de alguns utilizadoresEmail vazio no diretório, ou domínio fora de IGRP_OAUTH_ALLOWED_EMAIL_DOMAINSPreenche mail no diretório, ou acrescenta o domínio à lista.
Um utilizador antigo aparece no iGRP como novo, sem acessosO 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 entrarFiltro sem a exclusão de contas desativadas, ou cacheUsa o filtro com userAccountControl acima e sincroniza. Para efeito imediato, termina as sessões do utilizador no Application Center.
How is this guide?

Última atualização: