Autenticación OAuth2

Este texto fue traducido usando IA. Si deseas ver el texto original en inglés, haz clic aquí.

OAuth2 permite que las aplicaciones accedan de forma segura a los sitios de WordPress.com y Jetpack sin necesidad de las contraseñas de los usuarios. Proporciona un control detallado sobre lo que cada aplicación puede acceder.

OAuth2 permite que las aplicaciones soliciten solo los permisos específicos que necesitan a través de «scopes». Cuando los usuarios autorizan una aplicación, pueden ver y controlar exactamente qué acceso están otorgando.

Los usuarios inician sesión con su cuenta de WordPress.com y pueden aprobar o denegar los permisos solicitados, manteniendo el control sobre sus datos mientras conectan aplicaciones de forma segura.

Requisitos previos

Antes de desarrollar tu aplicación OAuth2, necesitas tener una aplicación de WordPress.com registrada con los siguientes datos:

1. Client ID: Identifica tu aplicación
2. Client Secret: Autentica tu aplicación (mantenlo seguro)
3. Redirect URI: A donde regresan los usuarios después de la autorización

Puedes obtener estas credenciales a través del Administrador de aplicaciones de WordPress.com.

Usa este formulario para registrar una nueva aplicación de WordPress.com

Endpoints de OAuth2

Si eres nuevo en OAuth2, puedes obtener más información en https://oauth.net/. Para la integración con WordPress.com, necesitas comprender los endpoints principales de OAuth2 disponibles bajo el espacio de nombres https://public-api.wordpress.com/oauth2/. Estos endpoints funcionan de manera consistente tanto para sitios de WordPress.com como para sitios conectados con Jetpack.

Endpoint de autorización

Endpoint: https://public-api.wordpress.com/oauth2/authorize

Método: GET (mediante redirección del usuario)

Aquí es donde comienza el flujo de OAuth2. A los usuarios se les presenta una interfaz de autorización para revisar y aprobar los permisos que tu aplicación está solicitando. El endpoint valida las credenciales de tu aplicación, la URI de redirección y genera códigos de autorización seguros para el intercambio de tokens.

Parámetros obligatorios:

• client_id: El ID de cliente de tu aplicación
• redirect_uri: Debe coincidir con la URI de redirección registrada
• response_type: «code» para el flujo de código de autorización o «token» para el flujo implícito

Parámetros opcionales:

• scope: Permisos separados por espacios (por defecto, acceso a un solo blog)
• state: Recomendado para protección contra CSRF
• blog: URL o ID de un blog específico para acceso a un solo sitio

URL de autorización de ejemplo (flujo de código de autorización):

https://public-api.wordpress.com/oauth2/authorize?client_id=12345&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&response_type=code&scope=posts%20media&state=abc123xyz

URL de autorización de ejemplo (flujo implícito):

https://public-api.wordpress.com/oauth2/authorize?client_id=12345&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&response_type=token&scope=posts%20media&state=abc123xyz

URL de autorización de ejemplo (blog específico):

https://public-api.wordpress.com/oauth2/authorize?client_id=12345&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&response_type=code&blog=yourblog.wordpress.com&scope=posts%20media&state=abc123xyz

Respuesta/Acción: Después de la aprobación del usuario, redirige a tu redirect_uri con:

• Flujo de código de autorización: ?code=AUTHORIZATION_CODE&state=YOUR_STATE
• Flujo implícito: #access_token=TOKEN&expires_in=64800&token_type=bearer&site_id=BLOG_ID
• Denegación del usuario: ?error=access_denied

Nota importante: El parámetro redirect_uri debe coincidir exactamente con la URI de redirección registrada al crear tu aplicación. Incluso diferencias menores (como la falta de barras diagonales finales) provocarán que la autorización falle. Esta es una medida de seguridad para prevenir redirecciones maliciosas.

Endpoint de solicitud de token

Endpoint: https://public-api.wordpress.com/oauth2/token

Método: POST

Este endpoint seguro de servidor a servidor gestiona dos tipos de concesión diferentes para obtener tokens de acceso. Elige el tipo de concesión adecuado según tu caso de uso:

Concesión de código de autorización (uso en producción)

Usa este tipo de concesión para todas las aplicaciones en producción. Intercambia códigos de autorización (recibidos de la autorización del usuario) por tokens de acceso, manteniendo tu client secret seguro.

Parámetros obligatorios:

• client_id: El ID de cliente de tu aplicación
• client_secret: El client secret de tu aplicación
• code: Código de autorización del paso de autorización
• grant_type: Debe ser «authorization_code»
• redirect_uri: Debe coincidir con la URI de redirección de autorización

Ejemplo de solicitud:

curl -X POST https://public-api.wordpress.com/oauth2/token 
  -d "client_id=12345" 
  -d "client_secret=your_client_secret" 
  -d "code=received_authorization_code" 
  -d "grant_type=authorization_code" 
  -d "redirect_uri=https://yourapp.com/callback"

Concesión de contraseña (solo para desarrollo y pruebas)

Este tipo de concesión permite a los propietarios de aplicaciones obtener tokens directamente usando sus credenciales de WordPress.com, omitiendo el flujo de autorización del usuario.

Usa la concesión por contraseña para:

• Probar endpoints de la API durante el desarrollo
• Pruebas automatizadas donde simular la autorización del usuario no es práctico
• Desarrollo personal en tus propios sitios de WordPress.com

Restricciones de seguridad:

• Solo funciona con tus propias credenciales de WordPress.com (no las de otros usuarios)
• Requiere exponer las credenciales en tu código
• Omite el consentimiento del usuario y los beneficios de seguridad de OAuth2
• Nunca lo uses en aplicaciones en producción

Parámetros obligatorios:

• client_id: El ID de cliente de tu aplicación
• client_secret: El secreto de cliente de tu aplicación
• grant_type: Debe ser «password»
• username: Tu nombre de usuario de WordPress.com
• password: Tu contraseña de WordPress.com (o contraseña de aplicación si tienes 2FA habilitado)

Ejemplo de solicitud:

curl -X POST https://public-api.wordpress.com/oauth2/token 
  -d "client_id=12345" 
  -d "client_secret=your_client_secret" 
  -d "grant_type=password" 
  -d "username=your_username" 
  -d "password=your_password_or_app_password"

Autenticación en dos pasos: Si tienes 2FA habilitado, crea una contraseña de aplicación en los Ajustes de tu cuenta de WordPress.com y úsala en lugar de tu contraseña habitual.

Ruta de migración: Comienza con Password Grant para mayor comodidad durante el desarrollo, pero implementa el flujo Authorization Code Flow antes de lanzar a producción. Piensa en Password Grant como un atajo de desarrollo que debe reemplazarse con una autorización de usuario adecuada en aplicaciones en producción.

Formato de respuesta del token (ambos tipos de concesión):

{
    "access_token": "YOUR_API_TOKEN",
    "blog_id": "blog_id_number", 
    "blog_url": "https://yourblog.wordpress.com",
    "token_type": "bearer"
}

Endpoint de información del token

Endpoint: https://public-api.wordpress.com/oauth2/token-info

Método: GET

Proporciona validación e inspección segura de tokens. Devuelve información detallada sobre los tokens, incluyendo el ID de usuario, el ID del blog y los permisos de alcance. Es esencial para verificar la autenticidad de los tokens, especialmente cuando se transmiten entre sistemas o en aplicaciones móviles.

Parámetros obligatorios:

• client_id: El ID de cliente de tu aplicación
• token: El token de acceso a validar

Ejemplo de solicitud:

GET https://public-api.wordpress.com/oauth2/token-info?client_id=12345&token=your_access_token_here

Ejemplo de solicitud CURL:

curl "https://public-api.wordpress.com/oauth2/token-info?client_id=12345&token=your_access_token_here"

Formato de respuesta (Token válido):

{
    "client_id": "12345",
    "user_id": "123456789",
    "blog_id": "987654321", 
    "scope": "posts,media"
}

Respuesta (Token inválido): Devuelve un error si el token no fue autorizado para tu aplicación o no es válido.

Endpoint de autenticación

Endpoint: https://public-api.wordpress.com/oauth2/authenticate

Método: GET (mediante redirección del usuario)

Un endpoint especializado para aplicaciones de WordPress.com Connect que solo necesitan verificación básica de identidad del usuario. Optimizado para la funcionalidad «Iniciar sesión con WordPress.com», diseñado para la verificación de identidad en lugar de la gestión de contenido.

Parámetros obligatorios:

• client_id: El ID de cliente de tu aplicación
• redirect_uri: Debe coincidir con la URI de redirección registrada
• response_type: Usa «code» para un intercambio seguro del lado del servidor

Parámetros opcionales:

• scope: Normalmente «auth» para acceso básico al perfil
• state: Recomendado para protección contra CSRF

URL de autenticación de ejemplo:

https://public-api.wordpress.com/oauth2/authenticate?client_id=12345&redirect_uri=https%3A%2F%2Fyourapp.com%2Fauth-callback&response_type=code&scope=auth&state=random_secure_string

Respuesta/Acción: Después de la aprobación del usuario, redirige a tu redirect_uri con un código de autorización. Intercambia este código en el endpoint de token para recibir un token con alcance limitado, que normalmente proporciona acceso solo a:

Acceso disponible a la API:

• Endpoint /me/ para información básica del perfil de usuario
• Datos de verificación de identidad del usuario (ID, nombre de usuario, correo electrónico, avatar_URL, estado de verificación)

Flujos de trabajo de OAuth2

WordPress.com admite dos flujos de trabajo principales de OAuth2, cada uno diseñado para diferentes tipos de aplicaciones y requisitos de seguridad:

Flujo de código de autorización (Recomendado)

El flujo de código de autorización es el flujo de trabajo estándar de OAuth2 para aplicaciones del lado del servidor donde puedes almacenar de forma segura los secretos del cliente. Este flujo proporciona la mayor seguridad al intercambiar un código de autorización por un token de acceso a través de una solicitud segura de servidor a servidor.

Ventaja de seguridad: El secreto del cliente nunca aparece en el código del lado del cliente, y los tokens de acceso se obtienen a través de solicitudes autenticadas del servidor.

Flujo implícito (Heredado)

El flujo implícito fue diseñado para aplicaciones basadas en navegador donde el token de acceso se devuelve directamente en el fragmento de la URL. Sin embargo, este enfoque ahora se considera menos seguro y ha sido en gran medida descontinuado en favor de alternativas más seguras como PKCE (Proof Key for Code Exchange).

Importante: Recomendamos utilizar el flujo de código de autorización siempre que sea posible para una mayor seguridad.

Alcances y permisos de OAuth2

El poder de OAuth2 reside en su sistema de permisos granular. Al solicitar autorización, especificas scopes que definen exactamente a qué puede acceder tu aplicación.

Scopes disponibles

• users: Ver información del usuario
• sites: Ver información general del sitio y opciones
• posts: Ver y gestionar entradas
• comments: Ver y gestionar comentarios de entradas
• taxonomy: Ver y gestionar etiquetas y categorías
• follow: Seguir y dejar de seguir blogs
• sharing: Conectar servicios de redes sociales
• freshly-pressed: Ver entradas de Freshly Pressed
• notifications: Ver y gestionar notificaciones del usuario
• insights: Ver analíticas de tu aplicación
• read: Gestionar y ver suscripciones del Reader
• stats: Ver estadísticas del sitio
• media: Gestionar medios del sitio
• menus: Ver y gestionar menús del sitio
• batch: Agrupar múltiples solicitudes GET en lote
• videos: Ver información de vídeos

Scopes especiales

• global: Otorga acceso completo a los datos del usuario en todos los servicios de WordPress.com y sitios conectados
• auth: Scope limitado que proporciona acceso únicamente al endpoint /me/ para flujos de autenticación básica. Consulta WordPress.com Connect para más información relacionada.

Buenas prácticas para scopes

Sigue siempre el principio de mínimo privilegio:

// Request only necessary permissions
const scopes = 'posts,media'; // Not 'global' unless truly needed

Implementar la autenticación OAuth2

Paso 1: Solicitud de autorización

Dirige a los usuarios al endpoint de autorización con los parámetros requeridos:

Parámetros requeridos

• client_id: El ID de cliente de tu aplicación
• redirect_uri: Debe coincidir con la URI registrada en los ajustes de tu aplicación
• response_type: Usa «code» para el flujo de código de autorización o «token» para el flujo implícito

Parámetros opcionales

• blog: URL o ID de un blog específico para acceso a un solo sitio
• scope: Lista de permisos solicitados separados por espacios
• state: Parámetro de seguridad recomendado para prevenir ataques CSRF

Ejemplo de URL de autorización

const authUrl = `https://public-api.wordpress.com/oauth2/authorize?` +
  `client_id=${clientId}&` +
  `redirect_uri=${encodeURIComponent(redirectUri)}&` +
  `response_type=code&` +
  `scope=posts,media&` +
  `state=${secureRandomString}`;

// // Redirect user to authorization
window.location.href = authUrl;

Paso 2: Intercambio del código de autorización

Después de la autorización del usuario, recibirás (en la ubicación de redirect_url) un código de autorización que debe intercambiarse por un token de acceso.

Intercambio de token del lado del servidor

Realiza una solicitud POST al endpoint de token:

$curl = curl_init( 'https://public-api.wordpress.com/oauth2/token' );

curl_setopt( $curl, CURLOPT_POST, true );
curl_setopt( $curl, CURLOPT_POSTFIELDS, array(
    'client_id' => $your_client_id,
    'redirect_uri' => $your_redirect_url,
    'client_secret' => $your_client_secret_key,
    'code' => $_GET['code'], // The authorization code
    'grant_type' => 'authorization_code'
) );

curl_setopt( $curl, CURLOPT_RETURNTRANSFER, 1);

$auth = curl_exec( $curl );
$secret = json_decode( $auth );
$access_token = $secret->access_token;

Respuesta exitosa

{
    "access_token": "YOUR_API_TOKEN",
    "blog_id": "blog_id_number",
    "blog_url": "https://yourblog.wordpress.com",
    "token_type": "bearer"
}

Paso 3: Realizar llamadas autenticadas a la API

Usa el token Bearer en el encabezado Authorization para todas las solicitudes a la API:

$access_token = 'YOUR_API_TOKEN';
$curl = curl_init( 'https://public-api.wordpress.com/rest/v1/me/' );

curl_setopt( $curl, CURLOPT_HTTPHEADER, array( 'Authorization: Bearer ' . $access_token ) );
curl_setopt( $curl, CURLOPT_RETURNTRANSFER, 1 );

$response = curl_exec( $curl );

Funciones avanzadas de OAuth2

Gestión de alcances de token

Los diferentes alcances de token proporcionan diferentes niveles de acceso:

• Tokens de blog único: Otorgan acceso a un blog específico
• Tokens globales: Proporcionan acceso a todos los sitios WordPress.com y sitios Jetpack conectados del usuario
• Endpoints específicos de usuario: Algunos endpoints (likes, follows) funcionan en todos los blogs con cualquier token de usuario

OAuth del lado del cliente (implícito)

Para aplicaciones del lado del cliente, los tokens pueden devolverse en el fragmento de la URL utilizando el flujo implícito:

https://yourapp.com/callback#access_token=TOKEN&expires_in=64800&token_type=bearer&site_id=BLOG_ID

Consideraciones importantes:

• Actualmente los tokens expiran después de dos semanas
• Utiliza el valor de expires_in para gestionar la renovación del token
• Adecuado únicamente para clientes públicos donde los secretos no pueden almacenarse de forma segura

Validación y gestión de tokens

Gestionar correctamente los tokens OAuth2 es crucial para una aplicación robusta. Esto incluye validar tokens, manejar las respuestas de la API y gestionar de forma adecuada la expiración de tokens o los permisos insuficientes.

Endpoint de información del token

Verifica la autenticidad del token utilizando el endpoint de información del token:

GET https://public-api.wordpress.com/oauth2/token-info?client_id=your_client_id&token=your_token

Respuesta válida:

{
    "client_id": "your_client_id",
    "user_id": "user_id_number",
    "blog_id": "blog_id_number",
    "scope": "posts,media"
}

Desarrollo y pruebas

Pruebas con Password Grant (solo propietarios del cliente)

Los propietarios de la aplicación pueden usar el password grant para obtener el token de autenticación:

$curl = curl_init( 'https://public-api.wordpress.com/oauth2/token' );

curl_setopt( $curl, CURLOPT_POST, true );

curl_setopt( $curl, CURLOPT_POSTFIELDS, array(
    'client_id' => $your_client_id,
    'client_secret' => $your_client_secret_key,
    'grant_type' => 'password',
    'username' => $your_wpcom_username,
    'password' => $your_wpcom_password, // Use Application Password if 2FA enabled
) );

curl_setopt( $curl, CURLOPT_RETURNTRANSFER, 1);
$auth = curl_exec( $curl );
$auth = json_decode( $auth );
$access_token = $auth->access_token;

Importante: Este método requiere una contraseña de aplicación si la autenticación en dos pasos está habilitada.

Mejores prácticas de seguridad y manejo de errores

Directrices de implementación

1. Validación del parámetro state: Valida siempre el parámetro state para prevenir ataques CSRF
2. Almacenamiento seguro de tokens: Almacena los tokens de acceso de forma segura utilizando el cifrado adecuado
3. Solicitud de permisos mínimos: Solicita únicamente los permisos que tu aplicación realmente necesita
4. Comunicación clara con el usuario: Explica por qué se requieren permisos específicos
5. Gestión adecuada de errores: Gestiona de forma elegante los fallos de autorización, la expiración de tokens y los cambios de alcance

Requisitos de HTTPS

Todas las comunicaciones OAuth2 deben utilizar HTTPS para proteger los tokens y los códigos de autorización durante la transmisión.

Gestión de tokens

• Almacena los tokens de acceso de forma segura en el lado del servidor
• Implementa mecanismos adecuados de renovación de tokens
• Proporciona documentación clara sobre el ciclo de vida de los tokens
• Gestiona de forma elegante la expiración de tokens en tu aplicación

Gestión de errores

Errores comunes de OAuth2 y sus significados:

• access_denied: El usuario rechazó la autorización
• invalid_client: Credenciales de cliente no válidas
• invalid_grant: Código de autorización no válido o expirado
• invalid_scope: El alcance solicitado no es válido o no está disponible

Implementa siempre una gestión de errores exhaustiva para proporcionar a los usuarios información clara cuando se produzcan problemas de autorización.

Conclusión

OAuth2 proporciona un método de autenticación seguro y fácil de usar para las integraciones con WordPress.com. Al implementar una gestión adecuada de los alcances, prácticas de seguridad y manejo de errores, puedes crear aplicaciones que respeten la privacidad del usuario y al mismo tiempo ofrezcan una funcionalidad potente. El sistema de permisos granulares garantiza que los usuarios mantengan el control sobre sus datos mientras permite que tu aplicación ofrezca características valiosas.

Para consultar la documentación completa de los endpoints de la API y ejemplos adicionales, visita la Referencia de la REST API de WordPress.com.