Provisionar usuários e grupos com SCIM usando a API REST

Sobre o provisionamento do SCIM no GitHub Enterprise Server

Para provisionar e manter contas de usuário usando o SCIM, seu sistema de gerenciamento de identidades deve oferecer a seguinte funcionalidade:

• Autenticação de logon único implementando Security Assertion Markup Language (SAML) 2.0
• Gerenciamento do ciclo de vida do usuário com o SCIM (Sistema de Gerenciamento de Usuários entre Domínios)

Ao configurar a autenticação e o provisionamento para a empresa, você pode usar um IdP parceiro ou outra combinação de sistemas de gerenciamento de identidades.

• Usar um provedor de identidade parceiro
• Usar outros sistemas de gerenciamento de identidades

Usar um provedor de identidade parceiro

Cada IdP parceiro fornece um aplicativo simplificado que implementa o SSO e o gerenciamento do ciclo de vida do usuário. Para simplificar a configuração, a GitHub recomenda que você use um aplicativo de IdP parceiro para autenticação e provisionamento. Para obter mais informações e uma lista de IdPs parceiros, consulte Sobre o provisionamento de usuários com o SCIM no GitHub Enterprise Server.

Para obter mais informações sobre como configurar o provisionamento do SCIM usando um IdP parceiro, confira Configurando o provisionamento do SCIM para gerenciar usuários.

Usar outros sistemas de gerenciamento de identidades

Se você não puder usar um IdP parceiro para autenticação e provisionamento devido à sobrecarga de migração, custos de licenciamento ou inércia organizacional, poderá usar outro sistema de gerenciamento de identidades ou uma combinação de sistemas. Os sistemas devem fornecer a autenticação usando SAML e o gerenciamento do ciclo de vida do usuário usando SCIM. Eles também devem aderir às diretrizes de integração do GitHub.

O GitHub não testou a integração com todos os sistemas de gerenciamento de identidades. Embora seja possível realizar a integração com o GitHub Enterprise Server, a equipe de suporte do GitHub pode não ser capaz de fornecer assistência com problemas relacionados a esses sistemas. Consulte a documentação, a equipe de suporte ou outros recursos do sistema se precisar de ajuda com um sistema de gerenciamento de identidades que não seja um IdP parceiro ou se usar um IdP parceiro apenas para autenticação SAML.

Pré-requisitos

Para implementar o SCIM usando a API REST, os pré-requisitos gerais para usar o SCIM no GitHub Enterprise Server se aplicam. Consulte a seção "Pré-requisitos" em Configurando o provisionamento do SCIM para gerenciar usuários.

Além disso, os seguintes pré-requisitos são aplicáveis:

• Você deve ter concluído as etapas 1 a 3 em Configurando o provisionamento do SCIM para gerenciar usuários.

  • Você deve usar o personal access token (classic) criado para o usuário de instalação interno para autenticar solicitações para a API REST.

• Para provisionar usuários e grupos com a API REST do GitHub, seu sistema de gerenciamento de identidades deve oferecer suporte ao padrão SCIM 2.0. Para obter mais informações, confira as seguintes RFCs no site do IETF:

  • RFC 7642: Definições, visão geral, conceitos e requisitos
  • RFC 7643: Esquema principal
  • RFC 7644: Protocolo

• Os registros de usuários para os sistemas que você usa em autenticação e provisionamento devem compartilhar um identificador exclusivo e atender aos critérios de correspondência do GitHub. Para saber mais, confira Pontos de extremidade da API REST para SCIM na documentação da API REST.

Melhores práticas para provisionamento do SCIM usando a API REST do GitHub

Ao configurar o sistema de gerenciamento de identidades para provisionamento de usuários ou grupos de usuários no GitHub, o GitHub recomenda enfaticamente que você siga as diretrizes a seguir.

• Garantir que o sistema de gerenciamento de identidades seja a única fonte de operações de gravação
• Enviar solicitações válidas para pontos de extremidade da API REST
• Provisionar usuários antes de provisionar grupos
• Validar o acesso para grupos no GitHub
• Reconhecer a limitação de fluxo no GitHub
• Configurar streaming de log de auditoria

Garantir que o sistema de gerenciamento de identidades seja a única fonte de operações de gravação

Para garantir que seu ambiente tenha uma fonte única de verdade, você só deve fazer gravação programaticamente na API REST para provisionamento do SCIM a partir do seu sistema de gerenciamento de identidades. O GitHub recomenda enfaticamente que apenas um sistema envie solicitações POST, PUT, PATCH ou DELETE à API.

No entanto, você pode recuperar com segurança informações das APIs do GitHub com solicitações GET em scripts ou solicitações ad hoc de um proprietário da empresa.

Enviar solicitações válidas para pontos de extremidade da API REST

Os pontos de extremidade da API REST do GitHub para provisionamento de usuários com SCIM exigem solicitações bem formadas. Leve em consideração as seguintes diretrizes:

• As solicitações que não corresponderem às expectativas da API retornarão um erro 400 Bad Request.
• Os pontos de extremidade da API REST para provisionamento de usuários com SCIM exigem um cabeçalho User-Agent. O GitHub rejeitará solicitações sem esse cabeçalho.

Provisionar usuários antes de provisionar grupos

Os grupos SCIM são eficazes para o gerenciamento do acesso de usuários em escala. Por exemplo, você pode usar grupos no sistema de gerenciamento de identidades para gerenciar a associação da equipe e da organização no GitHub.

Para gerenciar a associação da equipe com grupos no sistema de gerenciamento de identidades, conclua sequencialmente as seguintes etapas:

1. Provisione contas de usuário no GitHub.
2. Provisione um grupo no GitHub.
3. Atualize a associação do grupo no sistema de gerenciamento de identidades.
4. Crie uma equipe no GitHub mapeada para o grupo no sistema de gerenciamento de identidades.

Validar o acesso para grupos no GitHub

Se você gerencia o acesso usando grupos no sistema de gerenciamento de identidades, você pode validar o acesso que os usuários devem obter. Use a API REST para comparar as associações de grupo do sistema com a compreensão desses grupos do GitHub. Para saber mais, confira Pontos de extremidade de API REST para grupos externos e Pontos de extremidade de API REST para equipes na documentação da API REST.

Reconhecer a limitação de fluxo no GitHub

Se um administrador do site tiver habilitado a limitação de fluxo em sua instância, você poderá encontrar erros ao provisionar usuários pela primeira vez. Você pode examinar os logs do IdP para confirmar se houve falha no provisionamento do SCIM ou nas operações de push devido a um erro de limite de taxa. A resposta a uma tentativa de provisionamento com falha dependerá do IdP.

Para saber mais, confira Limites de taxa para a API REST.

Configurar o streaming de log de auditoria

O log de auditoria da empresa exibe detalhes sobre atividades em sua empresa. Você pode usar o log de auditoria para oferecer suporte à configuração do SCIM. Para saber mais, confira Sobre o log de auditoria da sua empresa.

Devido ao volume de eventos nesse log, o GitHub retém os dados por 180 dias. Para garantir que você não perca dados do log de auditoria e veja atividades mais detalhadas no log, a GitHub recomenda configurar o streaming de log de auditoria. Ao transmitir o log de auditoria, você pode, opcionalmente, optar por transmitir eventos para solicitações de API, incluindo solicitações a pontos de extremidade da API REST para provisionamento do SCIM. Para saber mais, confira Como transmitir o log de auditoria para sua empresa.

Provisionar usuários usando a API REST

Para provisionar, listar ou gerenciar usuários, faça solicitações para os pontos de extremidade da API REST a seguir. Você pode ler sobre os pontos de extremidade de API associados na documentação da API REST e ver exemplos de código, além de revisar eventos de log de auditoria associados a cada solicitação.

Para que uma pessoa com uma identidade no sistema de gerenciamento de identidades possa acessar a empresa, você deverá criar o usuário correspondente. Sua empresa não exige uma licença disponível para provisionar uma nova conta de usuário.

• Para obter uma visão geral dos atributos com suporte para usuários, confira SCIM na documentação da API REST.
• Você pode exibir usuários provisionados na interface do usuário do GitHub. Para saber mais, confira Visualizar pessoas na sua empresa.

Ação	Método	Ponto de extremidade e mais informações	Eventos no log de auditoria
Liste todos os usuários provisionados da empresa, que inclui todos os usuários desprovisionados controladamente, definindo active como false.	GET	/scim/v2/Users	N/D
Crie um usuário. A resposta da API inclui um campo id para identificar exclusivamente o usuário.	POST	/scim/v2/Users	external_identity.provision user.create Se a solicitação adicionar a função enterprise_owner, business.add_admin Se a solicitação adicionar a função billing_manager, business.add_billing_manager Se a solicitação for bem-sucedida, external_identity.scim_api_success Se a solicitação apresentar falhas, external_identity.scim_api_failure
Recupere um usuário existente na empresa usando o campo id da solicitação POST enviada para a criação do usuário.	GET	/scim/v2/Users/{scim_user_id}	N/D
Atualize todos os atributos de um usuário existente usando o campo id da solicitação POST enviada para a criação do usuário. Atualize active para false desprovisionar controladamente o usuário ou para true para reativá-lo. Para obter mais informações, confira Desprovisionamento controlado de usuários usando a API REST e Reativar usuários com a API REST.	PUT	/scim/v2/Users/{scim_user_id}	external_identity.update, a menos que esteja realizando desprovisionamento controlado ou reprovisionamento Se a solicitação adicionar a função enterprise_owner, business.add_admin Se a solicitação adicionar billing_manager, business.add_billing_manager Se a solicitação remover a função enterprise_owner, business.remove_admin Se a solicitação remover a função billing_manager, business.remove_billing_manager Se a solicitação for bem-sucedida, external_identity.scim_api_success Se a solicitação apresentar falhas, external_identity.scim_api_failure
Atualize um atributo individual para um usuário existente usando o campo id da solicitação POST enviada para a criação do usuário. Atualize active para false desprovisionar controladamente o usuário ou para true para reativá-lo. Para obter mais informações, confira Desprovisionamento controlado de usuários usando a API REST e Reativar usuários com a API REST.	PATCH	/scim/v2/Users/{scim_user_id}	external_identity.update, a menos que esteja realizando desprovisionamento controlado ou reprovisionamento Se a solicitação adicionar a função enterprise_owner, business.add_admin Se a solicitação adicionar billing_manager, business.add_billing_manager Se a solicitação remover a função enterprise_owner, business.remove_admin Se a solicitação remover a função billing_manager, business.remove_billing_manager Se a solicitação for bem-sucedida, external_identity.scim_api_success Se a solicitação apresentar falhas, external_identity.scim_api_failure
Para excluir completamente um usuário existente, você pode desprovisioná-lo integralmente. Após esse desprovisionamento, não será possível reativar o usuário e você deverá provisioná-lo como um novo usuário. Para obter mais informações, confira Desprovisionamento completo de usuários usando a API REST.	DELETE	/scim/v2/Users/{scim_user_id}	external_identity.deprovision user.remove_email Se a solicitação for bem-sucedida, external_identity.scim_api_success Se a solicitação apresentar falhas, external_identity.scim_api_failure

Desprovisionamento controlado de usuários usando a API REST

Para impedir que um usuário inicie uma sessão para acessar a empresa, você pode desprovisioná-lo controladamente enviando uma solicitação PUT ou PATCH para atualizar o campo active do usuário de false para /scim/v2/Users/{scim_user_id}. Quando você desprovisiona um usuário, o GitHub oculta os campos login e email dos registros do usuário e ele é suspenso.

Quando você desprovisiona um usuário controladamente, o evento external_identity.update não é exibido no log de auditoria. Os seguintes eventos são exibidos no log de auditoria:

• user.suspend
• user.remove_email
• user.rename
• external_identity.deprovision
• Se a solicitação for bem-sucedida, external_identity.scim_api_success
• Se a solicitação falhar, external_identity.scim_api_failure

Você pode exibir todos os usuários suspensos da empresa. Para saber mais, confira Visualizar pessoas na sua empresa.

Reativar usuários com a API REST

Para permitir que um usuário desprovisionado controladamente inicie uma sessão para acessar a empresa, cancele a suspensão do usuário enviando uma solicitação PUT ou PATCH para /scim/v2/Users/{scim_user_id} que atualize o campo active do usuário para true.

Quando você reativa um usuário, o evento external_identity.update não é exibido no log de auditoria. Os seguintes eventos são exibidos no log de auditoria:

• user.unsuspend
• user.remove_email
• user.rename
• external_identity.provision
• Se a solicitação for bem-sucedida, external_identity.scim_api_success
• Se a solicitação falhar, external_identity.scim_api_failure

Desprovisionamento completo de usuários usando a API REST

Para excluir completamente um usuário, você pode desprovisioná-lo enviando uma solicitação DELETE para /scim/v2/Users/{scim_user_id}. A empresa reterá todos os recursos e comentários criados pelo usuário.

Os seguintes eventos ocorrem ao desprovisionar completamente um usuário:

• Os campos login e email dos registros usuário são ocultados.
• O nome de exibição do usuário é definido como uma sequência vazia.
• O GitHub exclui todos os atributos SCIM, e-mails, chaves SSH, personal access tokens e chaves GPG do usuário.
• A conta do usuário no GitHub é suspensa e a autenticação para iniciar sessão na conta falhará.

Para reprovisionar o usuário, use o método POST para criar um novo usuário. O novo usuário pode reutilizar o login do usuário desprovisionado. Se o endereço de email do usuário desprovisionado e do novo usuário for o mesmo, o GitHub atribuirá os commits existentes do Git associados ao endereço de email ao novo usuário. Os recursos e comentários existentes criados pelo usuário original não serão associados ao novo usuário.

Provisionamento de grupos usando a API REST

Para controlar o acesso a repositórios em sua empresa, você pode usar grupos no sistema de gerenciamento de identidades para controlar a associação da organização e da equipe para usuários da empresa. Você pode ler sobre os pontos de extremidade de API associados na documentação da API REST e ver exemplos de código, além de revisar eventos de log de auditoria associados a cada solicitação.

Embora sua empresa não exija uma licença disponível para provisionar uma nova conta de usuário, se você provisionar um grupo que resulte na adição de usuários a uma organização, será necessário ter licenças disponíveis para esses usuários.

• Para obter uma visão geral dos atributos com suporte para grupos, consulte SCIM na documentação da API REST.
• Para obter uma visão geral dos eventos de log de auditoria relacionados a grupos, confira Auditar eventos de log para sua empresa.
• Você pode exibir grupos provisionados na interface do usuário do GitHub. Para saber mais, confira Gerenciando associações de equipes com grupos de provedores de identidade.

Ação	Método	Ponto de extremidade e mais informações	Eventos relacionados no log de auditoria
Liste todos os grupos definidos para a empresa.	GET	/scim/v2/Groups	N/D
Para definir um novo grupo de IdP para a empresa, crie o grupo. A resposta da API inclui um campo id para identificar exclusivamente o grupo.	POST	/scim/v2/Groups	external_group.provision external_group.update_display_name Se a solicitação incluir uma lista de usuários, external_group.add_member Se a solicitação for bem-sucedida, external_group.scim_api_success Se a solicitação apresentar falhas, external_group.scim_api_failure
Recupere um grupo existente na empresa usando id da solicitação POST enviada para a criação do grupo.	GET	/scim/v2/Groups/{scim_group_id}	N/D
Atualize todos os atributos de um grupo existente.	PUT	/scim/v2/Groups/{scim_group_id}	external_group.update Se a solicitação atualizar o nome do grupo, external_group.update_display_name Se a solicitação adicionar um usuário ao grupo, external_group.add_member Se a solicitação remover um usuário do grupo, external_group.remove_member Se a solicitação for bem-sucedida, external_group.scim_api_success Se a solicitação apresentar falhas, external_group.scim_api_failure Podem surgir eventos adicionais no log de auditoria caso o usuário já seja membro da organização com a equipe vinculada ao grupo do IdP. Para saber mais, confira Eventos de log de auditoria adicionais para alterações em grupos do IdP.
Atualize um atributo individual para um grupo existente.	PATCH	/scim/v2/Groups/{scim_group_id}	external_group.update Se a solicitação atualizar o nome do grupo, external_group.update_display_name Se a solicitação adicionar um usuário ao grupo, external_group.add_member Se a solicitação remover um usuário do grupo, external_group.remove_member Se a solicitação for bem-sucedida, external_group.scim_api_success Se a solicitação apresentar falhas, external_group.scim_api_failure Podem surgir eventos adicionais no log de auditoria caso o usuário já seja membro da organização com a equipe vinculada ao grupo do IdP. Para saber mais, confira Eventos de log de auditoria adicionais para alterações em grupos do IdP.
Excluir completamente um grupo existente.	DELETE	/scim/v2/Groups/{scim_group_id}	external_group.delete Se a solicitação excluir um grupo vinculado a uma equipe em uma organização na qual o usuário não possui outra associação de equipe, org.remove_member Se a solicitação excluir um grupo vinculado a uma equipe em uma organização na qual o usuário possui outra associação de equipe, team.remove_member Se a solicitação for bem-sucedida, external_group.scim_api_success Se a solicitação apresentar falhas, external_group.scim_api_failure

Eventos de log de auditoria adicionais para alterações em grupos do IdP

Se você atualizar os membros de um grupo existente usando uma solicitação PUT ou PATCH para /scim/v2/Groups/{scim_group_id}, o GitHub poderá adicionar o usuário à organização ou removê-lo, dependendo da associação atual do usuário na organização. Se o usuário já for membro de pelo menos uma equipe na organização, ele será membro da organização. Se o usuário não for membro de nenhuma equipe na organização, ele provavelmente também não é membro da organização.

Se sua solicitação atualizar um grupo vinculado a uma equipe em uma organização na qual um usuário ainda não é membro, além de external_group.update, os seguintes eventos aparecerão no log de auditoria:

• org.add_member
• Se a solicitação adicionar um usuário a um grupo vinculado a uma equipe em uma organização da qual o usuário ainda não é membro, org.add_member
• Se a solicitação adicionar o usuário a um grupo vinculado a uma equipe em uma organização, team.add_member

Se sua solicitação atualizar um grupo vinculado a uma equipe em uma organização na qual um usuário já é membro, além de external_group.update, os seguintes eventos aparecerão no log de auditoria:

• Se a solicitação remover o usuário de um grupo vinculado a uma equipe em uma organização e a equipe não for a última equipe da organização da qual o usuário é membro, team.remove_member
• Se a solicitação remover um usuário de um grupo vinculado à última equipe em uma organização da qual o usuário já é membro, org.remove_member

Solução de problemas de provisionamento do SCIM

• Se as suas solicitações à API REST tiverem limitação fluxo, saiba mais em Reconhecer a limitação de fluxo do GitHub.

• Caso habilite o streaming de log de auditoria e eventos de fluxo para solicitações de API, você poderá revisar todas as solicitações para os pontos de extremidade da API REST do provisionamento do SCIM filtrando eventos dos controladores EnterpriseUsersScim ou EnterpriseGroupsScim.

• Se uma solicitação do SCIM falhar e você não conseguir determinar a causa, verifique o status do sistema de gerenciamento de identidades para garantir que os serviços estejam disponíveis.

• Se uma solicitação de provisionamento de um usuário falhar com o erro 400 e a mensagem de erro no log do sistema de gerenciamento de identidades indicar problemas com a propriedade da conta ou a formatação do nome de usuário, consulte Considerações de nome de usuário para autenticação externa.

• Após a autenticação bem-sucedida, o GitHub vincula o usuário autenticado a uma identidade provisionada pelo SCIM. Os identificadores exclusivos para autenticação e provisionamento devem corresponder. Para obter mais informações, consulte Pontos de extremidade da API REST para SCIM.

• Se você gerenciar o acesso usando grupos no sistema de gerenciamento de identidades, poderá solucionar problemas usando a API REST ou a interface do usuário Web do GitHub.

  • Use a API REST para comparar as associações de grupo do sistema de gerenciamento de identidades com a compreensão desses grupos do GitHub. Confira Pontos de extremidade de API REST para grupos externos e Pontos de extremidade de API REST para equipes.
  • Para obter mais informações sobre como solucionar problemas usando a interface do usuário Web, consulte Solucionar problemas de subscrição de equipe com grupos de provedores de identidade.

Para obter sugestões adicionais de solução de problemas, confira Solução de problemas de gerenciamento de identidade e acesso da empresa.