Skip to main content

Identificación y autorización de usuarios para aplicaciones de GitHub

Tu GitHub App puede realizar acciones en nombre de un usuario, como crear un informe de problemas, crear un despliegue, y utilizar otras terminales compatibles.

Cuando tu GitHub App actúe en nombre de un usuario, ésta realiza solicitudes de usuario a servidor. Estas solicitudes deben autorizarse con un token de acceso de usuario. Las solicitudes de usuario a servidor incluyen el solicitar datos para un usuario, como el determinar qué repositorios mostrar a un usuario en particular. Estas solicitudes también incluyen las acciones que activa un usuario, como ejecutar una compilación.

Para mantener más seguros los tokens de acceso de usuario a servidor, puedes utilizar tokens de acceso que caducarán después de 8 horas, y un token de actualización que se puede intercambiar por un token de acceso nuevo. Para obtener más información, consulte "Actualizar los tokens de acceso de usuario a servidor".

Identificar usuarios en tu sitio

A fin de autorizar a los usuarios para las aplicaciones estándar que se ejecutan en el buscador, use el flujo de aplicaciones web.

A fin de autorizar a los usuarios para aplicaciones sin interfaz gráfica sin acceso directo al buscador, como las herramientas de CLI o administradores de credenciales de Git, use el flujo de dispositivos. En el flujo de dispositivos se usa la concesión de autorización de dispositivos de OAuth 2.0.

Flujo de aplicaciones Web

Al utilizar el flujo de aplicaciones web, el proceso para identificar a los usuarios en tu sitio es:

  1. Se redirecciona a los usuarios para solicitar su identidad de GitHub
  2. GitHub redirecciona a los usuarios de vuelta a tu sitio
  3. Tu GitHub App accede a la API con el token de acceso del usuario

Si selecciona Solicitar la autorización del usuario (OAuth) durante la instalación al crear o modificar la aplicación, el paso 1 se completará durante la instalación de la aplicación. Para más información, vea "Autorización de usuarios durante la instalación".

1. Solicitud de la identidad de un usuario de GitHub

Dirige al usuario a la siguiente URL en su buscador:

GET https://github.com/login/oauth/authorize

Cuando la aplicación de GitHub especifica un parámetro login, solicita a los usuarios a una cuenta específica que pueden utilizar para iniciar sesión y autorizar la aplicación.

Parámetros

NombreTipoDescripción
client_idstringObligatorio. Id. de cliente de la aplicación de GitHub. Puede encontrarlo en la configuración de la aplicación de GitHub al seleccionarla. Nota: El id. de la aplicación y el id. de cliente no son iguales y tampoco son intercambiables.
redirect_uristringLa URL en tu aplicación a donde se enviará a los usuarios después de la autorización. Esto debe ser una coincidencia exacta con una de las URL que ha proporcionado como URL de devolución de llamada al configurar la aplicación de GitHub y no puede contener ningún parámetro adicional.
statestringEste deberá contener una secuencia aleatoria para dar protección contra los ataques de falsificación y podría contener cualquier otros datos arbitrarios.
loginstringSugiere una cuenta específica para utilizar para registrarse y autorizar la app.
allow_signupstringYa sea que se ofrezca no una opción para que los usuarios autenticados se registren para GitHub durante el flujo de OAuth. El valor predeterminado es true. Use false cuando una directiva prohíba los registros.

Nota: No es necesario proporcionar ámbitos en la solicitud de autorización. A diferencia de la OAuth trandicional, el token de autorizción se limita a los permisos asociados con tu GitHub App y a aquellos del usuario.

2. GitHub redirecciona a los usuarios de vuelta al sitio

Si el usuario acepta la solicitud, GitHub le redirecciona de vuelta al sitio con un valor code temporal en un parámetro de código así como con el estado que haya proporcionado en el paso anterior en un parámetro state. Si los estados no coinciden significa que un tercero creó la solicitud y que se debe anular el proceso.

Nota: Si selecciona Solicitar autorización de usuario (OAuth) durante la instalación al crear o modificar la aplicación, GitHub devuelve un valor code temporal que tendrá que intercambiar por un token de acceso. El parámetro state no se devuelve cuando GitHub inicia el flujo de OAuth durante la instalación de la aplicación.

Intercambie este valor code por un token de acceso. Cuando se habilita el vencimiento de tokens, el token de acceso vence en 8 horas y el token de actualización en 6 meses. Cada que actualizas el token, obtienes un nuevo token de actualización. Para más información, vea "Actualización de tokens de acceso de usuario a servidor".

Los tokens de usuario con vigencia determinada son una característica opcional actualmente y están sujetos a cambios. Para participar en la característica de expiración de tokens de usuario a servidor, vea "Activación de características opcionales para aplicaciones".

Haz una solicitud a la siguiente terminal para recibir un token de acceso:

POST https://github.com/login/oauth/access_token

Parámetros

NombreTipoDescripción
client_idstringObligatorio. Id. de cliente de la aplicación de GitHub.
client_secretstringObligatorio. Secreto de cliente de la aplicación de GitHub.
codestringObligatorio. Código que ha recibido como respuesta al paso 1.
redirect_uristringLa URL en tu aplicación a donde se enviará a los usuarios después de la autorización. Esto debe ser una coincidencia exacta con una de las URL que ha proporcionado como URL de devolución de llamada al configurar la aplicación de GitHub y no puede contener ningún parámetro adicional.

Response

Predeterminadametne, la respuesta lleva el siguiente formato. Los parámetros de respuesta expires_in, refresh_token y refresh_token_expires_in solo se devuelven cuando se habilitan los tokens de acceso de usuario a servidor que expiran.

{
  "access_token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a",
  "expires_in": 28800,
  "refresh_token": "ghr_1B4a2e77838347a7E420ce178F2E7c6912E169246c34E1ccbF66C46812d16D5B1A9Dc86A1498",
  "refresh_token_expires_in": 15811200,
  "scope": "",
  "token_type": "bearer"
}

3. La aplicación de GitHub accede a la API con el token de acceso del usuario

El token de acceso del usuario permite que la GitHub App haga solicitudes a la API a nombre del usuario.

Authorization: Bearer OAUTH-TOKEN
GET https://api.github.com/user

Por ejemplo, en curl, puedes configurar el encabezado de autorización de la siguiente manera:

curl -H "Authorization: Bearer OAUTH-TOKEN" https://api.github.com/user

Flujo de dispositivos

Nota: El flujo de dispositivos se encuentra en versión beta pública y está sujeto a cambios.

Este flujo de dispositivos te permite autorizar usuarios para una app sin encabezado, tal como una herramienta de CLI o un administrador de credenciales de Git.

Antes de que puedas utilizar el flujo de dispositivos para identificar y autorizar usuarios, primero debes habilitarlo en la configuración de la aplicación. Para más información sobre cómo habilitar el flujo de dispositivos, vea "Modificación de una aplicación de GitHub". Para más información sobre cómo autorizar a los usuarios mediante el flujo de dispositivos, vea "Autorización de aplicaciones de OAuth".

Revisar a qué recursos de instalación puede acceder un usuario

Ya que tengas un token de OAuth para un usuario, puedes revisar a qué instalaciones puede acceder.

Authorization: Bearer OAUTH-TOKEN
GET /user/installations

También puedes verificar qué repositorios se encuentran accesibles para un usuario para una instalación.

Authorization: Bearer OAUTH-TOKEN
GET /user/installations/:installation_id/repositories

Puede encontrar más detalles en: Enumeración de las instalaciones de aplicaciones accesibles para el token de acceso de usuario y Enumeración de repositorios accesibles para el token de acceso de usuario.

Gestionar una autorización revocada a una GitHub App

Si un usuario revoca su autorización de una aplicación de GitHub, la aplicación recibirá el webhook github_app_authorization de forma predeterminada. Las GitHub Apps no pueden desuscribirse de este evento. Cualquiera puede revocar su autorización de una aplicación de GitHub desde su página de configuración de cuenta de GitHub. Revocar la autorización de una GitHub App no la desinstalará. Debes programar tu GitHub App para que cuando reciba su webhook deje de llamar a la API en nombre de la persona que revocó el token. Si la aplicación de GitHub sigue usando un token de acceso revocado, recibirá el error 401 Bad Credentials.

Permisos a nivel de usuario

Puede agregar permisos de nivel de usuario a la aplicación de GitHub para acceder a los recursos del usuario, como los correos electrónicos, que conceden usuarios independientes como parte del flujo de autorización de usuarios. Los permisos de nivel de usuario difieren de los permisos de nivel de organización y repositorio, que se conceden en el momento de la instalación en una cuenta personal o de la organización.

Puede seleccionar permisos de nivel de usuario desde la configuración de la aplicación de GitHub en la sección Permisos de usuario de la página Permisos y webhooks. Para más información sobre cómo seleccionar permisos, vea "Edición de permisos de una aplicación de GitHub".

Cuando un usuario instala tu app en su cuenta, el aviso de instalación listará los permisos a nivel de usuario que tu app está solicitando y explicará que la app puede pedir estos permisos a los usuarios independientes.

Ya que los permisos a nivel de usuario se otorgan individualmente, puedes agregarlos a tu app existente sin solicitar que los usuarios los mejoren. Sin embargo, necesitarás enviar usuarios existentes a través del flujo de autorización de usuarios para autorizar los permisos nuevos y obtener un token nuevo de usuario a servidor para estas solicitudes.

Solicitudes de usuario a servidor

Mientras que la mayoría de tu interacción con la API deberá darse utilizando tus tokens de acceso a la instalación de servidor a servidor, ciertas terminales te permiten llevar a cabo acciones a través de la API utilizando un token de acceso. La aplicación puede realizar las siguientes solicitudes mediante puntos de conexión GraphQL o REST.

Terminales compatibles

Ejecutores de Acciones

Secretos de las Acciones

Artifacts

Ejecuciones de Verificación

Conjuntos de Verificaciones

Códigos de Conducta

Estados de Despliegue

Implementaciones

Eventos

Fuentes

Blobs de Git

Confirmaciones de GIT

Referencias de Git

Matrículas de Git

Árboles de Git

Plantillas de Gitignore

Instalaciones

Límites de interacción

Asignados de Informes de Problemas

Comentarios de Informes de Problemas

Eventos de Informe de Problemas

Línea de tiempo del Informe de Problemas

Issues

Trabajos

Etiquetas

Licencias

Markdown

Meta

Hitos

Ganchos de organización

Invitaciones a las Organizaciones

Miembros de la Organización

Colaboradores Externos de una Organización

Poyectos de Equipo de una Organización

Repositorios de Equipo de la Organización

Sincronización de Equipos de la Organización

Equipos de la Organización

Las organizaciones

Autorizaciones de Credencial para las Organizaciones

Scim de las Organizaciones

Importaciones de Código Fuente

Colaboradores de Proyecto

Proyectos

Comentarios de Extracción

Eventos de Revisión en Solciitudes de Extracción

Solicitudes de Revisión para Solicitudes de Extracción

Revisiones de Solicitudes de Extracción

Extracciones

Reacciones

Repositorios

Actividad del Repositorio

Correcciones de Seguridad Automatizadas de un Repositorio

Ramas de los Repositorios

Colaboradores del Repositorio

Comentarios de Confirmaciones de un Repositorio

Confirmaciones de Repositorio

Comunidad del Repositorio

Contenido de los Repositorios

Envíos de Evento de un Repositorio

Ganchos de Repositorio

Invitaciones a un repositorio

Claves de Repositorio

Páginas de Repositorio

Lanzamientos de repositorio

Estadísticas de Repositorio

Alertas de Vulnerabilidad en Repositorios

Root

Estados

Debates de Equipo

Temas

Tráfico

Bloquear Usuarios

Correos electrónicos de usuario

Seguidores del Usuario

Utilizar Llaves Gpg

Llaves Públicas de Usuario

Usuarios

Ejecuciones de Flujo de Trabajo

Workflows

Información adicional