Referência de configuração do SAML

Sobre a configuração do SAML

Para usar o logon único (SSO) SAML para autenticação no GitHub, você deve configurar tanto o provedor de identidade SAML (IdP) externo quanto sua instância do GitHub Enterprise Server. Em uma configuração SAML, GitHub funciona como um SP (provedor de serviços SAML). Para obter mais informações sobre autenticação para sua empresa, confira Conceitos básicos de gerenciamento de identidade e acesso.

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ê deve inserir valores únicos do seu IdP SAML ao configurar o SSO SAML para GitHub e também deve inserir valores únicos de GitHub no seu IdP.

Metadados SAML

Os metadados de SP para sua instância do GitHub Enterprise Server estão disponíveis em http(s)://HOSTNAME/saml/metadata, em que HOSTNAME é o nome do host da sua instância. GitHub Enterprise Server usa a associação urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST .

Valor	Outros nomes	Descrição	Exemplo
ID da Entidade do SP	URL do SharePoint, restrição de público	A URL de nível mais alto para sua instância do GitHub Enterprise Server	http(s)://HOSTNAME
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	http(s)://HOSTNAME/saml/consume
URL de logon único (SSO) do SP
URL em que o IdP começa com SSO	http(s)://HOSTNAME/sso

Atributos SAML

Os atributos SAML a seguir estão disponíveis para GitHub. Você pode alterar os nomes de atributo no Console de Gerenciamento, com exceção do administrator atributo. Para obter mais informações, consulte Administrar sua instância por meio da interface do usuário da Web.

Nome	Obrigatório	Descrição
NameID		Identificador de usuário persistente. Qualquer formato de identificador de nome persistente pode ser usado.
GitHub normalizará o NameID elemento a ser usado 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 reassociação de contas a cada login, o que pode ser prejudicial ao gerenciamento de autorização. | | SessionNotOnOrAfter | | A data que GitHub invalida a sessão associada. Após a invalidação, a pessoa deve se autenticar mais uma vez para acessar sua instância do GitHub Enterprise Server da sua empresa. Para obter mais informações, confira Duração e tempo limite da sessão. | | | | administrator | | Quando o valor for true, GitHub promoverá automaticamente o usuário para ser um administrador do site. A definição desse atributo como algo que não seja true resultará em rebaixamento, desde que o valor não esteja em branco. A omissão desse atributo ou um valor em branco não vai alterar a função do usuário. | | username | | O nome de usuário para sua instância do GitHub Enterprise Server. | | | | full_name | | 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. Você pode especificar mais de um endereço. Se você sincronizar o uso da licença entre GitHub Enterprise Server e GitHub Enterprise Cloud, GitHub Connect usará emails para identificar usuários únicos em todos os produtos. Para saber mais, confira Sincronizando o uso de licença do GitHub Enterprise Server para a nuvem. | | public_keys | | chaves SSH públicas para o usuário. Você pode especificar mais de uma chave. | | gpg_keys | | chaves GPG 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

GitHub requer 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 asserção, o GitHub ignorará a asserção.

• O IdP sempre deve fornecer o elemento <Audience> como parte do elemento <AudienceRestriction>. O valor deve corresponder ao seu EntityId para GitHub. Esse valor é a URL em que você acessa GitHub, como http(s)://HOSTNAME.

• Seu IdP deve fornecer uma única 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://HOSTNAME/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>
  

Certificado de autenticação SAML para AuthnRequests

Quando você configura GitHub Enterprise Server e inicia a instância pela primeira vez, um certificado de autenticação SAML autoassinado é gerado, separado do certificado SAML do IdP. Esse certificado é usado para assinar o AuthnRequests SAML enviado para o IdP e é válido por dez anos. Ele é armazenado em /data/user/common/saml-sp.p12, e você pode exibir os detalhes no formato codificado em base64 em http(s)://HOSTNAME/saml/metadata.

Se o IdP validar o certificado de autenticação SAML, ou se as declarações criptografadas em SAML estiverem habilitadas, os usuários poderão enfrentar problemas de autenticação quando o certificado expirar. Para verificar a data de validade, um GitHub Enterprise Server administrador pode se conectar ao servidor por meio do SSH e executar o comando abaixo. Confira Conectando-se ao shell administrativo por SSH.

sudo openssl pkcs12 -in /data/user/common/saml-sp.p12 -clcerts -nokeys -password pass: | sudo openssl x509 -noout -enddate

Para gerar novamente esse certificado de assinatura do SAML SP se ele tiver expirado e for exigido pelo IdP ou declarações criptografadas, um GitHub Enterprise Server administrador poderá executar os comandos abaixo em uma GitHub Enterprise Server sessão SSH.

# Backup the old certificate
sudo cp /data/user/common/saml-sp.p12 /data/user/common/saml-sp.p12-$(date +%d%m%Y_%H%M%S)

saml_tempdir=$(sudo mktemp -d)
sudo openssl req -new -newkey rsa:4096 -days 3650 -nodes -x509 -sha256 -subj "/CN=github_enterprise" -keyout $saml_tempdir/saml.key -out $saml_tempdir/saml.crt
sudo openssl pkcs12 -export -inkey $saml_tempdir/saml.key -in $saml_tempdir/saml.crt -nodes -password pass: -out /data/user/common/saml-sp.p12
sudo rm -rf $saml_tempdir

sudo nomad stop github-unicorn
sudo nomad run -hcl1 /etc/nomad-jobs/github/unicorn.hcl

Duração e tempo limite da sessão

Para impedir que uma pessoa se autentique com seu IdP e fique autorizada indefinidamente, GitHub invalida periodicamente a sessão para cada conta de usuário com acesso aos sua instância do GitHub Enterprise Server 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 SessionNotOnOrAfter atributo, GitHub invalida uma sessão uma semana após a autenticação bem-sucedida com o IdP.

GitHub dará suporte a uma duração de sessão personalizada se o IdP fornecer a opção de configurar um SessionNotOnOrAfter atributo e valor e se esse atributo estiver incluído nas respostas SAML. Se o IdP não permitir um atributo SessionNotOnOrAfter, um administrador do site poderá configurar um tempo limite de sessão SAML personalizado para todos os usuários na sua instância usando o comando ghe-config saml.default-session-expiration [seconds] no shell administrativo.

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

Seja qual for o método de autenticação usado na sua instância, o GitHub Enterprise Server terminará uma sessão de usuário após duas semanas de inatividade contínua.