Autenticación como una instalación de una aplicación de GitHub

Acerca de la autenticación como una instalación de GitHub App

Una vez que GitHub App se instala en una cuenta, puedes realizar la autenticación como una instalación de la aplicación para las solicitudes de API. Esto permite que la aplicación acceda a los recursos que son propiedad de esa instalación, siempre y cuando se haya concedido a la aplicación el acceso y los permisos necesarios del repositorio. Las solicitudes de API realizadas por una instalación de la aplicación se atribuyen a la aplicación. Para obtener más información sobre cómo instalar aplicaciones de GitHub, consulta "Instalación de aplicaciones de GitHub".

Por ejemplo, si quieres que tu aplicación cambie el campo Status de una incidencia en un proyecto que pertenece a una organización denominada "octo-org", te autenticarías como la instalación de octo-org de la aplicación. La escala de tiempo del problema indicaría que la aplicación actualizó el estado.

Para realizar una solicitud de API como instalación, primero debes generar un token de acceso de instalación. A continuación, enviarás el token de acceso de instalación en el encabezado Authorization de las solicitudes de API posteriores. También puedes usar los SDK de Octokit de GitHub, que pueden generar un token de acceso de instalación automáticamente.

Algunos puntos de conexión de la API de REST no aceptan tokens de acceso de instalación y la mayoría de los puntos de conexión de la API de REST requieren que la aplicación tenga determinados permisos para usar un punto de conexión. Para ver si un punto de conexión de la API de REST acepta tokens de acceso de instalación y para ver qué permisos son necesarios, consulte la documentación del punto de conexión.

Las instalaciones de aplicaciones también pueden usar GraphQL API. De forma similar a la API REST, la aplicación debe tener determinados permisos para acceder a objetos en GraphQL API. En el caso de las solicitudes de GraphQL, debes probar que la aplicación tiene los permisos necesarios para las consultas y mutaciones de GraphQL que deseas realizar.

También puedes usar un token de acceso de instalación para autenticarte para el acceso de Git basado en HTTP. La aplicación debe tener el permiso de repositorio "Contenido". Después, puedes usar el token de acceso de instalación como contraseña HTTP. Reemplaza TOKEN por el token de acceso de instalación: git clone https://x-access-token:TOKEN@github.com/owner/repo.git

Las solicitudes realizadas con un token de acceso de instalación a veces se denominan solicitudes de "servidor a servidor".

Para obtener más información sobre la autenticación como una aplicación en nombre de un usuario en lugar de como una instalación de la aplicación, consulta "Autenticación con una aplicación de GitHub en nombre de un usuario".

Uso de un token de acceso de instalación para autenticarte como una instalación de la aplicación

Para autenticarte como una instalación con un token de acceso de instalación, usa primero la API REST para generar un token de acceso de instalación. A continuación, usa ese token de acceso de instalación en el encabezado Authorization de una API REST o una solicitud de GraphQL API. El token de acceso de instalación expirará después de 1 hora.

Generación de un token de acceso de instalación

Genera un JSON Web Token (JWT) para la aplicación. Para más información, consulta "Generación de un JSON Web Token (JWT) para una aplicación de GitHub".
Consigue el identificador de la instalación con el que deseas autenticarte.

Si respondes a un evento de webhook, la carga del webhook incluirá el identificador de la instalación.

También puedes usar la API REST para buscar el identificador de una instalación de la aplicación. Por ejemplo, puedes obtener un identificador de instalación con los puntos de conexión GET /users/{username}/installation, GET /repos/{owner}/{repo}/installation, GET /orgs/{org}/installation o GET /app/installations. Para obtener más información, consulta "Puntos de conexión de la API de REST para GitHub Apps".

Puedes encontrar el identificador de aplicación en la página de configuración de la aplicación. El id. de la aplicación es diferente del id. de cliente. Para más información sobre cómo desplazarte a la página de configuración en tu GitHub App, consulta “Modificación del registro de una instancia de GitHub App”.
Envía una solicitud de API REST POST a /app/installations/INSTALLATION_ID/access_tokens. Incluye JSON Web Token en el encabezado Authorization de la solicitud. Reemplaza INSTALLATION_ID por el identificador de la instalación con el que deseas autenticarte.

Por ejemplo, envía esta solicitud curl. Reemplaza INSTALLATION_ID por el identificador de la instalación y JWT por JSON Web Token:
```
curl --request POST \
--url "http(s)://HOSTNAME/api/v3/app/installations/INSTALLATION_ID/access_tokens" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer JWT" \
--header "X-GitHub-Api-Version: 2022-11-28"
```
Opcionalmente, puedes utilizar los parámetros de cuerpo repositories o repository_ids para especificar repositorios individuales a los que puede acceder el token de acceso a la instalación. Si no usas repositories o repository_ids para conceder acceso a repositorios específicos, el token de acceso a la instalación tendrá acceso a todos los repositorios a los que se concedió acceso a la instalación. Al token de acceso de instalación no se le puede conceder acceso a los repositorios a los que la instalación no tuvo acceso. Es posible enumerar hasta 500 repositorios.

Opcionalmente, usa el parámetro de cuerpo permissions para especificar los permisos que debe tener el token de acceso de instalación. Si no se especifica permissions, el token de acceso de instalación tendrá todos los permisos concedidos a la aplicación. No se pueden conceder al token de acceso a la instalación permisos que la aplicación no tenía concedidos.

Al usar los parámetros permissions para reducir el acceso del token, se aumenta la complejidad de dicho token debido al número de permisos de la solicitud y al número de repositorios a los que tendrá acceso. Si la complejidad es demasiado grande, se recibirá un mensaje de error que indica el número máximo de repositorios que se pueden admitir. En este caso, se deben solicitar menos permisos con el parámetro permissions, utilizar el parámetro repositories o repository_ids para solicitar menos repositorios, o bien instalar la aplicación en repositorios all de su organización.

La respuesta incluirá un token de acceso de instalación, la hora en que expira el token, los permisos que tiene el token y los repositorios a los que puede acceder el token. El token de acceso de instalación expirará después de 1 hora.

Para obtener más información sobre este punto de conexión, consulta "Puntos de conexión de la API de REST para GitHub Apps".

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.

Autenticación con un token de acceso de instalación

Para autenticarte con un token de acceso de instalación, inclúyelo en el encabezado Authorization de la solicitud de API. El token de acceso funcionará con GraphQL API y la API REST.

La aplicación debe tener los permisos necesarios para usar el punto de conexión. Para obtener más información, vea «Elección de permisos para una aplicación de GitHub».

En el ejemplo siguiente, reemplaza INSTALLATION_ACCESS_TOKEN por un token de acceso de instalación:

curl --request GET \
--url "http(s)://HOSTNAME/api/v3/meta" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer INSTALLATION_ACCESS_TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"

Uso del SDK de Octokit.js para autenticarte como una instalación de la aplicación

Puedes usar el SDK de Octokit.js de GitHub para autenticarte como una instalación de la aplicación. Una ventaja de usar el SDK para autenticarte es que no tienes que generar un JSON Web Token (JWT) personalmente. Además, el SDK se encargará de regenerar un token de acceso a la instalación para que no tengas que preocuparte por la expiración de una hora.

Debes instalar e importar octokit para usar la biblioteca de Octokit.js. En el ejemplo siguiente se usan instrucciones import de acuerdo con ES6. Para obtener más información sobre los diferentes métodos de instalación e importación, consulta la sección Uso del archivo README de Octokit.js.

Uso de Octokit.js para autenticarte con un identificador de instalación

Obtén el identificador de GitHub App. Puedes encontrar el id. de la aplicación en la página de configuración de la GitHub App. Para más información sobre cómo desplazarte a la página de configuración en tu GitHub App, consulta "Modificación del registro de una instancia de GitHub App".
Genere una clave privada. Para más información, consulta "Administración de claves privadas para aplicaciones de GitHub".
Consigue el identificador de la instalación con el que deseas autenticarte.

Si respondes a un evento de webhook, la carga del webhook incluirá el identificador de la instalación.

También puedes usar la API REST para buscar el identificador de una instalación de la aplicación. Por ejemplo, puedes obtener un identificador de instalación con los puntos de conexión GET /users/{username}/installation, GET /repos/{owner}/{repo}/installation, GET /orgs/{org}/installation o GET /app/installations. Para más información, consulta "Puntos de conexión de la API de REST para GitHub Apps".
Importa App desde octokit. Cree una nueva instancia de App. En el ejemplo siguiente, reemplaza APP_ID por una referencia al identificador de la aplicación. Reemplaza PRIVATE_KEY por una referencia a la clave privada de la aplicación.
JavaScript
```
import { App } from "octokit";

const app = new App({
  appId: APP_ID,
  privateKey: PRIVATE_KEY,
});
```
```
import { App } from "octokit";

const app = new App({
  appId: APP_ID,
  privateKey: PRIVATE_KEY,
});
```
Usa el método getInstallationOctokit para crear una instancia autenticada de octokit. En el ejemplo siguiente, reemplaza INSTALLATION_ID por el identificador de la instalación de la aplicación en nombre de la cual quieras autenticarte.
JavaScript
```
const octokit = await app.getInstallationOctokit(INSTALLATION_ID);
```
```
const octokit = await app.getInstallationOctokit(INSTALLATION_ID);
```
Usa un método octokit para realizar una solicitud a la API.

La aplicación debe tener los permisos necesarios para usar el punto de conexión. Para obtener más información, vea «Elección de permisos para una aplicación de GitHub».

Por ejemplo, para realizar una solicitud a GraphQL API:
JavaScript
```
await octokit.graphql(`
  query {
    viewer {
      login
    }
  }
  `)
```
```
await octokit.graphql(`
  query {
    viewer {
      login
    }
  }
  `)
```
Por ejemplo, para realizar una solicitud a la API REST:
JavaScript
```
await octokit.request("GET /meta")
```
```
await octokit.request("GET /meta")
```

Uso de Octokit.js para autenticarte en respuesta a un evento de webhook

El SDK de Octokit.js también pasa una instancia octokit autenticada previamente a los controladores de eventos de webhook.

Obtén el identificador de GitHub App. Puedes encontrar el id. de la aplicación en la página de configuración de la GitHub App. Para más información sobre cómo desplazarte a la página de configuración en tu GitHub App, consulta "Modificación del registro de una instancia de GitHub App".
Genere una clave privada. Para más información, consulta "Administración de claves privadas para aplicaciones de GitHub".
Consigue el secreto de webhook que especificaste en la configuración de la aplicación. Para más información sobre las cargas útiles de webhooks, consulta "Uso de webhooks con aplicaciones de GitHub".
Importa App desde octokit. Cree una nueva instancia de App. En el ejemplo siguiente, reemplaza APP_ID por una referencia al identificador de la aplicación. Reemplaza PRIVATE_KEY por una referencia a la clave privada de la aplicación. Reemplaza WEBHOOK_SECRET por el secreto de webhook de la aplicación.
JavaScript
```
import { App } from "octokit";

const app = new App({
  appId: APP_ID,
  privateKey: PRIVATE_KEY,
  webhooks: { WEBHOOK_SECRET },
});
```
```
import { App } from "octokit";

const app = new App({
  appId: APP_ID,
  privateKey: PRIVATE_KEY,
  webhooks: { WEBHOOK_SECRET },
});
```

Usa un método app.webhooks.* para controlar eventos de webhook. Para obtener más información, consulta la sección Webhooks del LÉAME de Octokit.js. Por ejemplo, para crear un comentario sobre un problema cuando se abre la incidencia:

app.webhooks.on("issues.opened", ({ octokit, payload }) => {
  await octokit.request("POST /repos/{owner}/{repo}/issues/{issue_number}/comments", {
      owner: payload.repository.owner.login,
      repo: payload.repository.name,
      issue_number: payload.issue.number,
      body: `This is a bot post in response to this issue being opened.`,
      headers: {
        "x-github-api-version": "2022-11-28",
      },
    }
  )
});