---
title: LDAP + Keycloak + SSO
slug: admin/ldap-keycloak-sso
createdAt: 2025-07-24T21:16:27.819Z
---

##  1. Configurando o LDAP no Keycloak

De acordo com a documentação oficial (Server Administration Guide), para integrar o LDAP você deve navegar até **User Federation** no Admin Console e selecionar **“ldap”** como provedor.

::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/ocfiCTJcj8Gdyx_Q5mGGF_imagem.png" size="34" width="358" height="939" position="center" showCaption="false"}

A partir daí, você preenche as configurações essenciais, como:

- URL de conexão (ldap\:// ou ldaps\://),
- Bind DN (usuário com permissão de leitura),
- Credentials,
- Base DN para usuários,
- Modo de edição (por exemplo, READ\_ONLY ou UNSYNCED),
- Atributos LDAP como username, UUID, etc.

![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/i9Z8UY4i9aJ7Us7gcNRJR_imagem.png)

## 2. Mapeamento de Atributos e Grupos

O Keycloak cria automaticamente mapeamentos básicos (username, email, nome, sobrenome). É possível definir mapeamentos personalizados como por exemplo cargo, departamento, número de registro — via **user-attribute-ldap-mapper**.

![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/JfiXYUHt5RGMElmSSicIP_imagem.png)

Também é possível usar **group-ldap-mapper** ou **role-ldap-mapper** para mapear grupos ou roles do LDAP para grupos ou roles no Keycloak (realm-level ou client-level).

![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/AfevaFwMx10ClbfplH0Q4_imagem.png)

##  3. Ajustes Avançados e Performance

- É possível habilitar **LDAPS (conexão segura via SSL/TLS)** configurando Use Truststore SPI para garantir que o Keycloak confie no certificado TLS do LDAP.
- Exista **pool de conexões LDAP** configurável via com.sun.jndi.ldap.connect.pool.\* para melhorar performance em cenários com alta carga ou muitos usuários.
- Para depurar ou logar melhor as requisições LDAP, recomenda-se habilitar o nível TRACE em org.keycloak.storage.ldap nos logs.

##  4. Exemplo resumido

### Etapa 1: Configurar User Federation

- Vá ao console de administração → **User Federation** → **Add provider: ldap**
- Preencha campos como Display Name, Connection URL, Bind DN/Credential, Users DN, Edit Mode, atributos LDAP
- Teste conexão e autenticação e salve

![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/xzEm6_Y93fjoZcAmCfvDr_imagem.png)

### Etapa 2: Sincronizar usuários

- Se você ativou *Import Users*, use “Synchronize all users” ou configure sync periódica
- Se optar por não importar, o Keycloak consulta de forma unificada no momento do login



::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/TW2y-aPFqq65F11bDabsn_imagem.png" size="48" width="525" height="495" position="center" showCaption="false"}

### Etapa 3: Configurar Mappers

- Atributos básicos são mapeados automaticamente
- Para atributos customizados, crie mappers tipo user-attribute-ldap-mapper

![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/sKQrnINlxXwi9AfuFLHfY_imagem.png)

- Para grupos/roles LDAP, use group-ldap-mapper ou role-ldap-mapper indicando DN base, atributos e destino (realm ou client)

![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/grI9nYhhN7hDw4w8XOhuC_imagem.png)

### SSO com Keycloak + LDAP

###  1. SSO "Automático" com Kerberos (SPNEGO / Windows AD)

Se você estiver usando **LDAP do Active Directory (AD)**, é possível configurar o **Kerberos/SPNEGO** para autenticação automática do usuário no Keycloak — sem ele precisar digitar login/senha no navegador (SSO verdadeiro).

- O navegador (Chrome/Edge/Firefox) usa o ticket do **Windows Logon (Kerberos)** para autenticar automaticamente no Keycloak.
- É necessário configurar:
  - Keycloak como um **SPNEGO/Kerberos realm**
  - Um service account com SPN no Active Directory (ex: HTTP/keycloak.seudominio.com.br)
  - Truststore com o keytab (.keytab)
  - Navegadores devem estar configurados para confiar no domínio

###  2. SSO entre aplicações via tokens OIDC/SAML

Após o **usuário se autenticar uma vez**, todas as **aplicações integradas com Keycloak** (via OIDC ou SAML) aceitarão o token dele e ele não precisará se autenticar novamente.

Isso é o que normalmente chamamos de **SSO na prática**.

**Exemplo**:

- Aplicação A → redireciona para login Keycloak → autentica com LDAP
- Usuário acessa Aplicação B → redireciona também → já está autenticado → entra direto

:::hint{type="danger"}
⚠️ Nesse caso, o login **só é automático após a primeira autenticação** (diferente do SPNEGO, que pode fazer isso sem intervenção do usuário).
:::

###  3. Login automático via Reverse Proxy (NGINX/IIS)

Outra abordagem é colocar um **proxy reverso autenticado** (ex: NGINX com módulo Kerberos ou IIS com NTLM) **na frente do Keycloak**. O proxy faz a autenticação com o AD e injeta o login no header para o Keycloak aceitar via **Identity Brokering ou autenticação externa**.