OAuth 2.0 Authorization Code Flow 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 flujos de autorización en múltiples dispositivos. OAuth 2.0 te permite elegir scopes específicos y granulares que te otorgan permisos específicos en nombre de un usuario. Para habilitar OAuth 2.0 en tu App, debes habilitarlo en la configuración de autenticación de tu App que se encuentra en la sección de configuración de App de la Developer Console.

¿Cuánto tiempo permanecerán válidas mis credenciales?

Por defecto, el access token que crees a través del Authorization Code Flow con PKCE solo permanecerá válido durante dos horas, a menos que hayas usado el scope offline.access.

Refresh tokens

Los refresh tokens permiten a una aplicación obtener un nuevo access token sin solicitarlo al usuario mediante el flujo de refresh token. Si se aplica el scope offline.access, se emitirá un refresh token de OAuth 2.0. Con este refresh token, obtienes un access token. Si no se pasa este scope, no generaremos un refresh token. Un ejemplo de la solicitud que harías para usar un refresh token para obtener un nuevo access token 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 seleccionar la configuración de autenticación de tu App para que sea OAuth 1.0a o OAuth 2.0. También puedes habilitar una App para acceder tanto a OAuth 1.0a como a OAuth 2.0. OAuth 2.0 se puede usar solo 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 guardar 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, dado que normalmente se ejecutan en un navegador o dispositivo móvil, no pueden usar tus client secrets. Si seleccionas un tipo de App que es un cliente confidencial, se te proporcionará un client secret. Si seleccionaste un tipo de cliente que es un cliente confidencial en la Developer Console, 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. Aún se te requiere incluir el Client Id en el cuerpo para las solicitudes con un cliente público.

Scopes

Los scopes te permiten establecer un acceso granular para tu App, de modo que tu App solo tenga los permisos que necesita. Para saber más sobre qué scopes se corresponden con qué endpoints, consulta nuestra guía de mapeo 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 Retweet por ti.
tweet.moderate.write	Ocultar y mostrar respuestas a tus Tweets.
users.email	Correo electrónico de un usuario autenticado.
users.read	Cualquier cuenta que puedas ver, incluidas 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 quitar el silencio a cuentas por ti.
like.read	Tweets que te han gustado y los likes que puedes ver.
like.write	Dar y quitar Like a Tweets por ti.
list.read	Lists, miembros de list y seguidores de list que has creado o de las que eres miembro, incluidas las listas privadas.
list.write	Crear y gestionar Lists por ti.
block.read	Cuentas que has bloqueado.
block.write	Bloquear y desbloquear cuentas por ti.
bookmark.read	Obtener Tweets marcados como favoritos de un usuario autenticado.
bookmark.write	Marcar y eliminar Bookmarks de Tweets.
dm.read	Todos los Mensajes Directos que puedes ver, incluidos los Mensajes Directos de cuentas protegidas.
dm.write	Enviar y gestionar Mensajes Directos por ti.
media.write	Subir medios.

Límites de tasa

En su mayor parte, los límites de tasa son los mismos que al autenticarse con OAuth 1.0a, con la excepción de Tweets lookup y Users lookup. Estamos aumentando el límite por App de 300 a 900 solicitudes cada 15 minutos al usar OAuth 2.0 para Tweet lookup y user lookup. Para saber más, asegúrate de consultar nuestra documentación sobre límites de tasa.

Grant types

Solo proporcionamos authorization code con PKCE y refresh token como los grant types admitidos para este lanzamiento inicial. Es posible que proporcionemos más grant types en el futuro.

Flujo de OAuth 2.0

OAuth 2.0 usa un flujo similar al que utilizamos actualmente para OAuth 1.0a. Puedes consultar un diagrama y una explicación detallada en nuestra documentación sobre este tema.

Glosario


Término	Descripción
Grant types	El marco OAuth especifica varios grant types para diferentes casos de uso y un marco para crear nuevos grant types. Los ejemplos incluyen authorization code, client credentials, device code y refresh token.
Cliente confidencial	Los clientes son aplicaciones que pueden autenticarse de forma segura con el servidor de autorización, por ejemplo, manteniendo su client secret registrado a salvo.
Cliente público	Los clientes no pueden usar client secrets registrados, como aplicaciones que se ejecutan en un navegador o dispositivo móvil.
Authorization code flow	Utilizado tanto por clientes confidenciales como públicos para intercambiar un authorization code por un access token.
PKCE	Una extensión del authorization code flow para prevenir varios ataques y poder realizar el intercambio OAuth desde clientes públicos de forma segura.
Client ID	Se puede encontrar en la sección keys and tokens de la Developer Console bajo el encabezado “Client ID”. Si no lo ves, ponte en contacto con nuestro equipo directamente. Se necesitará el Client ID para generar la URL de autorización.
Redirect URI	Tu callback URL. Necesitarás tener validación de coincidencia exacta.
Authorization code	Esto permite a una aplicación acceder a las 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 por el usuario. Tendrás que intercambiarlo por un access token dentro de 30 segundos, o el auth_code expirará.
Access token	Los access tokens son el token que las aplicaciones usan para realizar solicitudes a la API en nombre de un usuario.
Refresh token	Permite a una aplicación obtener un nuevo access token sin solicitarlo al usuario mediante el flujo de refresh token.
Client Secret	Si has seleccionado un tipo de App que es un cliente confidencial, se te proporcionará un “Client Secret” bajo “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 tener los siguientes parámetros en la URL de autorización.


Parámetro	Descripción
response_type	Necesitarás especificar que se trata de un code con la palabra “code”.
client_id	Se puede encontrar en la Developer Console bajo el encabezado “Client ID”.
redirect_uri	Tu callback URL. 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 callback URL.
state	Una cadena aleatoria que proporcionas para verificar contra 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 realizas.
code_challenge_method	Especifica el método que estás utilizando para realizar una solicitud (S256 O plain).

Authorize URL

Con OAuth 2.0, creas una URL de autorización, que puedes usar para permitir que un usuario se autentique a través de 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

Necesitarás tener la codificación adecuada para que esta URL funcione; asegúrate de consultar nuestra documentación sobre codificación por porcentaje.