Flujo de código de autorización de OAuth 2.0 con PKCE

Flujo de código de autorización de OAuth 2.0 con PKCE

Introducción

OAuth 2.0 es un protocolo de autorización estándar del sector que permite un mayor control sobre el alcance de una aplicación y sobre los flujos de autorización en múltiples dispositivos. OAuth 2.0 te permite elegir ámbitos específicos y granulares que te otorgan permisos concretos en nombre de un usuario. 

Para habilitar OAuth 2.0 en tu App, debes activarlo en la configuración de autenticación de tu App, dentro de la sección de configuración de la App en la Consola de desarrollador.

¿Durante cuánto tiempo seguirán siendo válidas mis credenciales?

Por defecto, el token de acceso que generes mediante el flujo de código de autorización con PKCE solo se mantendrá válido durante dos horas, a menos que hayas usado el scope offline.access.

Tokens de actualización

Los tokens de actualización permiten que una aplicación obtenga un nuevo token de acceso sin necesidad de solicitar nuevamente la autorización del usuario, mediante el flujo de token de actualización.

Si se aplica el scope offline.access, se emitirá un token de actualización de OAuth 2.0. Con este token de actualización, se puede obtener un token de acceso. Si este scope no se pasa, no generaremos un token de actualización.

Un ejemplo de la solicitud que deberías hacer para usar un token de actualización y obtener un nuevo token de acceso es el siguiente:

POST 'https://api.x.com/2/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'refresh_token=bWRWa3gzdnk3WHRGU1o0bmRRcTJ5VUxWX1lZTDdJSUtmaWcxbTVxdEFXcW5tOjE2MjIxNDc3NDM5MTQ6MToxOnJ0OjE' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_id=rG9n6402A3dbUJKzXTNX4oWHJ

Configuración de la App

Puedes configurar la autenticación de tu App como OAuth 1.0a u OAuth 2.0. También puedes habilitar una App para que utilice tanto OAuth 1.0a como OAuth 2.0.

OAuth 2.0 solo se puede usar con la X API v2. Si has seleccionado OAuth 2.0, podrás ver un Client ID en la sección Keys and Tokens de tu App. 

Clientes confidenciales

Los clientes confidenciales pueden mantener credenciales de forma segura sin exponerlas a partes no autorizadas y autenticarse de forma segura con el servidor de autorización, manteniendo tu client secret protegido. Los clientes públicos, como normalmente se ejecutan en un navegador o en un dispositivo móvil, no pueden usar tus client secrets. Si seleccionas un tipo de App que sea un cliente confidencial, se te proporcionará un client secret. 

Si seleccionaste en la Consola de desarrollador un tipo de cliente que sea un cliente confidencial, también podrás ver un Client Secret. Tus opciones son Native App, Single page App, Web App, Automated App o bot. Native App y Single page Apps son clientes públicos y Web App y Automated App o bots son clientes confidenciales.

No necesitas client id para clientes confidenciales con un encabezado Authorization válido. Sin embargo, aún debes incluir Client Id en el cuerpo de las solicitudes con un cliente público. 

Alcances

Los alcances te permiten configurar un acceso granular para tu App de modo que solo tenga los permisos que necesita. Para obtener más información sobre qué alcances se asignan a qué endpoints, consulta nuestra guía de asignación de autenticación.

Scope	Descripción
tweet.read	Todos los Tweets que puedes ver, incluidos los Tweets de cuentas protegidas.
tweet.write	Publicar Tweets y hacer Retweets por ti.
tweet.moderate.write	Ocultar y volver a mostrar respuestas a tus Tweets.
users.email	Correo electrónico de un usuario autenticado.
users.read	Cualquier cuenta que puedas ver, incluidas las cuentas protegidas.
follows.read	Personas que te siguen y personas a las que sigues.
follows.write	Seguir y dejar de seguir personas por ti.
offline.access	Mantente conectado a tu cuenta hasta que revoques el acceso.
space.read	Todos los Spaces que puedes ver.
mute.read	Cuentas que has silenciado.
mute.write	Silenciar y dejar de silenciar cuentas por ti.
like.read	Tweets que te han gustado y “me gusta” que puedes ver.
like.write	Marcar con “me gusta” y quitar el “me gusta” en Tweets por ti.
list.read	Listas, miembros de listas y seguidores de listas que has creado o de las que eres miembro, incluidas las listas privadas.
list.write	Crear y administrar listas por ti.
block.read	Cuentas que has bloqueado.
block.write	Bloquear y desbloquear cuentas por ti.
bookmark.read	Obtener los Tweets que un usuario autenticado ha guardado en marcadores.
bookmark.write	Agregar Tweets a marcadores y eliminar Tweets de marcadores.
media.write	Cargar contenido multimedia.

Límites de tasa

En la mayoría de los casos, los límites de tasa son los mismos que cuando se autentica con OAuth 1.0a, con la excepción de la búsqueda de Tweets y de Usuarios. Estamos aumentando el límite por App de 300 a 900 solicitudes cada 15 minutos cuando se usa OAuth 2.0 para la búsqueda de Tweets y la búsqueda de usuarios. Para obtener más información, consulta nuestra documentación sobre límites de tasa.

Tipos de concesión

Solo admitimos código de autorización con PKCE y token de actualización como tipos de concesión compatibles para este lanzamiento inicial. Es posible que ofrezcamos más tipos de concesión en el futuro.

Flujo de OAuth 2.0

OAuth 2.0 utiliza un flujo similar al que usamos actualmente para OAuth 1.0a. Consulta un diagrama y una explicación detallada en nuestra documentación sobre este tema. 

Glosario

Término	Descripción
Grant types	El framework OAuth especifica varios tipos de grant para diferentes casos de uso y un marco para crear nuevos grant types. Algunos ejemplos son authorization code, client credentials, device code y refresh token.
Confidential client	Los clientes confidenciales son aplicaciones que pueden autenticarse de forma segura con el servidor de autorización, por ejemplo, manteniendo su client secret registrado a salvo.
Public client	Los clientes públicos no pueden usar client secrets registrados, como las aplicaciones que se ejecutan en un navegador o en un dispositivo móvil.
Authorization code flow	Flujo utilizado tanto por confidential clients como por public clients para intercambiar un authorization code por un access token.
PKCE	Una extensión del authorization code flow para evitar varios tipos de ataques y poder realizar el intercambio OAuth desde public clients de forma segura.
Client ID	Se puede encontrar en la sección “Keys and tokens” de la Consola de desarrollador bajo el encabezado “Client ID”. Si no lo ves, ponte en contacto directamente con nuestro equipo. El Client ID será necesario para generar la URL de authorize.
Redirect URI	Tu URL de callback. Necesitarás tener validación de coincidencia exacta.
Authorization code	Esto permite que una aplicación invoque APIs en nombre de los usuarios. Conocido como auth_code. El auth_code tiene un límite de tiempo de 30 segundos una vez que el propietario de la App recibe un auth_code aprobado del usuario. Tendrás que intercambiarlo por un access token dentro de esos 30 segundos o el auth_code caducará.
Access token	Los access tokens son los tokens que las aplicaciones usan para hacer solicitudes a la API en nombre de un usuario.
Refresh token	Permite que una aplicación obtenga un nuevo access token sin volver a solicitar la intervención del usuario, mediante el refresh token flow.
Client Secret	Si has seleccionado un tipo de App que sea un confidential client, se te proporcionará un “Client Secret” debajo de “Client ID” en la sección “Keys and tokens” de tu App.

Parámetros

Para construir una URL de autorización OAuth 2.0, deberás asegurarte de que la URL de autorización incluya los siguientes parámetros. 

Parameter	Descripción
response_type	Deberás especificar que se trata de un código usando la palabra “code”.
client_id	Se puede encontrar en la Consola de desarrollador bajo el encabezado “Client ID”.
redirect_uri	Tu URL de callback. Este valor debe corresponder a una de las Callback URLs definidas en la configuración de tu App. Para OAuth 2.0, deberás tener validación de coincidencia exacta para tu URL de callback.
state	Una cadena aleatoria que proporcionas para verificar y protegerte frente a ataques CSRF. La longitud de esta cadena puede ser de hasta 500 caracteres.
code_challenge	Un parámetro PKCE, un secreto aleatorio para cada solicitud que hagas.
code_challenge_method	Especifica el método que estás usando para realizar una solicitud (S256 o plain).

URL de autorización

Con OAuth 2.0, creas una URL de autorización que puedes usar para permitir que un usuario se autentique mediante un flujo de autenticación, similar a “Iniciar sesión con X”. 

Un ejemplo de la URL que estás creando es el siguiente:

https://x.com/i/oauth2/authorize?response_type=code&client_id=M1M5R3BMVy13QmpScXkzTUt5OE46MTpjaQ&redirect_uri=https://www.example.com&scope=tweet.read%20users.read%20account.follows.read%20account.follows.write&state=state&code_challenge=challenge&code_challenge_method=plain

Para que esta URL funcione, debes usar la codificación adecuada; asegúrate de consultar nuestra documentación sobre la codificación porcentual.