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. No canto superior direito de qualquer página, clique na sua foto de perfil e, em seguida, clique em Configurações.

   

2. Na barra lateral esquerda, clique em Developer settings (Configurações do desenvolvedor).

3. Na barra lateral esquerda, clique em Aplicativos GitHub.

4. To the right of the aplicativo GitHub you want to modify, click Edit.

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

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 Server 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

# 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),
  # 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. Certifique-se de incluir os valores entre aspas duplas.

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.v3+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') must be a numeric value representing the future time at which the assertion expires.",
  "documentation_url": "https://docs.github.com/enterprise/3.1/rest"
}

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. 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 Aplicativos do GitHub para efetuar a autenticação. Para obter mais informações, consulte "Instalando aplicativos 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. É 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 listar as instalações para um aplicativo autenticado, inclua o JWT gerado acima no cabeçalho de autorização no pedido da API:

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

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

Para criar um token de acesso de instalação, inclua o JWT gerado acima no cabeçalho Autorização no pedido de API e substitua :installation_id pelo id da instalação da instalação:

$ curl -i -X POST \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github.v3+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.v3+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 de extremidade da API REST disponíveis para uso por Aplicativos do GitHub usando um token de acesso de instalação, consulte "pontos de extremidade 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