Diagram the user-facing flow for authentication

[kadamwhite]

We need to solidify and diagram the user-facing flow(s) we will use as part of this authentication mechanism. For example, maybe it would look like this:

• User presses "connect with WordPress" button in an external app
• User is prompted to enter their site's URL
• User is redirected to their site's login screen in a new, native device browser tab
• User logs in and is redirected to a connected applications management screen showing "so-and-so application wishes to connect to your site."
• User clicks a button to confirm they wish to connect that application.
• User is redirected to the original application, which (invisible to the user) receives a token which it uses to authenticate requests going forward. Application is now connected.

Maybe it will look like that, maybe it will look different. This issue is the place to

• propose applications and flows which do this handshake well
• identify other authentication scenarios which should be accounted for (perhaps more developer-facing flows for example to connect a CLI tool with no formal UI)
• discuss nuances of how our desired flow could be implemented within WordPress

The issue will be closed once we have general agreement within the people in this organization's @WP-API/authentication team on the desired flow(s), and have merged a PR with diagrams of those flows into this repository.

[mindgraffiti]

User is redirected to their site's login screen in a new, native device browser tab

Is there a reason why the user can't be redirected by using their in-app web browser? That way, it doesn't break them out of the flow they were in. Google sign-in uses this type of flow, and it seems pretty successful.

[aaronpk]

Yes, the best practices for OAuth say that you should use the in-app browser for this. That's specifically the API that opens a browser window inside the app (which shares system cookies, and which the app can't inspect) rather than showing the web page in an embedded web view. https://tools.ietf.org/html/rfc8252#section-6

[kadamwhite]

Yes, good point; I misarticulated the flow here. I didn't mean to imply the requirement to bump them to a different application, but rather to clarify the use of the device's browser rather than the third-party application. Thanks for clarifying!

[dshanske]

How will the site getting the URL allow it to know the site is configured for this oauth2 flow? Are we hard coding the endpoints?

[dshanske]

Just realized, that is out of scope for a user flow discussion. Sorry

[dshanske]

The connected apps screen should note what permissions are being granted and let the user specifically decline some permissions. This is consistent with most auth user flows. It should not be full access to everything the user can access.

[aerych]

As we're discussing candidate flows, I thought it might be helpful to reference some of the existing authentications flows in the WordPress mobile apps. Some of these are quite similar to what's being discussed. Others illustrate varying degrees of complexity a user must endure. This is just a high level overview. Happy to go deeper into the details on any that are particularly interesting.

Log In Flows

This is an overview of the main login flows currently in the mobile app's as illustrated by WordPress for iOS.

• Email + magic link
• Email address + Password
• Site address + username & password
• Google
• Apple

A few thoughts:

Email + magic link:
This is a flow that necessarily takes the user into not one but two separate apps in order to successfully authenticate. First to their email application, then to their browser. It illustrates the possibility for out-of-app flows to be successful.

Email address + Password
Perhaps the simplest flow. An Auth flow that takes an email address and password and returns a bearer token. Challenging if a user has forgotten their email address.

Site address + username & password:
Second simplest flow due to the surprising number of users who struggle to enter their site address. Additional challenges due to sites that are unreadable due to an unavailable XML-RPC service.

Google
A JWT implementation similar to what is being discussed for the REST API. Most of the interaction is transparent to the user. Can be more complicated if the user is not already logged into the correct Google account.

Apple
Similar to Google in that its a third party service. The interaction can be very brief and transparent (as shown here) or, can be complicated as Apple requires two factor security and a PIN before Sign In With Apple can be used.

Publicize Flows

The process of connecting a social service for sharing has some similarities to potential REST API authentication flows. Below you can see the flows for Tumblr and Twitter.

Both Tumblr and Twitter prompt the user to log in (if they are not already) then ask the user to confirm the connection between the requesting app and their service. Implementations vary slightly, most noticeable by the extra loading screen in the Tumblr flow.

[koke]

To add to what @aerych listed, I'd say that for all our existing mobile users that are not on WordPress.com or using Jetpack, all we have today is a username and password. I would prefer to have a password-based login flow for new users as well, but forcing everyone to go through the web-based oAuth flow would mean having to re-authenticate all of those users.

In addition to that, we also need to store the password so we can (in a very hacky way) log the user into a web view for post previews. If we only had an oAuth flow we would also need a way to authenticate previews (and potentially other wp-admin pages) with a token.

I understand that we might not want to encourage users to enter their passwords in third party apps, but I think we should make an exception for the official ones

[koke]

Yes, the best practices for OAuth say that you should use the in-app browser for this. That's specifically the API that opens a browser window inside the app (which shares system cookies, and which the app can't inspect) rather than showing the web page in an embedded web view. https://tools.ietf.org/html/rfc8252#section-6

That section mentions solutions that are integrated in the app UX but are still a properly sandboxed browser. I believe that's available with Chrome on Android:

Some platforms support a browser feature known as "in-app browser
tabs", where an app can present a tab of the browser within the app
context without switching apps, but still retain key benefits of the
browser such as a shared authentication state and security context.
On platforms where they are supported, it is RECOMMENDED, for
usability reasons, that apps use in-app browser tabs for the
authorization request.

On the other hand, Section 8.12 is more clear about this:

Section 9 of OAuth 2.0 [RFC6749] documents two approaches for native
apps to interact with the authorization endpoint. This best current
practice requires that native apps MUST NOT use embedded user-agents
to perform authorization requests and allows that authorization
endpoints MAY take steps to detect and block authorization requests
in embedded user-agents.

In any case, we should be careful with interpreting the spec too literally on this, as these are recommendations based on what was available at the time of writing (October 2017). Just around the same time, Apple introduced ASWebAuthenticationSession (then SFAuthenticationSession) which provides an integrated in-app experience, but with proper sandboxing to ensure that the container app can't access anything inside the web view.

[aaronpk]

Please keep in mind that specs are a snapshot in time, and things do change like you've noticed with the new iOS mechanism for opening a secure browser for OAuth within the app.

The latest update to the OAuth specs is in the works right now in the document "OAuth 2.0 Security Best Current Practice", and one of the things it says is the password grant MUST NOT be used.

I strongly encourage you to adopt the best current practices for OAuth and avoid password authentication entirely.

[koke]

I think I agree in theory with the idea of the oAuth flow. The case for WebAuthn or other forms of multi-factor authentication makes it way more interesting. Considering that the authentication system in core is extensible, and people might be using different plugins for multi-factor, SSO,... it makes sense to consider that the apps might not be, in fact, a first party client.

I think the UX on the web-based flow would be worse for most users, but will also be more secure and flexible for those that don't use the stock authentication. I think that's a fair trade off.

That's the theoretical view. The reality is that we have thousands of existing users for whom all we have is a username and password. And once we start adding support for WP-API in the apps, we will likely have a long transition period in which we need to make calls to both XML-RPC and the REST API. In addition to that, we will need to be able to authenticate post previews and potentially other web views in wp-admin.

This means we need a migration path for existing users to convert a password into a token without making the user log in twice. For new users, we will also need to ask for their password (and convert to a token) unless the tokens also work on XML-RPC and to authenticate wp-admin views.

I would imagine that in a few years the WordPress apps and other existing third parties (thinking of @danielpunkass' MarsEdit, for instance) will transition all existing XML-RPC calls to the REST API and we might be able to deprecate the password grant. But unless a migration path is provided, basic auth starts looking like our best solution, which would ironically be less secure for users, by sending passwords on every request instead of once.

The latest update to the OAuth specs is in the works right now in the document "OAuth 2.0 Security Best Current Practice", and one of the things it says is the password grant MUST NOT be used.

That is correct but that document is a work in progress. At the top of that document it clearly says:

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 9, 2020.

I've been trying to track down the rationale for that decision, and in the latest meeting minutes:

Grant type PSWD to be deprecated – call in room showed
                          in favor 10 none against
                                  Need to provide alternatives to lots of folks
                                  using this grant

The authors seem unanimously convinced to move forward with this, but they also acknowledge the need for a migration path, although I haven't seen one specified yet. I would hope that gets sorted out before that draft becomes a recommendation.

[aaronpk]

The authors seem unanimously convinced to move forward with this, but they also acknowledge the need for a migration path, although I haven't seen one specified yet. I would hope that gets sorted out before that draft becomes a recommendation.

Could you please voice this concern on the OAuth mailing list? This is exactly the kind of feedback that is valuable for the authors of the draft, and this is the time to share it since the document is in last call.

[koke]

I just sent an email, thanks for the suggestion. It's not showing up in the archive, but I imagine the list would be moderated.

[aaronpk]

Perfect, thanks. Yes I believe the first message from new members is moderated. They're usually pretty quick to approve them.

[koke]

Just for reference, the email I sent to the oauth-wg: https://mailarchive.ietf.org/arch/msg/oauth/-HIQYdle2wmL5_DoPh5c-245-mE