Migrando de LDAP para SAML com SCIM

Sobre a migração do LDAP para SAML e SCIM

Se a sua instância do GitHub Enterprise Server utiliza atualmente autenticação LDAP, você pode migrar para o Single Sign-On (SSO) SAML com provisionamento SCIM para obter recursos aprimorados de gerenciamento do ciclo de vida do usuário. Essa migração permite que você provisione, atualize e desprovisione automaticamente contas de usuário do seu IdP (provedor de identidade).

Observação

Você pode usar SAML ou LDAP, mas não ambos.

          **Pré-requisitos**:

Você deve ser um administrador de site no GitHub Enterprise Server.
Você deve ter acesso administrativo ao seu provedor de identidade SAML.
O IdP deve dar suporte aos protocolos SAML 2.0 e SCIM 2.0.
Você deve concluir um backup de sua instância antes de iniciar a migração.

O provisionamento scim requer a autenticação SAML como um pré-requisito, portanto, essa migração envolve quatro fases distintas:

       **Migrar para a autenticação SAML**: substitua LDAP pelo SSO do SAML.

       **Testar e verificar SAML**: Confirme que a autenticação funciona e os usuários estão vinculados corretamente.

       **Habilitar o Provisionamento SCIM**: Adicionar recursos automatizados de gerenciamento de usuário.

       **Testar e verificar o SCIM**: Confirmar que o provisionamento vincula identidades a contas existentes.

Este documento pressupõe familiaridade com a autenticação SAML e o provisionamento SCIM. Para obter mais informações sobre esses tópicos, consulte Configurar o logon único SAML para sua empresa e Sobre o provisionamento de usuário com o SCIM no GitHub Enterprise Server.

1. Entender os padrões de criação de usuário LDAP vs SCIM

Antes de iniciar a migração, é importante entender as principais diferenças entre como o LDAP e o SCIM lidam com o gerenciamento de usuários em GitHub Enterprise Server.

Attribute	LDAP	SCIM

          **Configuração do dispositivo** | Você configura o atributo de ID do usuário (padrão `uid`) e outras configurações LDAP no console de gerenciamento. Essa configuração determina como mapear entre usuários LDAP e usuários GitHub. Para obter mais informações sobre como configurar o LDAP, consulte [AUTOTITLE](/admin/managing-iam/using-ldap-for-enterprise-iam/using-ldap#ldap-attributes). | Habilite a autenticação SAML primeiro e, em seguida, configure o provisionamento SCIM com um token de autenticação. |

| Tempo de criação do usuário | Criação sob demanda: os usuários são criados no primeiro login após a autenticação LDAP bem-sucedida. | Pré-autenticação: os usuários devem ser provisionados via SCIM para que possam se autenticar. | | Origem inicial do nome de usuário | GitHub nome de usuário é baseado no identificador LDAP normalizado configurado durante a instalação. | O nome de usuário no GitHub é baseado no valor SCIM userName normalizado do seu IdP. | | Gerenciamento de nome de usuário | Flexível: os administradores podem alterar GitHub nomes de usuário independentemente do LDAP. Os nomes de usuário podem divergir dos identificadores LDAP ao longo do tempo, embora a autenticação seja mantida por meio de mapeamentos LDAP. Confira Referência de nome de usuário. | Rígido: Os nomes de usuário do GitHub sempre correspondem ao SCIM normalizado userName do seu IdP. Alterações de nome de usuário no lado GitHub não são permitidas. | | Controle de atributo do usuário | Híbrido: alguns atributos gerenciados pelo LDAP, outros podem ser gerenciados no dispositivo. | Controle IdP completo: todos os atributos de usuário são gerenciados por meio de atualizações SCIM enviadas do seu IdP. | | Fluxo de autenticação | GitHub Enterprise Server autentica-se com o seu servidor LDAP e consulta o mapeamento LDAP existente para localizar o usuário. | Durante o SSO do SAML, uma pesquisa de identidade externa é executada para localizar o usuário provisionado para autenticação. | | Característica chave | Sistema híbrido no qual dados de usuário do GitHub (especialmente nomes de usuário) podem ser parcialmente gerenciados no aplicativo independentemente do servidor LDAP. | Controle completo do provedor de identidade: o estado dos usuários do GitHub depende inteiramente do que o IdP envia por meio do SCIM, e os nomes de usuário não podem desviar-se do sistema de origem. |

Normalização e compatibilidade de nome de usuário

GitHub Enterprise Server normaliza nomes de usuário de acordo com regras específicas que se aplicam de forma consistente a LDAP, SAML e SCIM. Entender essas regras é fundamental para a migração bem-sucedida.

Para obter mais informações sobre a normalização do nome de usuário, consulte Considerações de nome de usuário para autenticação externa.

2. Planejar sua migração

Antes de iniciar a migração, você precisa entender sua configuração atual, preparar seu provedor de identidade e estabelecer métodos de acesso de backup. A fase de planejamento é essencial para garantir uma transição tranquila.

Preparando-se para mapear de LDAP para SCIM

O desafio crítico de migração é conciliar as abordagens de gerenciamento de usuários LDAP e SCIM.

          **Usuários LDAP (estado existente)**:

Tenha nomes de usuário do GitHub que possam ter sido alterados desde a criação inicial.
Manter a capacidade de autenticação por meio de mapeamentos LDAP, independentemente das alterações de nome de usuário
```
        **Usuários do SCIM (estado de destino)**:
```
Deve ser provisionado antes da autenticação
Devem ter nomes de usuário GitHub que correspondam aos valores SCIM normalizados userName
Pode ser vinculado a uma identidade externa com sua conta GitHub existente durante o provisionamento de usuários SCIM, mas somente se o SCIM normalizado userName corresponder ao nome de usuário existente do GitHub.

Requisitos de mapeamento de migração

Para vincular identidades SCIM com êxito a usuários LDAP existentes, você precisará capturar o estado atual dos usuários em sua instância:

       **Exportar nomes de usuário do GitHub existentes**: Use a interface de administrador do site, a API ou a CLI para obter uma lista completa dos nomes de usuário atuais do GitHub em sua instância. Para obter mais informações sobre a API de usuários, consulte [AUTOTITLE](/rest/users/users?apiVersion=2022-11-28#list-users). Para obter mais informações sobre o utilitário de linha de comando para exportar usuários, consulte [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities#ghe-user-csv).

       **Mapeie nomes de usuário do GitHub para usuários reais no seu IdP**: determine quais identidades correspondem a cada nome de usuário do GitHub na sua empresa.

       **Configure o atributo SCIM `userName`**: verifique se o IdP provisiona usuários SCIM com valores `userName` que correspondam aos nomes de usuário existentes GitHub que você gostaria de vincular.

       **Importante**: O destino para mapeamento é sempre o **nome de usuário do GitHub atual** em sua instância, não o ID de usuário LDAP original ou qualquer outro identificador.

Principais considerações de planejamento

          **Considerações importantes:**

* Tempo de inatividade necessário: essa migração requer tempo de inatividade durante uma janela de manutenção para alterar as configurações de autenticação. * Impacto para o usuário: após a migração, os usuários precisarão se autenticar por meio do IdP SAML em vez de as credenciais LDAP. * Associação de equipe: a sincronização de equipes LDAP será substituída pelo provisionamento de grupos SCIM, caso seja compatível com o seu IdP. As equipes mapeadas por LDAP precisarão ser atualizadas com um grupo SCIM apropriado, quando aplicável.

Capturar o estado da configuração do LDAP

Registre a configuração atual do LDAP para planejar mapeamentos SAML/SCIM equivalentes:

Em uma conta administrativa no GitHub Enterprise Server, no canto superior direito de qualquer página, clique em .
Se você ainda não estiver na página "Administração do site", no canto superior esquerdo, clique em Administração do site.
Na barra lateral " Site admin", clique em Console de Gerenciamento.
Na barra lateral "Configurações", clique em Autenticação.
Documente as seguintes configurações de LDAP: * Base de domínio e grupos de usuários restritos * User ID attribute (isso foi usado para criar nomes de usuário GitHub) * Nome do perfil, email e outros mapeamentos de atributo * Configuração de grupo de administradores * Configurações de sincronização de equipe
Verifique se você salvou uma lista de usuários existentes em sua instância que você vinculará a uma identidade SCIM.

3. Migrar para SAML e SCIM

Depois de concluir o planejamento, você pode começar a migrar do LDAP para a autenticação SAML. Isso envolve configurar o SAML tanto no seu provedor de identidade quanto no GitHub Enterprise Server, e então testar cuidadosamente a configuração antes de prosseguir para o SCIM.

          **Importante**: ao configurar o SAML, habilite "Permitir a criação de contas com autenticação interna" para reduzir o número de etapas necessárias ao habilitar o SCIM.

Habilitando a autenticação SAML

Para obter etapas detalhadas de configuração do SAML, consulte Configurar o logon único SAML para sua empresa.

Depois de habilitar o SAML, teste o sistema de autenticação antes de prosseguir para o SCIM. Com qualquer conta IdP atribuída ao aplicativo SAML configurada em sua instância, verifique se você é capaz de executar com êxito um logon de SSO.

          **Não prossiga para o SCIM até que a autenticação SAML esteja funcionando corretamente.**

Habilitar o provisionamento do SCIM

Depois de confirmar que a autenticação SAML funciona corretamente, você pode habilitar o SCIM para gerenciamento automatizado de usuários. O SCIM deve ser configurado tanto em GitHub Enterprise Server quanto no seu provedor de identidade.

Para obter etapas detalhadas para habilitar o SCIM, consulte Configurando o provisionamento de SCIM para o gerenciamento de usuários.

Testar o provisionamento do SCIM

Teste o provisionamento do SCIM para garantir que os usuários provisionados do SCIM estejam vinculados às contas de usuário existentes corretamente.

Para usuários que já têm contas da migração LDAP/SAML:

       **Atribua o usuário ao aplicativo SCIM** em seu IdP.

```
       **Verifique a vinculação automática**: verifique se o SCIM é vinculado automaticamente à conta existente:
```
- Os usuários mantêm os mesmos dados de nome de usuário e conta
- Nenhuma conta duplicada é criada
- A identidade SCIM aparece como vinculada nas configurações da empresa e nas interfaces de administração do site. Para saber mais, confira Visualizar e gerenciar o acesso SAML de um usuário à sua empresa.

       **Analisar logs de auditoria**: procure por eventos `external_identity.scim_api_success` e `external_identity.provision` que mostram a vinculação bem-sucedida aos usuários existentes.

Para novos usuários que não estão anteriormente em sua instância:

       **Verificar a criação do usuário**: Verifique se o usuário aparece em GitHub Enterprise Server com atributos corretos.

       **Autenticação de teste**: confirme se o novo usuário pode se autenticar por meio do SAML.

       **Testar atualizações de atributo**: atualize as informações do usuário no IdP e confirme a sincronização de alterações.

       **Teste de desprovisionamento**: remova o acesso do usuário e confirme que o usuário está suspenso.

Distribuir o SCIM para todos os usuários

Para todos os usuários restantes que ainda não foram provisionados via SCIM:

       **Atribua gradualmente usuários** ao aplicativo GitHub Enterprise Server em seu IdP.

       **Monitorar o processo de vinculação**: acompanhe a vinculação automática bem-sucedida com base na correspondência dos nomes de usuário.

       **Acompanhe o progresso**: use logs de auditoria para monitorar eventos `external_identity` para vincular ao progresso.

       **Resolva conflitos**: resolva conflitos de nome de usuário ou problemas de mapeamento conforme eles surgem.

4. Atualizar a equipe e a participação na organização

Após a migração, se você usou anteriormente a sincronização de grupo LDAP para controlar associações de equipe, poderá substituir esses mapeamentos de equipe por grupos SCIM. Se estiver reutilizando uma equipe existente, você precisará remover todos os membros da equipe antes de vincular um grupo IdP.

Para saber mais, confira Gerenciando associações de equipes com grupos de provedores de identidade.

Quem pode usar esse recurso?

Neste artigo