Ryan McCue 06:39 on December 8, 2013

I’ve been messing around with…

I’ve been messing around with the WooCommerce code for OAuth, and unfortunately it has API consumers (that is, applications) tied to users. This is a pretty limited method, but it simplifies the code and flow a lot. The question is, do we want core to be limited to this extent, or do we need to think about something more complicated? With this sort of flow, we can show the user’s API key/secret on their profile page, and they just need to fill that in to their application. (We could also add an xAuth flow, where the application can request those keys via Basic authentication.)

Alternatively, we treat consumers as an entirely separate entity, which can then prompt users to authorise them. This is the more traditional OAuth flow that you see with Twitter, Facebook, etc. This increases the application complexity a bit, but allows a site admin to manage applications rather than having it managed per-user. It also allows “rogue” (misbehaving/compromised) application keys to be revoked, rather than requiring each user to regenerate a key/secret.

I’m on the fence about this one. There are benefits to both approaches, and I’ve summarised these below:

	One-consumer-per-user	Independent consumers
Setting up	User copies key/secret from profile page into application	Application developer registers via site admin, application directs user to authorise the application
Managing	All applications share key/secret	Applications registered via admin panel
Revoking	Users have to regenerate keys and change all existing applications	Admin revokes application
Site UI	Key/secret fields on user profile page	Consumer management settings page

If you can think of any other points here, post in the comments. I think it’s fairly split between the two at the moment, so I can’t really decide.

mikeschinkel 06:46 on December 8, 2013

Thanks for making this post. My position is not on the fence at all, independent consumers seems the optimal approach to me. One consumer per user is okay if you are dealing with an unimportant API and one that is very unlikely to have many consumers, but I don’t think we’d want to limit the large traffic sites that WordPress’ in that way.
- Ryan McCue 06:49 on December 8, 2013
  
  That was my feeling too, but the big issue is the (code, UI, and API) complexity it requires. We’ll also need a new admin interface to handle managing consumers just for this. To play devil’s advocate: larger traffic sites are probably going to customise their API and such anyway, so installing an alternative authentication plugin would be no big deal.
  - mikeschinkel 06:53 on December 8, 2013
    
    Understood about the complexity, but that didn’t stop WordPress from adding other key pieces (such as HTTP support.)
    
    To play devil’s advocate back at you, we can create an API that quickly gets balkanized and for which few if any API client get built for it will be interoperable across sites, or we can do our best to help people building API clients to be able to leverage what will become the largest group of interoperable REST APIs on the web, probably by 3 orders of magnitude.
    - Ryan McCue 07:04 on December 8, 2013
      
      Understood about the complexity, but that didn’t stop WordPress from adding other key pieces (such as HTTP support.)
      
      That’s mostly internal complexity in the implementation, whereas we’re also talking about UI complexity (extra steps in managing clients and authorising applications) and API complexity (OAuth flow requirements for applications).
      
      To play devil’s advocate back at you, we can create an API that quickly gets balkanized and for which few if any API client get built for it will be interoperable across sites, or we can do our best to help people building API clients to be able to leverage what will become the largest group of interoperable REST APIs on the web, probably by 3 orders of magnitude.
      
      Whatever is in core will be interoperable, but both require site-specific steps: independent consumers have to be registered on the site (unless we add dynamic consumer registration, but the OAuth WG hasn’t finalised any of those specs yet), while per-user consumers require copying a key/secret into the application. Neither of these affect anything except the initial OAuth flow, afterwards all the API authentication is functionally identical for the application.
      - mikeschinkel 07:25 on December 8, 2013
        
        whereas we’re also talking about UI complexity (extra steps in managing clients and authorising applications)
        
        True, but only for those who are actually using the API. So no additional complexity except for those who are getting new benefits.
        
        and API complexity (OAuth flow requirements for applications).
        
        That’s for external users who, unless I’m mistaken would have to follow some type of process and the OAuth flow has IMO been the least painful way for non-tech users to hook up an API.
        
        Whatever is in core will be interoperable, but both require site-specific steps:…
        
        The interoperability I speak of is orthogonal to user action requireds; I meant if someone writes an API client to speak to the WordPress API such as an iPhone app in Objective-C then ideally it will work for all WordPress sites that enable to API. Period.
        
        Of course there is the issue of what happens with custom post types, custom taxonomies, custom tables, custom routes and other customization but hopefully we can implement in such a way that two developers building effectively the same functionality will end up building it as interoperable as possible.
        
        One area I’m especially concerned about is if hooks allowing developers to modify the output of the API for their own custom needs in manners will be able to render the API non-interoperable when they could have implemented inter-operably had they only been cognizant of the issues and/or known how. Ideally we’ll take an approach much like Post Format where much of the API is locked down so there can be interoperability, but where the API developer can still filter output by access rights, just not modify the output format or how well-known URLs behave. But I digress as this off-topic and should be discussed in another thread at the appropriate time.
  - mikeschinkel 06:56 on December 8, 2013
    
    Imagine if the same API client could be used for CNN blogs, Time blogs, Mashable and TechCruch et. al. I hope that global interoperability ”(assuming the site owner wants it)” can be a goal of the REST API.
Max Rice 20:23 on December 8, 2013

I think if time allows it and there’s no concerns about the extra admin screens or bloat, then going with independent consumers is ideal. When I implemented the authentication for WooCommerce, I had a lot of other components to finish and a tight deadline so I took the concept of “a good implementation today is better than a perfect implementation tomorrow”. I think the one consumer per user fits the majority of use cases without needing any additional complexity or screens, but it certainly doesn’t fit *every* use case. This is where versioning the API endpoint (with WC, it’s /wc-api/v1/) is important, as version can be bumped and new/different authentication schemes supported for that version.
- mikeschinkel 02:38 on December 9, 2013
  
  +1 on the versioned endpoint.
Max Cutler 06:51 on December 9, 2013

For mobile apps, asking a user to copy/type a string of random characters from the WP admin to the app is far too onerous and will hamper usage. Similarly, asking every potential API consumer to register individually with every site is also a non-starter. There needs to be some middle ground.

I think it’s necessary to have some form of auto-registration and token dispensing, but I’m not sure if there’s a secure way to do this. The consumer would have to provide the server with some form of identification, but it’s likely going to be trivial to spoof since finding the ID for e.g., the official mobile apps will be easy. This is ultimately one of the big advantages of oAuth 2 over SSL.

Conceptually, I think independent consumers is preferable over one-consumer-per-user; I’m just still not sold on the user and dev workflows involved for either one yet.
- Bryan Petty 17:59 on December 9, 2013
  
  Yeah, I don’t think independent consumers (as ideal as they might be) will work either.
  
  You have to keep in mind that because we’re targeting core, adding a new settings page in core is likely not going to go over well. My bet is that Matt, if not most other core devs, would push for no UI changes in the admin at all even if means a hacked up version of oAuth to support auto-registration through user credentials, one that won’t even support changing authentication tokens without a plugin (tokens would likely be required to change with password changes though). It may even require falling back to an unsecure method of registration if the site doesn’t have SSL available. We don’t have any options in admin for the XML-RPC API, and most people will likely be expecting the same from any other backend API for core. This is the reality we’re probably looking at for core implementation.
  
  If you’ve ever heard Matt explain the logic behind Jetpack’s social integration features, you’ve heard him talk about how it’s just not feasible to expect users to be able to register and configure new Facebook or Twitter applications with their WordPress installations to handle comments and syndication, and that’s even with regard to a plugin. I imagine that opinion will hold even more firm for core API use too.
  
  This certainly doesn’t mean it wouldn’t be possible to change this with a plugin to support UI changes and even a new settings page to manage independent consumers through use of a plugin to extend the API. Such a plugin could easily handle registering and authenticating API tokens not tied directly to specific user accounts without any changes required on the consumer end.
  
  At the least though, this should certainly be discussed with feedback from core committers before getting too far into implementation here if you’re going to move forward with UI additions in admin with more options.
  - Max Cutler 18:57 on December 9, 2013
    
    At the least though, this should certainly be discussed with feedback from core committers before getting too far into implementation here if you’re going to move forward with UI additions in admin with more options.
    
    +1
    
    Security has to be a primary concern in the design here, and if that means we don’t do oAuth for non-SSL sites then I think that’s okay. Falling back to Basic Auth for such sites is an acceptable compromise in my opinion, since we’re already doing that with XML-RPC. And that means we could also do oAuth 2 instead of 1, which will make things easier for API consumers.
    
    I think there are some open questions around how independent consumers would tie into the user-centric permissions model of WP, and it would be good to get feedback from the lead devs on this too.
    - mikeschinkel 19:04 on December 9, 2013
      
      Security has to be a primary concern in the design here, and if that means we don’t do oAuth for non-SSL sites then I think that’s okay.
      
      Isn’t that statement self-contradictory? If security is of true concern then SSL for oAuth 2 is a requirement.
      
      since we’re already doing that with XML-RPC.
      
      Which clearly is not ideal from a security standpoint. Do we really want to perpetuate this vulnerability?
      - Max Cutler 19:15 on December 9, 2013
        
        I have yet to see a secure design proposal for non-SSL sites that doesn’t involve a nightmare scenario for users and/or API consumers.
        
        So for non-SSL sites we have:
        
        1. Possibly insecure oAuth 1 with painful developer experience
        2. Basic auth with easy dev experience and precedent with XML-RPC
        3. ??? custom authentication solution that likely will have security issues but possibly a better dev experience
        
        I would choose #2 without a doubt, but I know some people might feel differently. I’d love to hear alternate proposals that wouldn’t make my life as a mobile dev a painful experience…
        
        Max Rice 21:25 on December 9, 2013
        
        I totally agree that the authentication options for non-SSL sites are pretty horrible at best, but you still need some way of securely authentication user over plain HTTP.
        
        While OAuth 1.0 is somewhat painful to use as a developer (certainly just stuffing API keys in the authorization header is much easier), it’s the only way to securely authenticate requests over HTTP.
        
        Amazon AWS uses a version of OAuth 1.0 (http://docs.aws.amazon.com/general/latest/gr/signature-version-2.html) for many of their APIs and I don’t think it’s prevented developers from building on it.
        
        The benefit to following a standard is that clients can use readily-available libraries in their chosen language so the learning curve in actually building out the authentication side of it basically goes away.
  - mikeschinkel 19:07 on December 9, 2013
    
    @ibaku – To address the no-admin UI concern (assuming it’s a specific concern for this feature) we could follow the lead of Roles & Capabilities; full functionality is built into WordPress but a plugin is needed to expose it.