Autenticarse con GitHub Apps

Generar una llave privada

Después de que creas una GitHub App, necesitarás generar una o más llaves privadas. Utilizarás la llave privada para firmar las solicitudes de token de acceso.

Puedes crear varias llaves privadas y rotarlas para prevenir el tiempo de inactividad si alguna llave se pone en riesgo o se pierde. Para verificar que una llave privada empata con una llave pública, consulta la sección Verificar llaves privadas.

Para generar una llave privada:

1. En la esquina superior derecha de cualquier página, da clic en tu foto de perfil y después da clic en Configuración.
2. En la barra lateral izquierda, haz clic en Developer settings (Parámetros del desarrollador).
3. En la barra lateral izquierda, da clic en GitHub Apps.
4. A la derecha del GitHub App que quieres modificar, haz clic en Editar.
5. En "Llaves privadas", da clic en Generar una llave privada.
6. 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.

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:

1. 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 obtener más información, consulta la sección Generar una llave privada.
2. Genera la huella digital de tu llave privada (PEM) localmente utilizando el siguiente comando:

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

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

Borra las llaves privadas

Puedes eliminar una llave privada que se haya perdido o puesto en riesgo si la borras, pero debes de tener por lo menos una llave privada. Cuando solo tienes una llave, necesitas generar una nueva antes de borrar la anterior.

Autenticarse como una GitHub App

El autenticarte como una GitHub App te permite hacer un par de cosas:

• Puedes recuperar información administrativa de alto nivel acerca de tu GitHub App.
• Puedes solicitar tokens de acceso para una instalación de la app.

Para autenticarte como una GitHub App, genera una llave privada en formato PEM y descárgala a tu máquina local. Utilizarás esta llave para firmar un Token Web (JWT) de JSON y cifrarlo utilizando el algoritmo RS256. GitHub revisa que la solicitud se autentique verificando el token con la llave pública almacenada de la app.

Aquí se muestra rápidamente un script de Ruby que puedes utilizar para generar un JWT. Nota que tendrás que ejecutar gem install jwt antes de utilizarlo.

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

YOUR_PATH_TO_PEM y YOUR_APP_ID son los valores que debes reemplazar. Asegúrate de poner los valores entre comillas dobles.

Utiliza tu identificador de GitHub App (YOUR_APP_ID) como el valor para la solicitud del iss (emisor) del JWT. Puedes obtener el identificador de GitHub App a través del ping del webhook inicial después de crear la app, o en cualquier momento desde la página de configuración de la app en la UI de GitHub.com.

Después de crear el JWT, configura el Header de la solicitud de la API:

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

YOUR_JWT es el valor que debes reemplazar.

El ejemplo anterior utiliza el tiempo de caducidad máximo de 10 minutos, después del cual, la API comenzará a devolver el 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 obtener una lista de las terminales de API de REST que puedes utilizar para obtener información de alto nivel acerca de una GitHub App, consulta la sección "GitHub Apps".

Autenticarse como una instalación

El autenticarte como una instalación te permite realizar acciones en la API para dicha instalación. Antes de autenticarte como una instalación, debes crear un token de acceso a ésta. Asegúrate de que ya hayas instalado tu GitHub App en por lo menos un repositorio; es imposible crear un token de instalación si una sola instalación. Las GitHub Apps utilizan estos tokens de acceso a la instalación para autenticarse. Para obtener más información, consulta la sección "Instalar las GitHub Apps".

Predeterimenadamente, los tokens de acceso de instalación tienen un alcance de todos los repositorios a los cuales tiene acceso dicha instalación. Puedes limitar el alcance del token de acceso de la instalación a repositorios específicos si utilizas el parámetro repository_ids. Consulta la terminal Crear un token de acceso de instalación para una app para encontrar más detalles. Los tokens de acceso de instalación cuentan con permisos configurados por la GitHub App y caducan después de una hora.

Para listar las instalaciones para una app autenticada, incluye el JWT generado anteriormente en el encabezado de autorización en la solicitud de la API:

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

La respuesta incluirá una lista de instalaciones en donde cada id de instalación pueda utilizarse para crear un token de acceso a la instalación. Para obtener más información acerca del formato de respuesta, consulta la "Lista de instalaciones para la app autenticada".

Para crear un token de acceso a la instalación, incluye el JWT que se generó anteriormente en el encabezado de autorización en la solicitud de la API y reemplaza a :installation_id con la id de la instalación:

$ curl -i -X POST \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github.v3+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 obtener más información acerca del formato de respuesta, consulta la terminal Crear un token de acceso de instalación para una app.

Para autenticarte con un token de acceso de instalación, inclúyela en el encabezado de Autorización en la solicitud de la API:

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

YOUR_INSTALLATION_ACCESS_TOKEN es el valor que debes reemplazar.

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

Para encontrar un listado de las terminales de la API de REST disponibles para utilizarse con las GitHub Apps utilizando un token de acceso de instalación, consulta la sección "Terminales Disponibles".

Para encontrar un listad de terminales relacionado con las instalaciones, consulta la sección "Instalaciones".

Acceso a Git basado en HTTP mediante una instalación

Las instalaciones con permisos en los contents de un repositorio pueden utilizar su token de acceso de instalación para autenticarse para acceso a 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