Usar SAML

Sobre o SAML para GitHub Enterprise Server

O SAML SSO permite que as pessoas efetuem a autenticação e acessem your GitHub Enterprise Server instance por meio de um sistema externo para gerenciamento de identidades.

O SAML é um padrão de autenticação e autorização baseado em XML. Ao configurar o SAML para your GitHub Enterprise Server instance, o sistema externo para autenticação é chamado de provedor de identidade (IdP). Sua instância atua como um provedor de serviço (SP) do SAML. Para obter mais informações, consulte Linguagem markup de declaração de segurança na Wikipédia.

If you want to authenticate some users without adding them to your identity provider, you can configure built-in authentication in addition to SAML SSO. Para obter mais informações, consulte "Permitir a autenticação integrada para usuários de fora do provedor de identidade".

Serviços SAML compatíveis

GitHub Enterprise Server é compatível com o SAML SSO, com IdPs que implementam o padrão SAML 2.0. Para obter mais informações, consulte a Wiki do SAML no site do OASIS.

GitHub officially supports and internally tests the following IdPs.

• Active Directory Federation Services (AD FS)
• Azure Active Directory (Azure AD)
• Okta
• OneLogin
• PingOne
• Shibboleth

GitHub Enterprise Server não é compatível com o logout único SAML. Para finalizar uma sessão do SAML ativa, os usuários devem efetuar o logout diretamente no seu IdP do SAML.

Considerações de nome de usuário no SAML

Cada nome de usuário do GitHub Enterprise Server é determinado por uma das seguintes afirmações na resposta SAML, ordenada por prioridade:

• Nome de usuário personalizado, se houver;
• Declaração http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name, se houver;
• Declaração http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress, se houver;
• Elemento NameID.

O elemento NameID é obrigatório, mesmo que os outros atributos estejam presentes.

É criado um mapeamento entre NameID e o nome de usuário do GitHub Enterprise Server. Portanto, o NameID deve ser persistente, exclusivo e não estar sujeito a alterações no ciclo de vida do usuário.

Nomes de usuário de GitHub Enterprise Server só podem conter caracteres alfanuméricos e traços (-). GitHub Enterprise Server normalizará qualquer caractere não alfanumérico do nome de usuário da sua conta em um traço. Por exemplo, um nome de usuário de gregory.st.john será normalizado para gregory-st-john. Observe que nomes de usuários normalizados também não podem iniciar ou terminar com um traço. Eles também não podem conter dois traços consecutivos.

Nomes de usuário criados a partir de endereços de e-mail são criados a partir dos caracteres normalizados que precedem o caractere @.

Se várias contas forem normalizadas no mesmo nome de usuário do GitHub Enterprise Server apenas a primeira conta de usuário é criada. Usuários subsequentes com o mesmo nome de usuário não serão capazes de fazer o login.

Esta tabela dá exemplos de como os nomes de usuário são normalizados em GitHub Enterprise Server:

Nome de usuário	Nome de usuário normalizado	Resultado
Ms.Bubbles	ms-bubbles	Nome de usuário criado com sucesso.
!Ms.Bubbles	-ms-bubbles	Este nome de usuário não é criado, porque começa com um traço.
Ms.Bubbles!	ms-bubbles-	Este nome de usuário não é criado, porque termina com um traço.
Ms!!Bubbles	ms--bubbles	Este nome de usuário não é criado, porque contém dois traços consecutivos.
Ms!Bubbles	ms-bubbles	Este nome de usuário não é criado. Embora o nome de usuário normalizado seja válido, ele já existe.
Ms.Bubbles@example.com	ms-bubbles	Este nome de usuário não é criado. Embora o nome de usuário normalizado seja válido, ele já existe.

Autenticação de dois fatores

Quando usar SAML ou CAS, a autenticação de dois fatores não é suportada ou gerenciada no appliance do GitHub Enterprise Server, mas pode ser suportada pelo provedor de autenticação externa. A aplicação da autenticação de dois fatores em organizações não está disponível. Para obter mais informações sobre a aplicação da autenticação de dois fatores nas organizações, consulte "Requiring two-factor authentication in your organization."

Metadados SAML

O metadados do provedor de serviço para your GitHub Enterprise Server instance está disponível em http(s)://[hostname]/saml/metadata.

Para configurar seu provedor de identidade manualmente, a URL do serviço de consumidor de declaração (ACS, Assertion Consumer Service) é http(s)://[hostname]/saml/consume e usa a associação urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST.

Atributos SAML

Os atributos a seguir estão disponíveis. Você pode alterar os nomes de atributos no console de gerenciamento, com exceção do atributo administrador.

Nome padrão do atributo	Tipo	Descrição
NameID	Obrigatório	Identificador de usuário persistente. Qualquer formato de identificador de nome persistente pode ser usado. O elemento NameID será usado para um nome de usuário do GitHub Enterprise Server, a menos que uma das declarações alternativas seja fornecida.
administrador	Opcional	Quando o valor for 'true', o usuário será promovido automaticamente como administrador. Qualquer outro valor ou um valor não existente rebaixará o usuário para uma conta regular.
nome de usuário	Opcional	Nome do usuário no GitHub Enterprise Server.
full_name	Opcional	Nome do usuário exibido na página de perfil. Após o provisionamento, os usuários podem alterar seus nomes.
emails	Opcional	Endereços de e-mail para o usuário. É possível especificar mais de um.
public_keys	Opcional	Chaves SSH públicas para o usuário. É possível especificar mais de um.
gpg_keys	Opcional	Chaves chaves GPG para o usuário. É possível especificar mais de um.

Para especificar mais de um valor para um atributo, use múltiplos elementos de <saml2:AttributeValue>.

<saml2:Attribute FriendlyName="public_keys" Name="urn:oid:1.2.840.113549.1.1.1" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
    <saml2:AttributeValue>ssh-rsa LONG KEY</saml2:AttributeValue>
    <saml2:AttributeValue>ssh-rsa LONG KEY 2</saml2:AttributeValue>
</saml2:Attribute>

Definir configurações SAML

1. From an administrative account on GitHub Enterprise Server, in the upper-right corner of any page, click .

   

2. If you're not already on the "Site admin" page, in the upper-left corner, click Site admin.

   

3. Na barra lateral esquerda, clique em Console de gerenciamento.

4. Na barra lateral esquerda, clique em Authentication.

5. Selecione SAML.

   

6. Optionally, to allow people to use built-in authentication if they don't have an account on your IdP, select Allow built-in authentication. Para obter mais informações, consulte "Permitir a autenticação integrada para usuários de fora do provedor de identidade".

   

7. Para habilitar SSO de resposta não solicitada, selecione IdP initiated SSO (SSO iniciado pelo IdP). Por padrão, o GitHub Enterprise Server responderá a uma solicitação iniciada pelo Provedor de identidade (IdP) não solicitado com AuthnRequest.

   

   Observação: recomendamos manter este valor não selecionado. Você deve habilitar esse recurso somente na rara instância em que sua implementação SAML não oferecer suporte ao SSO iniciado pelo provedor de serviços e quando recomendado pelo Suporte do GitHub Enterprise.

8. Selecione Disable administrator demotion/promotion (Desabilitar rebaixamento/promoção do administrador) se você não quiser que o provedor SAML determine direitos de administrador para usuários no your GitHub Enterprise Server instance.

   

9. Opcionalmente, para permitir que your GitHub Enterprise Server instance envie e receba declarações criptografadas para e do seu IdP do SAML, selecione Exigir declarações criptografadas. Para obter mais informações, consulte "Habilitando declarações criptografadas".

   

   Aviso: A configuração incorreta de declarações criptografadas pode fazer com que toda autenticação de your GitHub Enterprise Server instance falhe.

   • Você deve garantir que seu IdP é compatível com declarações e que a criptografia e os métodos de transporte principais no console de gerenciamento correspondem aos valores configurados no seu IdP. Você também deve fornecer o certificado público de your GitHub Enterprise Server instance ao seu IdP. Para obter mais informações, consulte "Habilitando declarações criptografadas".

   • Antes de habilitar as declarações criptografadas, GitHub recomenda verificações criptografadas de teste em um ambiente de preparo e confirma que a autenticação do SAML funciona como você espera. Para obter mais informações, consulte "Configurar instância de preparo".

10. No campo URL de logon único, digite o ponto de extremidade de HTTP ou HTTPS no seu IdP para solicitações de logon único. Esse valor é fornecido pela configuração do IdP. Se o host estiver disponível apenas na sua rede interna, você pode precisar que configure your GitHub Enterprise Server instance para usar servidores de nomes internos.

    

11. Como alternativa, no campo emissor, digite o nome do emissor do SAML. Fazer isso verifica a autenticidade das mensagens enviadas para your GitHub Enterprise Server instance.

    

12. Nos menus suspensos Método de assinatura e Método de compilação, escolha o algoritmo de hash usado pelo emissor SAML para verificar a integridade das solicitações do your GitHub Enterprise Server instance. Especifique o formato com menu suspenso Formato do Identificador do Nome.

    

13. Em Verification certificate (Certificado de verificação), clique em Choose File (Escolher arquivo) e escolha um certificado para validar as respostas SAML do IdP.

    

14. Modifique os nomes do atributo SAML para corresponder ao IdP, se necessário, ou aceite os nomes padrão.

    

Atualizando NameID do SAML de um usuário

1. From an administrative account on GitHub Enterprise Server, in the upper-right corner of any page, click .

   

2. If you're not already on the "Site admin" page, in the upper-left corner, click Site admin.

   

3. Selecione SAML.

4. Na lista de usuários, clique no nome de usuário para o qual você gostaria de atualizar o mapeamento de NameID.

5. No canto superior direito da página, clique em Security (Segurança).

6. À direita de "Atualizar o NameID do SAML", clique em Editar.

7. No campo "NameID", digite o novo NameID para o usuário.

8. Clique Atualizar o NameID.

Revogar o acesso �  your GitHub Enterprise Server instance

Se remover um usuário do seu provedor de identidade, você também deverá suspendê-lo manualmente. Caso contrário, ele continuará podendo fazer autenticação usando tokens de acesso ou chaves SSH. Para obter mais informações, consulte "Suspender e cancelar a suspensão de usuários".

Requisitos de mensagem de resposta

A mensagem de resposta deve atender aos seguintes requisitos:

• O <Destination> elemento deve sempre ser fornecido no documento de resposta raiz e deve corresponder ao URL do ACS somente quando o documento de resposta raiz estiver assinado. Se for assinada, a declaração será ignorada.
• O elemento <Audience> deve sempre ser fornecido como parte do elemento <AudienceRestriction>. Ele deve corresponder ao EntityId para GitHub Enterprise Server. Esta é a URL para a instância do GitHub Enterprise Server, como https://ghe.corp.example.com.
• Cada asserção na resposta deve ser protegida por uma assinatura digital. É possível fazer isso assinando cada elemento <Assertion> ou assinando o elemento <Response>.
• Um elemento <NameID> deve ser fornecido como parte do elemento <Subject>. Qualquer formato de identificador de nome persistente pode ser usado.
• O atributo Recipient deve estar presente e definido na URL do ACS. Por exemplo:

<samlp:Response ...>
  <saml:Assertion ...>
    <saml:Subject>
      <saml:NameID ...>...</saml:NameID>
      <saml:SubjectConfirmation ...>
        <saml:SubjectConfirmationData Recipient="https://ghe.corp.example.com/saml/consume" .../>
      </saml:SubjectConfirmation>
    </saml:Subject>
    <saml:AttributeStatement>
      <saml:Attribute FriendlyName="USERNAME-ATTRIBUTE" ...>
        <saml:AttributeValue>monalisa</saml:AttributeValue>
      </saml:Attribute>
    </saml:AttributeStatement>
  </saml:Assertion>
</samlp:Response>

Autenticação SAML

Mensagens de erro de registro de GitHub Enterprise Server para autenticação do SAML falhada no registro de autenticação em /var/log/github/auth.log. Para obter mais informações sobre os requisitos de resposta do SAML, consulte "Requisitos de mensagem de resposta".

Erro: "Outro usuário já possui a conta"

Quando um usuário inicia a sessão em GitHub Enterprise Server pela primeira vez com autenticação do SAML, GitHub Enterprise Server cria uma conta de usuário na instância e mapeia o NameID do SAML com a conta.

Quando o usuário inicia a sessão novamente, GitHub Enterprise Server compara o mapeamento do NameID da conta com a resposta do IdP. Se o NameID na resposta do IdP não corresponder mais ao NameID que GitHub Enterprise Server espera para o usuário. ocorrerá uma falha no login. O usuário receberá a seguinte mensagem.

Outro usuário já possui a conta. Solicite ao administrador que verifique o registro de autenticação.

De modo geral, a mensagem indica que o nome de usuário ou endereço de email da pessoa foi alterado no IdP. Certifique-se de que o mapeamento do NameID para a conta do usuário no GitHub Enterprise Server corresponde ao NameID do usuário no seu IdP. Para obter mais informações, consulte "Atualizar o NameID do SAML.

Se a resposta SAML não estiver assinada ou se a assinatura não corresponder ao conteúdo, o log de autenticação mostrará a seguinte mensagem de erro:

Se o Destinatário não coincide com a URL do ACS para a sua instância de GitHub Enterprise Server, uma das seguintes duas mensagens de erro aparecerá no log de autenticação quando um usuário tentar efetuar a autenticação.

Recipient na resposta SAML não pode ficar em branco.

Recipient na resposta SAML não era válido.

Certifique-se de definir o valor de Destinatário no seu IdP como a URL do ACS completo para a sua instância do GitHub Enterprise Server. Por exemplo, https://ghe.corp.example.com/saml/consume.

Erro: "Resposta do SAML não foi assinada ou foi modificada"

Se seu IdP não assinar a resposta do SAML ou a assinatura não corresponder ao conteúdo, será exibida a seguinte mensagem de erro no registro de autenticação.

Resposta SAML não assinada ou modificada.

Certifique-se de que você configurou as declarações assinadas para o aplicativo de GitHub Enterprise Server no seu IdP.

Erro: "Audiência é inválida" ou "Nenhuma declaração encontrada"

Se a resposta do IdP tiver um valor ausente ou incorreto para Audiência, a seguinte mensagem de erro aparecerá no registro de autenticação.

Audience inválido. O atributo Audience não corresponde a url_sua_instância

Certifique-se de definir o valor para Audiência no seu IdP para a EntityId para a sua instância do GitHub Enterprise Server, que é a URL completa para sua instância do GitHub Enterprise Server. Por exemplo, https://ghe.corp.example.com.