Autenticarse con GitHub Apps

Autenticarse como una GitHub App

La autenticación como una GitHub App es necesaria para las llamadas API server-to-server, lo que permite a tu GitHub App realizar varias acciones:

Recuperar información de administración de alto nivel acerca de tu GitHub App.
Solicitar tokens de acceso para una instalación de la aplicación, lo que te permite realizar llamadas API sin un usuario que haya iniciado sesión.

Para autenticarte como GitHub App, genera una clave privada en formato PEM y descárgala en la máquina local. Usarás esta clave para firmar un JSON Web Token (JWT) y codificarlo mediante el algoritmo RS256. GitHub valida la identidad de tu aplicación verificando el token con la llave pública almacenada de la app. Intercambiarás este token JWT por un token de instalación, que se usará para autenticar tu aplicación como una instalación específica.

Enumeración de las instalaciones de una aplicación

Para enumerar las instalaciones de tu aplicación, incluye el JWT en el encabezado de autorización de una solicitud de API a GET /app/installations. Para obtener más información sobre cómo generar un token JWT, consulta "Carga útil de JWT".

$ curl -i -X GET \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github+json" \
https://api.github.com/app/installations

La respuesta incluirá una lista de instalaciones en las que se puede usar el valor de id de cada instalación para crear un token de acceso de instalación. Para más información sobre el formato de respuesta, consulta "Enumeración de instalaciones para la aplicación autenticada".

Autenticarse como una instalación

La autenticación como una instalación permite a la aplicación acceder a esa organización o ese usuario a través de la API, así como a los recursos públicos en GitHub. Para autenticarte como una instalación, debes usar un token de acceso de instalación, que obtendrás enviando un token JWT a GitHub para probar la identidad de la aplicación. Asegúrate de que ya has instalado tu aplicación de GitHub por lo menos en una organización o una cuenta de usuario; es imposible crear un token de instalación si una instalación. Para obtener más información, consulta "Instalar GitHub Apps."

De manera predeterminada, el ámbito de los tokens de acceso de instalación está limitado a todos los repositorios a los cuales se ha concedido acceso a una instalación. Puedes limitar más el ámbito del token de acceso de instalación a repositorios específicos mediante el parámetro repository_ids. Los tokens de acceso de instalación tienen los permisos configurados por la GitHub App y, como el acceso al repositorio, también se pueden limitar mediante el parámetro permissions. Para obtener más información, consulta Creación de un token de acceso de instalación para un punto de conexión de aplicación en la documentación sobre los puntos de conexión. Los tokens de instalación expiran en 1 hora.

Para crear un token de acceso de instalación, incluye el JWT en el encabezado de autorización de la solicitud de API y reemplaza :installation_id por el valor de id de la instalación. Para obtener más información sobre cómo generar un token JWT, consulta "Carga útil de JWT".

$ curl -i -X POST \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github+json" \
https://api.github.com/app/installations/:installation_id/access_tokens

La respuesta incluirá tu token de acceso de instalación, la fecha de caducidad, los permisos del token, y los repositorios a los cuales tiene acceso. Para más información sobre el formato de respuesta, consulta Creación de un token de acceso de instalación para un punto de conexión de aplicación.

Para autenticarte con un token de acceso de instalación, inclúyelo en el encabezado de autorización de la solicitud de API. Reemplaza YOUR_INSTALLATION_ACCESS_TOKEN por un token de acceso de instalación:

$ curl -i \
-H "Authorization: Bearer YOUR_INSTALLATION_ACCESS_TOKEN" \
-H "Accept: application/vnd.github+json" \
https://api.github.com/installation/repositories

Nota: En la mayoría de los casos, puedes usar Authorization: Bearer o Authorization: token para pasar un token. Sin embargo, si vas a pasar un token web JSON (JWT), debes usar Authorization: Bearer.

Acceder a las terminales de la API como una instalación

Para ver una lista de los puntos de conexión de la API REST que están disponibles para su uso por GitHub Apps mediante un token de acceso de instalación, consulta "Puntos de conexión disponibles para aplicaciones de GitHub".

Para ver una lista de los puntos de conexión relacionados con las instalaciones, consulta "Instalaciones".

Acceso a Git basado en HTTP mediante una instalación

Las instalaciones con permisos en el elemento contents de un repositorio pueden usar sus tokens de acceso de instalación para autenticarse para el acceso de Git. Utiliza el token de acceso de instalación como la contraseña HTTP:

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

Generación de un JSON Web Token (JWT)

El token JWT que se usa para autenticar tu aplicación se compone de varias notificaciones, así como de una firma que se usa para validar su autenticidad. Estas notificaciones son:

Notificación	Significado	Detalles
`iat`	Emitido a las	La hora a la que se creó el JWT. Para evitar un desfase del reloj, se recomienda establecer este valor 60 segundos antes de la hora en cuestión.
`exp`	Expira a las	La hora de expiración del JWT, después de la cual no se puede usar para solicitar un token de instalación. El valor de `exp` debe ser máximo 10 minutos después.
`iss`	Emisor	El identificador de la aplicación, el cual se usa para buscar la clave pública correcta para comprobar la firma del JWT.

Los tokens deben firmarse mediante el algoritmo RS256, con la correspondiente notificación alg de RS256.

Uso de Ruby

Aquí se muestra un script de Ruby que puedes utilizar para generar un JWT. Ten en cuenta que tendrás que ejecutar gem install jwt antes de usarla. YOUR_PATH_TO_PEM y YOUR_APP_ID son los valores que debes reemplazar. Asegúrate de poner los valores entre comillas dobles.

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

Usar Python

Este es un script similar para generar un JWT en Python. Ten en cuenta que tendrás que usar pip install jwt para utilizar este script. Este script te pedirá la ubicación del archivo PEM y el id. de la aplicación, o puedes pasarlo como argumentos insertados al ejecutar el 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)

Usa el identificador de GitHub App (YOUR_APP_ID) como valor de la notificación de JWT iss (emisor). Puedes obtener el identificador de GitHub App a través del ping de webhook inicial después de crear la aplicación o en cualquier momento desde la página de configuración de la aplicación en la interfaz de usuario de GitHub.com.

Después de crear el JWT, establécelo en el elemento Header de la solicitud de API:

$ curl -i -H "Authorization: Bearer YOUR_JWT" -H "Accept: application/vnd.github+json" https://api.github.com/app

YOUR_JWT es el valor que debes reemplazar.

En los ejemplos anteriores se usa el tiempo de expiración máximo de 10 minutos, después del cual la API comenzará a devolver un error 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/rest"
}

Necesitarás crear un nuevo JWT después de que el tiempo caduque.

Acceder a terminales de API como una GitHub App

Para ver una lista de los puntos de conexión de la API REST que puedes usar para obtener información de alto nivel sobre una GitHub App, consulta "Aplicaciones de GitHub".

Generar una llave privada

Después de crear una GitHub App, deberás generar una o varias claves privadas para realizar solicitudes a la API de GitHub como la propia aplicación. Usarás la clave privada para firmar los JWT usados para solicitar un token de acceso de instalación.

Puedes crear varias llaves privadas y rotarlas para prevenir el tiempo de inactividad si alguna llave se pone en riesgo o se pierde. Para comprobar que una clave privada coincide con una clave pública, consulta Verificación de claves privadas.

Para generar una llave privada:

En la esquina superior derecha de cualquier página, haga clic en la foto del perfil y, luego, en Settings (Configuración).
En la barra lateral izquierda, haga clic en Developer settings (Configuración de desarrollador).
En la barra lateral izquierda, haga clic en GitHub Apps (Aplicaciones de Github). 1. A la derecha de la GitHub App que desea modificar, haga clic en Edit.
En "Claves privadas", haz clic en Generar una clave privada.
Verás una llave privada en formato PEM que se descarga en tu ordenador. Asegúrate de almacenar este archivo, ya que GitHub solo almacena la porción pública de la llave.

Nota: Si usas una biblioteca que requiere un formato de archivo específico, el archivo PEM que descargues estará en formato PKCS#1 RSAPrivateKey.

Verificar las llaves privadas

GitHub genera una huella digital para cada par de llaves pública y privada utilizando la función de hash SHA-256. Puedes verificar que tu llave privada empate con la llave pública almacenada en GitHub generando la huella digital de tu llave privada y comparándola con la huella digital que se muestra en GitHub.

Para verificar una llave privada:

Encuentra la huella digital del par de llaves pública y privada que quieras verificar en la sección "Llaves privadas" de tu página de configuración de desarrollador de GitHub App. Para más información, vea Generación de una clave privada.

Genera la huella digital de tu clave privada (PEM) localmente utilizando el siguiente comando:

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

Compara los resultados de la huella digital generada localmente con aquella que ves en GitHub.

Borra las llaves privadas

Puedes quitar una clave privada que se haya perdido o puesto en riesgo eliminándola, pero siempre debes de tener al menos una clave privada registrada para tu GitHub App. Si tu GitHub App solo tiene una clave, deberás generar una nueva antes de eliminar la antigua. Eliminación de la última clave privada