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. Selecciona la GitHub App que quieres modificar.
   
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 Enterprise genera una huella digital para cada par de llaves pública y privada utilizando una función de hash SHA-1. Puedes verificar que tu llave privada empate con la llave pública almacenada en GitHub Enterprise generando la huella digital de tu llave privada y comparándola con la huella digital que se muestra en GitHub Enterprise.

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 App GitHub. 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 sha1 -c

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

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 App GitHub

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

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

Para autenticarte como una App GitHub, 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 Enterprise 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
  iat: Time.now.to_i,
  # JWT expiration time (10 minute maximum)
  exp: Time.now.to_i + (10 * 60),
  # App GitHub'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.

Utiliza tu identificador de App GitHub (YOUR_APP_ID) como el valor para la solicitud del iss (emisor) del JWT. Puedes obtener el identificador de App GitHub 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.machine-man-preview+json" http(s)://[hostname]/api/v3/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://developer.github.com/enterprise/enterprise-server@2.19/v3"
}

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

Acceder a terminales de API como una App GitHub

Para obtener una lista de las terminales de API de REST que puedes utilizar para obtener información de alto nivel acerca de una App GitHub, 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. Las App GitHub utilizan estos tokes de acceso a la instalación para autenticarse.

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 App GitHub y caducan después de una hora.

Para crear un token de acceso de instalación, incluye el JWT previamente generado en el encabezado de autorización en la solicitud de la API:

$ curl -i -X POST \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github.machine-man-preview+json" \
http(s)://[hostname]/api/v3/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.machine-man-preview+json" \
http(s)://[hostname]/api/v3/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 App GitHub 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