Entries from Oct 2013 ↓

Proposal - Securing the WordPress JSON API

I was recently added to the WordPress API team and this post contains my thoughts about the recent authentication discussion.

WordPress have a reasonably robust authentication system built in, the username and password system and it would be possible to use it along with Basic Auth to allow for API authentication. Please forgive any typos in advance; this was long and I didn’t really have the time to fully proof it.

Authentication, Identity and Authorization

While Authentication is very important there is also Authorization to consider. Here’s a nice blog post from Apigee on the difference between three (3) terms: Identity, Authentication and Authorization (IMO Apigee are the leading experts on web API design at the moment). In a nutshell here’s what they terms mean:

The Term What it Means
Identity Who is making the request?
Authentication Are they really who they say they are?
Authorization Are they allowed to do what they are trying to do?

And as they point out we may not need them all but what we need is the point of this post.

As a side note they say "Take Twitter’s API; open for looking up public information about a user, but other operations require authentication." What this says to me is an API key would be ideal for most read activities but most write activities should require Authentication.

Authorization without Authentication

As much as we need Authentication I think we need Authorization even more. There are some API actions we’ll happily allow anyone to do such as download the list of our most popular posts and we don’t need to authenticate for that, we only need to authorize.

Why authorize? Why not just allow open access? So we can track who we authorized in case, for example we need to rate-limit their usage or even revoke their access.

About SSL

Let me get this out of the way sooner than later. Anything that requires SSL is a non-starter just as requiring PHP 5.3 for WordPress 3.7 is a non-starter. Need I say more on this point?

However we could allow support for SSL, assuming that for what we implement the SSL and non-SSL solutions are compatible.

Mainstream Options for API Security

Let’s discus the variety of methods for securing an API; some mainstream and some a bit esoteric. Bottom line is that most informed people seem to say "Don’t role your own." So with that in mind I believe we have these options:

Option Discussion
OAuth 2 Generally considered the best balanced security option for mainstream web apps where security and ease of interaction for users is balanced. But can be complex to implement, especially on the client end, and requires SSL to be secure.
Basic Auth Not as good as OAuth 2 but super easy for the client to implement OTOH it is not secure unless SSL is used.
Digest Auth More secure than Basic Auth but still not fully secure. Quite a pain for the client to implement..
Amazon Auth Well-tested and doesn’t require SSL but is non-standard (ignoring "defacto-" standards) and still requires an API key.
API Keys Very simple for the client to implement and as secure the Capabilities tied to the API key, i.e. if it can only see public data and not update then it’s "secure enough". Fully secure if used with SSL. Assuming users can’t change passwords with the API key then it’s more secure than Basic Auth because user credential are never in a position to be compromised.

(Did I miss anything?)

Given the available options it would seem to me that OAuth 2, Digest Auth and even Amazon Auth are non-starters as a requirement for use of a JSON API in WordPress core because of the complexity each of them heave onto the API client developer, at least if one of these is the option for accessing the JSON API.

Basic Auth vs. API Keys

Which leaves the unsecure Basic Auth and mildly secure API Keys. So review the pros and cons of using Basic Auth – which is tied to the WordPress user’s username and password in the current version of the JSON API – and API keys:

  Pros Cons
Basic Auth
  • Easy to implement
  • Insecure
  • If API login is compromised then user may loose their account or be made to go through the hassle of regaining access.
  • Since APIs access can be automated it’s much more likely that a hacker could capture a username/password on a non-SSL API call (calls might be made continuously) than for a user login (which comparatively happen very infrequently.)
  • Can only support one Authorization profile per user account.
  • To support multiple authorization profiles a user would need create multiple user accounts,
  • To allow another person API access they either need to share their username/password or create another user account for them.
  • If API access requires a user account some sites could go from 5-10 users to having 50,000+ users (think of smaller sites like Mashable.)
  • If multiple user accounts are required then we’ll need a way to relate user accounts and allow one user account to manage other user accounts.
API Keys
  • API authorization is decoupled from user accounts.
  • One or many API keys can be tied to a single user account.
  • If API Key is compromised user can login and deactivate it.
  • Plugins could easily deactivate API keys if they follow an abuse pattern.
  • API keys could be added with expiration dates.
  • Sites with a large number of API users do not gain an explosion of regular users.
  • Each API Key can potentially support a different Authorization Profile (example use-case: I provide on API key to a social network – the key has limited capability – and use another API key – one that can do anything my user account can do – for an official WordPress mobile app that I use to access my site.)
  • Requires what appears to be more architecture

It seems to me from this comparison that API keys are the only reasonable option for allowing JSON API access to much of WordPress. However they are only appropriate for some use-cases and not even as-is they are not as a complete solution. Let’s discuss the rest of the solution for the use-cases in which I think they apply.

It also seems to me that tying API access to users accounts could easily create an explosion of complexity and significant user experience problems as users see their logins hacked by unsecure usage and then are locked out of or even loose their blogs.

API Roles and Capabilities

One of the ways in which API Keys might be acceptable without Authentication is that some things can be made freely available holders of API keys if we add in "API Roles and Capabilities."

Just like User Roles that are assigned a collection of Capabilities we could add "API Roles" that also have "API Capabilities". These Capabilities could be used to determine the Authorization status for each (what I’ll name) an "API Service" when requested.

Note: I’m defining an "API Service" as a URL + an HTTP method (GET, POST, etc.) and I’m calling the collection of Authorizations for all API Services as a "Authorization Profile."

I’ve reviewed the code for the WP_Role, WP_Roles and WP_User classes and I think the first two could be used without modification. If so then we only introduce a WP_API_Request class. And depending on the opinion of others the WP_API_Request class could be standalone or the WP_User class could be refactored to extend from an abstract WP_Auth class thereby allowing the new WP_API_Request class to also extend from WP_Auth.

We could then decide on a convention that any Capability name prefixed with 'api_' is a capability for an API Service and we add a function current_api_request_can() or just api_request_can(). Armed with api_request_can() we could write code like the following (note that api_request_can() assumes 'api_' as a prefix and thus does not require it to be passed):

Source code example

Are We Adding Too Much Code?

Although a comment was made that "we don’t want a huge chunk of code just for authentication" I would suggest that even if it were to be a large amount of code, which I doubt there would be, it shouldn’t matter how much code we add as long as that code doesn’t require significant maintenance and more importantly does not impose significant complexity onto the admin user in terms of "more options."

  • Assume that in Settings > General we add only one (1) single checkbox with the label "Enable JSON API" which by default we leave unchecked.

  • Once the user has explicitly chosen to enable the API (the equivalent of activating the plugin we have today) a single "Tools > JSON API" option is added.

  • The Tools/JSON API admin page can use tabs to organize the information so it would not be overwhelming, if even needed.

  • To offer the user the list of API keys we can reuse/modify the Taxonomy add/edit functionality assuming we add a 'user_api_key' taxonomy to allow us to store, lookup and manage API keys related to Users who would "own" the API keys.

  • Another tab for the Tools/JSON API admin page could potentially offer the ability to add and manage API Roles and another tab for API Capabilities. Or not, we could require these be managed programmatically just like User roles currently are.

  • And finally a main tab that allows you to force SSL use, or not.

What I’ve describe above it really not that much code. Would it make sense to risk the potential downside of tying the API to username and password in order to simply avoid the code that the API keys management would require?

Handling Escalating Security Requirements

Consider the "API Services" discussed earlier; we could implement a mapping of authentication requirements to API services such that different services have different authentication/authorization requirements. Consider this table:

Requirement HTTP Methods API Services That Allows Example API Service
No API Key Required GET Access to public information with a low risk of needing a rate limiter. An API service that returns site name and other metadata. The metadata could also including a links to an API service to request an API key via API.
API Key GET Access to public information that might need to be rate limited. Return the current list of blog posts.
API Key + Nonce POST, PUT Add Content or Update Revertible Content Update of Posts, add Taxonomy Terms.
Nonce GET Add Content or Update Revertible Content Update of Posts, add Taxonomy Terms.
SSL+Basic Auth GET Returns secure information for client w/o API Key Retrieve an API key programatically.
SSL+API Key POST, PUT Updates secure information Modify User Profile, Deletes Posts.
SSL+Basic Auth POST, PUT Update highly sensitive information Change user password

API Keys + Nonces

Note that we combine nonces with API keys. One of the ways WordPress handles security is with nonces, and the API need be no different. Note that the nonce would be generated by WordPress core or a plugin for the logged in user to allow their browser’s to use the API via AJAX. These use-cases would authorize for the JSON API similar to how the current AJAX system in WordPress authorizes.

For mobile apps nonces could also be offered to last for longer, requiring a mobile device to retrieve a new nonce once every 15 minutes or so but then allowing them to just use the nonce + API key within those windows. Of course you wouldn’t want a 15 minute window for nonces used with AJAX apps

Using SSL

So if we follow the outlined approach we can provide a reasonably level of API access without requiring SSL but we can still enforce the benefit of SSL for those who are likely to have the where-with-all to upgrade to SSL.

Consider this, if they need their sensitive parts of their site updated via API then they are likely special enough that they can make sure that SSL happens. But if unexpected consequences occur and someone builds a SaaS that people want to use but that requires SSL then frankly it creates an opportunity for hosting companies to see a high level of demand for turnkey SSL setup.

And optionally we can add an 'WPAPI_ALLOW_NO_SSL' constant for those site builders and site owners with a "Devil May Care" attitude.

Summary

In summary I’m proposing for the JSON API for WordPress to:

  • Use API Keys for Authorization
    • (And if you are still not convinced, read this).
  • Incorporate API Roles and Capabilities
  • Support Escalating Authentication Requirements for API Services
  • Build Single Menu Item Admin UI for the admin to Manage the API.

Let me know your reactions in the comments below.

What the World Needs is a Markdown IDE for Programmer Documentation

As an active JetBrains’ PhpStorm user one of my feature requests was for First Class WYSIWYG Markdown/Markdown Extra Support. Unfortunately they told me (and others) to use a 3rd party plugin which given it’s lack of quality and features turned out to be a non-starter for me. So I continue to use Markdown Pro which I love for what it is but I really need an order of magnitude more features.

But today I was thinking hard about how I’m going to implement documentation for the project I’ve worked on over the past 3 months without killing myself. A sad realization came over me that using MarkDown Pro would be very painful to use because it’s really nothing more than a glorified Notepad with Markdown support and a preview window; it has nothing to support me in the developer of documentation projects.

Then it hit me; what I really need is not an ability for PhpStorm to edit markup but instead a full-featured documentation IDE targeting programmers. And frankly I think the company best positioned to offer this would be JetBrains but I’d be happy to see any company offer it, if someone just will (Maybe those Sublime guys could…?)

So if you are from JetBrains or from some other company please consider the following feature set:

Features

Here are just some of the features that I’d love to see a Documentation IDE support

  • Manage "Documentation Projects" vs. just individual markdown files.
  • Multi-pane editor like PhpStorm but with panes that support document creation.
    • Vertical or horizontal split edit and preview windows.
  • CSS-based Themes for preview.
  • File Watchers for post processing LESS, Saas another other features.
  • Version control support for Git, Mercurial, SVN, etc.
    • Support for docs in a subdir of a code repository or as independent repo.
  • Support for all major Markup/Markdown format including Different Dialects and HTML
    • Conversion between Markup/Markdown formats
    • Ability to configure all and/or specific documents to be edited in one format/dialect and saved in another.
  • Ability to Publish and Maintain Documentation Websites from DocStorm
    • Publish directly to GitHub Pages as well as maintain existing GitHub pages.
    • Publish to Evernote, DropBox, etc.
    • Offer "POST-To-Publish" feature that would allow us to publish and update using HTTP POSTs so that we could write our own server-side integrations to other locations besides GitHub such as CMS (WordPress, Ghost, etc), Wikis (Mediawiki, etc.), SaaS platforms and more using our own PHP, Ruby, Python, Node.js or other code server-side code.
  • Navigation Between Documents
    • Jump to Document via selected hyperlink
    • Jump to Section of Document via selected hyperlink+fragment
    • Jump to File by Name
    • Jump to Headings in Project (find by autocomplete)
  • Refactoring
    • Refactor Document Structure to change all affected links
      • If URL changes
      • If URL fragment changes
    • Move selected content into a new file and insert a link to the new file.
    • Provide a tree view of files and allow refactoring by drag-and-drop in tree view, with all necessary link fix-up.
  • Manage Images
    • As part of the project, relative to the project root
    • Enable images to be previewed inline
  • Search and Replace like the wonderful PhpStorm search & replace)
    • Regular expression search.
    • Highlight on up/down arrow of selected options.

Also potentially valuable would be integrations with existing documentation tools although I can’t yet envision exactly what that would look like:

Benefits to JetBrains

Back to JetBrains and why they should do this. Currently they have IDEs for Java, PHP, Ruby, Python and Javascript programmers and for the most part (I would assume) few of their customers cross over and purchase multiple tools. However if they were to offer a "DocStorm" then every one of their current IDE customers they might be able to up-sell a sizeable number of developers.

But even if they won’t do it, maybe someone else will? 

Update

If you like this idea please vote for it on the JetBrains tracker

Update 9-Oct-2013

So JetBrains considered the idea, but decided against it. :-(  But they have changed their mind in the past if they’ve had enough requests, so please vote for both these tickets, if you will:

Better yet, if you are in the editor space and looking to expand your market, please consider building this flavor of your product and I expect you will find many new customers.