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

Acerca de los tokens de acceso de usuario

Nota:

Si un usuario informa de que no pueden ver los recursos que pertenecen a su organización después de autorizar tu GitHub App y la organización usa el inicio de sesión único de SAML, indica al usuario que inicie una sesión de SAML activa para su organización antes de volver a autorizar. Para más información, consulta SAML y aplicaciones de GitHub en la documentación de GitHub Enterprise Cloud.

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 a una aplicación se le concede acceso a un repositorio y otro, y el usuario puede acceder a un repositorio y a otro, el token de acceso del usuario puede acceder a un repositorio, pero no a los otros. 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 y en AUTOTITLE.

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 AUTOTITLE.

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 AUTOTITLE.

Los usuarios pueden revocar su autorización de GitHub App. Para más información, consulta AUTOTITLE. Si un usuario revoca su autorización de un GitHub App, la aplicación recibirá el evento webhook. Las aplicaciones 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 . Para más información sobre este webhook, consulta AUTOTITLE.

Debes mantener protegidos los tokens de acceso de usuario y los tokens de actualización. Para más información, consulta AUTOTITLE.

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 AUTOTITLE.

Dirige al usuario a esta URL y agrega los parámetros de consulta necesarios de la siguiente lista de parámetros: . Por ejemplo, esta URL especifica los parámetros y : .

Parámetro de consulta	Tipo	¿Necesario?	Descripción
`client_id`	`string`	Obligatorio	El ID de cliente para su 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 obtener más información sobre cómo acceder a la página de configuración de tu GitHub App, consulta AUTOTITLE.
`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 "URL de callback" en los ajustes de tu 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.

| string | Se recomienda encarecidamente | Se usa para proteger el flujo de autenticación con PKCE (clave de prueba para Intercambio de código). Obligatorio si se incluye . Debe ser un hash SHA-256 de 43 caracteres de una cadena aleatoria generada por el cliente. Consulta la RFC de PKCE para obtener más información sobre esta extensión de seguridad. code_challenge_method | string | Se recomienda encarecidamente | Se usa para proteger el flujo de autenticación con PKCE (clave de prueba para Intercambio de código). Obligatorio si se incluye . Debe ser : no se admite el método de desafío de código . 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 | Si a los usuarios no autenticados se les ofrecerá la opción de registrarse en GitHub durante el flujo de OAuth. El valor predeterminado es . Use cuando una directiva prohíba los registros. prompt | string | Opcionales | Obliga a que el selector de cuentas aparezca si se configura como . El selector de cuentas también aparecerá si la aplicación tiene un URI de redirección no HTTP o si el usuario tiene varias cuentas iniciadas.

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 que puedes usar en el paso siguiente para crear un token de acceso de usuario. Si especificaste algo en el paso anterior, 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 en el paso anterior, GitHub también incluirá un parámetro . Si el parámetro no coincide con el parámetro 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.

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: https://github.com/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 de un registro de aplicación de GitHub.
`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.

code_verifier | string | Se recomienda encarecidamente. Se usa para proteger el flujo de autenticación con PKCE (clave de prueba para Intercambio de código). Es obligatorio si code_challenge se envió durante la autorización del usuario. Debe ser el valor original que se usa para generar code_challenge en la solicitud de autorización. Esto se puede almacenar en una cookie junto con el parámetro state o en una variable de sesión durante la autenticación, en función de la arquitectura de la aplicación. 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.

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`.

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 "https://api.github.com/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 del dispositivo, consulta AUTOTITLE.

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 AUTOTITLE.

El flujo de dispositivo usa la concesión de autorización de dispositivos de OAuth 2.0.

Envía una solicitud a junto con un parámetro de consulta . 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 obtener más información sobre cómo acceder a la página de configuración de tu GitHub App, consulta AUTOTITLE.

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: .
`verification_uri`	`string`	La dirección URL donde los usuarios deben ingresar su información. La URL es: `https://github.com/login/device`.
`expires_in`	`integer`	Número de segundos antes de que [objeto1] y [objeto2] 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 () 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 . El valor predeterminado es 5 segundos.

Solicite al usuario que introduzca el valor del paso anterior en https://github.com/login/device.

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

Sondea junto con los parámetros de consulta , y (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 .

Parámetro de consulta	Tipo	Descripción
`client_id`	`string`	Obligatorio. El ID de cliente para su 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 .
`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 pasará por alto. 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 . Si lo haces, alcanzarás el limite de frecuencia y se producirá un error . ** La respuesta de error agrega 5 segundos a la última.

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

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 siga realizando la interrogación a una frecuencia que no sea más rápida que la especificada por .
`slow_down`	Cuando recibes el error, se añaden 5 segundos adicionales al período mínimo o lapso de tiempo requerido entre tus solicitudes. Por ejemplo, si en el intervalo de inicio se necesitaban al menos 5 segundos entre solicitudes y recibes una respuesta de error , 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 que debe usar.
`expired_token`	Si el código del dispositivo ha expirado, verá el error . Debes hacer una nueva solicitud para un código de dispositivo.
`unsupported_grant_type`	El tipo de concesión debe ser especificado e incluirse como parámetro de entrada al consultar la solicitud de token de OAuth.
`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 proporcionado no es válido.
`access_denied`	Cuando un usuario hace clic en Cancelar durante el proceso de autorización, se producirá un error y el usuario no podrá volver a utilizar el código de verificación.
`device_flow_disabled`	El flujo de dispositivos no ha sido habilitado en la configuración de la aplicación. Para más información sobre cómo habilitar el flujo de dispositivos, consulta AUTOTITLE.

Cuando el usuario haya escrito , 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`.

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 "https://api.github.com/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.

Cuando un usuario instala la aplicación, GitHub le redirigirá a , donde es el id. de cliente de la aplicación.
Si el usuario acepta la solicitud de autorización, GitHub redirigirá al usuario a la primera URL de devolución de llamada en la configuración de tu aplicación y proporcionará un parámetro de consulta.

Si quiere controlar qué URL callback se usa, no seleccione Solicitar autorización de usuario (OAuth) durante la instalación. En su lugar, dirija a los usuarios a través del flujo completo de la aplicación web y especifique el parámetro correspondiente.

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 de un registro de aplicación de GitHub.
`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.

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`.

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 "https://api.github.com/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 para el 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 AUTOTITLE.

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 AUTOTITLE.

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 los datos o valores que especificas no son correctos, recibirás un mensaje de error.

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 AUTOTITLE.

Redirigir una discordancia de URI

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

Para resolver este error, proporciona un valor 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 predetermine a la primera URL de devolución de llamada que aparece en el registro de GitHub App. Para más información, consulta AUTOTITLE.

Código de verificación incorrecto

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

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 .

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 AUTOTITLE.

Tipo de concesión no admitido

Cuando solicitas un token de acceso de usuario a través del flujo de dispositivos, el parámetro debe ser . Cuando actualizas un token de acceso de usuario mediante un token de actualización, el parámetro debe ser . Si no usas el tipo de concesión correcto, recibirás un error .

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 .

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 AUTOTITLE.

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

En este artículo