PHP
Article

WP API and OAuth – Using WordPress without WordPress

By Bruno Skvorc

In this tutorial, we’ll learn how to install and use WP-API with OAuth – a WordPress plugin which uses REST-like API endpoints to allow reading of WP content to unauthenticated users, and writing of WP content to users who authenticate via OAuth (or via Cookies for themes and plugins).

WordPress Logo

Using the plugin isn’t very straightforward, and the prerequisite list is quite long, so this post was written to make it simple and relatively approachable (as long as you’re in control of your own server).

The tutorial assumes basic familiarity with the terminal, and with Vagrant for ease of development.

Installing

As usual, we’ll be using SitePoint’s trusty Homestead Improved instance to get a fresh environment up and running:

git clone https://github.com/swader/homestead_improved hi_wp_github
cd hi_wp_github
sed -i '' "s@map\: \.@map\: $PWD@g" Homestead.yaml

That last line is a shortcut that makes the current folder of the host machine shared into the VM’s Code folder. I also changed the sites block to:

sites:
    - map: test.app
      to: /home/vagrant/Code/wptest

Remember to have test.app (or the URL you choose) in your /etc/hosts file, as per instructions.

Next, we get a new instance of WP up and running. Since Homestead has MySQL pre-installed, this is a piece of cake.

cd ~/Code
wget https://wordpress.org/latest.tar.gz
tar -xvzf latest.tar.gz
mv wordpress wptest
cd wptest
cp wp-config-sample.php wp-config.php

After we update wp-config.php accordingly and set up our keys and database credentials, the WP instance is ready and can be finalized by running it in the browser.

WP-API

Despite the flak it’s taken over the years (a large part of it fired from my own Dual Flak Cannons), WP really is trying to get with the times while still accommodating their old, technically inept userbase.

One such effort is the WP-API, a REST-like set of endpoints built into WP as a plugin so that the internals of a WordPress installation can become accessible to the outside. For example, getting your posts in JSON format is as simple as pinging /wp-json/posts.

It can be easily installed via the default plugin manager – the stable version is 1.2.* at the time of this writing – so let’s do that.

Installing the wp-rest-api plugin

If we test immediately after installation, the URL /wp-json/posts should produce a JSON array of the initial “Hello World” post. However, the actual submission process (updating and posting) isn’t as simple.

OAuth – Server

Unfortunately, as with all things WP, even their attempts to be modern are already out of date.

As such, they use OAuth1 rather than OAuth2 for authentication. For that, we’ll need the OAuth1 plugin installed. For that, though, we need the wp-cli upgrade, a way to use WP commands from the terminal:

curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp

Then, we grab the OAuth plugin:

cd ~/Code/wptest
git clone https://github.com/WP-API/OAuth1 wp-content/plugins/oauth-server

Activate the plugin (which should now appear in the Plugins list) and back in the terminal run:

wp oauth1 add

This should produce a key / secret combination that can be used for OAuth authentication:

ID: 4
Key: xOp1fGMgouBl
Secret: Sk7YcM48qsmcDPp2NSmna3kMEfTtDNfxpy43xjWp1mSP7ytw

Aside from being out of date with their protocol approach, there’s also the problem of us having to use 3-legged OAuth rather than something simpler, UI-less like 2-legged OAuth flow. For differences, read this extensive guide. Hopefully, that’ll improve later.

The good news, though, is that if you’re the owner of the WP site and you’re enabling OAuth API access for others – you’re done! It’s up to them to develop a client, and that’s what we’ll do next.

OAuth – Client

To test submissions into WP via WP-API, we need an “app” to serve as the “submitter”. For that, we make a new project in another folder in the virtual machine – perfect for testing. First, we edit the virtual machine’s Homestead.yaml file to include a new site:

sites:
    - map: test.app
      to: /home/vagrant/Code/wptest
    - map: test2.app
      to: /home/vagrant/Code/submitter

Then, we exit the VM with exit and re-provision with vagrant provision and then re-renter the VM with vagrant ssh. Now that our submitter virtual host is defined, let’s add a simple index.php file into it, and a (for now) empty callback.php file.

mkdir ~/Code/submitter
touch ~/Code/submitter/index.php
touch ~/Code/submitter/callback.php
touch ~/Code/submitter/credentials.php
cd ~/Code/submitter

The credentials file should hold the keys we got from the WP app:

// credentials.php
<?php

return [
    'consumer_key' => 'xOp1fGMgouBl',
    'consumer_secret' => 'Sk7YcM48qsmcDPp2NSmna3kMEfTtDNfxpy43xjWp1mSP7ytw'
];

We’ll also need some packages installed:

composer require --dev symfony/var-dumper
composer require guzzlehttp/guzzle:~5

VarDumper is there to help us debug, and Guzzle 5 is there to help us issue requests at the WP-API. We could use a generic OAuth client, but why not use Guzzle’s?

composer require guzzlehttp/oauth-subscriber

Note that the submitter we’ll be building below is just a demo script, and should only be used as inspiration for implementing OAuth+WP-API in your own application, not as a full application demo.

One more thing – by default, WordPress blocks login redirections to external sites (those differing in domain) so a new filter needs to be added which will allow this. Back in the WP app’s sources, open default-filters.php and add the following somewhere into the file:

add_filter( 'allowed_redirect_hosts' , 'my_allowed_redirect_hosts' , 10 );
function my_allowed_redirect_hosts($content){
    $content[] = 'test2.app';
    return $content;
}

Naturally, replace test2.app with your own URL if you used a different one.

Authentication – Leg 1

Authenticating with WP API over OAuth is something that’s completely missing from the docs, but that’s because OAuth authentication is something that’s quite specific and almost identical across projects. That doesn’t mean it’s simple, though. We’ll mostly be following the procedure from this post, in one way or another.

Give the index.php file the following contents:

<?php

require_once 'vendor/autoload.php';

session_start();

use GuzzleHttp\Client;
use GuzzleHttp\Subscriber\Oauth\Oauth1;

$client = new Client([
    'defaults' => ['auth' => 'oauth']
]);

$oauth = new Oauth1(include 'credentials.php');

$client->getEmitter()->attach($oauth);
$callback = 'http://test2.app/callback.php';

$req = $client->createRequest("POST", 'http://test.app/oauth1/request',
    ['body' => ['oauth_callback' => $callback]]);

try {

    $res = $client->send($req);
    parse_str($res->getBody());

    $_SESSION['oauth_token'] = $oauth_token;
    $_SESSION['oauth_token_secret'] = $oauth_token_secret;

    header("Location: http://test.app/oauth1/authorize?oauth_token={$oauth_token}&oauth_callback=".$callback);

} catch (\Exception $e) {
    dump($e);
}

First, we define a new Guzzle client and set its default auth mode as Oauth. Then, we set up a new OAuth1 client instance and give it the key and secret we got before by running wp oauth1 add. We use this instance as an emitter and create a POST request from it (also defining a callback – the URL to which WP is supposed to redirect us once we authorize it), which is then sent to our WP app.

In the try/catch block, we turn the response into two strings: $oauth_token and $oauth_token_secret, both of which we need to continue the auth process. We save them into the session, and go on to step 2: the callback.php file.

Authentication – Leg 2

For the second leg of the 3-legged OAuth flow, we need to build the callback.php file.

When we log into WP and Authorize our submitter app, WP sends us back to the callback URL we provided. It’ll also send along some additional params: oauth_token, oauth_verifier and wp_scope.

We use the verifier and the oauth_token to send a request to the /access endpoint and get an access token (the secret) which will finally let us do operations on the database.

<?php

require_once 'vendor/autoload.php';

session_start();

use GuzzleHttp\Client;
use GuzzleHttp\Exception\ClientException;
use GuzzleHttp\Subscriber\Oauth\Oauth1;

$authToken = $_GET['oauth_token'];
$authVerifier = $_GET['oauth_verifier'];

$client = new Client(['defaults' => ['auth' => 'oauth']]);

$oauth = new Oauth1(
    array_merge(include 'credentials.php',
        ['token' => $_SESSION['oauth_token']])
);

$client->getEmitter()->attach($oauth);

if ($authToken == $_SESSION['oauth_token']) {
    $req = $client->createRequest("POST", 'http://test.app/oauth1/access',
        ['body' => ['oauth_verifier' => $authVerifier]]);

    try {
        $res = $client->send($req);

        $params = (string)$res->getBody();

        parse_str($params);

        $_SESSION['oauth_token'] = $oauth_token;
        $_SESSION['oauth_token_secret'] = $oauth_token_secret;

        header("Location: makepost.php");
    } catch (ClientException $e) {
        dump((string)$e->getResponse()->getBody());
    } catch (\Exception $e) {
        dump($e);
    }
}

Authentication – Leg 3

Finally, let’s create a file makepost.php which we’ll use to create a sample post in our WP app – if that goes through, it means everything is working just fine.

<?php

require_once 'vendor/autoload.php';

session_start();

use GuzzleHttp\Client;
use GuzzleHttp\Exception\ClientException;
use GuzzleHttp\Subscriber\Oauth\Oauth1;

$client = new Client([
    'defaults' => ['auth' => 'oauth']
]);

$array = array_merge(include 'credentials.php', [
    'token' => $_SESSION['oauth_token'],
    'token_secret' => $_SESSION['oauth_token_secret']
]);

$oauth = new Oauth1($array);

$client->getEmitter()->attach($oauth);

$post = [
    'title' => 'From outside!',
    'content' => 'This post was submitted via the API!!!',
    'status' => 'publish'
];

$req = $client->createRequest("POST", 'http://test.app/wp-json/posts',
    ['json' => $post]);

try {
    $res = $client->send($req);
    dump((string)$res->getBody());
} catch (ClientException $e) {
    dump((string)$e->getResponse()->getBody());
} catch (\Exception $e) {
    dump($e);
}

We’ve got a simple “post” in the form of an array with three fields, and defaulting to “publish” mode so we can immediately see it on the home page of our WP app, without having to go into the editor and publish it manually.

After execution, the post should be visible on the home screen of our WP app:

Post has been published

Of course, the three files above (index.php, callback.php, makepost.php) are examples of OAuth use, and should probably be turned into something more reusable and coherent, but for purely testing if the integration works, they’re just fine. Fear not, though – we’ll be upgrading this significantly in an upcoming post.

Conclusion

In this tutorial, we installed and activated WP-API and WP-Oauth, in an attempt to make our WP installation accessible to the outside (authenticated) world. As you can see, it’s not exactly straightforward, but hopefully this tutorial helped in getting you up and running.

Have you had experiences with WP-API yet? Would you like to see more examples? Let us know!

  • http://rundtomwp.dk/ Holger Govertz

    Isn’t it possible to do this without using the terminal, or in my case the command line, I use Desktop server for my local dev environment, and creating sites is just a click with the mouse. Besides creating test sites what will the next step be if I want to avoid the command line?

    • Dirk Leeward

      This OAuth plugin won’t install from within WordPress, it requires the CLI. The also prevents its use on WPEngine and other similar managed hosts.

  • Darren Hundt

    Hi. This article explains a lot of questions I’ve had about creating an iOS app for a lot of my clients who use WP websites I’ve built for them. I use a basic shared hosting plan for them (hostgator) and install WP on it. Is the process described in this article something I could do? I generally only interact with the site via 1)wp-admin, 2)FTP, 3)phpMyAdmin, & 4)cPanel. Not with anything with a command line. Thanks for the helpful article.

    • http://www.bitfalls.com/ Bruno Skvorc

      I doubt it, sorry. You need command line access for this to work. However, there’s some chance of WP-API making it into WP core soon, and then an official update will install this for you. Fingers crossed for early 2016.

    • Daniel Rodd

      Darren, I also have a hostgator shared hosting plan, you need to access shell or sso, it’s actually quite simply, from your local pc you can install something like putty and voila, from putty for instance you simply provide your host ip address which can be found directly in your cpanel dashboard, the port is 2222, after that it’s going to load a very similar interface like dos, this is shell access, it’s going to ask for login credentials, these are simply your hostgator cpanel username without @ or domain and your cpanel password, the password will not display as you type, but don’t worry, just hit enter, I had trouble learning this, but after much research and googling, I was finally able to gain access to shell in a shared plan, you can too, cheers
      Daniel Rodd

      • Darren Hundt

        Thank you for the reply! I’m going to try it out.

        D

        • Daniel Rodd

          damn, I meant ssh, not sso hehe, cheers!

  • http://aj-js.github.io Adam Lea

    After executing: wp oauth1 add

    I dont get:
    ID: 4
    Key: xOp1fGMgouBl
    Secret: Sk7YcM48qsmcDPp2NSmna3kMEfTtDNfxpy43xjWp1mSP7ytw

    Instead I get (the ID is filled given, Key and Secret are blank):
    ID: 51
    Key:
    Secret:

    Any thoughts to why this might be happening? Appreciate any help…

    • http://www.bitfalls.com/ Bruno Skvorc

      This tends to happen when parts of the plugin weren’t activated properly, or the new key wasn’t properly inserted into the database. I’m afraid I can’t help you off the top of my head, other than suggesting you try reinstalling the plugins and making sure everything goes smoothly from start to finish.

      • http://aj-js.github.io Adam Lea

        Thank you. Will try that and see what happens :)
        – Adam

  • Good Stuff Slu

    Isn’t there any way for users to login via their username and password?

    • http://www.bitfalls.com/ Bruno Skvorc

      You’d have to modify the plugin to forward that info to the helper tool which generates the key entries etc. This will all change soon, because the API is slated for integration into WP core.

  • http://www.softhopper.net/ Soft Hopper

    Thanks for making video also :)

Recommended

Learn Coding Online
Learn Web Development

Start learning web development and design for free with SitePoint Premium!

Get the latest in PHP, once a week, for free.