Note
Atualmente, o SCIM para o GitHub Enterprise Server está em beta e sujeito a alterações. A recomendação do GitHub é para, primeiro, realizar testes em uma instância de preparo. Confira Configurar uma instância de preparo.
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
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:
-
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
- Limitar o escopo do token SCIM
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.
Warning
Se você usar um IdP parceiro para provisionamento do SCIM, o aplicativo no IdP deverá ser o único sistema que faz solicitações de gravação à API. Se você fizer solicitações ad hoc usando os métodos POST, PUT, PATCH ou DELETE, tentativas posteriores de sincronização falharão e o provisionamento não funcionará adequadamente para sua 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:
- Provisione contas de usuário no GitHub.
- Provisione um grupo no GitHub.
- Atualize a associação do grupo no sistema de gerenciamento de identidades.
- 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.
Limitar o escopo do token SCIM
Para uma melhor postura de segurança, recomendamos usar um personal access token (classic) apenas com o escopo scim:enterprise para limitar o acesso do token aos pontos de extremidade da API REST necessários para fazer 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.
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 |
|
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} |
|
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} |
|
| 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} |
|
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.suspenduser.remove_emailuser.renameexternal_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.unsuspenduser.remove_emailuser.renameexternal_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
logineemaildos 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 |
|
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} |
|
| Atualize um atributo individual para um grupo existente. | PATCH | /scim/v2/Groups/{scim_group_id} |
|
| Excluir completamente um grupo existente. | DELETE | /scim/v2/Groups/{scim_group_id} |
|
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
EnterpriseUsersScimouEnterpriseGroupsScim. -
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
400e 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.