Configure a federação LDAP ou Active Directory para o IBM Bob on-premises usando o recurso personalizado BobIDP e o comando bobctl configure-idp.

Use bobctl configure-idp para conectar seu ambiente LDAP ou Active Directory ao Keycloak como um provedor de federação de usuários. Você pode concluir essa configuração durante a instalação ou a qualquer momento após a implantação.

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 IDP a partir do template fornecido antes de registrar um provedor LDAP.

cp config-idp-template.yaml my-idp.yaml

O arquivo de configuração tem duas seções: campos de nível superior que se aplicam a toda a implantação, e uma lista ldaps opcional onde cada entrada descreve um provedor de federação LDAP.

Campos de nível superior

Campo	Obrigatório	Descrição
`domains`	Sim	Lista de domínios de e-mail que o Bob aceita no login. Remover um domínio cancela seu registro; usuários com esse domínio não conseguirão fazer login.
`adminEmails`	Não	Lista de e-mails de usuários a serem concedidos acesso de administrador do Bob. O operador atualiza de forma atômica o grupo `bob-admins` do Keycloak e o banco de dados de administradores do Bob.
`ldaps`	Não	Lista de configurações de provedor de federação LDAP. Omita completamente para implantações que usam apenas usuários diretos do Keycloak.

Campos obrigatórios (por entrada de provedor LDAP)

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.

Importante:

O campo domains é a única forma de 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 esse não é o método correto e pode causar erros de autenticação.

Campos opcionais (por entrada de provedor LDAP)

Campo	Descrição
`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`	Nome de um Secret pré-existente contendo a senha da conta de bind. Deve ser criado no namespace da instância antes de executar `bobctl configure-idp`.
`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`	Nome de um Secret pré-existente contendo o certificado CA do servidor LDAP no formato PEM. Deve ser criado no namespace da instância antes de executar `bobctl configure-idp`.
`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. Com a sincronização de grupos, usuários e membros de grupos do seu diretório LDAP são 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. Eles não são incluídos na 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

# Domínios de e-mail que o Bob deve aceitar no login
domains:
  - corp.example.com

# Usuários a serem concedidos acesso de administrador do Bob
adminEmails:
  - alice@corp.example.com

# Provedores de federação LDAP
ldaps:
  - 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

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

    useTruststoreSpi: always
    ldapsCACertSecret: corp-ldap-ca

    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 configure-idp --config my-idp.yaml

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

Antes de aplicar uma configuração IDP 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 configure-idp --config my-idp.yaml --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.

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

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 IDP, execute o comando configure-idp para aplicar a configuração ao cluster.

./bobctl configure-idp --config my-idp.yaml

Flag	Obrigatório	Descrição
`--config <file>`	Sim	Especifica o caminho para o arquivo de configuração IDP.
`--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 IDP verificando as condições de status reportadas pelo recurso personalizado BobIDP.

Verificação	O que confirma
`Ready`	A configuração foi aplicada com sucesso.
`LDAPRegistered`	O provedor LDAP foi registrado no Keycloak.
`LDAPReachable`	O servidor LDAP está acessível a partir do cluster.
`LDAPAuthenticated`	As credenciais de bind configuradas são válidas.
`LDAPUserSyncSucceeded`	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_IDP_WAIT_TIMEOUT:

BOB_IDP_WAIT_TIMEOUT=900 ./bobctl configure-idp --config my-idp.yaml

Configurando múltiplos provedores LDAP

Para integrar usuários de múltiplas fontes LDAP ou Active Directory, adicione cada diretório como uma entrada separada na lista ldaps do arquivo de configuração IDP e execute novamente o configure-idp.

./bobctl configure-idp --config my-idp.yaml

Inspecionando o status do recurso IDP

Para visualizar o status da configuração IDP:

oc get bobidp -n <instance-namespace>

Para visualizar informações detalhadas de configuração e status:

oc get bobidp bob-idp -n <instance-namespace> -o yaml

Verificando a integração

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

Verifique o status do recurso personalizado BobIDP:

oc get bobidp bob-idp -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