Note
SCIM para GitHub está atualmente 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".
Quando você usa um IdP para IAM em GitHub Enterprise Server, o SSO SAML controla e protege o acesso a recursos corporativos, como repositórios, problemas e solicitações de pull. O SCIM cria automaticamente contas de usuários e gerencia o acesso para sua instância do GitHub Enterprise Server quando você faz alterações no seu IdP. Você também pode sincronizar equipes em GitHub Enterprise Server com grupos em seu IdP. Para obter mais informações, consulte "Sobre o provisionamento de usuários com o SCIM no GitHub Enterprise Server".
Visão geral
Este guia ajudará você a configurar a autenticação SAML e o provisionamento do SCIM para o GitHub Enterprise Server no PingFederate.
Antes de começar, observe o seguinte:
- O uso do PingFederate como IdP para GitHub Enterprise Server está em beta. Entre em contato com a equipe da sua conta para fornecer feedback.
- Este guia é baseado no PingFederate versão 12.1. As instruções podem variar para outras versões.
- Este guia pressupõe que você esteja usando um servidor LDAP como armazenamento de dados de backup. Os armazenamentos de dados JDBC devem funcionar, mas as instruções podem variar um pouco.
- 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
Os pré-requisitos gerais para usar o SCIM no GitHub Enterprise Server são aplicáveis. Consulte a seção "Pré-requisitos" em "Configurando o provisionamento do SCIM para gerenciar usuários".
Além disso:
- Para configurar o SCIM, você deve ter concluído as etapas 1 a 4 em "Configurando o provisionamento do SCIM para gerenciar usuários".
- Você precisará do personal access token (classic) criado para que o usuário de configuração autentique as solicitações do PingFederate.
- 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.
- Talvez seja necessário configurar o firewall no PingFederate para permitir conexões de saída com o endpoint
https://HOSTNAME/api/v3/scim/v2
em sua instância do GitHub Enterprise Server.
- Talvez seja necessário configurar o firewall no PingFederate para permitir conexões de saída com o endpoint
- 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.
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.
- Criar um adaptador SAML
- Configurar uma instância do adaptador LDAP do IdP
- Gerenciar a saída SAML do adaptador do IdP
Antes de iniciar esta seção, certifique-se de ter seguido as etapas 1 e 2 em "Configurando o provisionamento do SCIM para gerenciar usuários".
Criar um adaptador SAML
-
Abra o console administrativo do PingFederate.
-
Clique em Aplicativos no cabeçalho e, em seguida, clique em Conexões SP na barra lateral esquerda.
-
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.
-
Em uma nova guia, inicie sessão na instância do GitHub Enterprise Server como o usuário de configuração interno e navegue até
https://HOSTNAME/saml/metadata
. Baixe a página como um arquivo XML. -
Na página "Conexão SP" do PingFederate, carregue o arquivo da etapa anterior como o arquivo de metadados. Certifique-se de fazer isso em até 5 minutos após o download do arquivo.
-
Vá para a guia "Tipo de conexão".
-
Selecione Perfis de SSO do navegador e desmarque Provisionamento de saída (isso será habilitado posteriormente).
-
Clique em Avançar.
-
Na guia "Opções de conexão", certifique-se de que apenas a opção SSO do navegador esteja selecionada.
-
Clique em Avançar.
-
Na guia "Informações Gerais", insira os detalhes a seguir.
- "ID da Entidade do Parceiro": a URL do host do GitHub Enterprise Server (
https://HOSTNAME.com
) - "Nome da Conexão": um nome descritivo para sua conexão SP no PingFederate
- "URL Base": a URL do host do GitHub Enterprise Server (
https://HOSTNAME.com
) - "Log de Transações": Padrão
- Os outros campos devem ser deixados em branco.
- "ID da Entidade do Parceiro": a URL do host do GitHub Enterprise Server (
-
Clique em Avançar.
-
Clique em Configurar SSO do Navegador.
-
Clique em Configurar Criação de Declaração.
-
Na guia "Mapeamento da Origem da Autenticação", clique em Mapear Nova Instância do Adaptador.
-
Na guia "Instância do Adaptador", clique em Gerenciar Instâncias do Adaptador.
-
Clique em Criar Nova Instância.
Configurar uma instância do adaptador LDAP do IdP
Note
Esta seção se aplica se você usa um servidor LDAP. Se você não usa LDAP, precisará se conectar ao adaptador usando as configurações apropriadas para seus requisitos.
-
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
- "Nome da Instância": Um nome para identificar a instância, como
-
Clique em Avançar.
-
Na guia "Adaptador do IDP", na parte inferior da página, clique em Gerenciar Validadores de Credenciais de Senha.
-
Clique em Criar Nova Instância.
-
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
- "Nome da Instância": Um nome para identificar a instância, como
-
Clique em Avançar.
-
Na guia "Configuração da Instância", clique em Gerenciar Armazenamentos de Dados.
-
Clique em Adicionar Novo Armazenamento de Dados.
-
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
- "Nome da Instância": qualquer valor exclusivo, como
-
Clique em Avançar.
-
Na guia "Configuração LDAP", configure os detalhes do servidor LDAP.
-
Clique em Testar Conexão. Você deverá ver a mensagem "O teste de conectividade foi bem-sucedido".
-
Na parte inferior da página, clique em Avançado.
-
Clique na guia "Atributos Binários LDAP" e adicione
guidAttribute
eobjectGUID
como atributos. -
Clique em Concluído. Você deve estar de volta à guia "Configuração LDAP".
-
Clique em Avançar e em Salvar.
-
Na guia "Gerenciar Armazenamentos de Dados", clique em Concluído.
-
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
-
Clique em Avançar, em Avançar novamente e em Salvar.
Gerenciar a saída SAML do adaptador do IdP
-
Na página "Gerenciar Validadores de Credenciais de Senha", clique em Concluído.
-
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.
- "Instância do Validador de Credenciais de Senha": o nome da instância do validador que você criou acima (por exemplo
-
Clique em Avançar e, em seguida, em Avançar novamente.
-
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 em sua instância durante o provisionamento do SCIM.
-
-
Clique em Avançar e, em seguida, em Avançar novamente.
-
Revise suas configurações na página de resumo e, em seguida, clique em Salvar.
-
Na guia "Adaptadores de IdP", você deve ver o adaptador que acabou de criar. Clique em Concluído.
-
Na guia "Instância do Adaptador", no menu suspenso "Instância do Adaptador", selecione o adaptador que acabou de criar.
-
Clique em Avançar.
-
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).
-
Clique em Avançar.
-
Na guia "Cumprimento do Contrato de Atributo", mapeie o
SAML_SUBJECT
a "Adaptador" como a origem eusername
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. -
Clique em Avançar, em Avançar novamente e em Concluído.
-
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.
-
Clique em Avançar e Concluído até chegar à guia "Credenciais".
-
Na guia "Credenciais", clique em Configurar Credenciais e, em seguida, clique em Gerenciar Certificados.
-
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").
-
Para a "Senha", use a senha de desafio do certificado.
-
Clique em Avançar e em Salvar.
-
Na guia "Gerenciamento de Certificados", você deverá ver o certificado que acabou de importar. Clique em Concluído.
-
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".
-
Clique em Avançar, em Concluído e, em seguida, em Avançar.
-
Na guia "Resumo", ative a chave para "Ponto de extremidade do aplicativo SSO".
-
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.
- Na página "Conexões do SP", na linha da nova conexão, clique em Selecionar ação e, em seguida, em Exportar Metadados.
- 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.
- 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 para o campo "Emissor" nas configurações SAML do GitHub. - Abra o arquivo de metadados que você baixou e prepare-o para as próximas etapas.
Configure o GitHub Enterprise Server
-
Inicie sessão em sua instância do GitHub Enterprise Server como um usuário com acesso ao Console de Gerenciamento.
-
Navegue até a seção "Autenticação" do Console de Gerenciamento e ative o SAML. Confira "Configurar o logon único SAML para sua empresa".
-
Insira os valores a seguir do arquivo de metadados que você baixou na 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).
- Para a "URL de logon único", use o valor
-
Para o "Certificado de verificação", carregue o arquivo de certificado X509 que você criou anteriormente.
-
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.
Antes de iniciar esta seção, certifique-se de ter seguido as etapas 1 a 4 em "Configurando o provisionamento do SCIM para gerenciar usuários".
Definir configurações do SCIM
-
Volte para a página "Conexões do SP" no PingFederate e selecione a conexão do SP que você criou anteriormente.
-
Clique na guia "Tipo da Conexão".
-
Selecione Provisionamento de Saída.
-
Certifique-se de que Perfis de SSO do Navegador esteja selecionada.
-
Clique em Avançar até chegar à guia "Provisionamento de Saída". Em seguida, clique em Configurar Provisionamento.
-
Na guia "Destino", insira os detalhes a seguir.
- "URL Base":
https://HOSTNAME/api/v3/scim/v2/
- "Token de Acesso": os personal access token (classic) criados para o usuário de configuração interno
- "URL Base":
-
Clique em Avançar.
-
Na guia "Gerenciar Canal", clique em Criar e insira um nome de canal exclusivo, como
pfghscim
. -
Clique em Avançar.
-
Na guia "Origem", escolha o armazenamento de dados que você criou anteriormente.
-
Clique em Avançar.
-
Na guia "Configurações da Origem", mantenha todas as configurações padrão. Outras configurações provavelmente funcionarão, mas não foram confirmadas.
-
Clique em Avançar.
-
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. Consulte a lista a seguir para obter os campos do SCIM compatíveis com o GitHub e os valores esperados em cada um.
- Nome de usuário: 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 sequência de caracteres que represente a função pretendida pelo usuário no GitHub. As funções válidas são
enterprise_owner
euser
.
Após terminar de definir as configurações, clique em Avançar.
Conclua a configuração e o teste
- Na guia "Ativação e Resumo", selecione Ativo em "Status do Canal".
- Na guia "Gerenciar Canais", clique em Concluído.
- Na guia "Provisionamento da Saída", clique em Salvar. O SCIM agora está configurado e habilitado.
- Aguarde alguns minutos para que o provisionamento seja executado, abra uma nova janela privada do navegador e navegue até sua instância em
https://HOSTNAME/login
. - Clique em Iniciar Sessão com SSO. Você deverá ser redirecionado para a página de login do PingFederate.
- Você também deverá ser capaz de iniciar sessão com as credenciais de um usuário no servidor LDAP que foi provisionado para o GitHub Enterprise Server.
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.
Quando terminar de configurar o SCIM, você poderá desabilitar algumas configurações do SAML habilitadas para o processo de configuração. Confira "Configurando o provisionamento do SCIM para gerenciar usuários".
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.
-
Em uma janela de terminal, verifique se o OpenSSL está instalado executando
openssl version
. Se ainda não estiver, instale-o. -
Gere uma chave privada usando o comando a seguir.
Shell openssl req -nodes -sha256 -newkey rsa:2048 -keyout MyPrivateKey.key -out MyCertificateRequest.csr
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.
-
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
ls | grep MyPrivateKey.key
-
Gere o certificado usando o comando a seguir.
Shell openssl x509 -req -days 365 -sha256 -in MyCertificateRequest.csr -signkey MyPrivateKey.key -out pfgh256.crt
openssl x509 -req -days 365 -sha256 -in MyCertificateRequest.csr -signkey MyPrivateKey.key -out pfgh256.crt
-
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
ls | grep pfgh256.crt
-
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
openssl pkcs12 -export -in pfgh256.crt -inkey MyPrivateKey.key -out pfgh256.p12
-
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
ls | grep pfgh256.p12