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 comprobar que una clave privada coincide con una clave pública, consulta Verificación de claves privadas.

Para generar una llave privada:

1. En la esquina superior derecha de cualquier página, haga clic en la foto del perfil y, luego, en Settings (Configuración).

   

2. In the left sidebar, click Developer settings.

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

4. En "Claves privadas", haz clic en Generar una clave privada.

5. 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 más información, vea Generación de una clave privada.
2. 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

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 GitHub App, genera una clave privada en formato PEM y descárgala en la máquina local. Usarás esta clave para firmar un token web JSON (JWT) y codificarlo mediante 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. Ten en cuenta que tendrás que ejecutar gem install jwt antes de usarla.

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.

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 el ejemplo anterior 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".

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 "Instalar 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 ámbito del token de acceso de instalación a repositorios específicos mediante el parámetro repository_ids. Para más información, consulta Creación de un token de acceso de instalación para un punto de conexión de aplicación. Los tokens de acceso de instalación cuentan con permisos configurados por la GitHub App y caducan después de una hora.

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

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

Para crear un token de acceso de instalación, incluye el JWT generado anteriormente en el encabezado de autorización de la solicitud de API y reemplaza :installation_id por el valor de id de la instalación:

$ 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úyela en el encabezado de Autorización en la solicitud de la API:

$ curl -i \
-H "Authorization: Bearer YOUR_INSTALLATION_ACCESS_TOKEN" \
-H "Accept: application/vnd.github+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 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 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