Autenticar com os aplicativos GitHub

Gerar uma chave privada

Após criar um aplicativo GitHub, você deverá gerar uma ou mais chaves privadas. Você usará a chave privada para assinar solicitações de token de acesso.

Você pode criar várias chaves privadas e girá-las para evitar período de inatividade se uma chave for comprometida ou perdida. Para verificar se uma chave privada corresponde a uma chave pública, consulte Verificando chaves privadas.

Para gerar uma chave privada:

1. In the upper-right corner of any page, click your profile photo, then click Settings.
   
2. Na barra lateral esquerda, clique em Developer settings (Configurações do desenvolvedor).
   
3. In the left sidebar, click GitHub Apps.
   
4. Select the GitHub App you want to modify.
   
5. Em "Chaves Privadas", clique em Gerar uma chave privada.
   
6. Você verá uma chave privada no formato PEM baixado no seu computador. Certifique-se de armazenar este arquivo porque o GitHub armazena apenas a parte pública da chave.

Verificar chaves privadas

O GitHub Enterprise gera uma impressão digital para cada par de chave privada e pública usando uma função hash SHA-1. Você pode verificar se a sua chave privada corresponde à chave pública armazenada no GitHub Enterprise, gerando a impressão digital da sua chave privada e comparando-a com a impressão digital exibida no GitHub Enterprise.

Para verificar uma chave privada:

1. Encontre a impressão digital para o par de chaves privada e pública que deseja verificar na seção "Chaves privadas" da página de configurações de desenvolvedor do seu aplicativo GitHub. Para obter mais informações, consulte Gerar uma chave privada.
   
2. Gere a impressão digital da sua chave privada (PEM) localmente usando o comando a seguir:

   $ openssl rsa -in PATH_TO_PEM_FILE -pubout -outform DER | openssl sha1 -c

3. Compare os resultados da impressão digital gerada localmente com a impressão digital que você vê no GitHub Enterprise.

Apagar chaves privadas

Você pode remover uma chave privada perdida ou comprometida excluindo-a. No entanto, você deve ter pelo menos uma chave privada. Quando você tem apenas uma chave, você deverá gerar uma nova antes de excluir a antiga.

Efetuar a autenticação um aplicativo GitHub

Efetuar a autenticação como um aplicativo GitHub permite que você faça algumas coisas:

• Você pode recuperar informações de gerenciamento de alto nível sobre seu aplicativo GitHub.
• Você pode solicitar tokens de acesso para uma instalação do aplicativo.

Para efetuar a autenticação como um aplicativo GitHub, gere uma chave privada no formato PEM e baixe-a para na sua máquina local. Você usará essa chave para assinar um JSON Web Token (JWT) e codificá-lo usando o algoritmo RS256. O GitHub Enterprise verifica se a solicitação foi autenticada, fazendo a verificação do token com a chave pública armazenada pelo aplicativo.

Aqui está um script Ruby rápido que você pode usar para gerar um JWT. Observe que você deve executar o gem install jwt antes de usá-lo.

require 'openssl'
require 'jwt'  # https://rubygems.org/gems/jwt

# Conteúdo da chave privada
private_pem = File.read(YOUR_PATH_TO_PEM)
private_key = OpenSSL::PKey::RSA.new(private_pem)

# Gerar o JWT
carga= {
  # emitido em
  iat: Time.now.to_i,
  # JWT expiration time (10 minute maximum)
  exp: Time.now.to_i + (10 * 60),
  # aplicativo GitHub's identifier
  iss: YOUR_APP_ID
}

jwt = JWT.encode(payload, private_key, "RS256")
puts jwt

YOUR_PATH_TO_PEM e YOUR_APP_ID são os valores que você deve substituir.

Use o seu identificador de aplicativo GitHub(YOUR_APP_ID) como o valor para a reivindicação do JWT iss (emissor). Você pode obter o identificador aplicativo GitHub por meio do ping inicial do webhook, após criar o aplicativo, ou a qualquer momento na da página de configurações do aplicativo na UI do GitHub.com.

Após criar o JWT, defina-o no Cabeçalho da solicitação de API:

$ curl -i -H "Authorization: Bearer YOUR_JWT" -H "Accept: application/vnd.github.machine-man-preview+json" http(s)://[hostname]/api/v3/app

YOUR_JWT é o valor que você deve substituir.

O exemplo acima usa o tempo máximo de expiração de 10 minutos, após o qual a API começará a retornar o erro 401:

{
  "message": "'Expiration' claim ('exp') deve ser um valor numérico que representa o tempo futuro em que expira a declaração.",
  "documentation_url": "https://developer.github.com/enterprise/2.18/v3"
}

Você deverá criar um novo JWT após o tempo expirar.

Acessar os pontos finais da API como um aplicativo GitHub

Para obter uma lista dos pontos finais da API REST que você pode usar para obter informações de alto nível sobre um aplicativo GitHub, consulte "aplicativos GitHub".

Autenticar como uma instalação

Autenticar como uma instalação permite que você execute ações na API para essa instalação. Antes de autenticar como uma instalação, você deverá criar um token de acesso de instalação. Estes tokens de acesso de instalação são usados por aplicativo GitHubs para efetuar a autenticação.

Por padrão, os tokens de acesso de instalação são limitados em todos os repositórios que uma instalação pode acessar. É possível limitar o escopo do token de acesso de instalação a repositórios específicos usando o parâmetro repository_ids. Consulte Criar um token de acesso de instalação para um ponto final de um aplicativo para obter mais informações. Os tokens de acesso de instalação têm as permissões configuradas pelo aplicativo GitHub e expiram após uma hora.

Para criar um token de acesso de instalação, inclua o JWT gerado acima no cabeçalho de autorização na solicitação de API:

$ curl -i -X POST \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github.machine-man-preview+json" \
http(s)://[hostname]/api/v3/app/installations/:installation_id/access_tokens

A resposta incluirá seu token de acesso de instalação, a data de validade, as permissões do token e os repositórios que o token pode acessar. Para obter mais informações sobre o formato de resposta, consulte Criar um token de acesso de instalação para um ponto de final doaplicativo.

Para efetuar a autenticação com um token de acesso de instalação, inclua-o no cabeçalho de autorização na solicitação de API:

$ curl -i \
-H "Authorization: token YOUR_INSTALLATION_ACCESS_TOKEN" \
-H "Accept: application/vnd.github.machine-man-preview+json" \
http(s)://[hostname]/api/v3/installation/repositories

YOUR_INSTALLATION_ACCESS_TOKEN é o valor que você deve substituir.

Acessar pontos finais da API como uma instalação

Para obter uma lista de pontos finais da API REST disponíveis para uso por aplicativo GitHubs usando um token de acesso de instalação, consulte "Pontos finais disponíveis".

Para obter uma lista de pontos finais relacionados a instalações, consulte "Instalações".

Acesso Git baseado em HTTP por uma instalação

As instalações com permissões no conteúdo `` de um repositório, podem usar seus tokens de acesso de instalação para efetuar autenticação para acesso ao Git. Use o token de acesso da instalação como a senha HTTP:

git clone https://x-access-token:<token>@github.com/owner/repo.git