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:
-
En la esquina superior derecha de cualquier página, da clic en tu foto de perfil y después da clic en Configuración.
-
En la barra lateral izquierda, haz clic en Developer settings (Parámetros del desarrollador).
-
En la barra lateral izquierda, da clic en GitHub Apps.
-
A la derecha del GitHub App que quieres modificar, haz clic en Editar.
-
En "Llaves privadas", da clic en Generar una llave 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 estás utilizando una biblioteca que requiere de un formato de archivo específico, el archivo PEM que descargues se encontrará en formato PKCS#1 RSAPrivateKey
.
Verificar las llaves privadas
GitHub Enterprise Server 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 Enterprise Server generando la huella digital de tu llave privada y comparándola con la huella digital que se muestra en GitHub Enterprise Server.
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 obtener más información, consulta la sección Generar una llave privada.
- 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
- Compara los resultados de la huella digital generada localmente con aquella que ves en GitHub Enterprise Server.
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 Enterprise Server 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" 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://docs.github.com/enterprise/3.1/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" \
http(s)://[hostname]/api/v3/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" \
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.v3+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 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