Skip to main content

Autenticar com os aplicativos GitHub

Você pode efetuar a autenticação como uma GitHub App ou como uma instalação.

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, 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.

    Ícone Settings (Configurações) na barra de usuário

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

  3. Na barra lateral esquerda, clique em Aplicativos do GitHub. Seção Aplicativos do GitHub 1. À direita do GitHub App que você deseja modificar, clique em Editar. Seleção do aplicativo

  4. Em "Chaves privadas", clique em Gerar uma chave privada. Gerar 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.

Observação: se você estiver usando uma biblioteca que exija um formato de arquivo específico, o arquivo PEM que você baixar estará no formato PKCS#1 RSAPrivateKey.

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. Impressão digital de 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 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. Exclusão da última chave privada

Efetuar a autenticação um GitHub App

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

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

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 verifica se a solicitação foi autenticada, fazendo a verificação do token com a chave pública armazenada pelo aplicativo.

Como gerar um JWT (Token Web JSON)

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.

python
#!/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.6/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".

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. Certifique-se de que você já instalou o aplicativo GitHub em pelo menos um repositório; é impossível criar um token de instalação sem uma única instalação. Estes tokens de acesso de instalação são usados por GitHub Apps para efetuar a autenticação. Para obter mais informações, confira "Como instalar Aplicativos do GitHub".

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

Para listar as instalações de um aplicativo autenticado, inclua o JWT gerado acima no cabeçalho Authorization na solicitação de API:

$ 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".

Para criar um token de acesso de instalação, inclua o JWT gerado acima no cabeçalho Authorization na solicitação de API e substitua :installation_id pela id da instalação:

$ 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 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: Bearer YOUR_INSTALLATION_ACCESS_TOKEN" \
-H "Accept: application/vnd.github+json" \
http(s)://HOSTNAME/api/v3/installation/repositories

YOUR_INSTALLATION_ACCESS_TOKEN é o valor que você precisará substituir.

Observação: Na maioria dos casos, você pode usar Authorization: Bearer ou Authorization: token a fim de passar um token. No entanto, se estiver passando um JWT (token Web JSON), você deverá usar Authorization: Bearer.

Acessar pontos finais da API como uma instalação

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

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