matrix-spec-proposals/proposals/3824-oidc-aware-clients.md

MSC3824: OAuth 2.0 API aware clients

As of spec 1.15 we now have two APIs for clients to authenticate:

• the Legacy API
• the OAuth 2.0 API

It is anticipated that in time all clients will support the OAuth 2.0 API. However, in the interim, some existing clients will continue to only support the Legacy API.

During this transition period it is proposed that a client could make some less-invasive changes to improve the user experience when talking to a homeserver that is using the OAuth 2.0 API without actually having to implement the full OAuth 2.0 API.

In this context it is helpful to distinguish four types of client:

1. OAuth 2.0 native client - This is a client that, where the homeserver supports it, uses the OAuth 2.0 API for login and registration. e.g. Element X, Element Web
2. OAuth 2.0 aware client - This is a client that is "aware" (see below) of the OAuth 2.0 API but will still uses the Legacy API (e.g. m.login.sso) to auth with an OAuth 2.0 API enabled homeserver.
3. Legacy client with SSO support - This is a client that is not aware of the OAuth 2.0 API but does support the m.login.sso from the Legacy API. e.g. Element Classic on iOS and Android
4. Legacy client without SSO support - This is a client that is not aware of the OAuth 2.0 API at all and nor does it support the m.login.sso Legacy API flow. Typically auth is done via m.login.password only. e.g. Fractal

The purpose of differentiating #2 and #3 is that, for a Legacy client with SSO support, the user journey can be optimised with minimal modifications when talking to an OAuth 2.0 API enabled homeserver.

To be clear: clients using the Legacy API would not need to make changes and become OAuth 2.0 aware, but it would likely be in their users' best interest to do so.

Proposal

Firstly, we make two backwards compatible changes to the Legacy API:

• The homeserver can optionally specify that where more than one authentication type is supported, that a specific m.login.sso auth type is preferred.
• A client can specify which action the user is wanting to achieve at the point of SSO redirection. This allows the homeserver to display the most relevant UI to the user.

We then describe how a client can use these new features and others to optimise the user experience without having to support the OAuth 2.0 API.

These are detailed below.

Homeserver indicates that an m.login.sso flow is preferred

Add an optional oauth_aware_preferred field to the response of GET /_matrix/client/v3/login:

• "oauth_aware_preferred"?: boolean

For example, if a homeserver is advertising password login for legacy clients only then it could return the following:

{
  "flows": [{
    "type": "m.login.password"
  }, {
    "type": "m.login.sso",
    "oauth_aware_preferred": true
  }]
}

If the client finds oauth_aware_preferred to be true then, assuming it supports that auth type, it should present this as the only login/registration method available to the user.

Client indicates action on SSO redirect

Add an optional query parameter action to GET /_matrix/client/v3/login/sso/redirect and GET /_matrix/client/v3/login/sso/redirect/{idpId} with meaning:

• login - the SSO redirect is for the purposes of signing an existing user in
• register - the SSO redirect is for the purpose of registering a new user account

e.g. https://matrix-client.matrix.org/_matrix/client/v3/login/sso/redirect?action=register

The client might determine the value based on whether the user clicked a "Login" or "Register" button.

n.b. we don't need to add this to the Login Fallback as that isn't used for registration.

Definition of OAuth 2.0 aware

For a client to be considered fully OAuth 2.0 aware it must:

• support the m.login.sso auth flow from the Legacy API
• where a oauth_aware_preferred value of true is present on an m.login.sso then only offer that auth flow to the user
• append action=login and action=register parameters to the SSO redirect URLs
• check and honour the m.3pid_changes capability so that the user is not offered the ability to add or remove 3PIDs if the homeserver says the capability is not available
• determine if the homeserver is using the OAuth 2.0 API by using server metadata discovery from the OAuth 2.0 API
• if a homeserver is using the OAuth 2.0 API as discovered in the previous step then:
  • link users to manage their account at the account_management_uri given by MSC4191 instead of native UI
  • do not offer the user the function to deactivate their account and instead refer them to the account management URL described above
  • if the user wishes to sign out a device session other than its own then the client must:
    • link the user to the account_management_uri given by MSC4191 if provided
    • append the action and device_id to the web UI link parameters described by MSC4191 so that the web UI knows that the user wishes to sign out a device and which one it is. e.g. ?action=org.matrix.device_delete&device_id=<device_id>
    • n.b. an earlier version of this MSC used the session_end value instead of org.matrix.device_delete. This has changed for consistency with MSC4191.

Optionally, an OAuth 2.0 aware client could:

• label the SSO button as "Continue" rather than "SSO" when oauth_aware_preferred is true. This is because after redirect the server may then offer a password and/or further upstream IdPs
• pass other query parameters for context when linking to the account web UI

For a homeserver using OAuth 2.0 API to provide support for OAuth 2.0 aware clients it must:

• support the OAuth 2.0 API
• provide an implementation of the m.login.sso authentication type from the Legacy API
• if password authentication was previously enabled on the homeserver then provide an implementation of the m.login.password authentication type from the Legacy API
• indicate that the m.login.sso is preferred by setting oauth_aware_preferred to true
• provide a value for the action param on the SSO redirect endpoints as defined above

Additionally, the homeserver should:

• advertise the account management UI in accordance with MSC4191

Potential issues

Clients might be discouraged from making the full transition to the OAuth 2.0 API because this proposal outlines a kind of "half way house".

Alternatives

Clients could assume that an m.login.sso is preferred directly from where the server metadata discovery indicates the OAuth 2.0 API is being used. However, this might hamper some more custom configuration.

The homeserver could only offer m.login.sso as the supported auth type but this would prevent non-SSO capable legacy clients from accessing the homeserver.

Capabilities negotiation could be used to indicate that m.login.sso is preferred.

For the param on redirect: a prompt parameter with values create and login exists in OIDC for use on the authorized endpoint. However, our use case is different and it might cause confusion to overload these terms.

Security considerations

None relevant.

Unstable prefix

While this feature is in development the following unstable prefixes should be used:

• In the /login response body: org.matrix.msc3824.delegated_oidc_compatibility instead of oauth_aware_preferred
• On the SSO redirect: org.matrix.msc3824.action instead of action query parameter

An earlier version of this MSC used the session_end value instead of the MSC4191 value org.matrix.device_delete. This should be resolved once the feature gets stabilised.

Dependencies

This MSC depends on the following MSCs, which at the time of writing have not yet been accepted into the spec:

• MSC4191: Account management for OAuth 2.0 API