diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md new file mode 100644 index 000000000..9c4886ef4 --- /dev/null +++ b/proposals/3824-oidc-aware-clients.md @@ -0,0 +1,183 @@ +# 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 +1. *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. +1. *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 +1. *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](https://spec.matrix.org/v1.16/client-server-api/#authentication-types) + 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`](https://spec.matrix.org/v1.16/client-server-api/#get_matrixclientv3login): + +- `"oauth_aware_preferred"?: boolean` + +For example, if a homeserver is advertising password login for legacy clients only then it could return the following: + +```json +{ + "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`](https://spec.matrix.org/v1.16/client-server-api/#get_matrixclientv3loginssoredirect) +and [`GET /_matrix/client/v3/login/sso/redirect/{idpId}`](https://spec.matrix.org/v1.16/client-server-api/#get_matrixclientv3loginssoredirectidpid) +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](https://spec.matrix.org/v1.16/client-server-api/#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](https://spec.matrix.org/v1.16/client-server-api/#m3pid_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](https://spec.matrix.org/v1.16/client-server-api/#get_matrixclientv1auth_metadata) 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](https://github.com/matrix-org/matrix-spec-proposals/blob/quenting/account-deeplink/proposals/4191-account-deeplink.md#account-management-url-parameters) + 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=` + - 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](https://github.com/matrix-org/matrix-spec-proposals/blob/quenting/account-deeplink/proposals/4191-account-deeplink.md#account-management-url-parameters) + 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](https://spec.matrix.org/v1.16/client-server-api/#authentication-types) from the [Legacy API] +- if password authentication was previously enabled on the homeserver then provide an implementation of the + `m.login.password` [authentication type](https://spec.matrix.org/v1.16/client-server-api/#authentication-types) 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](https://spec.matrix.org/v1.16/client-server-api/#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](https://spec.matrix.org/v1.16/client-server-api/#capabilities-negotiation) could be used to +indicate that [`m.login.sso`] is preferred. + +For the param on redirect: a `prompt` parameter with values +[`create`](https://openid.net/specs/openid-connect-prompt-create-1_0.html#rfc.section.4) and +[`login`](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) 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] + +[MSC4191]: https://github.com/matrix-org/matrix-spec-proposals/pull/4191 +[Legacy API]: https://spec.matrix.org/v1.16/client-server-api/#legacy-api +[OAuth 2.0 API]: https://spec.matrix.org/v1.16/client-server-api/#oauth-20-api +[`m.login.sso`]: https://spec.matrix.org/v1.16/client-server-api/#client-login-via-sso