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 Enterprise Server, você deve configurar seu IdP (provedor de identidade) do SAML externo e sua instância do GitHub Enterprise Server. Em uma configuração do SAML, o GitHub Enterprise Server 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 Enterprise Server 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 exclusivos do IdP do SAML ao configurar o SSO do SAML para o GitHub Enterprise Server, e também deve inserir valores exclusivos do GitHub Enterprise Server em seu IdP.

Metadados SAML

Os metadados do 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. O 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 SP, restrição de audiência	Sua URL de nível superior para 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 Enterprise Server. Você pode alterar os nomes de atributo no Console de Gerenciamento, com exceção do atributo administrator. Para saber mais, confira Administrar sua instância por meio da interface do usuário da Web.

Nome	Obrigatória	Descrição
NameID		Identificador de usuário persistente. Qualquer formato de identificador de nome persistente pode ser usado. GitHub Enterprise Server normalizará o elemento NameID 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 vinculação de contas em cada entrada, o que pode ser prejudicial ao gerenciamento de autorização.
SessionNotOnOrAfter		A data em que GitHub Enterprise Server 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. Para obter mais informações, confira Duração e tempo limite da sessão.
administrator		Quando o valor for true GitHub Enterprise Server o usuário será promovido automaticamente para 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		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. Você pode especificar mais de um endereço. 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		e as chaves GPG 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 Enterprise Server 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, GitHub Enterprise Server ignorará a declaração.

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

• 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://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 o GitHub Enterprise Server pela primeira vez e inicia a instância, 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 administrador do GitHub Enterprise Server pode se conectar ao servidor via 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 autenticação SP SAML se ele tiver expirado e for exigido pelo IdP ou pelas declarações criptografadas, um administrador do GitHub Enterprise Server poderá executar os comandos abaixo em uma sessão SSH do GitHub Enterprise Server.

# 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 mantenha-se autorizada indefinidamente, o GitHub Enterprise Server invalida periodicamente a sessão para cada conta de usuário com acesso a sua instância do GitHub Enterprise Server. 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 Enterprise Server invalida uma sessão uma semana após a autenticação bem-sucedida no IdP.

GitHub Enterprise Server oferecerá suporte a uma duração de sessão personalizada se o seu IdP fornecer a opção de configurar um atributo e valor SessionNotOnOrAfter e se esse atributo estiver incluído nas respostas do SAML. Se o IdP não permitir um atributo SessionNotOnOrAfter, um administrador de site poderá configurar um tempo limite de sessão do 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, o GitHub Enterprise Server poderá solicitar que as pessoas se autentiquem sempre que o GitHub Enterprise Server iniciar um redirecionamento.

Independentemente do 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.