WP REST API: Introducing the Authentication Broker

As an astute follower of the REST API project may have noticed, authentication with the API has been difficult and incomplete. While cookie authentication solves the issue for JavaScript code running on the site, external sites have a much harder time.

In particular, connecting a client to multiple sites is near-impossible, as the distributed nature of WordPress would require registering on every site.

To solve the decentralised registration problem, the REST API team (lead by myself and Ryan) is introducing the Authentication Broker system. Our initial default broker is at https://apps.wp-api.org/ and we’ve published the specification for the system.

Authentication Challenges

There are primarily two challenges when it comes to authentication: the protocol and application discovery. The protocol we have broadly settled on is OAuth 1, as the simpler OAuth 2 requires HTTPS. OAuth 1 builds in a cryptographic signing process to avoid replay attacks, while OAuth 2 relies on the security provided by SSL/TLS instead. As there are client libraries available for OAuth 1 in virtually every language, the additional cryptography is simple enough to not worry about too much.

The second challenge is application discovery. OAuth requires pre-registration of the application on the site, which then issues you a key and secret. This concept should be familiar to anyone who has registered a Facebook or Twitter application. The basic principle here is that you register your application with Facebook, which means the two parties (your app and Facebook) both have the “shared” secret. This is then used for the cryptographic signing. (Technically, Facebook uses OAuth 2, but the difference is not particularly relevant here.)

Because all WordPresses are their own sites, they are essentially each their own copy of Facebook in the above OAuth flow. This means as an app developer, you need to register an application on a WordPress site (using the OAuth 1 plugin) and copy the key and secret into your app. This is OK for people developing an app for their specific install of WordPress, but it’s no good for developers creating apps that can connect to anyone’s WordPress site. For distributable apps, this would require users to register your application manually on their site, then go through the usual OAuth process. This is the process that open source plugins typically have to do for Facebook and Twitter authentication, and it’s generally a terrible experience.

Solving Distributed Application Registration

To solve this issue, we have created a new project dubbed the REST API Authentication Broker. The broker is a separate registry of applications that WordPress installs can use as the authority on what applications can connect to it. This means a developer can create their application with the broker (similar to how they would on Facebook) and then they can use their key and secret to connect to all WordPress installs that delegate to the broker.

This also allows the broker to revoke bad acting applications from the registry, which will cause the rogue application to be disabled on all WordPress sites using it.

The WordPress ecosystem is very decentralized, allowing site owners to control who and what has access to their data. The broker adopts this philosophy by allowing anyone to run a broker service which WordPresses can delegate to. Brokers need only to be mutually recognised by the application and site to be used; our initial primary broker is simply a default broker built into the connection plugin. For example, a large organization that has several hundred WordPress installs could run their own broker server to act as the centralized point of authority on what apps they allow to connect to their sites.

It’s important to note that the broker is never able to access your site or user data directly. It’s just used as a registry of allowed applications that can use the normal OAuth process whereby a user on your site delegates permission on their behalf.

The Default Broker

Rather than explaining all this in the abstract, we decided to put our code where our mouth is and build the broker system with the intent for it to be adopted to solve this problem. We’ve been working on this for the last few months, and we’re finally ready to release it.

The “default” broker is currently hosted on https://apps.wp-api.org/ where you can sign up as a developer to create your app. You’ll be presented with a key and secret that you can use in your app to communicate with the broker and connect to any site using the broker plugin. The goal is to merge the broker plugin into the OAuth plugin, and eventually into core. This is the path we see to being able to authenticate with any WordPress site on the web!

We’re currently looking for feedback and testing of the new broker system. You can install the broker plugin on your site (which requires the OAuth 1 plugin) from GitHub.

Much more information about this can be found at https://apps.wp-api.org/ and you can even read the Specification for Brokered Authentication if you wish. The broker server, example client and the theme are all open source on GitHub too.

Thanks to everyone who helped in the development process and contributed their feedback.