Configurar autenticação e provisionamento com PingFederate

Quando você usa os Enterprise Managed Users, o SSO do SAML controla e protege o acesso a recursos corporativos, como repositórios, problemas e pull requests. O SCIM cria automaticamente contas de usuário e gerencia o acesso à sua empresa quando você faz alterações no IdP. Você também pode sincronizar equipes no GitHub com grupos no seu IdP. Para obter mais informações, confira “Sobre os Enterprise Managed Users”.

Visão geral

Este guia ajudará você a configurar a autenticação SAML e o provisionamento do SCIM para o GitHub no PingFederate.

Antes de começar, observe o seguinte:

• Este guia é baseado no PingFederate versão 12.1. As instruções podem variar para outras versões.
• Este guia fornece as etapas mínimas para configurar uma configuração de trabalho. Como seu diretório de identidade pode estar conectado ao PingFederate de forma diferente, você precisará escolher os atributos de dados corretos para SAML e SCIM com base no que está disponível no armazenamento de dados de backup.

Pré-requisitos

Se estiver configurando o provisionamento SCIM para uma nova empresa, certifique-se de concluir todas as etapas anteriores no processo de configuração inicial. Confira "Introdução aos Enterprise Managed Users".

Além disso:

• Você deve ter instalado o "conector EMU do GitHub" no PingFederate. Para baixar e instalar o conector, consulte Instalar o provisionador na documentação do PingIdentity.
• Para provisionar usuários com o SCIM, você precisa usar um servidor LDAP como o armazenamento de dados de backup.
• Talvez seja necessário configurar o firewall no PingFederate para permitir conexões de saída para os pontos de extremidade do SCIM no GitHub:
  • Para o GitHub.com: https://api.github.com/scim/v2/enterprises/ENTERPRISE
  • Para o GHE.com: https://api.SUBDOMAIN.ghe.com/scim/v2/enterprises/SUBDOMAIN
• O "modo de provisionamento" do PingFederate deve ser definido como um valor que permita o provisionamento do SCIM. Consulte a seção "Antes de começar" no guia Definindo configurações de provisionamento de saída do PingIdentity.
• Durante este procedimento, você precisará carregar um certificado X509 no PingFederate. Talvez você queira criar e armazenar o certificado antes de continuar. Você também precisará da senha de desafio para o certificado. Consulte a seção "Exemplo de criação de um certificado X509" mais adiante neste artigo.
• Durante esse procedimento, você precisará carregar um arquivo de metadados SAML no PingFederate. Se você estiver configurando uma empresa que usa o residência de dados no GHE.com, será mais fácil criar esse arquivo antes de começar. Confira “Como criar um arquivo de metadados SAML para o GHE.com”.

1. Configure o SAML

Nesta seção, você criará um conector SAML no PingFederate, configurará uma instância do adaptador LDAP do IdP e gerenciará a saída SAML do adaptador do IdP.

1. Criar um adaptador SAML
2. Configurar uma instância do adaptador LDAP do IdP
3. Gerenciar a saída SAML do adaptador do IdP

Antes de iniciar esta seção, verifique se você seguiu as etapas anteriores descritas em “Introdução aos Enterprise Managed Users”.

Criar um adaptador SAML

1. Abra o console administrativo do PingFederate.

2. Clique em Aplicativos no cabeçalho e, em seguida, clique em Conexões SP na barra lateral esquerda.

3. Clique em Usar um modelo para esta conexão e selecione o "GitHub EMU Connector" na lista suspensa "Modelo de Conexão".

   Note

   Se você não vir essa opção, o conector EMU do GitHub não foi instalado. Se precisar de ajuda, contate o representante da Ping.

4. Para preencher alguns campos na configuração do PingFederate, você carregará um arquivo XML contendo metadados SAML da sua empresa. Para localizar o arquivo:

   • Se estiver configurando uma empresa no GitHub.com, você encontrará esse arquivo em um arquivo ZIP anexado ao “GitHub EMU Connector” no PingFederate.
   • Se estiver configurando uma empresa no GHE.com, você criará o arquivo manualmente. Confira “Como criar um arquivo de metadados SAML para o GHE.com”.

5. Na página “Conexão do SP” do PingFederate, carregue o arquivo da etapa anterior como o arquivo de metadados.

6. Vá para a guia "Tipo de conexão".

7. Selecione Perfis de SSO do navegador e desmarque Provisionamento de saída (isso será habilitado posteriormente).

8. Clique em Avançar.

9. Na guia "Opções de conexão", certifique-se de que apenas a opção SSO do navegador esteja selecionada.

10. Clique em Avançar.

11. Na guia "Informações Gerais", insira os detalhes a seguir.

    • “ID da entidade do parceiro”: a URL do host do GitHub (https://github.com ou https://SUBDOMAIN.ghe.com)
    • "Nome da Conexão": um nome descritivo para sua conexão SP no PingFederate
    • “URL base”: a URL do host do GitHub (https://github.com ou https://SUBDOMAIN.ghe.com)
    • "Log de Transações": Padrão
    • Os outros campos devem ser deixados em branco.

12. Clique em Avançar.

13. Clique em Configurar SSO do Navegador.

14. Clique em Configurar Criação de Declaração.

15. Na guia "Mapeamento da Origem da Autenticação", clique em Mapear Nova Instância do Adaptador.

16. Na guia "Instância do Adaptador", clique em Gerenciar Instâncias do Adaptador.

17. Clique em Criar Nova Instância.

Configurar uma instância do adaptador LDAP do IdP

1. Na página "Criar Instância do Adaptador" no PingFederate, na guia "Tipo", insira os detalhes a seguir.

   • "Nome da Instância": Um nome para identificar a instância, como pfghadapter
   • "ID da instância": um ID para a instância, como pfghadapter
   • "Tipo": Adaptador de IDP em forma HTML
   • "Instância Pai": Nenhuma

2. Clique em Avançar.

3. Na guia "Adaptador do IDP", na parte inferior da página, clique em Gerenciar Validadores de Credenciais de Senha.

4. Clique em Criar Nova Instância.

5. Na guia "Tipo", insira os detalhes a seguir.

   • "Nome da Instância": Um nome para identificar a instância, como pfghdocscv
   • "ID da instância": um ID para a instância, como pfghdocscv
   • "Tipo": Validador de Credenciais de Senha do Nome de usuário LDAP
   • "Instância Pai": Nenhuma

6. Clique em Avançar.

7. Na guia "Configuração da Instância", clique em Gerenciar Armazenamentos de Dados.

8. Clique em Adicionar Novo Armazenamento de Dados.

9. Na guia "Tipo do Armazenamento de Dados", insira os detalhes a seguir.

   • "Nome da Instância": qualquer valor exclusivo, como pfghdocsds
   • "Tipo": Diretório (LDAP)
   • "Valores de Máscara no Log": Desmarcado

10. Clique em Avançar.

11. Na guia "Configuração LDAP", configure os detalhes do servidor LDAP.

12. Clique em Testar Conexão. Você deverá ver a mensagem "O teste de conectividade foi bem-sucedido".

13. Na parte inferior da página, clique em Avançado.

14. Clique na guia "Atributos Binários LDAP" e adicione guidAttribute e objectGUID como atributos.

15. Clique em Concluído. Você deve estar de volta à guia "Configuração LDAP".

16. Clique em Avançar e em Salvar.

17. Na guia "Gerenciar Armazenamentos de Dados", clique em Concluído.

18. Na guia "Configuração da Instância", insira os detalhes a seguir.

    • "Armazenamento de Dados LDAP": o nome do armazenamento de dados que você criou acima
    • "Base de Pesquisa": o local no diretório onde você deseja que as pesquisas LDAP comecem
    • "Filtro de Pesquisa": um filtro que garante que o nome de usuário inserido pelo usuário ao iniciar sessão corresponda a um campo no servidor LDAP (por exemplo: sAMAccountName=${username})
    • "Escopo da Pesquisa": Subárvore
    • "Correspondência com Diferenciação de Maiúsculas e Minúsculas": selecionada

19. Clique em Avançar, em Avançar novamente e em Salvar.

Gerenciar a saída SAML do adaptador do IdP

1. Na página "Gerenciar Validadores de Credenciais de Senha", clique em Concluído.

2. Na guia "Adaptador do IDP", insira os detalhes a seguir.

   • "Instância do Validador de Credenciais de Senha": o nome da instância do validador que você criou acima (por exemplo pfghdocscv). Clique em Atualizar para finalizar sua seleção.
   • Todos os outros campos podem ser mantidos nos valores padrão ou modificados de acordo com seus requisitos.

3. Clique em Avançar e, em seguida, em Avançar novamente.

4. Na guia "Adaptador do Adaptador", insira os detalhes a seguir.

   • "Atributo de Chave de Usuário Exclusiva": username

   • Ao lado do atributo username, selecione "Pseudônimo".

   Note

   Essa etapa é importante. O atributo do adaptador é usado para identificar exclusivamente um usuário no GitHub durante o provisionamento do SCIM.

5. Clique em Avançar e, em seguida, em Avançar novamente.

6. Revise suas configurações na página de resumo e, em seguida, clique em Salvar.

7. Na guia "Adaptadores de IdP", você deve ver o adaptador que acabou de criar. Clique em Concluído.

8. Na guia "Instância do Adaptador", no menu suspenso "Instância do Adaptador", selecione o adaptador que acabou de criar.

9. Clique em Avançar.

10. Na guia "Método de Mapeamento", selecione Usar apenas os Valores de Contrato do Adaptador na Declaração SAML (outras seleções podem funcionar, mas não foram confirmadas).

11. Clique em Avançar.

12. Na guia "Cumprimento do Contrato de Atributo", mapeie o SAML_SUBJECT a "Adaptador" como a origem e username como o valor.

    Note

    Essa etapa é importante. O SAML_SUBJECT normalizado precisará corresponder aos nomes de usuário normalizados dos usuários provisionados pelo SCIM.

13. Clique em Avançar, em Avançar novamente e em Concluído.

14. Você deve estar de volta à guia "Mapeamento da Origem da Autenticação" e a seção "Nome da Instância do Adaptador" deve conter a instância do adaptador que você acabou de criar.

15. Clique em Avançar.

16. Na guia “Configurações de Protocolo”, selecione Definir Configurações de Protocolo.

17. Em “URL do Serviço de Consumidor de Declaração”, adicione uma linha com os seguintes detalhes:

    • “Padrão” selecionado
    • “Índice”: 0
    • “Associação”: POST
    • “URL do ponto de extremidade”: /enterprises/ENTERPRISE/saml/consume, em que ENTERPRISE é o seu nome corporativo ou subdomínio

18. Clique em Avançar.

19. Na guia “Associações do SAML Permitidas”, garanta que apenas “POST” e “REDIRECT” estejam selecionados.

20. Clique em Avançar.

21. Na página “Política de Assinatura”, garanta que apenas “SIGN RESPONSE AS REQUIRED” esteja selecionado.

22. Clique em Avançar.

23. Na guia “Política de Criptografia”, garanta que apenas “NONE” esteja selecionado.

24. Clique em Avançar.

25. Clique em Save (Salvar).

26. Clique em Avançar e Concluído até chegar à guia "Credenciais".

27. Na guia "Credenciais", clique em Configurar Credenciais e, em seguida, clique em Gerenciar Certificados.

28. Na página "Gerenciamento de Certificados", clique em Importar e carregue um certificado X509 (para obter ajuda, consulte a seção "Exemplo de criação de um certificado X509").

29. Para a "Senha", use a senha de desafio do certificado.

30. Clique em Avançar e em Salvar.

31. Na guia "Gerenciamento de Certificados", você deverá ver o certificado que acabou de importar. Clique em Concluído.

32. Na guia "Configurações de Assinatura Digital":

    • Selecione o certificado que você acabou de criar para "Certificado de Autenticação".
    • Você pode deixar o certificado secundário em branco e a caixa de seleção "Incluir o certificado na assinatura" desmarcada.
    • O algoritmo de assinatura deve ser "RSA SHA256".

33. Clique em Avançar, em Concluído e, em seguida, em Avançar.

34. Na guia "Resumo", ative a chave para "Ponto de extremidade do aplicativo SSO".

35. Clique em Save (Salvar). Você deverá ser levado de volta para a lista de conexões da controladora de armazenamento, onde deve ver sua conexão da controladora de armazenamento recém-criada.

Coletar informações para sua configuração do SAML

Você precisará de alguns detalhes do PingFederate para configurar o SAML no GitHub.

1. Na página "Conexões do SP", na linha da nova conexão, clique em Selecionar ação e, em seguida, em Exportar Metadados.
2. Na guia "Assinatura de Metadados", na linha da nova conexão, selecione o certificado de autenticação criado acima. Para baixar o certificado, clique em Avançar e, em seguida, clique em Exportar.
3. No PingFederate, clique em Sistema no cabeçalho, em Servidor e em Configurações de Protocolo. Verifique se o SAML 2.0 ENTITY ID está definido. Anote isso, pois você precisará dele no campo “Emissor” das configurações do SAML do GitHub.
4. Abra o arquivo de metadados que você baixou e prepare-o para as próximas etapas.

Configurar o GitHub

1. Entre no GitHub como o usuário de instalação da sua empresa.

2. Habilite o SAML nas configurações da empresa. Consulte "Configurar o logon único SAML para usuários gerenciados pela empresa".

3. Insira os valores a seguir do arquivo de metadados SAML da seção anterior.

   • Para a "URL de logon único", use o valor location do campo <md: SingleSignOnService>. Esse valor deve ser uma URL terminada em /idp/SSO.saml2.
   • Para o "Emissor", use o valor entityId do campo <md: EntityDescriptor> (uma URL).

4. Para o "Certificado de verificação", carregue o arquivo de certificado X509 que você criou anteriormente.

5. Clique em Salvar alterações.

2. Configure o SCIM

Nesta seção, você definirá as configurações do SCIM e o mapeamento de atributos no PingFederate.

1. Definir configurações do SCIM
2. Mapeie campos LDAP no SCIM
3. Conclua a configuração e o teste

Antes de iniciar esta seção, verifique se você seguiu as etapas anteriores descritas em “Introdução aos Enterprise Managed Users”.

Definir configurações do SCIM

1. Volte para a página "Conexões do SP" no PingFederate e selecione a conexão do SP que você criou anteriormente.

2. Clique na guia "Tipo da Conexão".

3. Selecione Provisionamento de Saída.

4. Certifique-se de que Perfis de SSO do Navegador esteja selecionada.

5. Clique em Avançar até chegar à guia "Provisionamento de Saída". Em seguida, clique em Configurar Provisionamento.

6. Na guia "Destino", insira os detalhes a seguir.

   • “URL base”: https://api.github.com/scim/v2/enterprises/{enterprise}/ ou https://api.SUBDOMAIN.ghe.com/scim/v2/enterprises/SUBDOMAIN
   • “Token de acesso”: o personal access token (classic) criado para o usuário de configuração

7. Clique em Avançar.

8. Na guia "Gerenciar Canal", clique em Criar e insira um nome de canal exclusivo, como pfghscim.

9. Clique em Avançar.

10. Na guia "Origem", escolha o armazenamento de dados que você criou anteriormente.

11. Clique em Avançar.

12. Na guia "Configurações da Origem", mantenha todas as configurações padrão. Outras configurações provavelmente funcionarão, mas não foram confirmadas.

13. Clique em Avançar.

14. Na guia "Local de Origem", configure de onde em seu servidor LDAP você gostaria que os usuários provisionados viessem. Isso pode variar de acordo com sua configuração e necessidades. Após a configuração, clique em Avançar.

Mapeie campos LDAP no SCIM

Na guia "Mapeamento de Atributos", você precisará mapear campos do seu servidor LDAP em campos do SCIM. Confira a lista a seguir para obter os campos do SCIM com suporte do GitHub e os valores esperados em cada um.

• Nome de usuário: ele será normalizado e usado como o nome de usuário do GitHub para o usuário provisionado. Confira "Considerações de nome de usuário para autenticação externa". Isso deve corresponder à normalização do assunto enviado com a declaração SAML que você configurou com a propriedade SAML_SUBJECT no PingFederate.
• Email: um campo que contém o endereço de e-mail do usuário.
• Nome de Exibição: um nome legível para o usuário.
• Nome Formatado: o nome completo do usuário, incluindo todos os nomes do meio, títulos e sufixos, formatados para exibição.
• Nome: o primeiro nome do usuário.
• Sobrenome: o sobrenome do usuário.
• ID Externo: esse identificador é gerado por um provedor IdP.
• Funções: esse campo deve conter uma cadeia de caracteres que represente a função pretendida do usuário no GitHub. As funções válidas são enterprise_owner, user, billing_manager e guest_collaborator.

Após terminar de definir as configurações, clique em Avançar.

Conclua a configuração e o teste

1. Na guia "Ativação e Resumo", selecione Ativo em "Status do Canal".
2. Na guia "Gerenciar Canais", clique em Concluído.
3. Na guia "Provisionamento da Saída", clique em Salvar. O SCIM agora está configurado e habilitado.
4. Aguarde alguns minutos para que o provisionamento seja executado. Depois, abra uma nova janela privada do navegador e navegue até o GitHub.
5. Clique em Iniciar Sessão com SSO. Você deverá ser redirecionado para a página de login do PingFederate.
6. Você também poderá entrar com as credenciais de um usuário no servidor LDAP que tenha sido provisionado no GitHub.

O provisionamento do PingFederate lida com usuários e grupos de forma independente. Os usuários devem ser atribuídos diretamente para serem provisionados. Os usuários que estão em um grupo atribuído, mas não atribuídos diretamente, não serão provisionados.

Exemplo de criação de um certificado X509

Há várias maneiras de criar um certificado X509. Aqui está um exemplo que pode atender às suas necessidades.

1. Em uma janela de terminal, verifique se o OpenSSL está instalado executando openssl version. Se ainda não estiver, instale-o.

2. Gere uma chave privada usando o comando a seguir.

   Shell

   openssl req -nodes -sha256 -newkey rsa:2048 -keyout MyPrivateKey.key -out MyCertificateRequest.csr
   

   Insira as informações necessárias e anote a senha de desafio que você criou.

3. Para garantir que a chave tenha sido criada, execute o comando a seguir. Um arquivo chamado MyPrivateKey.key deve ser listado na saída do comando.

   Shell

   ls | grep MyPrivateKey.key
   

4. Gere o certificado usando o comando a seguir.

   Shell

   openssl x509 -req -days 365 -sha256 -in MyCertificateRequest.csr -signkey MyPrivateKey.key -out pfgh256.crt
   

5. Para garantir que o certificado tenha sido criado, execute o comando a seguir. Um arquivo chamado pfgh256.crt deve ser listado na saída do comando.

   Shell

   ls | grep pfgh256.crt
   

6. Exporte um arquivo PKCS nº 12 usando o comando a seguir. Este é o arquivo do qual você deve fazer upload para o PingFederate.

   Shell

   openssl pkcs12 -export -in pfgh256.crt -inkey MyPrivateKey.key -out pfgh256.p12
   

7. Para garantir que o arquivo foi exportado, execute o comando a seguir. Um arquivo chamado pfgh256.p12 deve ser listado na saída do comando.

   Shell

   ls | grep pfgh256.p12
   

Como criar um arquivo de metadados SAML para o GHE.com

Como alguns valores variam do arquivo de metadados que o PingFederate fornece para o GitHub.com, você criará um arquivo XML para os metadados SAML da sua empresa manualmente.

1. Copie o XML a seguir em um editor de texto.

   XML

   <?xml version="1.0"?>
   <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
     entityID="https://SUBDOMAIN.ghe.com/enterprises/SUBDOMAIN" cacheDuration="PT1440M">
     <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"
       AuthnRequestsSigned="false" WantAssertionsSigned="false">
       <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
       <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
         Location="https://SUBDOMAIN.ghe.com/enterprises/SUBDOMAIN/saml/consume" isDefault="true"
         index="0"/>
     </md:SPSSODescriptor>
   </md:EntityDescriptor>
   

2. Substitua todas as instâncias de SUBDOMAIN pelo subdomínio do GHE.com da sua empresa. Por exemplo: octocorp.

3. Salve o arquivo como um arquivo XML.

4. Volte às instruções em “Como criar um adaptador do SAML”.