Generación de un token de acceso de usuario para una aplicación de GitHub

Acerca de los tokens de acceso de usuario

Un token de acceso de usuario es un tipo de token de OAuth. A diferencia de un token de OAuth tradicional, el token de acceso de usuario no usa ámbitos. En su lugar, usa permisos específicos. Un token de acceso de usuario solo tiene los permisos que el usuario y la aplicación tienen. Por ejemplo, si se ha concedido permiso a la aplicación para escribir el contenido de un repositorio, pero el usuario solo puede leerlo, el token de acceso de usuario solo puede leer el contenido.

Del mismo modo, un token de acceso de usuario solo puede acceder a los recursos a los que el usuario y la aplicación pueden acceder. Por ejemplo, si se concede acceso a una aplicación al repositorio A y B, y el usuario puede acceder al repositorio B y C, el token de acceso de usuario puede acceder al repositorio B, pero no A ni a C. Puedes usar la API REST para comprobar a qué instalaciones y qué repositorios de una instalación puede acceder un token de acceso de usuario. Para más información, consulta GET /user/installations y GET /user/installations/{installation_id}/repositories en Puntos de conexión de la API de REST para instalaciones de GitHub Apps.

Al realizar solicitudes de API con un token de acceso de usuario, se aplican los límites de frecuencia de los tokens de acceso de usuario. Para más información, consulta Límites de frecuencia para aplicaciones de GitHub.

De manera predeterminada, el token de acceso de usuario expira después de ocho horas. Puedes usar un token de actualización para regenerar un token de acceso de usuario. Para más información, consulta Actualización de tokens de acceso de usuario.

Los usuarios pueden revocar su autorización de una instancia de GitHub App. Para más información, consulta Vencimiento y revocación de tokens. Si un usuario revoca su autorización de una instancia de GitHub App, la aplicación recibirá el webhook github_app_authorization. Las instancias de GitHub Apps no pueden cancelar la suscripción a este evento. Si la aplicación recibe este webhook, debes dejar de llamar a la API en nombre del usuario que ha revocado el token. Si la aplicación sigue usando un token de acceso revocado, recibirá el error 401 Bad Credentials. Para más información sobre este webhook, consulta Eventos y cargas de webhook.

Debes mantener protegidos los tokens de acceso de usuario y los tokens de actualización. Para más información, consulta Procedimientos recomendados para crear una aplicación de GitHub.

Uso del flujo de aplicación web para generar un token de acceso de usuario

Si la aplicación se ejecuta en el explorador, debes usar el flujo de aplicación web para generar un token de acceso de usuario. Para ver un tutorial sobre el uso del flujo de aplicaciones web, consulta Creación de un botón "Inicio de sesión con GitHub" con una aplicación de GitHub.

1. Dirige al usuario a esta URL y agrega los parámetros de consulta necesarios de la siguiente lista de parámetros: http(s)://HOSTNAME/login/oauth/authorize. Por ejemplo, esta URL especifica los parámetros client_id y state: http(s)://HOSTNAME/login/oauth/authorize?client_id=12345&state=abcdefg.

   Parámetro de consulta	Tipo	¿Necesario?	Descripción
   client_id	string	Obligatorio	El id. de cliente de la instancia de GitHub App. El id. de cliente es diferente del id. de la aplicación. Puedes encontrar el id. de cliente en la página de configuración de la aplicación. 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.
   redirect_uri	string	Se recomienda encarecidamente	La URL en tu aplicación a donde se enviará a los usuarios después de la autorización. Debe ser una coincidencia exacta con una de las URL que has proporcionado como "Dirección URL de devolución de llamada" en la configuración de la aplicación y no puede contener ningún parámetro adicional.
   state	string	Se recomienda encarecidamente	Si se especifica, el valor debe contener una cadena aleatoria para la protección contra ataques de falsificación, y también contener otros datos arbitrarios.
   login	string	Opcionales	Si se especifica, el flujo de aplicación web solicitará a los usuarios una cuenta específica que puedan usar para iniciar sesión y autorizar la aplicación.
   allow_signup	boolean	Opcionales	Con independencia de que se ofrezca a los usuarios no autenticados una opción para que se registren en GitHub durante el flujo de OAuth. El valor predeterminado es true. Use false cuando una directiva prohíba los registros.

2. Si el usuario acepta la solicitud de autorización, GitHub redirigirá al usuario a una de las URL de devolución de llamada de la configuración de la aplicación y proporcionará un parámetro de consulta code que puedes usar en el paso siguiente para crear un token de acceso de usuario. Si en el paso anterior has especificado redirect_uri, se usará esa URL de devolución de llamada. De lo contrario, se usará la primera URL de devolución de llamada de la página de configuración de la aplicación.

   Si has especificado el parámetro state en el paso anterior, GitHub también incluirá un parámetro state. Si el parámetro state no coincide con el parámetro state que has enviado en el paso anterior, no se puede confiar en la solicitud y se debe anular el flujo de la aplicación web.

3. Cambia el valor code del paso anterior para un token de acceso de usuario mediante la realización de una solicitud POST a esta dirección URL, junto con los parámetros de consulta siguientes: http(s)://HOSTNAME/login/oauth/access_token

   Parámetro de consulta	Tipo	Descripción
   client_id	string	Obligatorio. El id. de cliente de la instancia de GitHub App. El id. de cliente es diferente del id. de la aplicación. Puedes encontrar el id. de cliente en la página de configuración de la aplicación. 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".
   client_secret	string	Obligatorio. El secreto de cliente de GitHub App. Puedes generar un secreto de cliente en la página de configuración de la aplicación.
   code	string	Obligatorio. El código que has recibido en el paso anterior.
   redirect_uri	string	La URL en tu aplicación a donde se enviará a los usuarios después de la autorización. Debe ser una coincidencia exacta con una de las URL que has proporcionado como "Dirección URL de devolución de llamada" al configurar GitHub App y no puede contener ningún parámetro adicional.
   repository_id	string	Identificador de un único repositorio al que puede acceder el token de acceso de usuario. Si la GitHub App o el usuario no pueden acceder al repositorio, se omitirá. Usa este parámetro para restringir aún más el acceso del token de acceso de usuario.

4. GitHub responderá con una respuesta que incluye los parámetros siguientes:

   Parámetro de respuesta	Tipo	Descripción
   access_token	string	Token de acceso de usuario. El token comienza con ghu_.
   expires_in	integer	Número de segundos hasta que access_token expira. Si deshabilitaste la expiración de los tokens de acceso de usuario, este parámetro se omitirá. El valor siempre será 28800 (8 horas).
   refresh_token	string	El token de actualización. Si deshabilitaste la expiración de los tokens de acceso de usuario, este parámetro se omitirá. El token comienza con ghr_.
   refresh_token_expires_in	integer	Número de segundos hasta que refresh_token expira. Si deshabilitaste la expiración de los tokens de acceso de usuario, este parámetro se omitirá. El valor siempre será 15897600 (6 meses).
   scope	string	Ámbitos que tiene el token. Este valor siempre será una cadena vacía. A diferencia de un token de OAuth tradicional, el token de acceso de usuario se limita a los permisos que tienen tanto la aplicación como el usuario.
   token_type	string	Tipo de token. El valor siempre será bearer.

5. Usa el token de acceso de usuario del paso anterior para realizar solicitudes de API en nombre del usuario. Incluye el token de acceso de usuario en el encabezado Authorization de una solicitud de API. Por ejemplo:

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

Uso del flujo de dispositivos para generar un token de acceso de usuario

Si la aplicación no tiene encabezado ni acceso a un explorador, debes usar el flujo de dispositivos para generar un token de acceso de usuario. Por ejemplo, las herramientas de la CLI, Raspberry Pis simples y las aplicaciones de escritorio deben usar el flujo de dispositivo. Para un tutorial que usa el flujo de dispositivo, consulta Creación de una CLI con una aplicación de GitHub.

Antes de que pueda utilizar el flujo de dispositivos, primero debe habilitarlo en los ajustes de su app. Para más información sobre cómo habilitar el flujo de dispositivos, consulta Modificación del registro de una instancia de GitHub App.

En el flujo de dispositivos se usa la concesión de autorización de dispositivos de OAuth 2.0.

1. Envía una solicitud POST a http(s)://HOSTNAME/login/device/code junto con un parámetro de consulta client_id. El id. de cliente es diferente del id. de la aplicación. Puedes encontrar el id. de cliente en la página de configuración de la aplicación. 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.

2. GitHub dará una respuesta que incluirá los parámetros de consulta siguientes:

   Parámetro de respuesta	Tipo	Descripción
   device_code	string	Código de verificación que se usa para comprobar el dispositivo. Este código tiene 40 caracteres de longitud.
   user_code	string	Código de verificación que la aplicación debe mostrar para que el usuario pueda escribir el código en un explorador. El código es de 8 caracteres con un guión medio a la mitad. Por ejemplo: WDJB-MJHT.
   verification_uri	string	Dirección URL donde los usuarios deben escribir su user_code. La URL es: http(s)://HOSTNAME/login/device.
   expires_in	integer	Número de segundos antes de que device_code y user_code expiren. El valor predeterminado es de 900 segundos (15 minutos).
   interval	integer	Número mínimo de segundos que deben pasar antes de poder realizar una nueva solicitud de token de acceso (POST http(s)://HOSTNAME/login/oauth/access_token) para completar la autorización del dispositivo. Si realizas una solicitud antes de que se supere este intervalo, alcanzarás el límite de frecuenta y se producirá un error slow_down. El valor predeterminado es 5 segundos.

3. Pide al usuario que escriba el valor user_code del paso anterior en http(s)://HOSTNAME/login/device.

   Si el usuario no escribe el código antes de que pase el tiempo expires_in, el código no será válido. En este caso, debes reiniciar el flujo del dispositivo.

4. Sondea POST http(s)://HOSTNAME/login/oauth/access_token junto con los parámetros de consulta client_id, device_code y grant_type (descritos a continuación) hasta que expiren los códigos de dispositivo y usuario, o bien el usuario haya autorizado correctamente la aplicación al escribir user_code.

   Parámetro de consulta	Tipo	Descripción
   client_id	string	Obligatorio. El identificador de cliente de GitHub App.
   device_code	string	Obligatorio. El código de verificación del dispositivo que has recibido en el paso anterior.
   grant_type	string	Obligatorio. El tipo de concesión debe ser urn:ietf:params:oauth:grant-type:device_code.
   repository_id	string	Identificador de un único repositorio al que puede acceder el token de acceso de usuario. Si la GitHub App o el usuario no pueden acceder al repositorio, se omitirá. Usa este parámetro para restringir aún más el acceso del token de acceso de usuario.

   No sondees este punto de conexión con una frecuencia mayor que la indicada por interval. Si lo haces, alcanzarás el limite de frecuencia y se producirá un error slow_down. La respuesta de error slow_down agrega 5 segundos a la última instancia de interval.

   Hasta que el usuario escriba el código, GitHub responderá con un estado 200 y un parámetro de consulta de respuesta error.

   Nombre del error	Descripción
   authorization_pending	Este error ocurre cuando la solicitud de autorización se encuentra pendiente y el usuario no ha ingresado el código de usuario aún. Se espera que la aplicación continúe el sondeo de POST http(s)://HOSTNAME/login/oauth/access_token con una frecuencia que no sea más rápida que la especificada por interval.
   slow_down	Cuando recibe el error slow_down, se agregan 5 segundos adicionales al valor interval mínimo o período de tiempo necesario entre las solicitudes mediante POST http(s)://HOSTNAME/login/oauth/access_token. Por ejemplo, si en el intervalo de inicio se necesitaban al menos 5 segundos entre solicitudes y recibes una respuesta de error slow_down, ahora tendrás que esperar al menos 10 segundos antes de poder realizar una nueva solicitud para un token. La respuesta de error incluye el nuevo valor interval que debe usar.
   expired_token	Si el código del dispositivo ha expirado, verá el error token_expired. Debes hacer una nueva solicitud para un código de dispositivo.
   unsupported_grant_type	El tipo de concesión debe ser urn:ietf:params:oauth:grant-type:device_code e incluirse como parámetro de entrada al sondear la solicitud de token de OAuth POST http(s)://HOSTNAME/login/oauth/access_token.
   incorrect_client_credentials	Para el flujo de dispositivos, debes pasar la ID de cliente de tu app, la cual puedes encontrar en la página de configuración de la misma. El id. de cliente es diferente del id. de la aplicación y el secreto de cliente.
   incorrect_device_code	El valor device_code proporcionado no es válido.
   access_denied	Cuando un usuario hace clic en Cancelar durante el proceso de autorización, se producirá un error access_denied y el usuario no podrá volver a utilizar el código de verificación.
   device_flow_disabled	El flujo de dispositivos no se habilitó en los ajustes de la app. Para más información sobre cómo habilitar el flujo de dispositivos, consulta Modificación del registro de una instancia de GitHub App.

5. Cuando el usuario haya escrito user_code, GitHub dará una respuesta que incluye los siguientes parámetros de consulta:

   Parámetro de respuesta	Tipo	Descripción
   access_token	string	Token de acceso de usuario. El token comienza con ghu_.
   expires_in	integer	Número de segundos hasta que access_token expira. Si deshabilitaste la expiración de los tokens de acceso de usuario, este parámetro se omitirá. El valor siempre será 28800 (8 horas).
   refresh_token	string	El token de actualización. Si deshabilitaste la expiración de los tokens de acceso de usuario, este parámetro se omitirá. El token comienza con ghr_.
   refresh_token_expires_in	integer	Número de segundos hasta que refresh_token expira. Si deshabilitaste la expiración de los tokens de acceso de usuario, este parámetro se omitirá. El valor siempre será 15897600 (6 meses).
   scope	string	Ámbitos que tiene el token. Este valor siempre será una cadena vacía. A diferencia de un token de OAuth tradicional, el token de acceso de usuario se limita a los permisos que tienen tanto la aplicación como el usuario.
   token_type	string	Tipo de token. El valor siempre será bearer.

6. Usa el token de acceso de usuario del paso anterior para realizar solicitudes de API en nombre del usuario. Incluye el token de acceso de usuario en el encabezado Authorization de una solicitud de API. Por ejemplo:

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

Generación de un token de acceso de usuario cuando un usuario instala la aplicación

Si seleccionas Solicitar autorización de usuario (OAuth) durante la instalación en la configuración de la aplicación, GitHub iniciará el flujo de la aplicación web inmediatamente después de que un usuario instale la aplicación.

Puedes generar un token de acceso de usuario con este método independientemente de si la aplicación está instalada en una cuenta de usuario o en una cuenta de organización. Pero si la aplicación se ha instalado en una cuenta de organización, tendrás que usar el flujo de aplicación web o el de dispositivos a fin de generar un token de acceso de usuario para otros usuarios de la organización.

1. Cuando un usuario instala la aplicación, GitHub le redirigirá a http(s)://HOSTNAME/login/oauth/authorize?client_id=CLIENT_ID, donde CLIENT_ID es el id. de cliente de la aplicación.

2. Si el usuario acepta la solicitud de autorización, GitHub redirigirá al usuario a la primera URL de devolución de llamada de la configuración de la aplicación y proporcionará un parámetro de consulta code.

   Si quieres controlar qué URL de devolución de llamada se usa, no selecciones Solicitar autorización de usuario (OAuth) durante la instalación. En su lugar, dirige a los usuarios por el flujo de aplicación web completo y especifica el parámetro redirect_uri.

3. Cambia el valor code del paso anterior para un token de acceso de usuario mediante la realización de una solicitud POST a esta dirección URL, junto con los parámetros de consulta siguientes: http(s)://HOSTNAME/login/oauth/access_token

   Parámetro de consulta	Tipo	Descripción
   client_id	string	Obligatorio. El id. de cliente de la instancia de GitHub App. El id. de cliente es diferente del id. de la aplicación. Puedes encontrar el id. de cliente en la página de configuración de la aplicación. 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".
   client_secret	string	Obligatorio. El secreto de cliente de GitHub App. Puedes generar un secreto de cliente en la página de configuración de la aplicación.
   code	string	Obligatorio. El código que has recibido en el paso anterior.
   redirect_uri	string	La URL en tu aplicación a donde se enviará a los usuarios después de la autorización. Debe ser una coincidencia exacta con una de las URL que has proporcionado como "Dirección URL de devolución de llamada" al configurar GitHub App y no puede contener ningún parámetro adicional.
   repository_id	string	Identificador de un único repositorio al que puede acceder el token de acceso de usuario. Si la GitHub App o el usuario no pueden acceder al repositorio, se omitirá. Usa este parámetro para restringir aún más el acceso del token de acceso de usuario.

4. GitHub responderá con una respuesta que incluye los parámetros siguientes:

   Parámetro de respuesta	Tipo	Descripción
   access_token	string	Token de acceso de usuario. El token comienza con ghu_.
   expires_in	integer	Número de segundos hasta que access_token expira. Si deshabilitaste la expiración de los tokens de acceso de usuario, este parámetro se omitirá. El valor siempre será 28800 (8 horas).
   refresh_token	string	El token de actualización. Si deshabilitaste la expiración de los tokens de acceso de usuario, este parámetro se omitirá. El token comienza con ghr_.
   refresh_token_expires_in	integer	Número de segundos hasta que refresh_token expira. Si deshabilitaste la expiración de los tokens de acceso de usuario, este parámetro se omitirá. El valor siempre será 15897600 (6 meses).
   scope	string	Ámbitos que tiene el token. Este valor siempre será una cadena vacía. A diferencia de un token de OAuth tradicional, el token de acceso de usuario se limita a los permisos que tienen tanto la aplicación como el usuario.
   token_type	string	Tipo de token. El valor siempre será bearer.

5. Usa el token de acceso de usuario del paso anterior para realizar solicitudes de API en nombre del usuario. Incluye el token de acceso de usuario en el encabezado Authorization de una solicitud de API. Por ejemplo:

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

Uso de un token de actualización para generar un token de acceso de usuario

De manera predeterminada, los tokens de acceso de usuario expiran después de ocho horas. Si recibes un token de acceso de usuario con una expiración, también recibirás un token de actualización. El token de actualización expira después de 6 meses. Puedes usar este token de actualización para regenerar un token de acceso de usuario. Para más información, consulta Actualización de tokens de acceso de usuario.

GitHub recomienda encarecidamente que uses tokens de acceso de usuario que expiren. Si anteriormente has optado por no participar en el uso de tokens de acceso de usuario que expiran, pero quieres volver a habilitar esta característica, consulta Activación de características opcionales para Aplicaciones de GitHub.

Solución de problemas

En las secciones siguientes, se describen algunos errores que puedes recibir cuando generas un token de acceso de usuario.

Credenciales de cliente incorrectas

Si el client_id o el client_secret que especificas no son correctos, recibirás un error incorrect_client_credentials.

Para resolver este error, asegúrate de que tienes las credenciales correctas para tu GitHub App. Puedes encontrar el id. de cliente y el secreto de cliente en la página de configuración de GitHub App. Para más información sobre cómo navegar a la página de configuración de GitHub App, consulta Modificación del registro de una instancia de GitHub App.

Redirigir una discordancia de URI

Si especificas una redirect_uri que no coincide con una de las URL de devolución de llamada en el registro de GitHub App, recibirás un error redirect_uri_mismatch.

Para resolver este error, proporciona un redirect_uri que coincida con una de las URL de devolución de llamada para el registro de GitHub App u omite este parámetro para que se establezca de manera predeterminada en la primera URL de devolución de llamada que aparece en el registro de GitHub App. Para más información, consulta Acerca de la dirección URL de devolución de llamada de autorización de usuario.

Código de verificación incorrecto

Si usas el flujo de dispositivos y el código de verificación (device_code) que especificaste no es correcto, expiró o no coincide con el valor que recibiste de la solicitud inicial a http(s)://HOSTNAME/login/device/code, recibirás un error bad_verification_code.

Para resolver este error, debes volver a empezar el flujo de dispositivos para obtener un código nuevo. Para más información, consulta Uso del flujo de dispositivos para generar un token de acceso de usuario.

Token de actualización incorrecto

Si el token de actualización que especificaste no es válido o expiró, recibirás un error bad_refresh_token.

Para resolver este error, primero debes reiniciar el flujo de la aplicación web o el flujo de dispositivos para obtener un token de actualización y un token de acceso de usuario nuevo. Solo recibirás un token de actualización si GitHub App optó por la expiración de los tokens de acceso de usuario. Para más información, consulta Actualización de tokens de acceso de usuario.

Tipo de concesión no admitido

Cuando solicitas un token de acceso de usuario a través del flujo de dispositivos, el parámetro grant_type debe ser urn:ietf:params:oauth:grant-type:device_code. Cuando actualizas un token de acceso de usuario mediante un token de actualización, el parámetro grant_type debe ser refresh_token. Si no usas el tipo de concesión correcto, recibirás un error unsupported_grant_type.

Correo electrónico de usuario no comprobado

Si el usuario para el que intentas generar un token de acceso de usuario no ha comprobado su dirección de correo electrónico principal con GitHub, recibirás un error unverified_user_email.

Para resolver este error, solicita al usuario que compruebe la dirección de correo electrónico principal en su cuenta de GitHub. Para más información, consulta Verificar tu dirección de correo electrónico en la documentación de GitHub Free.