Configure a federação LDAP ou Active Directory para o IBM Bob on-premises usando o recurso personalizado BobLDAP e o comando bobctl add-ldap.

O Bob on-premises integra seu ambiente LDAP ou Active Directory ao Keycloak por meio do utilitário bobctl, que configura o diretório como um provedor de federação de usuários do Keycloak. Embora essa integração seja normalmente configurada durante a instalação, ela também pode ser configurada, atualizada ou mantida após a implantação como parte das atividades contínuas de gerenciamento de usuários.

Antes de começar

Antes de configurar a federação LDAP, verifique se os seguintes requisitos são atendidos:

O cluster do OpenShift Container Platform (OCP) tem conectividade de rede com o servidor LDAP na porta apropriada:

389 para ldap://
636 para ldaps://

Uma conta de serviço (bind DN) com acesso de leitura ao diretório está disponível, ou o servidor LDAP está configurado para permitir binds anônimos.

Se você estiver usando ldaps:// com uma autoridade de certificação (CA) privada ou assinada internamente, obtenha o certificado CA do servidor LDAP no formato PEM.

O utilitário de linha de comando bobctl está instalado e o oc está configurado e autenticado no cluster de destino.

Referência do arquivo de configuração

Crie um arquivo de configuração LDAP a partir do template fornecido antes de registrar um provedor LDAP.

cp config-ldap-template.yaml my-ldap.yaml

O arquivo de configuração contém parâmetros obrigatórios e opcionais que definem como o Bob se conecta, autentica e sincroniza usuários do seu diretório LDAP.

Campos obrigatórios

Campo	Descrição
`name`	Um identificador único e descritivo para o provedor LDAP. Cada provedor configurado deve ter um nome distinto.
`vendor`	Especifica o tipo de diretório LDAP a ser integrado. Valores suportados: `other` (OpenLDAP e compatível com LDAPv3), `ad` (Microsoft Active Directory), `rhds` (Red Hat Directory Server), `tivoli` (IBM Security Directory Server), `edirectory` (NetIQ eDirectory).
`connectionUrl`	A URL completa do servidor LDAP, incluindo o protocolo (`ldap://` ou `ldaps://`), nome do host e número de porta.
`usersDn`	O local do diretório onde as contas de usuário são armazenadas e de onde as entradas de usuário são pesquisadas e importadas.
`usernameLDAPAttribute`	O atributo de diretório que os usuários fornecem como nome de usuário ao autenticar.
`rdnLDAPAttribute`	O atributo de diretório usado para identificar entradas dentro da estrutura do diretório. Na maioria das configurações, é o mesmo que `usernameLDAPAttribute`.
`uuidLDAPAttribute`	Um atributo de diretório único, estável e imutável usado para identificar permanentemente cada conta de usuário.
`userObjectClasses`	Uma lista separada por vírgulas de classes de objetos LDAP que definem quais entradas do diretório são reconhecidas e processadas como contas de usuário.
`domains`	Um ou mais domínios de e-mail associados ao diretório. Durante a autenticação, os usuários cujos endereços de e-mail correspondem a qualquer um dos domínios configurados são automaticamente roteados para este provedor LDAP para validação de credenciais.

Importante:

O parâmetro domains é o único método suportado para configurar o roteamento baseado em domínio em implantações on-premises. Não configure domínios pela interface de usuário de administração do Bob porque isso não é suportado e pode causar erros de autenticação.

Campos opcionais

Campo	Descrição
`adminEmails`	Endereços de e-mail de usuários para conceder privilégios administrativos. O Bob atribui automaticamente acesso de administrador a esses usuários.
`bindDn`	O DN da conta de serviço usado para autenticar e conectar ao diretório. Pode ser omitido se o diretório permitir acesso de bind anônimo.
`bindPasswordSecret`	Referencia o Secret que armazena a senha da conta de bind. Este Secret é criado automaticamente quando a opção `--bind-password` é fornecida com o comando `bobctl`.
`useTruststoreSpi`	Especifica quando o certificado CA do LDAP é usado para validação do servidor. Valores: `always` (padrão, para certificados CA privados ou emitidos internamente), `ldapsOnly` (para certificados CA publicamente confiáveis), `never` (ao conectar por `ldap://` não seguro).
`ldapsCACertSecret`	Referencia o Secret que contém o certificado CA do servidor LDAP no formato PEM. Este Secret é criado automaticamente quando `--ca-cert-file` é fornecido.
`searchScope`	Determina a profundidade das pesquisas de diretório. `2` pesquisa todos os contêineres filhos e subárvores (padrão); `1` restringe as pesquisas apenas às entradas filhas diretas.
`customUserSearchFilter`	Um filtro adicional aplicado a todas as operações de pesquisa de usuário, por exemplo para excluir contas de serviço ou restringir pesquisas a tipos específicos de usuário.
`userSync.enabled`	Quando definido como `true`, todos os usuários são importados quando o provedor é configurado inicialmente, e as alterações subsequentes do diretório são sincronizadas a cada cinco minutos. Recomendado para a maioria das implantações.
`userAttributeMappings`	Define como os atributos do diretório são mapeados para os campos de perfil de usuário do Bob, como `email`, `firstName` e `lastName`.
`priority`	Determina a ordem em que os provedores são avaliados quando múltiplos provedores estão configurados. Os provedores com valores menores são verificados primeiro. O padrão é `0`.
`groupMapper`	Sincroniza grupos LDAP no Keycloak. Consulte Configurando a sincronização de grupos LDAP.

Comportamento de sincronização de usuários

Quando userSync.enabled é definido como true, o Bob realiza uma importação única de todos os usuários quando o provedor LDAP é registrado. Após a conclusão da importação inicial, a sincronização contínua do ciclo de vida do usuário é gerenciada automaticamente pelo SCIM.

Dica:

Para diretórios LDAP grandes, considere manter userSync.enabled como false e permitir que os usuários sejam provisionados quando fizerem login pela primeira vez. Essa abordagem pode reduzir o tempo necessário para registrar o provedor LDAP.

Configurando a sincronização de grupos LDAP

Use a configuração opcional groupMapper para sincronizar grupos LDAP com o Keycloak. A sincronização de grupos permite que usuários e membros de grupos definidos no seu diretório LDAP sejam importados e gerenciados pelo Keycloak.

O parâmetro groupsDn é obrigatório. Todos os outros parâmetros são opcionais e podem ser personalizados para corresponder ao schema e à estrutura de grupos do seu diretório LDAP.

Restrição:

Os grupos bob-admins e bob-users são grupos gerenciados pela plataforma e são excluídos automaticamente da sincronização de grupos LDAP.

Parâmetro	Valor padrão	Descrição
`groupsDn`	Obrigatório	Nome distinto (DN) base que contém as entradas de grupos LDAP.
`name`	`groups`	Nome de exibição do mapeador de grupos no Keycloak.
`groupNameLdapAttribute`	`cn`	Atributo LDAP que o Keycloak usa como nome do grupo.
`groupObjectClasses`	`groupOfNames`	Classe ou classes de objetos LDAP que identificam entradas de grupo.
`membershipLdapAttribute`	`member`	Atributo na entrada do grupo que contém informações de membros.
`membershipAttributeType`	`DN`	Formato dos valores de membros. Valores suportados: `DN` (nomes distintos) e `UID` (IDs de usuário).
`userRolesRetrieveStrategy`	`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE`	Método usado para determinar membros de grupos.
`memberOfLdapAttribute`	`memberOf`	Atributo do usuário contendo informações de membros de grupo quando `GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE` é usado.
`customGroupSearchFilter`	Nenhum	Filtro LDAP adicional usado ao pesquisar grupos. O filtro deve estar entre parênteses, por exemplo `(cn=dept-*)`.
`mode`	`LDAP_ONLY`	Modo de sincronização. Valores suportados: `LDAP_ONLY` e `READ_ONLY`.
`groupsPath`	`/`	Local na hierarquia de grupos do Keycloak onde os grupos sincronizados são criados.

Estratégias de recuperação de membros de grupo

O parâmetro userRolesRetrieveStrategy controla como o Keycloak identifica os membros de grupo de um usuário.

Estratégia	Descrição
`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE`	Recupera membros de grupo pesquisando entradas de grupo que contêm referências a usuários.
`GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE`	Recupera membros de grupo a partir do atributo `memberOf` do usuário.
`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE_RECURSIVELY`	Recupera membros de grupo recursivamente, incluindo grupos aninhados quando suportado pelo diretório LDAP.

Dica:

Use LOAD_GROUPS_BY_MEMBER_ATTRIBUTE a menos que seu diretório LDAP armazene informações de membros de grupo nas entradas de usuário por meio do atributo memberOf ou use estruturas de grupos aninhados que requerem pesquisas recursivas.

Exemplo de configuração

name: corp-ldap

vendor: other
connectionUrl: ldaps://ldap.corp.example.com:636
usersDn: ou=People,dc=corp,dc=example,dc=com
usernameLDAPAttribute: uid
rdnLDAPAttribute: uid
uuidLDAPAttribute: entryUUID
userObjectClasses: inetOrgPerson,organizationalPerson,person

domains:
  - corp.example.com

bindDn: cn=bob-svc,ou=ServiceAccounts,dc=corp,dc=example,dc=com

useTruststoreSpi: always

userSync:
  enabled: true

userAttributeMappings:
  - ldapAttribute: mail
    userModelAttribute: email
  - ldapAttribute: givenName
    userModelAttribute: firstName
  - ldapAttribute: sn
    userModelAttribute: lastName

# Optional: synchronize LDAP groups into Keycloak
groupMapper:
  groupsDn: ou=Groups,dc=corp,dc=example,dc=com
  groupObjectClasses: groupOfNames
  membershipLdapAttribute: member

./bobctl add-ldap --config corp-ldap.yaml \
  --bind-password '<bind-password>' \
  --ca-cert-file /path/to/ca.crt

Validando uma configuração LDAP antes de aplicá-la

Antes de aplicar uma configuração LDAP ao cluster, use a opção --dry-run para validar a configuração e visualizar os recursos que seriam criados. Executar um dry run pode ajudar a identificar problemas comuns de configuração antes que qualquer alteração seja feita no cluster.

./bobctl add-ldap --config my-ldap.yaml \
  --bind-password '<bind-password>' \
  --ca-cert-file /path/to/ca.crt \
  --dry-run

O dry run realiza as seguintes verificações:

Valida que todos os parâmetros de configuração obrigatórios estão presentes no arquivo de configuração.

Verifica se o arquivo de certificado CA especificado está disponível localmente quando --ca-cert-file é usado.

Exibe uma visualização do recurso personalizado BobLDAP que seria criado ou atualizado.

Mostra os Kubernetes Secrets que seriam gerados como parte da configuração.

Sai sem criar, modificar ou excluir nenhum recurso no cluster.

Nota:

A operação dry-run não valida a conectividade de rede com o servidor LDAP, não autentica as credenciais fornecidas no diretório, nem confirma a existência de Secrets referenciados no cluster. Essas validações são realizadas somente após a aplicação da configuração e são refletidas nas condições de status LDAPReachable e LDAPAuthenticated.

Aplicando a configuração

Após criar e validar seu arquivo de configuração LDAP, execute o comando add-ldap para aplicar a configuração ao cluster.

./bobctl add-ldap --config my-ldap.yaml \
  --bind-password '<bind-password>' \
  --ca-cert-file /path/to/ca.crt

Flag	Obrigatório	Descrição
`--config <file>`	Sim	Especifica o caminho para o arquivo de configuração LDAP.
`--bind-password <password>`	Não	Cria o `bindPasswordSecret` no cluster. Não é obrigatório quando o diretório permite acesso de bind anônimo.
`--ca-cert-file <path>`	Não	Cria o `ldapsCACertSecret` a partir de um arquivo PEM local. Pode ser omitido ao usar uma CA publicamente confiável ou uma conexão `ldap://` não segura.
`--dry-run`	Não	Valida a configuração e exibe uma visualização dos recursos que seriam criados ou atualizados, sem aplicar nenhuma alteração ao cluster.

Quando o comando é executado, o bobctl aguarda o operador reconciliar a configuração e valida o provedor LDAP verificando as condições de status reportadas pelo recurso personalizado BobLDAP.

Verificação	O que confirma
`Ready`	O provedor foi criado e registrado com sucesso.
`LDAPReachable`	O servidor LDAP está acessível a partir do cluster.
`LDAPAuthenticated`	As credenciais de bind configuradas são válidas.
`UserSyncSucceeded`	A importação inicial de usuários foi concluída com sucesso. Esta condição é avaliada somente quando `userSync.enabled` está definido como `true`.

O timeout de validação padrão é 600 segundos (10 minutos). Em ambientes com diretórios grandes, a sincronização inicial de usuários pode levar vários minutos para ser concluída. Para aumentar o timeout, defina a variável de ambiente BOB_LDAP_WAIT_TIMEOUT:

BOB_LDAP_WAIT_TIMEOUT=900 ./bobctl add-ldap --config my-ldap.yaml

Configurando múltiplos provedores LDAP

Para integrar usuários de múltiplas fontes LDAP ou Active Directory, crie um arquivo de configuração separado para cada diretório e atribua um valor único ao campo name em cada configuração.

./bobctl add-ldap --config ldap-corp.yaml
./bobctl add-ldap --config ldap-subsidiary.yaml

Inspecionando o status do recurso LDAP

Para visualizar o status dos provedores LDAP configurados:

oc get bobldap -n <instance-namespace>

Para visualizar informações detalhadas de configuração e status de um provedor específico:

oc get bobldap <name> -n <instance-namespace> -o yaml

Verificando a integração

Após a conclusão bem-sucedida do bobctl add-ldap, verifique se a integração LDAP está funcionando corretamente.

Verifique o status do recurso personalizado BobLDAP:

oc get bobldap <name> -n <instance-namespace> -o yaml

Verifique se as seguintes condições de status estão definidas como True:

Condição	Propósito
`Ready`	Confirma que o provedor LDAP foi registrado com sucesso.
`LDAPReachable`	Confirma que o cluster consegue se comunicar com o servidor LDAP.
`LDAPAuthenticated`	Confirma que as credenciais de bind configuradas são válidas.
`UserSyncSucceeded`	Confirma que todos os usuários foram importados com sucesso. Presente somente quando `userSync.enabled: true`.

Se alguma condição for False, revise o campo message correspondente para obter detalhes de diagnóstico.

Faça login usando credenciais do diretório LDAP federado para verificar se a autenticação do usuário está funcionando.

Abra a URL do Bob:

https://bob.<namespace>.<ingress-domain>

Um login bem-sucedido confirma que a conectividade, autenticação, roteamento de domínio, provisionamento SCIM e mapeamento de funções estão funcionando corretamente.

Após o primeiro login do usuário, confirme que o registro do usuário está disponível no Bob.

Abra o Bob administration UI:

https://bob.<namespace>.<ingress-domain>/admin

Faça login como administrador do Bob e verifique se o usuário de teste aparece na lista de usuários.

Se groupMapper estiver configurado para mapear um grupo LDAP para administradores do Bob:

Faça login com uma conta de usuário que pertença ao grupo de administradores mapeado.
Confirme que o usuário consegue acessar o Bob administration UI.
Verifique se as funções de nível de administrador estão disponíveis.

Se userSync.enabled: true, os usuários são importados automaticamente após o registro do provedor LDAP. O usuário de teste deve aparecer no Bob sem necessitar de um login inicial.

Se o usuário não aparecer após vários minutos, revise os logs do bob-admin em busca de erros de provisionamento:

oc logs -n <instance-namespace> -l app=bob-admin --tail=100

Revise os erros relacionados ao SCIM reportados e resolva-os antes de tentar novamente o processo de sincronização.

Integração LDAP