Referência de configuração do SAML

Sobre a configuração do SAML

Para usar o SSO (logon único) do SAML para autenticação no GitHub, você precisa configurar seu IdP (provedor de identidade) do SAML externo e sua empresa ou organização no GitHub. Em uma configuração do SAML, o GitHub funciona como um SP (provedor de serviços) do SAML. Para obter mais informações sobre autenticação para sua empresa, confira Sobre o gerenciamento de identidades e acesso.

O GitHub fornece integração de acordo com a especificação SAML 2.0. Para obter mais informações, confira o wiki do SAML no site do OASIS.

Você precisa inserir valores exclusivos do IdP do SAML ao configurar o SSO do SAML para o GitHub, além de inserir valores exclusivos do GitHub no seu IdP.

Metadados SAML

Os metadados do SP para o GitHub Enterprise Cloud estão disponíveis para organizações ou empresas com o SSO do SAML. O GitHub usa a associação urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST.

Se você usar os Enterprise Managed Users, só poderá habilitar o SSO do SAML na empresa.

Organizações

Você pode configurar o SSO do SAML para uma organização individual em sua empresa. Você também pode configurar o SSO do SAML para uma organização se usar uma organização individual no GitHub Enterprise Cloud e não usar uma conta empresarial. Para saber mais, confira Gerenciar o logon único SAML para sua organização.

Os metadados do SP de uma organização no GitHub estão disponíveis em https://github.com/orgs/ORGANIZATION/saml/metadata, em que ORGANIZATION é o nome da sua organização no GitHub.

Valor	Outros nomes	Descrição	Exemplo
ID da Entidade do SP	URL do SP, restrição de audiência	A URL de nível superior para sua organização em GitHub.com	https://github.com/orgs/ORGANIZATION
URL do Serviço do Consumidor de Declaração (ACS) do SP	URL de resposta, destinatário ou destino	URL em que o IdP envia respostas do SAML	https://github.com/orgs/ORGANIZATION/saml/consume
URL de logon único (SSO) do SP
URL em que o IdP começa com SSO	https://github.com/orgs/ORGANIZATION/sso

Enterprises

Dependendo do ambiente, os metadados do SP de uma empresa no GitHub Enterprise Cloud ficam disponíveis em um destes locais:

• https://github.com/enterprises/ENTERPRISE/saml/metadata, em que ENTERPRISE é o nome da sua empresa
• https://SUBDOMAIN.ghe.com/enterprises/SUBDOMAIN/saml/metadata, em que SUBDOMAIN é o subdomínio da sua empresa

Valor	Outros nomes	Descrição	Exemplo
ID da Entidade do SP	URL do SP, restrição de audiência	A URL de nível superior para sua empresa em GitHub.com	https://github.com/enterprises/ENTERPRISE
URL do Serviço do Consumidor de Declaração (ACS) do SP	URL de resposta, destinatário ou destino	URL em que o IdP envia respostas do SAML	https://github.com/enterprises/ENTERPRISE/saml/consume
URL de logon único (SSO) do SP
URL em que o IdP começa com SSO	https://github.com/enterprises/ENTERPRISE/saml/sso

Atributos SAML

Os atributos do SAML a seguir estão disponíveis para o GitHub.

Nome	Obrigatória	Descrição
NameID		Identificador de usuário persistente. Qualquer formato de identificador de nome persistente pode ser usado. Se você usar uma empresa com os Enterprise Managed Users, o GitHub normalizará o elemento NameID para usá-lo como um nome de usuário, a menos que uma das declarações alternativas seja fornecida. Para saber mais, confira Considerações de nome de usuário para autenticação externa. > [!NOTE] É importante usar um identificador persistente e legível. O uso de um formato de identificador transitório como urn:oasis:names:tc:SAML:2.0:nameid-format:transient resultará na vinculação de contas em cada entrada, o que pode ser prejudicial ao gerenciamento de autorização.
SessionNotOnOrAfter		A data em que o GitHub invalida a sessão associada. Após a invalidação, a pessoa deve se autenticar mais uma vez para acessar recursos da sua empresa. Para obter mais informações, confira Duração e tempo limite da sessão.
full_name		Se você configurar o SSO do SAML para uma empresa e usar Enterprise Managed Users, o e o nome completo do usuário a ser exibido na página de perfil do usuário.
emails		Os endereços de email do usuário. Se você sincronizar o uso de licença entre GitHub Enterprise Server e GitHub Enterprise Cloud, o GitHub Connect usará emails para identificar os usuários exclusivos em todos os produtos. Para saber mais, confira Sincronizando o uso da licença entre o GitHub Enterprise Server e o GitHub Enterprise Cloud.
public_keys		Se você configurar o SSO do SAML para uma empresa e usar Enterprise Managed Users, a para o usuário. Você pode especificar mais de uma chave.
gpg_keys		Se você configurar o SSO do SAML para uma empresa e usar Enterprise Managed Users e as para o usuário. Você pode especificar mais de uma chave.

Para especificar mais de um valor para um atributo, use vários elementos <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>

Requisitos da resposta SAML

O GitHub exige que a mensagem de resposta do IdP atenda aos requisitos a seguir.

• O seu IdP precisa fornecer o elemento <Destination> no documento de resposta raiz e precisa corresponder à URL do ACS somente quando o documento de resposta raiz está assinado. Se o IdP assinar a declaração, o GitHub vai ignorar a declaração.

• O IdP sempre deve fornecer o elemento <Audience> como parte do elemento <AudienceRestriction>. O valor precisa corresponder à EntityId do GitHub.

  • Se você configurar o SAML para uma organização, esse valor será https://github.com/orgs/ORGANIZATION.
  • Se você configurar o SAML para uma empresa, essa URL será https://github.com/enterprises/ENTERPRISE ou https://SUBDOMAIN.ghe.com/enterprises/SUBDOMAIN.

• Seu IdP deve fornecer uma só declaração na resposta com uma assinatura digital. Para fazer isso, você pode assinar o elemento <Assertion> ou assinar o elemento <Response>.

• Seu IdP deve fornecer um elemento <NameID> como parte do elemento <Subject>. Você pode usar qualquer formato de identificador de nome persistente.

• Seu IdP deve incluir o atributo Recipient, que deve ser definido como a URL do ACS. O exemplo a seguir demonstra o atributo.

  <samlp:Response ...>
    <saml:Assertion ...>
      <saml:Subject>
        <saml:NameID ...>...</saml:NameID>
        <saml:SubjectConfirmation ...>
          <saml:SubjectConfirmationData Recipient="https://github.com/enterprises/ENTERPRISE/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>
  

Duração e tempo limite da sessão

Para impedir que uma pessoa se autentique com seu IdP e mantenha-se autorizada por tempo indefinido, o GitHub invalida periodicamente a sessão para cada conta de usuário com acesso a recursos da sua empresa. Após a invalidação, a pessoa deve se autenticar com o IdP mais uma vez.

Por padrão, se o IdP não declara um valor para o atributo SessionNotOnOrAfter, o GitHub invalida uma sessão 24 horas após a autenticação bem-sucedida no IdP.

O GitHub dará suporte a uma duração de sessão personalizada se o IdP fornecer a opção de configurar um atributo SessionNotOnOrAfter e um valor.

Se você definir um valor de duração de sessão personalizado menor que 24 horas, o GitHub poderá solicitar que as pessoas se autentiquem sempre que o GitHub iniciar um redirecionamento.

Para evitar erros de autenticação, recomendamos a duração mínima da sessão de quatro horas. Para saber mais, confira Autenticação SAML.