Autenticar com os aplicativos GitHub

Efetuar a autenticação um GitHub App

A autenticação como um GitHub App é necessária para chamadas à API server-to-server, que permitem que o GitHub App faça algumas coisas:

• Recupere informações de gerenciamento de alto nível sobre o GitHub App.
• Solicite tokens de acesso para uma instalação do aplicativo, permitindo que você faça chamadas à API sem um usuário conectado.

Para se autenticar como um GitHub App, gere uma chave privada no formato PEM e baixe-a no computador local. Você usará essa chave para assinar um JWT (Token Web JSON) e codificá-lo usando o algoritmo RS256. O GitHub Enterprise Server valida a identidade do aplicativo verificando o token com a chave pública armazenada pelo aplicativo. Você trocará esse JWT por um token de instalação, usado para autenticar o aplicativo como uma instalação específica.

Como listar as instalações de um aplicativo

Para listar as instalações do aplicativo, inclua o JWT no cabeçalho de autorização na solicitação de API para GET /app/installations. Para obter mais informações sobre como gerar um JWT, confira "Conteúdo do JWT".

$ curl -i -X GET \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github+json" \
http(s)://HOSTNAME/api/v3/app/installations

A resposta incluirá uma lista de instalações em que a id de cada instalação pode ser usada para criar um token de acesso de instalação. Para obter mais informações sobre o formato de resposta, confira "Listar instalações para o aplicativo autenticado".

Autenticar como uma instalação

A autenticação como instalação permite que o aplicativo acesse essa organização ou usuário por meio da API, bem como recursos públicos no GitHub Enterprise Server. Para se autenticar como uma instalação, você precisa usar um token de acesso de instalação, obtido enviando um JWT ao GitHub Enterprise Server para provar a identidade do aplicativo. Verifique se você já instalou o aplicativo GitHub em pelo menos uma organização ou conta de usuário. É impossível criar um token de instalação sem uma instalação. Para obter mais informações, confira "Como instalar Aplicativos do GitHub".

Por padrão, os tokens de acesso de instalação têm como escopo todos os repositórios que uma instalação pode acessar. Você pode limitar mais o escopo do token de acesso de instalação a repositórios específicos usando o parâmetro repository_ids. Os tokens de acesso de instalação têm as permissões configuradas pelo GitHub App e, como o acesso ao repositório, o escopo também pode ser reduzido usando o parâmetro permissions. Para obter mais informações, confira a documentação do ponto de extremidade Criar um token de acesso de instalação para um aplicativo. Todos os tokens de instalação expiram após uma hora.

Para criar um token de acesso de instalação, inclua o JWT do cabeçalho de autorização na solicitação da API e substitua :installation_id por id da instalação. Para obter mais informações sobre como gerar um JWT, confira "Conteúdo do JWT".

$ curl -i -X POST \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github+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, confira o ponto de extremidade Criar um token de acesso de instalação para um aplicativo.

Para fazer a autenticação com um token de acesso de instalação, inclua-o no cabeçalho de autorização na solicitação da API. Substitua YOUR_INSTALLATION_ACCESS_TOKEN por um token de acesso de instalação:

$ curl -i \
-H "Authorization: Bearer YOUR_INSTALLATION_ACCESS_TOKEN" \
-H "Accept: application/vnd.github+json" \
http(s)://HOSTNAME/api/v3/installation/repositories

Acessar pontos finais da API como uma instalação

Para ver uma lista de pontos de extremidade da API REST disponíveis para serem usados pelos GitHub Apps usando um token de acesso de instalação, confira "Pontos de extremidade disponíveis para Aplicativos do GitHub".

Para ver uma lista de pontos de extremidade relacionados às instalações, confira "Instalações".

Acesso Git baseado em HTTP por uma instalação

As instalações com permissões no contents de um repositório podem usar os tokens de acesso de instalação para autenticar o acesso do 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

Como gerar um JWT (Token Web JSON)

O JWT usado para autenticar o aplicativo é composto por várias declarações, bem como uma assinatura usada para validar a autenticidade. Essas declarações são:

Os tokens precisam ser assinados usando o algoritmo RS256, com uma declaração correspondente alg de RS256.

Usando o Ruby

Veja um script Ruby que você pode usar para gerar um JWT. Observe que você precisará executar gem install jwt antes de usá-lo. YOUR_PATH_TO_PEM e YOUR_APP_ID são os valores que você precisará substituir. Certifique-se de incluir os valores entre aspas duplas.

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

# Private key contents
private_pem = File.read("YOUR_PATH_TO_PEM")
private_key = OpenSSL::PKey::RSA.new(private_pem)

# Generate the JWT
payload = {
  # issued at time, 60 seconds in the past to allow for clock drift
  iat: Time.now.to_i - 60,
  # JWT expiration time (10 minute maximum)
  exp: Time.now.to_i + (10 * 60),
  # GitHub App's identifier
  iss: "YOUR_APP_ID"
}

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

Usando Python

Veja um script semelhante para gerar um JWT no Python. Observe que você precisará usar pip install jwt para usar esse script. Esse script solicitará a localização do arquivo PEM e a ID do aplicativo, ou você pode transmiti-los como argumentos embutidos ao executar o script.

#!/usr/bin/env python3
import jwt
import time
import sys

# Get PEM file path
if len(sys.argv) > 1:
    pem = sys.argv[1]
else:
    pem = input("Enter path of private PEM file: ")

# Get the App ID
if len(sys.argv) > 2:
    app_id = sys.argv[2]
else:
    app_id = input("Enter your APP ID: ")

# Open PEM
with open(pem, 'rb') as pem_file:
    signing_key = jwt.jwk_from_pem(pem_file.read())

payload = {
    # Issued at time
    'iat': int(time.time()),
    # JWT expiration time (10 minutes maximum)
    'exp': int(time.time()) + 600,
    # GitHub App's identifier
    'iss': app_id
}

# Create JWT
jwt_instance = jwt.JWT()
encoded_jwt = jwt_instance.encode(payload, signing_key, alg='RS256')

print(f"JWT:  ", encoded_jwt)

Use o identificador do GitHub App (YOUR_APP_ID) como o valor da declaração iss (emissor) do JWT. Obtenha o identificador do GitHub App por meio do ping de webhook inicial após a criação do aplicativo ou a qualquer momento na página de configurações do aplicativo na interface do usuário do GitHub.com.

Depois de criar o JWT, defina-o no Header da solicitação de API:

$ curl -i -H "Authorization: Bearer YOUR_JWT" -H "Accept: application/vnd.github+json" http(s)://HOSTNAME/api/v3/app

YOUR_JWT é o valor que você precisará substituir.

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

{
  "message": "'Expiration' claim ('exp') must be a numeric value representing the future time at which the assertion expires.",
  "documentation_url": "https://docs.github.com/enterprise/3.5/rest"
}

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

Acessar os pontos finais da API como um GitHub App

Para ver uma lista de pontos de extremidade da API REST que você pode usar para obter informações de alto nível sobre um GitHub App, confira "Aplicativos do GitHub".

Gerar uma chave privada

Depois de criar um GitHub App, você precisará gerar uma ou mais chaves privadas para fazer solicitações à API do GitHub Enterprise Server como o próprio aplicativo. Você usará a chave privada para assinar os JWTs usados para solicitar um token de acesso de instalação.

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, confira Como verificar chaves privadas.

Para gerar uma chave privada:

1. No canto superior direito de qualquer página, clique na foto do seu perfil e em Configurações.

   

2. Na barra lateral esquerda, clique em Configurações do desenvolvedor.

3. Na barra lateral esquerda, clique em Aplicativos do GitHub. 1. À direita do GitHub App que você deseja modificar, clique em Editar.

4. Em "Chaves privadas", clique em Gerar uma chave privada.

5. 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 Server gera uma impressão digital para cada par de chave privada e pública usando a função hash SHA-256. Você pode verificar se a sua chave privada corresponde à chave pública armazenada no GitHub Enterprise Server, gerando a impressão digital da sua chave privada e comparando-a com a impressão digital exibida no GitHub Enterprise Server.

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 GitHub App. Para obter mais informações, confira Como gerar uma chave privada.
2. Gere a impressão digital da chave privada (PEM) localmente usando o seguinte comando:

   $ openssl rsa -in PATH_TO_PEM_FILE -pubout -outform DER | openssl sha256 -binary | openssl base64

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

Apagar chaves privadas

Você pode remover ou perder uma chave privada comprometida excluindo-a, mas sempre precisa ter pelo menos uma chave privada registrada para o GitHub App. Quando o GitHub App tiver apenas uma chave, será necessário gerar uma nova antes de excluir a antiga.