Configurando o provisionamento de usuários com o SCIM no GitHub Enterprise Server

Sobre o provisionamento de usuários do GitHub Enterprise Server

Se você usar o SSO (logon único) do SAML para sua instância do GitHub Enterprise Server, poderá configurar o SCIM para criar ou suspender automaticamente as contas de usuário e permitir acesso à instância ao atribuir ou desatribuir o aplicativo no IdP. Para obter mais informações sobre o SCIM, confira Sistema de Gerenciamento de Usuários entre Domínios: protocolo (RFC 7644) no site do IETF.

Se você não configurar o provisionamento de usuários com SCIM, seu IdP não se comunicará com GitHub Enterprise Server automaticamente quando você atribuir ou cancelar a atribuição do aplicativo a um usuário. Sem SCIM, GitHub Enterprise Server cria uma conta de usuário usando o provisionamento SAML Just-in-Time (JIT) na primeira vez que alguém navega para GitHub Enterprise Server e entra autenticando-se por meio de seu IdP.

Para configurar o provisionamento para sua empresa, você deve habilitar o provisionamento em GitHub Enterprise Server e, em seguida, instalar e configurar um aplicativo de provisionamento em seu IdP.

Provedores de identidade compatíveis

Durante a beta privada, a equipe da conta fornecerá a documentação para a configuração do SCIM para GitHub Enterprise Server em um IdP com suporte.

Como posso gerenciar os ciclos de vida do usuário com o SCIM?

Com o SCIM, você gerencia o ciclo de vida das contas de usuário do seu IdP:

• Quando você provisiona um novo usuário, o IdP solicita que o sua instância do GitHub Enterprise Server crie uma conta e envie um email de integração para o usuário. Se você atribuir um grupo ao aplicativo no IdP, o IdP provisionará contas para todos os membros do grupo.
• Quando você atualiza as informações associadas à identidade de um usuário no IdP, o IdP atualiza a conta do usuário no GitHub.
• Quando você cancela a atribuição do usuário do aplicativo do IdP ou desativa uma conta de usuário no IdP, o IdP se comunica com o GitHub para invalidar as sessões e desabilitar a conta do membro. As informações da conta desabilitada serão mantidas e o respectivo nome de usuário será alterado para um hash do nome de usuário original.
• Se você reatribuir um usuário ao aplicativo IdP ou reativar sua conta em seu IdP, a conta de usuário será reativada e o nome de usuário será restaurado.

Quando o SCIM estiver habilitado, você não poderá mais excluir, suspender nem promover usuários provisionados pelo SCIM diretamente no GitHub Enterprise Server. Você deve gerenciar esses processos por meio do seu IdP.

O que acontecerá com os usuários existentes na minha instância?

Se você usa o SSO do SAML e está habilitando o SCIM, deve estar ciente do que acontece com os usuários existentes durante o provisionamento do SCIM.

• Quando o SCIM estiver habilitado, os usuários com identidades vinculadas ao SAML não poderão entrar até que suas identidades tenham sido provisionadas pelo SCIM.
• Quando sua instância recebe uma solicitação do SCIM, as identidades do SCIM são correspondidas aos usuários existentes comparando-se o campo userName do SCIM com o nome de usuário do GitHub. Se um usuário com um nome de usuário correspondente não existir, GitHub criará um novo usuário.
• Se GitHub identificar com êxito um usuário do IdP, mas os detalhes da conta, como endereço de email, nome ou sobrenome não correspondem, a instância substituirá os detalhes pelos valores do IdP. Qualquer endereço de email diferente do email principal fornecido pelo SCIM também será excluído da conta do usuário.

O que acontece durante a autenticação SAML?

Depois que um administrador do IdP permite que uma pessoa acesse a sua instância do GitHub Enterprise Server, o usuário pode se autenticar por meio do IdP para acessar o GitHub Enterprise Server usando o SSO de SAML.

• Quando um usuário se autentica por meio do SAML, para associar um usuário a uma identidade SAML, o GitHub compara uma reivindicação NameID normalizada do IdP (ou outro valor que você configurou) com o nome de usuário da conta. Para obter detalhes sobre a normalização, consulte Considerações de nome de usuário para autenticação externa.
• Se não houver uma conta com um nome de usuário correspondente na instância, o usuário não fará login.
  • Para fazer essa correspondência, GitHub Enterprise Server compara a declaração SAML NameId do IdP com o atributo userName do SCIM para cada conta de usuário provisionada pelo SCIM na instância.
  • Além disso, para o ID do Entra, o GitHub Enterprise Server compara o identificador de objeto da solicitação SAML com um ID externo existente do SCIM.
• Se o ambiente não usar NameID para identificar os usuários de forma exclusiva, o administrador do site poderá configurar os atributos de usuário personalizados para a instância. O GitHub Enterprise Server respeitará esse mapeamento quando o SCIM estiver configurado. Para obter mais informações sobre o mapeamento de atributos do usuário, confira Configurar o logon único SAML para sua empresa.

Pré-requisitos

• Você precisa configurar o SSO de SAML para sua instância do GitHub Enterprise Server. Para saber mais, confira Configurar o logon único SAML para sua empresa.

• Você precisa permitir a autenticação interna para usuários que não têm uma conta no IdP. Para saber mais, confira Como permitir a autenticação interna para usuários de fora do seu provedor.

• O IdP precisa dar suporte à realização de chamadas do SCIM a um SP (provedor de serviços).

• Você deve ter acesso administrativo no seu IdP para configurar o aplicativo para o provisionamento do usuário para GitHub Enterprise Server.

Habilitar provisionamento de usuários para a sua empresa

Para executar ações de provisionamento em sua instância, você criará uma conta de usuário integrada e promoverá a conta a um proprietário de empresa.

Depois de habilitar o SCIM em uma instância do GitHub Enterprise Server, todas as contas de usuário serão suspensas. A conta de usuário interna continuará a executar ações de provisionamento. Depois de conceder a um usuário acesso à sua instância do IdP, o IdP se comunicará com a instância usando SCIM para cancelar a suspensão da conta do usuário.

1. Crie uma conta de usuário integrada para executar ações de provisionamento em sua instância. Para saber mais, confira Como permitir a autenticação interna para usuários de fora do seu provedor.

2. Promova a conta de usuário dedicada a um proprietário corporativo. Para saber mais, confira Convidar pessoas para gerenciar sua empresa.

3. Entre na instância como o novo proprietário corporativo.

4. Crie um personal access token (classic) com o escopo admin:enterprise. Não especifique uma data de validade para o personal access token (classic). Para saber mais, confira Gerenciar seus tokens de acesso pessoal.

   Warning

   Lembre-se de não especificar uma data de validade para o personal access token (classic). Se você especificar uma data de validade, o SCIM não funcionará mais após a data de validade.

   Note

   Você precisará deste personal access token para testar a configuração do SCIM e configurar o aplicativo para o SCIM no IdP. Armazene o token com segurança em um gerenciador de senhas até que você precise do token novamente posteriormente nestas instruções.

5. Conecte-se via SSH ao sua instância do GitHub Enterprise Server. Se sua instância for composta por vários nós, por exemplo, se a alta disponibilidade ou a replicação geográfica estiver configurada, efetue SSH no nó primário. Se você usar um cluster, poderá efetuar SSH em qualquer nó. Substitua HOSTNAME pelo nome do host da instância ou pelo nome do host ou endereço IP de um nó. Para saber mais, confira Acesar o shell administrativo (SSH).

   Shell

   ssh -p 122 admin@HOSTNAME
   

6. Para habilitar o SCIM, execute os comandos fornecidos pelo gerente de conta no Equipe de vendas do GitHub.

7. Aguarde a conclusão da execução de suas configurações.

8. Para validar se o SCIM está operacional, execute os comandos a seguir. Substitua PAT DA ETAPA 3 e NOME DO HOST DA INSTÂNCIA por valores reais.

   $ GHES_PAT="PAT FROM STEP 3"
   $ GHES_HOSTNAME="YOUR INSTANCE'S HOSTNAME"
   $ curl --location --request GET 'https://$GHES_HOSTNAME/api/v3/scim/v2/Users' \
       --header 'Content-Type: application/scim' \
       --header 'Authorization: Bearer $GHES_PAT'
   

   O comando deve retornar uma matriz vazia.

9. Configurar provisionamento de usuário no aplicativo para GitHub Enterprise Server no seu IdP. Para solicitar documentação para um IdP válido, entre em contato com o gerenciador de contas em Equipe de vendas do GitHub. Se não houver suporte ao IdP, você deverá criar o aplicativo e configurar o SCIM manualmente.