Como configurar o provisionamento de usuários na empresa com o SCIM

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, você 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 faz login autenticando por meio de seu IdP.

A configuração do provisionamento permite que o IdP se comunique com a sua instância do GitHub Enterprise Server quando você atribui ou desatribui o aplicativo do GitHub Enterprise Server a um usuário no IdP. Ao atribuir o aplicativo, o IdP pedirá que a sua instância do GitHub Enterprise Server crie uma conta e envie um email de integração ao usuário. Ao desatribuir o aplicativo, o seu IdP irá comunicar-se com GitHub Enterprise Server para invalidar quaisquer sessões de SAML e desabilitar a conta do integrante.

Para configurar o provisionamento para o seu negócio, você deve habilitar o provisionamento em GitHub Enterprise Server e, em seguida, instalar e configurar um aplicativo de provisionamento no seu IdP.

O aplicativo de provisionamento no IdP se comunica com o GitHub Enterprise Server usando a API do SCIM. Para obter mais informações, confira "SCIM" na documentação da API REST.

Sobre identidades e declarações

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.

Durante a autenticação, a instância tenta associar o usuário a uma identidade SAML. Por padrão, a instância compara a declaração NameID do IdP com o nome de usuário da conta. O GitHub Enterprise Server normaliza o valor de NameID para a comparação. Para obter mais informações sobre a normalização de nome de usuário, confira "Considerações de nome de usuário para autenticação externa".

Se não houver uma conta existente com um nome de usuário correspondente na instância, o usuário não conseguirá entrar. Para fazer essa correspondência, o GitHub Enterprise Server compara a declaração SAML NameId do IdP com a declaração username para cada conta de usuário fornecida pelo SCIM na instância.

Durante a autenticação SAML, alguns ambientes podem usar um valor diferente de NameID como declaração de identificação exclusiva. Se o ambiente não usar NameID para identificar os usuários, 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. Há suporte para mapeamentos personalizados em GitHub Enterprise Server 3.6.5 ou 3.7.2 e posteriores. Para obter mais informações sobre como mapear atributos de usuário, confira "Como configurar o logon único do SAML para sua empresa".

Se GitHub Enterprise Server identifica 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 substitui 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.

Provedores de identidade compatíveis

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

Pré-requisitos

• Você precisa configurar o SSO de SAML para sua instância do GitHub Enterprise Server. Para obter mais informações, 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 obter mais informações, 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 obter mais informações, 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 obter mais informações, confira "Convidar pessoas para gerenciar sua empresa".

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

4. Crie um personal access token com o escopo admin:enterprise. Não especifique uma data de validade para o personal access token. Para obter mais informações, confira "Criando um token de acesso pessoal".

   Aviso: certifique-se de não especificar uma data de validade para o personal access token. Se você especificar uma data de validade, o SCIM não funcionará mais após a data de validade.

   Observação: 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.

   1. 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ó. Para obter mais informações sobre o acesso SSH, confira "[AUTOTITLE](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh)".

   $ ssh -p 122 admin@HOSTNAME

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

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

7. 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.

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