|
| 1 | +# MSC3824: OAuth 2.0 API aware clients |
| 2 | + |
| 3 | +As of spec 1.15 we now have two APIs for clients to authenticate: |
| 4 | + |
| 5 | +- the [Legacy API] |
| 6 | +- the [OAuth 2.0 API] |
| 7 | + |
| 8 | +It is anticipated that in time all clients will support the [OAuth 2.0 API]. However, in the interim, some existing |
| 9 | +clients will continue to only support the [Legacy API]. |
| 10 | + |
| 11 | +During this transition period it is proposed that a client could make some less-invasive changes to improve the user |
| 12 | +experience when talking to a homeserver that is using the [OAuth 2.0 API] without actually having to implement the full |
| 13 | +[OAuth 2.0 API]. |
| 14 | + |
| 15 | +In this context it is helpful to distinguish four types of client: |
| 16 | + |
| 17 | +1. *OAuth 2.0 native client* - This is a client that, where the homeserver supports it, uses the [OAuth 2.0 API] for login |
| 18 | + and registration. e.g. Element X, Element Web |
| 19 | +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 |
| 20 | + [Legacy API] (e.g. [`m.login.sso`]) to auth with an [OAuth 2.0 API] enabled homeserver. |
| 21 | +1. *Legacy client with SSO support* - This is a client that is not aware of the [OAuth 2.0 API] but does support the |
| 22 | + [`m.login.sso`] from the [Legacy API]. e.g. Element Classic on iOS and Android |
| 23 | +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 |
| 24 | + it support the [`m.login.sso`] [Legacy API] flow. Typically auth is done via `m.login.password` only. e.g. Fractal |
| 25 | + |
| 26 | +The purpose of differentiating #2 and #3 is that, for a Legacy client with SSO support, the user journey can be |
| 27 | +optimised with minimal modifications when talking to an [OAuth 2.0 API] enabled homeserver. |
| 28 | + |
| 29 | +To be clear: clients using the [Legacy API] would not need to make changes and become *OAuth 2.0 aware*, but it would |
| 30 | +likely be in their users' best interest to do so. |
| 31 | + |
| 32 | +## Proposal |
| 33 | + |
| 34 | +Firstly, we make two backwards compatible changes to the [Legacy API]: |
| 35 | + |
| 36 | +- The homeserver can optionally specify that where more than one |
| 37 | + [authentication type](https://spec.matrix.org/v1.16/client-server-api/#authentication-types) |
| 38 | + is supported, that a specific [`m.login.sso`] auth type is preferred. |
| 39 | +- A client can specify which action the user is wanting to achieve at the point of SSO redirection. This allows the |
| 40 | + homeserver to display the most relevant UI to the user. |
| 41 | + |
| 42 | +We then describe how a client can use these new features and others to optimise the user experience without having |
| 43 | +to support the [OAuth 2.0 API]. |
| 44 | + |
| 45 | +These are detailed below. |
| 46 | + |
| 47 | +### Homeserver indicates that an `m.login.sso` flow is preferred |
| 48 | + |
| 49 | +Add an optional `oauth_aware_preferred` field to the response of |
| 50 | +[`GET /_matrix/client/v3/login`](https://spec.matrix.org/v1.16/client-server-api/#get_matrixclientv3login): |
| 51 | + |
| 52 | +- `"oauth_aware_preferred"?: boolean` |
| 53 | + |
| 54 | +For example, if a homeserver is advertising password login for legacy clients only then it could return the following: |
| 55 | + |
| 56 | +```json |
| 57 | +{ |
| 58 | + "flows": [{ |
| 59 | + "type": "m.login.password" |
| 60 | + }, { |
| 61 | + "type": "m.login.sso", |
| 62 | + "oauth_aware_preferred": true |
| 63 | + }] |
| 64 | +} |
| 65 | + |
| 66 | +``` |
| 67 | + |
| 68 | +If the client finds `oauth_aware_preferred` to be `true` then, assuming it supports that auth type, it should |
| 69 | +present this as the only login/registration method available to the user. |
| 70 | + |
| 71 | +### Client indicates `action` on SSO redirect |
| 72 | + |
| 73 | +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) |
| 74 | +and [`GET /_matrix/client/v3/login/sso/redirect/{idpId}`](https://spec.matrix.org/v1.16/client-server-api/#get_matrixclientv3loginssoredirectidpid) |
| 75 | +with meaning: |
| 76 | + |
| 77 | +- `login` - the SSO redirect is for the purposes of signing an existing user in |
| 78 | +- `register` - the SSO redirect is for the purpose of registering a new user account |
| 79 | + |
| 80 | +e.g. `https://matrix-client.matrix.org/_matrix/client/v3/login/sso/redirect?action=register` |
| 81 | + |
| 82 | +The client might determine the value based on whether the user clicked a "Login" or "Register" button. |
| 83 | + |
| 84 | +n.b. we don't need to add this to the [Login Fallback](https://spec.matrix.org/v1.16/client-server-api/#login-fallback) |
| 85 | +as that isn't used for registration. |
| 86 | + |
| 87 | +### Definition of OAuth 2.0 aware |
| 88 | + |
| 89 | +For a client to be considered fully *OAuth 2.0 aware* it **must**: |
| 90 | + |
| 91 | +- support the [`m.login.sso`] auth flow from the [Legacy API] |
| 92 | +- where a `oauth_aware_preferred` value of `true` is present on an [`m.login.sso`] then *only* offer that auth flow |
| 93 | + to the user |
| 94 | +- append `action=login` and `action=register` parameters to the SSO redirect URLs |
| 95 | +- check and honour the `m.3pid_changes` |
| 96 | + [capability](https://spec.matrix.org/v1.16/client-server-api/#m3pid_changes-capability) so that the user is not |
| 97 | + offered the ability to add or remove 3PIDs if the homeserver says the capability is not available |
| 98 | +- determine if the homeserver is using the [OAuth 2.0 API] by using |
| 99 | + [server metadata discovery](https://spec.matrix.org/v1.16/client-server-api/#get_matrixclientv1auth_metadata) from the |
| 100 | + [OAuth 2.0 API] |
| 101 | +- if a homeserver is using the [OAuth 2.0 API] as discovered in the previous step then: |
| 102 | + - link users to manage their account at the `account_management_uri` given by [MSC4191] instead of native UI |
| 103 | + - do not offer the user the function to deactivate their account and instead refer them to the account management URL |
| 104 | + described above |
| 105 | + - if the user wishes to sign out a device session other than its own then the client **must**: |
| 106 | + - link the user to the `account_management_uri` given by [MSC4191] if provided |
| 107 | + - append the `action` and `device_id` to the web UI link parameters described by |
| 108 | + [MSC4191](https://github.com/matrix-org/matrix-spec-proposals/blob/quenting/account-deeplink/proposals/4191-account-deeplink.md#account-management-url-parameters) |
| 109 | + so that the web UI knows that the user wishes to sign out a device and which one it is. |
| 110 | + e.g. `?action=org.matrix.device_delete&device_id=<device_id>` |
| 111 | + - n.b. an earlier version of this MSC used the `session_end` value instead of `org.matrix.device_delete`. This has |
| 112 | + changed for consistency with [MSC4191]. |
| 113 | + |
| 114 | +Optionally, an *OAuth 2.0 aware* client **could**: |
| 115 | + |
| 116 | +- label the SSO button as "Continue" rather than "SSO" when `oauth_aware_preferred` is `true`. This is because after |
| 117 | + redirect the server may then offer a password and/or further upstream IdPs |
| 118 | +- pass other |
| 119 | + [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) |
| 120 | + when linking to the account web UI |
| 121 | + |
| 122 | +For a homeserver using [OAuth 2.0 API] to provide support for *OAuth 2.0 aware* clients it **must**: |
| 123 | + |
| 124 | +- support the [OAuth 2.0 API] |
| 125 | +- provide an implementation of the [`m.login.sso`] |
| 126 | + [authentication type](https://spec.matrix.org/v1.16/client-server-api/#authentication-types) from the [Legacy API] |
| 127 | +- if password authentication was previously enabled on the homeserver then provide an implementation of the |
| 128 | + `m.login.password` [authentication type](https://spec.matrix.org/v1.16/client-server-api/#authentication-types) from the [Legacy API] |
| 129 | +- indicate that the [`m.login.sso`] is preferred by setting `oauth_aware_preferred` to `true` |
| 130 | +- provide a value for the `action` param on the SSO redirect endpoints as defined above |
| 131 | + |
| 132 | +Additionally, the homeserver **should**: |
| 133 | + |
| 134 | +- advertise the account management UI in accordance with [MSC4191] |
| 135 | + |
| 136 | +## Potential issues |
| 137 | + |
| 138 | +Clients might be discouraged from making the full transition to the [OAuth 2.0 API] because this proposal outlines a |
| 139 | +kind of "half way house". |
| 140 | + |
| 141 | +## Alternatives |
| 142 | + |
| 143 | +Clients could assume that an [`m.login.sso`] is preferred directly from where the |
| 144 | +[server metadata discovery](https://spec.matrix.org/v1.16/client-server-api/#server-metadata-discovery) indicates the |
| 145 | +[OAuth 2.0 API] is being used. However, this might hamper some more custom configuration. |
| 146 | + |
| 147 | +The homeserver could only offer [`m.login.sso`] as the supported auth type but this would prevent non-SSO capable legacy |
| 148 | +clients from accessing the homeserver. |
| 149 | + |
| 150 | +[Capabilities negotiation](https://spec.matrix.org/v1.16/client-server-api/#capabilities-negotiation) could be used to |
| 151 | +indicate that [`m.login.sso`] is preferred. |
| 152 | + |
| 153 | +For the param on redirect: a `prompt` parameter with values |
| 154 | +[`create`](https://openid.net/specs/openid-connect-prompt-create-1_0.html#rfc.section.4) and |
| 155 | +[`login`](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) exists in OIDC for use on the authorized |
| 156 | +endpoint. However, our use case is different and it might cause confusion to overload these terms. |
| 157 | + |
| 158 | +## Security considerations |
| 159 | + |
| 160 | +None relevant. |
| 161 | + |
| 162 | +## Unstable prefix |
| 163 | + |
| 164 | +While this feature is in development the following unstable prefixes should be used: |
| 165 | + |
| 166 | +- In the /login response body: `org.matrix.msc3824.delegated_oidc_compatibility` instead of |
| 167 | + `oauth_aware_preferred` |
| 168 | +- On the SSO redirect: `org.matrix.msc3824.action` instead of `action` query parameter |
| 169 | + |
| 170 | +An earlier version of this MSC used the `session_end` value instead of the [MSC4191] |
| 171 | +value `org.matrix.device_delete`. This should be resolved once the feature gets stabilised. |
| 172 | + |
| 173 | +## Dependencies |
| 174 | + |
| 175 | +This MSC depends on the following MSCs, which at the time of writing have not yet |
| 176 | +been accepted into the spec: |
| 177 | + |
| 178 | +- [MSC4191]: Account management for [OAuth 2.0 API] |
| 179 | + |
| 180 | +[MSC4191]: https://github.com/matrix-org/matrix-spec-proposals/pull/4191 |
| 181 | +[Legacy API]: https://spec.matrix.org/v1.16/client-server-api/#legacy-api |
| 182 | +[OAuth 2.0 API]: https://spec.matrix.org/v1.16/client-server-api/#oauth-20-api |
| 183 | +[`m.login.sso`]: https://spec.matrix.org/v1.16/client-server-api/#client-login-via-sso |
0 commit comments