archive
/
matrix-spec-proposals
mirror of https://github.com/matrix-org/matrix-spec-proposals
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

MSC3824: OAuth 2.0 API aware clients (#3824)

Browse Source 
* Add an optional query parameter to SSO redirect

* MSC3824

* Update proposals/3824-sso-redirect-action.md

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* Add supported actions per auth type

* Add GET /_matrix/client/v3/register alternative

* Rework proposal to be about OIDC aware clients

* Rename proposal file

* Use _ formatted flag name

* Fixes to Homeserver and Client requirements list

* RECOMMENDED: label SSO button as "Continue"

* Use unstable prefix for action query param

* Reference to MSC3861

* Update proposals/3824-oidc-aware-clients.md

Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com>

* Style

* Reorganise requiremetns

* Add 3pid and session management requirements

* Update account management/web UI link parameters for consistency with MSC2965

https://github.com/sandhose/matrix-doc/blob/msc/sandhose/oidc-discovery/proposals/2965-oidc-discovery.md#account-management-url-parameters

* Update to reference OAuth 2.0 API in spec and MSC4191

* Add note about session_end vs org.matrix.session_end

* Update proposals/3824-oidc-aware-clients.md

* Add note on where action=login|register value might come from

* Clarify what was meant by "compatibility layer"

* Add requirement about deactivating account

* Use org.matrix.device_delete from MSC4191 not org.matrix.session_end

* Update proposals/3824-oidc-aware-clients.md

Co-authored-by: David Baker <dbkr@users.noreply.github.com>

* Cleanup

* Feedback from review

Re https://github.com/matrix-org/matrix-spec-proposals/pull/3824#discussion_r2410559153

* Linewrap

* DItto

* Links

* Link to m.login.sso

* Attempt to clarify purpose/intent of MSC

* Fix links

* Spelling

* Clarify that server discovery is needed + that the whole thing is optional

* Clarify that m.login.password is only required where homeserver previously supported it

* Apply suggestions from code review

Co-authored-by: Hubert Chathi <hubertc@matrix.org>

---------

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com>
Co-authored-by: David Baker <dbkr@users.noreply.github.com>
Co-authored-by: Hubert Chathi <hubertc@matrix.org>
main
Hugh Nimmo-Smith 1 week ago committed by GitHub
parent 2b6da16d52
commit e9f0f31d27
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 183 additions and 0 deletions
Show Stats Download Patch File Download Diff File

183
proposals/3824-oidc-aware-clients.md
Unescape Escape View File

@ -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=<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
Write Preview
Loading…
Cancel
Save