Autenticación OAuth2

OAuth2 es un protocolo que permite que las aplicaciones puedan interactuar con blogs en WordPress.com y webs de WordPress autoalojadas que utilizan Jetpack. El objetivo principal de OAuth es permitir a los desarrolladores interactuar con webs de WordPress.com y Jetpack sin necesidad de almacenar credenciales confidenciales. Nuestra implementación también permite que los usuarios gestionen sus propias conexiones.

Si acabas de empezar en el mundo de OAuth, tienes más información en https://oauth.net/. Si ya conoces bien OAuth, lo único que realmente necesitas saber son los dos endpoints de autenticación: el endpoint de autorización y el de la solicitud de token. Estos endpoints son https://public-api.wordpress.com/oauth2/authorize y https://public-api.wordpress.com/oauth2/token

Los mismos endpoints se utilizan para blogs de WordPress.com y sitios de Jetpack. Antes de comenzar a desarrollar una aplicación, necesitarás un ID de cliente, una URI de redirección y una clave secreta de cliente. Esta información se utilizará para autenticar tu aplicación y verificar que las llamadas a la API que se realicen sean válidas. Puedes crear una aplicación o ver los detalles de tus aplicaciones con nuestro gestor de aplicaciones.

Conseguir un token de acceso

Para actuar en nombre de un usuario y hacer llamadas desde nuestra API necesitarás un token de acceso. Para conseguirlo debes seguir el flujo de token de acceso y solicitar al usuario que autorice tu aplicación para actuar en su nombre.

Los tokens de acceso se pueden solicitar por blog y usuario o como un token global por usuario. Además de los tokens globales, hay ciertos endpoints (como Me gusta y Seguir) donde puedes usar el token de un usuario en cualquier blog para actuar en su nombre.

Para empezar, tendrás que enviar al usuario al endpoint de autorización.

Parámetros necesarios:

• client_id debe establecerse en el ID de cliente de tu aplicación tal y como se encuentra en el gestor de aplicaciones.
• redirect_uri debe establecerse en la URL a la que el usuario será redirigido una vez que la solicitud sea autorizada. La redirect_uri debe coincidir con la que está en el gestor de aplicaciones.
• response_type puede ser «code» o «token». «Code» debe usarse en aplicaciones desde el servidor donde puedes garantizar que la información secreta está almacenada de forma segura. Estos tokens no caducan. «Token» debe usarse en aplicaciones del lado del cliente. Esto se llama «OAuth Implícito». Actualmente, los tokens duran dos semanas y los usuarios tendrán que autenticarse con tu aplicación una vez que el token caduque. Los tokens se devuelven a través del hash/fragmento de la URL.

Parámetros opcionales:

• blog:  Puedes pasar un parámetro de blog (&blog=) con la URL o ID de blog en un blog de WordPress.com o un sitio de Jetpack. Si no pasas un blog, o si el usuario no tiene acceso administrativo para gestionar el blog que has pasado, se le pedirá al usuario que seleccione el blog al que le estás otorgando acceso.
• scope: ver más abajo.

Alcance del token

El alcance del token define el tipo de acceso que tu aplicación tendrá a los datos del usuario. De forma predeterminada (si se omite el alcance), el token otorgará a la aplicación acceso completo a un único blog.

Por ejemplo, si tu aplicación necesita acceso solo a los endpoints de entradas y comentarios, establece el alcance en &scope=posts%20comments

Además, se admiten los siguientes valores especiales, y no deben usarse en combinación con ningún otro valor:

• auth: El alcance de auth (&scope=auth) otorgará a tu aplicación acceso solo a los endpoints de /me, y se utiliza principalmente con WordPress.com Connect.
• global: El alcance global (&scope=global) otorgará a tu aplicación acceso completo a todos los blogs que el usuario tiene en WordPress.com, incluidos cualquier blog de Jetpack que tengan conectado a su cuenta de WordPress.com. Si estás especificando el alcance como global, debes omitir el parámetro blog.

Autenticación del servidor/código

La redirección a tu aplicación incluye un código que necesitarás en el siguiente paso. Si el usuario ha denegado el acceso a tu aplicación, la redirección incluirá ?error=access_denied. Una vez que el usuario haya autorizado la solicitud, será redirigido a la redirect_url. La solicitud será algo así: http://developer.wordpress.com/?code=cw9hk1xG9k

Este es un código limitado en el tiempo que tu aplicación puede intercambiar por un token de autorización completo. Para hacerlo, necesitarás pasar el código al endpoint del token haciendo una solicitud POST a https://public-api.wordpress.com/oauth2/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 code from the previous request
	'grant_type' => 'authorization_code'
) );
curl_setopt( $curl, CURLOPT_RETURNTRANSFER, 1);
$auth = curl_exec( $curl );
$secret = json_decode($auth);
$access_key = $secret->access_token;

Se requiere que pases client_id, client_secret y redirect_uri para aplicaciones web. Estos parámetros deben coincidir con la información de tu aplicación, y el redirect_uri debe coincidir con el redirect_uri utilizado durante el paso de autorización (arriba). grant_type debe establecerse como «authorization_code». code debe coincidir con el código que recibiste en la redirección. Si todo funciona correctamente y el usuario otorga autorización, recibirás una cadena codificada en JSON que contiene el token y algo de información básica sobre el blog:

{
    "access_token": "YOUR_API_TOKEN",
    "blog_id": "blog ID",
    "blog_url": "blog url",
    "token_type": "bearer"
}

Ahora tienes un token de acceso que debe almacenarse de forma segura junto con el ID del blog y la URL del blog. Este token de acceso permite a tu aplicación actuar en nombre del usuario en este blog en concreto. Si quieres ver otro ejemplo, consulta nuestra implementación de Node.

Probando una aplicación como el propietario del cliente

Como propietario del cliente, puedes autenticarte con el password grant_type para omitir el paso de autorización de autenticación e iniciar sesión con tu nombre de usuario y contraseña de WordPress.com. Ten en cuenta que si estás utilizando la autenticación en dos pasos (muy recomendada), tendrás que crear una contraseña de aplicación para poder usar el password grant_type.

$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,
) );
curl_setopt( $curl, CURLOPT_RETURNTRANSFER, 1);
$auth = curl_exec( $curl );
$auth = json_decode($auth);
$access_key = $auth->access_token;

Como mencionamos anteriormente, esto solo está disponible para ti como propietario de la aplicación, y no para ningún otro usuario. Esto es solo con fines de prueba.

Cliente/OAuth implícito

Una vez que el usuario autentique su blog, será redirigido de vuelta a tu aplicación. El token y la información del usuario se incluirán en el fragmento de la URL.

Este token te permitirá hacer llamadas autenticadas del lado del cliente usando solicitudes CORS/AJAX. El token actualmente solo dura dos semanas. Usa el fragmento expires_in para detectar cuándo deberías solicitar una actualización.

Validar los tokens

Puede ser útil poder validar la autenticidad de un token: concretamente, que pertenece a tu aplicación y al usuario que estás autenticando. Esto es especialmente necesario al enviar un token a través de la red (por ejemplo, una aplicación móvil enviando el token como credenciales de inicio de sesión a una API). Para verificar un token, utiliza el endpoint /oauth/token-info, pasando el token y tu client_id:

Si el token proporcionado no ha sido autorizado para tu aplicación, el endpoint devolverá un error. Si el token es válido, recibirás una cadena codificada en JSON con el ID del usuario y el alcance del token:

{
    "client_id": "your client ID",
    "user_id": "user ID",
    "blog_id": "blog ID",
    "scope": "scope of the token"
}

Hacer una llamada a la API

Nuestra API se basa en JSON. Puedes ver todos los endpoints disponibles en nuestra documentación de la API. También puedes hacer llamadas a la API con nuestra API XML-RPC heredada. Para hacer una llamada autenticada a nuestras API, debes incluir tu token de acceso con la llamada. OAuth2 utiliza un token BEARER que se proporciona en una cabecera de autorización.

$access_key = 'YOUR_API_TOKEN';
$curl = curl_init( 'https://public-api.wordpress.com/rest/v1/me/' );
curl_setopt( $curl, CURLOPT_HTTPHEADER, array( 'Authorization: Bearer ' . $access_key ) );
curl_exec( $curl );

El ejemplo anterior devolvería información sobre el usuario autenticado.

jQuery.ajax( {
    url: 'https://public-api.wordpress.com/rest/v1/sites/' + site_id + '/posts/new',
    type: 'POST',
    data: { content: 'testing test' },
    beforeSend : function( xhr ) {
        xhr.setRequestHeader( 'Authorization', 'BEARER ' + access_token );
    },
    success: function( response ) {
        // response
    }
} );

El ejemplo anterior crearía una nueva entrada. Puedes hacer llamadas similares a los otros endpoints disponibles.