WooCommerce auth system and user flow

[mikejolley]

👋 Hi everyone!

I thought it might be useful to outline what is in WooCommerce now so that any new system developed in WordPress core can consider this use case, potentially take any useful parts of it, and allow WooCommerce to drop it's current auth system in favour of the core new one in the future.

For those not aware, WooCommerce core includes a custom authentication class and key based system for allowing read-only and write access to the REST API. There is also an authentication flow for apps to create new keys with the users permission which I believe is the end goal of this project.

API Keys and client authentication

WooCommerce includes an interface to create API keys for users to access the REST API via a custom authentication class which runs via WordPress authentication hooks.

The authentication system supports basic authentication over HTTPS connections where you provide only the consumer key and secret.

For non-secure connections there is a more complicated OAuth 1.0a "one-legged" authentication method in which you must generate a signature instead of sending raw credentials. We get quite a lot of support requests coming out of that due to the nuances of signature generation, so we much prefer the basic auth over HTTPS where possible.

API keys are stored in a custom database table:

Field	Type	Default	Extra
key_id	bigint(20) unsigned	NULL	auto_increment
user_id	bigint(20) unsigned
description	varchar(200)
permissions	varchar(10)
consumer_key	char(64)	NULL
consumer_secret	char(43)	NULL
nonces	longtext
truncated_key	char(7)
last_access	datetime

• Each key is associated with a WordPress user (user_id), so if you use a key, you're doing requests as the associated user.
• permissions stores whether or not the key is read-only or write access. A common request not covered is fine-grained control over which endpoints a key has access to read or write to.
• I believe nonces are used for oAuth to prevent replay attacks; nonces sent with requests are stored here and cannot be reused for 15 mins.
• truncated_key is used to show what key is being referred to in the admin area without revealing the full key.

I'm assuming that any auth system added to WordPress itself may require something similar for administrating granted keys...I won't go into the details too much of the screens themselves, but the various screens and flows are documented in the docs here.

Application authentication flow

WooCommerce has an authentication endpoint where apps can send users to connect, giving them a key, and allowing them to make API requests on the users behalf.

The endpoint, if you would like to test this, is /wc-auth/v1/authorize. Apps need to provide some parameters to tell this endpoint what to display and how to handle keys once the user grants access:

• app_name - Name of your app. This will be shown on the screen as the thing which wants to connect.
• user_id - This is the apps user ID, not the WordPress user ID. This allows the app to know which user keys are for when they are received.
• return_url - This is the URL the user is sent back to after granting or denying access.
• callback_url - This is where keys will be POSTed to. The consumer data posted here includes key_id, user_id (app user ID), consumer_key, consumer_secret, key_permissions. It is up the the app to store this data.
• scope - read_write or read access. Also shown on the auth screen.

So as an example, if I go here logged out: /wc-auth/v1/authorize?app_name=My App Name&user_id=123&return_url=http%3A%2F%2Fapp.com%2Freturn-page&callback_url=https%3A%2F%2Fapp.com%2Fcallback-endpoint&scope=read_write, this will show the following:

Once I log in, I am presented with the following call to actions:

Both actions return to the apps return URL, but only one creates a key and sends it to the callback URL. The page clearly shows which user is logged in, and lists what the API key might do (however in this case it's hardcoded text and does not represent fine-grained controls which would be awesome).

The code for this can be found here and there are some docs showing more screenshots here.

I'm not 100% sure how many apps are making use of this today. The woo mobile apps used it in the past, but now use Jetpack auth instead. Metorik I think may still be using it.

Happy to try to answer any questions about the above, and I'm keen to help where possible.