WP REST API: Introducing the Authentication Broker

As an astute follower of the REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. project may have noticed, authentication with the APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. has been difficult and incomplete. While cookie authentication solves the issue for JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. 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 HTTPSHTTPS HTTPS is an acronym for Hyper Text Transfer Protocol Secure. HTTPS is the secure version of HTTP, the protocol over which data is sent between your browser and the website that you are connected to. The 'S' at the end of HTTPS stands for 'Secure'. It means all communications between your browser and the website are encrypted. This is especially helpful for protecting sensitive data like banking information.. OAuth 1 builds in a cryptographic signing process to avoid replay attacks, while OAuth 2 relies on the security provided by SSLSSL Secure Sockets Layer. Provides a secure means of sending data over the internet. Used for authenticated and private actions./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 pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party) 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 sourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL. 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 coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.. 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 GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ too.

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