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

Sobre o provisionamento do SCIM em 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, GitHub recomenda que você use um único aplicativo IdP de parceiro para autenticação e provisionamento. Para obter mais informações e uma lista de IdPs de parceiros, consulte Sobre o provisionamento de usuário com o SCIM no GitHub Enterprise Server.

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

Usar outros sistemas de gerenciamento de identidades

Se você não puder usar um IdP parceiro único 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 autenticação usando o SAML e o gerenciamento do ciclo de vida do usuário usando o SCIM e devem seguir GitHubas diretrizes de integração.

O GitHub não oferece suporte expresso à mistura de IdPs de parceiros para autenticação e provisionamento e não testa todos os sistemas de gerenciamento de identidades. A equipe de suporte do GitHub talvez não consiga ajudar você em problemas relacionados a sistemas misturados ou não testados. Se você precisar de ajuda, consulte a documentação do sistema, a equipe de suporte ou outros recursos.

Pré-requisitos

Para implementar o SCIM usando a API REST, os pré-requisitos gerais para usar o SCIM em GitHub Enterprise Server se aplicam. Consulte a seção "Pré-requisitos" em Configuração do provisionamento 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 Configuração do provisionamento 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 na 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ário para os sistemas que você usa para autenticação e provisionamento devem compartilhar um identificador exclusivo e atender aos GitHubcritérios correspondentes. Para saber mais, confira Pontos de extremidade da API REST para SCIM na documentação da API REST.

Práticas recomendadas para provisionamento SCIM com a API REST de GitHub

Ao configurar seu sistema de gerenciamento de identidade para provisionar usuários ou grupos de usuários no GitHub, GitHub recomenda fortemente 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 endpoints da API REST
• Provisionar usuários antes de provisionar grupos
• Validar o acesso para grupos em GitHub
• Entender os limites de taxa em GitHub
• Configurar o streaming de log de auditoria
• Limitar o escopo do token SCIM
• Entender os efeitos do desprovisionamento

Garanta que o sistema de gestão de identidades seja a única fonte de operações de escrita

Para garantir que seu ambiente tenha uma fonte única de verdade, você deve apenas escrever programaticamente na API REST para provisionamento SCIM a partir do seu sistema de gerenciamento de identidades. GitHub recomenda fortemente 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 de GitHub com solicitações GET em scripts ou por meio de solicitações ad hoc feitas por um proprietário da empresa.

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

Os endpoints da API REST do GitHub para provisionamento de usuários com SCIM exigem requisiçõ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. 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 seu sistema de gerenciamento de identidades para gerenciar a associação a equipes e organizações no GitHub.

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

1. Provisionar contas de usuário em GitHub.
2. Criar um grupo em GitHub.
3. Atualize a associação do grupo no sistema de gerenciamento de identidades.
4. Crie uma equipe no GitHub que esteja mapeada para o grupo no seu sistema de gerenciamento de identidade.

Validar o acesso para grupos em 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. Você pode usar a API REST para comparar as associações do seu sistema a grupos com o entendimento do GitHub sobre esses grupos. Para saber mais, confira Endpoints de API REST para grupos externos e Endpoints de API REST para equipes na documentação da API REST.

Entender os limites de taxa em GitHub

Se um administrador do site tiver habilitado os limites de taxa 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 Log de auditoria para uma empresa.

Devido ao volume de eventos neste log, GitHub mantém os dados por 180 dias. Para garantir que você não perca dados de log de auditoria e exiba atividades mais granulares no log de auditoria, GitHub recomenda que você configure 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.

Limitar o escopo do token SCIM

Para melhorar a segurança, recomendamos usar um personal access token (classic) com apenas o escopo scim:enterprise para limitar o acesso do token aos endpoints da API REST necessários para realizar chamadas SCIM.

Se você usa atualmente um token com o escopo admin:enterprise, lembre-se de que esse token permite acesso a todas as ações na empresa. Você pode trocar seu token por um novo token apenas com o escopo scim:enterprise sem interrupção.

Entender os efeitos do desprovisionamento

Para remover o acesso de um usuário ao GitHub, você pode enviar ao seu provedor SCIM uma solicitação de "desprovisionamento parcial" ou de "desprovisionamento completo". O desprovisionamento forçado é uma ação irreversível que suspende permanentemente a conta do usuário GitHub.

Antes de implementar uma integração de API, entenda os tipos de desprovisionamento e os seus efeitos. Para saber mais sobre os diferentes tipos de desprovisionamento, seus efeitos e os eventos de log de auditoria gerados, confira Desprovisionar e restabelecer usuários com SCIM.

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, ver exemplos de código e 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 visualizar usuários provisionados na interface do usuário GitHub. Para saber mais, confira Visualizar pessoas na sua empresa.
• Administradores empresariais com acesso à CLI podem exportar um CSV completo de identidades de usuário provisionadas por SCIM usando a ferramenta ghe-scim-identities-csv.

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 para desprovisionamento controlado do usuário ou 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 para desprovisionamento controlado do usuário ou 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 suspender de forma permanente um usuário existente, você pode desprovisioná-lo. 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 rigoroso de usuários com 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 suave 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ê faz o desprovisionamento parcial de um usuário, GitHub ofusca os campos login e email do registro do usuário, e o usuário é suspenso.

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.

Desprovisionamento completo de usuários usando a API REST

Você pode desprovisionar o usuário 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.

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, ver exemplos de código e 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 resulta na adição de usuários a uma organização, você deverá 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 visualizar grupos provisionados na GitHub interface do usuário. 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}, GitHub poderá adicionar o usuário à organização ou removê-lo da organização, dependendo de o usuário pertencer ou não atualmente à 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 suas solicitações para a API REST forem limitadas por taxa, você poderá saber mais em Entender os limites de taxa em GitHub.

• Todas as solicitações SCIM que GitHub recebe, com exceção das requisições HTTP GET bem-sucedidas, gerarão um evento de log de auditoria. Esses logs conterão informações úteis sobre o resultado da solicitação, informações de conteúdo e erros. Esses logs podem ser usados para determinar se uma solicitação SCIM foi recebida ou não GitHub e solucionar problemas de falhas de API.

  • Para determinar se um usuário foi provisionado, você pode usar a seguinte consulta do log de auditoria: action:external_identity.provision user:USERNAME
  • Se você não encontrar um usuário usando a consulta acima, poderá pesquisar eventos action:external_identity.scim_api_failure na data em que esperava ter recebido a solicitação.

• Se uma solicitação 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, GitHub vincula o usuário que se autenticou 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 em seu sistema de gerenciamento de identidade, poderá solucionar problemas usando a API REST ou a interface do usuário da Web para GitHub.

  • Você pode usar a API REST para comparar as participações em grupos do seu sistema de gerenciamento de identidade com a interpretação que GitHub faz desses grupos. Confira Endpoints de API REST para grupos externos e Endpoints 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.