Acerca de los tokens de acceso de usuario
Nota: Los tokens de acceso de usuario que expiran actualmente son una característica opcional y están sujetos a cambios. Para participar o no en la característica de expiración de tokens consulta "Activación de características opcionales para Aplicaciones de GitHub". Para obtener más información, consulta Tokens de acceso con caducidad de usuario a servidor para las GitHub Apps.
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 obtener más información, vea «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 obtener más información, vea «Actualización de tokens de acceso de usuario».
Los usuarios pueden revocar su autorización de una instancia de GitHub App. Para obtener más información, vea «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 obtener más información, vea «Procedimientos recomendados para crear una aplicación de GitHub».
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 "Aplicaciones SAML y 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".
-
Dirige al usuario a esta URL y agrega los parámetros de consulta necesarios de la siguiente lista de parámetros:
https://github.com/login/oauth/authorize
. Por ejemplo, esta URL especifica los parámetrosclient_id
ystate
:https://github.com/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
. Usefalse
cuando una directiva prohíba los registros.prompt
string
Opcionales Obliga a que el selector de cuentas aparezca si se configura como select_account
. 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
code
que puedes usar en el paso siguiente para crear un token de acceso de usuario. Si en el paso anterior has especificadoredirect_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ámetrostate
. Si el parámetrostate
no coincide con el parámetrostate
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 solicitudPOST
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 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. -
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
Nota: El flujo del dispositivo está en versión preliminar pública y está sujeto a cambios.
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, consulte "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.
-
Envía una solicitud
POST
ahttps://github.com/login/device/code
junto con un parámetro de consultaclient_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". -
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:https://github.com/login/device
.expires_in
integer
Número de segundos antes de que device_code
yuser_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 https://github.com/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 errorslow_down
. El valor predeterminado es 5 segundos. -
Pide al usuario que escriba el valor
user_code
del paso anterior enhttps://github.com/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. -
Sondea
POST https://github.com/login/oauth/access_token
junto con los parámetros de consultaclient_id
,device_code
ygrant_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 escribiruser_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 errorslow_down
. La respuesta de errorslow_down
agrega 5 segundos a la última instancia deinterval
.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 https://github.com/login/oauth/access_token
con una frecuencia que no sea más rápida que la especificada porinterval
.slow_down
Cuando recibe el error slow_down
, se agregan 5 segundos adicionales al valorinterval
mínimo o período de tiempo necesario entre las solicitudes mediantePOST https://github.com/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 errorslow_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 valorinterval
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 OAuthPOST https://github.com/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". -
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
. -
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
https://github.com/login/oauth/authorize?client_id=CLIENT_ID
, dondeCLIENT_ID
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 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
. -
Cambia el valor
code
del paso anterior para un token de acceso de usuario mediante la realización de una solicitudPOST
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 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. -
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 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 obtener más información, vea «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 obtener más información, vea «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 https://github.com/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 obtener más información, vea «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".