From 138f00b07276e4bb134dbc0b7c350ab4307caf32 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Tue, 24 May 2022 14:29:07 +0100 Subject: [PATCH 01/37] Add an optional query parameter to SSO redirect --- proposals/xxxx-sso-redirect-action.md | 28 +++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 proposals/xxxx-sso-redirect-action.md diff --git a/proposals/xxxx-sso-redirect-action.md b/proposals/xxxx-sso-redirect-action.md new file mode 100644 index 00000000000..a1adf64ebcc --- /dev/null +++ b/proposals/xxxx-sso-redirect-action.md @@ -0,0 +1,28 @@ +# MSCxxxx: Login/register indication on SSO redirect + +At present a homeserver cannot tell if a request for `GET /_matrix/client/v3/login/sso/redirect` is intended to be used to sign in an existing user or register a new user. + +In the context of [MSC2964](https://github.com/matrix-org/matrix-doc/pull/2965) the homeserver needs to know the intent so that the correct UI can be shown to the user. + +## Proposal + +Add an optional query parameter `action` to `GET /_matrix/client/v3/login/sso/redirect` 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 + +## Potential issues + +None. + +## Alternatives + +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 + +Not applicable. From 5cba2ff86c1d720ef3a06295492979ae43acfbd1 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Tue, 24 May 2022 14:30:46 +0100 Subject: [PATCH 02/37] MSC3824 --- ...{xxxx-sso-redirect-action.md => 3824-sso-redirect-action.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename proposals/{xxxx-sso-redirect-action.md => 3824-sso-redirect-action.md} (95%) diff --git a/proposals/xxxx-sso-redirect-action.md b/proposals/3824-sso-redirect-action.md similarity index 95% rename from proposals/xxxx-sso-redirect-action.md rename to proposals/3824-sso-redirect-action.md index a1adf64ebcc..5a95dd49858 100644 --- a/proposals/xxxx-sso-redirect-action.md +++ b/proposals/3824-sso-redirect-action.md @@ -1,4 +1,4 @@ -# MSCxxxx: Login/register indication on SSO redirect +# MSC3824: Login/register indication on SSO redirect At present a homeserver cannot tell if a request for `GET /_matrix/client/v3/login/sso/redirect` is intended to be used to sign in an existing user or register a new user. From ca786913e52c62c6b814074117e04c092705f51e Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 25 May 2022 11:13:43 +0100 Subject: [PATCH 03/37] Update proposals/3824-sso-redirect-action.md Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/3824-sso-redirect-action.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3824-sso-redirect-action.md b/proposals/3824-sso-redirect-action.md index 5a95dd49858..751175796e5 100644 --- a/proposals/3824-sso-redirect-action.md +++ b/proposals/3824-sso-redirect-action.md @@ -2,7 +2,7 @@ At present a homeserver cannot tell if a request for `GET /_matrix/client/v3/login/sso/redirect` is intended to be used to sign in an existing user or register a new user. -In the context of [MSC2964](https://github.com/matrix-org/matrix-doc/pull/2965) the homeserver needs to know the intent so that the correct UI can be shown to the user. +In the context of [MSC2964](https://github.com/matrix-org/matrix-doc/pull/2964) the homeserver needs to know the intent so that the correct UI can be shown to the user. ## Proposal From 3a67748b47bec781d8b12e4de466e20adf342297 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Mon, 30 May 2022 12:42:28 +0100 Subject: [PATCH 04/37] Add supported actions per auth type --- proposals/3824-sso-redirect-action.md | 54 ++++++++++++++++++++++++--- 1 file changed, 49 insertions(+), 5 deletions(-) diff --git a/proposals/3824-sso-redirect-action.md b/proposals/3824-sso-redirect-action.md index 751175796e5..c0f3d08ed10 100644 --- a/proposals/3824-sso-redirect-action.md +++ b/proposals/3824-sso-redirect-action.md @@ -1,23 +1,67 @@ -# MSC3824: Login/register indication on SSO redirect +# MSC3824: Ability to distinguish between login and registration -At present a homeserver cannot tell if a request for `GET /_matrix/client/v3/login/sso/redirect` is intended to be used to sign in an existing user or register a new user. +A client can determine the available authentication methods/types via the `GET /_matrix/client/v3/login` endpoint. -In the context of [MSC2964](https://github.com/matrix-org/matrix-doc/pull/2964) the homeserver needs to know the intent so that the correct UI can be shown to the user. +However, unless registration is blanket disabled (i.e. `POST /_matrix/client/v3/register` returns `403`) then it is assumed that both login and registration are possible using all given auth types. + +Furthermore, a homeserver cannot tell if a `m.login.sso` request for `GET /_matrix/client/v3/login/sso/redirect` is intended to be used to login an existing user or register a new user. + +In the context of [MSC2964](https://github.com/matrix-org/matrix-doc/pull/2964): + +1. a client needs to know whether registration can be completed by a particular auth type; +2. the homeserver needs to know the intent so that the correct UI can be shown to the user. ## Proposal -Add an optional query parameter `action` to `GET /_matrix/client/v3/login/sso/redirect` with meaning: +Firstly, the homeserver can optionally specify which actions are supported for an authentication type. + +Secondly, a client can specify which action the user is wanting to achieve at the point of SSO redirection. + +### Homeserver specifies available actions per auth type + +Add an optional `actions` field to the response of `GET /_matrix/client/v3/login`: + +`actions?: ("login" | "register")[]` + +For example, if a homeserver supports password for login only, and SSO for login and registration then a response could look like: + +``` +{ + "flows": [{ + "type": "m.login.password", + "actions": ["login"], + }, { + "type": "m.login.sso", + "actions": ["login", "register"] + }] +} + +``` + +If no `actions` field is present then the client should assume that both `login` and `register` are both supported unless indicated elsewhere by the API (e.g. registration disabled `403`). + +If `actions` is empty array (i.e. `[]`) then no action is supported. + +### 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` + +n.b. we don't need to add this to the [Login Fallback](https://spec.matrix.org/v1.2/client-server-api/#login-fallback) as that isn't used for registration. + ## Potential issues None. ## Alternatives -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. +[Capabilities negotiation](https://spec.matrix.org/v1.2/client-server-api/#capabilities-negotiation) could be used for availability of login vs register. + +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 From 1b10fa9ce28211555426cfe2687309106a02413a Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Mon, 30 May 2022 13:17:32 +0100 Subject: [PATCH 05/37] Add GET /_matrix/client/v3/register alternative --- proposals/3824-sso-redirect-action.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/proposals/3824-sso-redirect-action.md b/proposals/3824-sso-redirect-action.md index c0f3d08ed10..a0d0d7f38ab 100644 --- a/proposals/3824-sso-redirect-action.md +++ b/proposals/3824-sso-redirect-action.md @@ -61,6 +61,8 @@ None. [Capabilities negotiation](https://spec.matrix.org/v1.2/client-server-api/#capabilities-negotiation) could be used for availability of login vs register. +Add a `GET /_matrix/client/v3/register` endpoint that would return the available flows for registration. There is an appealing elegance/symmetry to this approach. + 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 From 0cd72c649638f70ec3ed5bcce82410ed834197b4 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 15 Jun 2022 13:52:01 +0100 Subject: [PATCH 06/37] Rework proposal to be about OIDC aware clients --- proposals/3824-sso-redirect-action.md | 72 ++++++++++++++++++--------- 1 file changed, 49 insertions(+), 23 deletions(-) diff --git a/proposals/3824-sso-redirect-action.md b/proposals/3824-sso-redirect-action.md index a0d0d7f38ab..be7902be378 100644 --- a/proposals/3824-sso-redirect-action.md +++ b/proposals/3824-sso-redirect-action.md @@ -1,46 +1,43 @@ -# MSC3824: Ability to distinguish between login and registration +# MSC3824: OIDC aware clients -A client can determine the available authentication methods/types via the `GET /_matrix/client/v3/login` endpoint. +In the context of [MSC2964](https://github.com/matrix-org/matrix-doc/pull/2964) we can define four types of client: -However, unless registration is blanket disabled (i.e. `POST /_matrix/client/v3/register` returns `403`) then it is assumed that both login and registration are possible using all given auth types. +1. *OIDC native client* - This is a client that, where the homeserver supports it, talks to the specified OP in order to complete login and registration. e.g. Element X (WIP), Hydrogen (WIP) +1. *OIDC aware client* - This is a client that is aware of OIDC but will still use existing auth types (e.g. `m.login.sso`) to auth with an OIDC enabled homeserver. +1. *Legacy client with SSO support* - This is a client that is not aware of OIDC but does support `m.login.sso` flow. e.g. Element Web, iOS, Android, Fluffy, Nheko, Cinny +1. *Legacy client without SSO support* - This is a client that is not aware of OIDC at all and nor does it support `m.login.sso` flow. Typically auth is done via `m.login.password` only. e.g. Fractal -Furthermore, a homeserver cannot tell if a `m.login.sso` request for `GET /_matrix/client/v3/login/sso/redirect` is intended to be used to login an existing user or register a new user. +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 OIDC enabled homeserver. -In the context of [MSC2964](https://github.com/matrix-org/matrix-doc/pull/2964): - -1. a client needs to know whether registration can be completed by a particular auth type; -2. the homeserver needs to know the intent so that the correct UI can be shown to the user. +This proposal outlines changes to facilitate clients in becoming OIDC aware. ## Proposal -Firstly, the homeserver can optionally specify which actions are supported for an authentication type. +Firstly, 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. -Secondly, a client can specify which action the user is wanting to achieve at the point of SSO redirection. +Secondly, the homeserver can optionally specify which auth type is `delegated.oidc.compatibility` are supported for an authentication type. -### Homeserver specifies available actions per auth type +### Homeserver indicates that an `m.login.sso` flow is for compatibility -Add an optional `actions` field to the response of `GET /_matrix/client/v3/login`: +Add an optional `delegated.oidc.compatibility` field to the response of `GET /_matrix/client/v3/login`: -`actions?: ("login" | "register")[]` +`"delegated.oidc.compatibility"?: boolean` -For example, if a homeserver supports password for login only, and SSO for login and registration then a response could look like: +For example, if a homeserver is advertising password login for legacy clients only then it could return the following: ``` { "flows": [{ - "type": "m.login.password", - "actions": ["login"], + "type": "m.login.password" }, { "type": "m.login.sso", - "actions": ["login", "register"] + "delegated.oidc.compatibility": true }] } ``` -If no `actions` field is present then the client should assume that both `login` and `register` are both supported unless indicated elsewhere by the API (e.g. registration disabled `403`). - -If `actions` is empty array (i.e. `[]`) then no action is supported. +If the client finds `delegated.oidc.compatibility` 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 @@ -53,15 +50,34 @@ e.g. `https://matrix-client.matrix.org/_matrix/client/v3/login/sso/redirect?acti n.b. we don't need to add this to the [Login Fallback](https://spec.matrix.org/v1.2/client-server-api/#login-fallback) as that isn't used for registration. +### Definition of OIDC aware + +For a client to be considered *OIDC aware* it would: + +- support the `m.login.sso` auth flow +- where a `delegated.oidc.compatibility` value of `true` is present on an `m.login.sso` then offer that auth flow to the user +- append `action=login` and `action=register` parameters to the SSO redirect URLs +- sign post and link users to manage their account at the OP web UI given by [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) + +For an OIDC enabled homeserver to provide support for *OIDC aware* clients it would: + +- support OIDC delegation as per [MSC2964](https://github.com/matrix-org/matrix-spec-proposals/pull/2964) and others +- recommended to advertise the account management UI in accordance with [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) +- provide a compatibility layer for `m.login.password` and `m.login.sso` that wraps on to OIDC +- indicate that the `m.login.sso` is preferred by setting `delegated.oidc.compatibility` to `true` +- make use of the `action` param on the SSO redirect endpoints + ## Potential issues None. ## Alternatives -[Capabilities negotiation](https://spec.matrix.org/v1.2/client-server-api/#capabilities-negotiation) could be used for availability of login vs register. +Clients could assume that an `m.login.sso` is preferred directly from where [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) OP discovery indicates OIDC 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. -Add a `GET /_matrix/client/v3/register` endpoint that would return the available flows for registration. There is an appealing elegance/symmetry to this approach. +[Capabilities negotiation](https://spec.matrix.org/v1.2/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. @@ -71,4 +87,14 @@ None relevant. ## Unstable prefix -Not applicable. +While this feature is in development the following unstable prefixes should be used: + +* `delegated.oidc.compatibility` --> `org.matrix.msc3824.delegated.oidc.compatibility` + +## Dependencies + +This MSC depends on the following MSCs, which at the time of writing have not yet +been accepted into the spec: + +* [MSC2964](https://github.com/matrix-org/matrix-spec-proposals/pull/2964): Delegation of auth from homeserver to OIDC Provider +* [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965): OIDC Provider discovery From 8adb0ff81f12c21c7f32cc16ee96f026f764e1ea Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 15 Jun 2022 13:52:29 +0100 Subject: [PATCH 07/37] Rename proposal file --- .../{3824-sso-redirect-action.md => 3824-oidc-aware-clients.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename proposals/{3824-sso-redirect-action.md => 3824-oidc-aware-clients.md} (100%) diff --git a/proposals/3824-sso-redirect-action.md b/proposals/3824-oidc-aware-clients.md similarity index 100% rename from proposals/3824-sso-redirect-action.md rename to proposals/3824-oidc-aware-clients.md From e98fc1349396cdfb929680f555900354b7fc9bf9 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 15 Jun 2022 15:57:43 +0100 Subject: [PATCH 08/37] Use _ formatted flag name --- proposals/3824-oidc-aware-clients.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index be7902be378..e49dde209e4 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -15,13 +15,13 @@ This proposal outlines changes to facilitate clients in becoming OIDC aware. Firstly, 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. -Secondly, the homeserver can optionally specify which auth type is `delegated.oidc.compatibility` are supported for an authentication type. +Secondly, the homeserver can optionally specify which auth type is `delegated_oidc_compatibility` are supported for an authentication type. ### Homeserver indicates that an `m.login.sso` flow is for compatibility -Add an optional `delegated.oidc.compatibility` field to the response of `GET /_matrix/client/v3/login`: +Add an optional `delegated_oidc_compatibility` field to the response of `GET /_matrix/client/v3/login`: -`"delegated.oidc.compatibility"?: boolean` +`"delegated_oidc_compatibility"?: boolean` For example, if a homeserver is advertising password login for legacy clients only then it could return the following: @@ -31,13 +31,13 @@ For example, if a homeserver is advertising password login for legacy clients on "type": "m.login.password" }, { "type": "m.login.sso", - "delegated.oidc.compatibility": true + "delegated_oidc_compatibility": true }] } ``` -If the client finds `delegated.oidc.compatibility` to be `true` then, assuming it supports that auth type, it should present this as the only login/registration method available to the user. +If the client finds `delegated_oidc_compatibility` 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 @@ -55,7 +55,7 @@ n.b. we don't need to add this to the [Login Fallback](https://spec.matrix.org/v For a client to be considered *OIDC aware* it would: - support the `m.login.sso` auth flow -- where a `delegated.oidc.compatibility` value of `true` is present on an `m.login.sso` then offer that auth flow to the user +- where a `delegated_oidc_compatibility` value of `true` is present on an `m.login.sso` then offer that auth flow to the user - append `action=login` and `action=register` parameters to the SSO redirect URLs - sign post and link users to manage their account at the OP web UI given by [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) @@ -64,7 +64,7 @@ For an OIDC enabled homeserver to provide support for *OIDC aware* clients it wo - support OIDC delegation as per [MSC2964](https://github.com/matrix-org/matrix-spec-proposals/pull/2964) and others - recommended to advertise the account management UI in accordance with [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) - provide a compatibility layer for `m.login.password` and `m.login.sso` that wraps on to OIDC -- indicate that the `m.login.sso` is preferred by setting `delegated.oidc.compatibility` to `true` +- indicate that the `m.login.sso` is preferred by setting `delegated_oidc_compatibility` to `true` - make use of the `action` param on the SSO redirect endpoints ## Potential issues @@ -89,7 +89,7 @@ None relevant. While this feature is in development the following unstable prefixes should be used: -* `delegated.oidc.compatibility` --> `org.matrix.msc3824.delegated.oidc.compatibility` +* `delegated_oidc_compatibility` --> `org.matrix.msc3824.delegated_oidc_compatibility` ## Dependencies From ccf6b1bb728798cf5da5659e814be464fabb470a Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 22 Jun 2022 17:19:32 +0200 Subject: [PATCH 09/37] Fixes to Homeserver and Client requirements list --- proposals/3824-oidc-aware-clients.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index e49dde209e4..d8d477c9d2b 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -55,17 +55,17 @@ n.b. we don't need to add this to the [Login Fallback](https://spec.matrix.org/v For a client to be considered *OIDC aware* it would: - support the `m.login.sso` auth flow -- where a `delegated_oidc_compatibility` value of `true` is present on an `m.login.sso` then offer that auth flow to the user +- where a `delegated_oidc_compatibility` 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 - sign post and link users to manage their account at the OP web UI given by [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) For an OIDC enabled homeserver to provide support for *OIDC aware* clients it would: - support OIDC delegation as per [MSC2964](https://github.com/matrix-org/matrix-spec-proposals/pull/2964) and others -- recommended to advertise the account management UI in accordance with [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) - provide a compatibility layer for `m.login.password` and `m.login.sso` that wraps on to OIDC - indicate that the `m.login.sso` is preferred by setting `delegated_oidc_compatibility` to `true` - make use of the `action` param on the SSO redirect endpoints +- RECOMMENDED: advertise the account management UI in accordance with [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) ## Potential issues From 13e7f448582e6516a478e1469a3508b6f0c929be Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 22 Jun 2022 17:39:46 +0200 Subject: [PATCH 10/37] RECOMMENDED: label SSO button as "Continue" --- proposals/3824-oidc-aware-clients.md | 1 + 1 file changed, 1 insertion(+) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index d8d477c9d2b..f46bb373dcf 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -58,6 +58,7 @@ For a client to be considered *OIDC aware* it would: - where a `delegated_oidc_compatibility` 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 - sign post and link users to manage their account at the OP web UI given by [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) +- RECOMMENDED: label the SSO button as "Continue" For an OIDC enabled homeserver to provide support for *OIDC aware* clients it would: From 262b39509fe86dea8c7d4d4e68a475ed94ea33ad Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 22 Jun 2022 17:58:21 +0200 Subject: [PATCH 11/37] Use unstable prefix for action query param --- proposals/3824-oidc-aware-clients.md | 1 + 1 file changed, 1 insertion(+) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index f46bb373dcf..cbcd5db2ca5 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -91,6 +91,7 @@ None relevant. While this feature is in development the following unstable prefixes should be used: * `delegated_oidc_compatibility` --> `org.matrix.msc3824.delegated_oidc_compatibility` +* `action` query param --> `org.matrix.msc3824.action` ## Dependencies From c2ab31fe73e49df7d57896b8b38fd90389bc57bb Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Fri, 5 Aug 2022 09:50:17 +0100 Subject: [PATCH 12/37] Reference to MSC3861 --- proposals/3824-oidc-aware-clients.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index cbcd5db2ca5..83e7ca05895 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -1,5 +1,7 @@ # MSC3824: OIDC aware clients +This proposal is part of the broader [MSC3861: Matrix architecture change to delegate authentication via OIDC](https://github.com/matrix-org/matrix-spec-proposals/pull/2967). + In the context of [MSC2964](https://github.com/matrix-org/matrix-doc/pull/2964) we can define four types of client: 1. *OIDC native client* - This is a client that, where the homeserver supports it, talks to the specified OP in order to complete login and registration. e.g. Element X (WIP), Hydrogen (WIP) From 5bee1892dcc224cfade2402228e0863d14ccf6b4 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Thu, 18 May 2023 11:46:12 -0400 Subject: [PATCH 13/37] Update proposals/3824-oidc-aware-clients.md Co-authored-by: Patrick Cloke --- proposals/3824-oidc-aware-clients.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index 83e7ca05895..b37af0966f4 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -59,7 +59,7 @@ For a client to be considered *OIDC aware* it would: - support the `m.login.sso` auth flow - where a `delegated_oidc_compatibility` 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 -- sign post and link users to manage their account at the OP web UI given by [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) +- Link users to manage their account at the OP web UI given by [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) instead of native UI - RECOMMENDED: label the SSO button as "Continue" For an OIDC enabled homeserver to provide support for *OIDC aware* clients it would: From 0eea9ae7abe62b57c074653d28fa8930554fee7c Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Fri, 18 Aug 2023 15:47:01 +0100 Subject: [PATCH 14/37] Style --- proposals/3824-oidc-aware-clients.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index b37af0966f4..220670f812b 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -27,7 +27,7 @@ Add an optional `delegated_oidc_compatibility` field to the response of `GET /_m 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" @@ -59,7 +59,7 @@ For a client to be considered *OIDC aware* it would: - support the `m.login.sso` auth flow - where a `delegated_oidc_compatibility` 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 -- Link users to manage their account at the OP web UI given by [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) instead of native UI +- link users to manage their account at the OP web UI given by [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) instead of native UI - RECOMMENDED: label the SSO button as "Continue" For an OIDC enabled homeserver to provide support for *OIDC aware* clients it would: @@ -92,13 +92,13 @@ None relevant. While this feature is in development the following unstable prefixes should be used: -* `delegated_oidc_compatibility` --> `org.matrix.msc3824.delegated_oidc_compatibility` -* `action` query param --> `org.matrix.msc3824.action` +- `delegated_oidc_compatibility` --> `org.matrix.msc3824.delegated_oidc_compatibility` +- `action` query param --> `org.matrix.msc3824.action` ## Dependencies This MSC depends on the following MSCs, which at the time of writing have not yet been accepted into the spec: -* [MSC2964](https://github.com/matrix-org/matrix-spec-proposals/pull/2964): Delegation of auth from homeserver to OIDC Provider -* [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965): OIDC Provider discovery +- [MSC2964](https://github.com/matrix-org/matrix-spec-proposals/pull/2964): Delegation of auth from homeserver to OIDC Provider +- [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965): OIDC Provider discovery From eec93e198ad0bf0ca35d158800af8ed71ba64b6a Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Fri, 18 Aug 2023 15:53:50 +0100 Subject: [PATCH 15/37] Reorganise requiremetns --- proposals/3824-oidc-aware-clients.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index 220670f812b..b12bfd1d12e 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -54,21 +54,27 @@ n.b. we don't need to add this to the [Login Fallback](https://spec.matrix.org/v ### Definition of OIDC aware -For a client to be considered *OIDC aware* it would: +For a client to be considered fully *OIDC aware* it **must**: - support the `m.login.sso` auth flow - where a `delegated_oidc_compatibility` 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 - link users to manage their account at the OP web UI given by [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) instead of native UI -- RECOMMENDED: label the SSO button as "Continue" -For an OIDC enabled homeserver to provide support for *OIDC aware* clients it would: +Optionally, an *OIDC aware* client **could**: + +- label the SSO button as "Continue" + +For an OIDC enabled homeserver to provide support for *OIDC aware* clients it **must**: - support OIDC delegation as per [MSC2964](https://github.com/matrix-org/matrix-spec-proposals/pull/2964) and others - provide a compatibility layer for `m.login.password` and `m.login.sso` that wraps on to OIDC - indicate that the `m.login.sso` is preferred by setting `delegated_oidc_compatibility` to `true` - make use of the `action` param on the SSO redirect endpoints -- RECOMMENDED: advertise the account management UI in accordance with [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) + +Additionally, the homeserver **should**: + +- advertise the account management UI in accordance with [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) ## Potential issues From 54b3e85a37eec63d95fcfe9d185cb34aac4dbe5d Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Fri, 18 Aug 2023 16:06:38 +0100 Subject: [PATCH 16/37] Add 3pid and session management requirements --- proposals/3824-oidc-aware-clients.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index b12bfd1d12e..cf46fec0ef9 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -4,7 +4,7 @@ This proposal is part of the broader [MSC3861: Matrix architecture change to del In the context of [MSC2964](https://github.com/matrix-org/matrix-doc/pull/2964) we can define four types of client: -1. *OIDC native client* - This is a client that, where the homeserver supports it, talks to the specified OP in order to complete login and registration. e.g. Element X (WIP), Hydrogen (WIP) +1. *OIDC native client* - This is a client that, where the homeserver supports it, talks to the specified OpenID Provider in order to complete login and registration. e.g. Element X (WIP), Hydrogen (WIP) 1. *OIDC aware client* - This is a client that is aware of OIDC but will still use existing auth types (e.g. `m.login.sso`) to auth with an OIDC enabled homeserver. 1. *Legacy client with SSO support* - This is a client that is not aware of OIDC but does support `m.login.sso` flow. e.g. Element Web, iOS, Android, Fluffy, Nheko, Cinny 1. *Legacy client without SSO support* - This is a client that is not aware of OIDC at all and nor does it support `m.login.sso` flow. Typically auth is done via `m.login.password` only. e.g. Fractal @@ -59,7 +59,10 @@ For a client to be considered fully *OIDC aware* it **must**: - support the `m.login.sso` auth flow - where a `delegated_oidc_compatibility` 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 -- link users to manage their account at the OP web UI given by [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) instead of native UI +- link users to manage their account at the OpenID Provider web UI given by [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) instead of native UI +- check and honour the `m.3pid_changes` [capability](https://spec.matrix.org/v1.7/client-server-api/#m3pid_changes-capability) so that the user is not offered the ability to add or remove 3PIDs when OIDC is used +- if the user wishes to sign out a device session other than it's own then the client **must** link the user to the OpenID Provider web UI given by [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) if provided +- where the user is linked to the OpenID Provider web UI above, the client should include `#action=logout&device_id=` in the URL to indicate which device session the user wishes to sign out Optionally, an *OIDC aware* client **could**: @@ -82,7 +85,7 @@ None. ## Alternatives -Clients could assume that an `m.login.sso` is preferred directly from where [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) OP discovery indicates OIDC is being used. However, this might hamper some more custom configuration. +Clients could assume that an `m.login.sso` is preferred directly from where [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) OpenID Provider discovery indicates OIDC 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. From a7ecdfd0193d92b82c7ff1ce28782f2a35fe008e Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Mon, 21 Aug 2023 06:42:51 -0400 Subject: [PATCH 17/37] 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 --- proposals/3824-oidc-aware-clients.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index cf46fec0ef9..a7d8723d0d3 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -61,12 +61,14 @@ For a client to be considered fully *OIDC aware* it **must**: - append `action=login` and `action=register` parameters to the SSO redirect URLs - link users to manage their account at the OpenID Provider web UI given by [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) instead of native UI - check and honour the `m.3pid_changes` [capability](https://spec.matrix.org/v1.7/client-server-api/#m3pid_changes-capability) so that the user is not offered the ability to add or remove 3PIDs when OIDC is used -- if the user wishes to sign out a device session other than it's own then the client **must** link the user to the OpenID Provider web UI given by [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) if provided -- where the user is linked to the OpenID Provider web UI above, the client should include `#action=logout&device_id=` in the URL to indicate which device session the user wishes to sign out +- if the user wishes to sign out a device session other than it's own then the client **must**: + - link the user to the OpenID Provider web UI given by [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) if provided + - append the `action` and `device_id` to the web UI link parameters described by [MSC2965](https://github.com/sandhose/matrix-doc/blob/msc/sandhose/oidc-discovery/proposals/2965-oidc-discovery.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=session_end&device_id=` Optionally, an *OIDC aware* client **could**: - label the SSO button as "Continue" +- pass other [query parameters for context](https://github.com/sandhose/matrix-doc/blob/msc/sandhose/oidc-discovery/proposals/2965-oidc-discovery.md#account-management-url-parameters) when linking to the account web UI For an OIDC enabled homeserver to provide support for *OIDC aware* clients it **must**: From 4188601687630fda218af4e811953d8953ad17a3 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Mon, 15 Sep 2025 15:09:16 +0100 Subject: [PATCH 18/37] Update to reference OAuth 2.0 API in spec and MSC4191 --- proposals/3824-oidc-aware-clients.md | 60 ++++++++++++++-------------- 1 file changed, 31 insertions(+), 29 deletions(-) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index a7d8723d0d3..f577e3ffe72 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -1,17 +1,20 @@ -# MSC3824: OIDC aware clients +# MSC3824: OAuth 2.0 API aware clients -This proposal is part of the broader [MSC3861: Matrix architecture change to delegate authentication via OIDC](https://github.com/matrix-org/matrix-spec-proposals/pull/2967). +As of spec 1.15 we now have two APIs for clients to authenticate: -In the context of [MSC2964](https://github.com/matrix-org/matrix-doc/pull/2964) we can define four types of client: +- the [Legacy API](https://spec.matrix.org/v1.15/client-server-api/#legacy-api) +- the [OAuth 2.0 API](https://spec.matrix.org/v1.15/client-server-api/#oauth-20-api) -1. *OIDC native client* - This is a client that, where the homeserver supports it, talks to the specified OpenID Provider in order to complete login and registration. e.g. Element X (WIP), Hydrogen (WIP) -1. *OIDC aware client* - This is a client that is aware of OIDC but will still use existing auth types (e.g. `m.login.sso`) to auth with an OIDC enabled homeserver. -1. *Legacy client with SSO support* - This is a client that is not aware of OIDC but does support `m.login.sso` flow. e.g. Element Web, iOS, Android, Fluffy, Nheko, Cinny -1. *Legacy client without SSO support* - This is a client that is not aware of OIDC at all and nor does it support `m.login.sso` flow. Typically auth is done via `m.login.password` only. e.g. Fractal +In this context we can define four types of client: -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 OIDC enabled homeserver. +1. *OAuth 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 aware client* - This is a client that is aware of the OAuth 2.0 API but will still uses the Legacy PI (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` flow. 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 `m.login.sso` flow. Typically auth is done via `m.login.password` only. e.g. Fractal -This proposal outlines changes to facilitate clients in becoming OIDC aware. +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. + +This proposal outlines changes to facilitate clients in becoming OAuth 2.0 API aware. ## Proposal @@ -50,36 +53,36 @@ Add an optional query parameter `action` to `GET /_matrix/client/v3/login/sso/re e.g. `https://matrix-client.matrix.org/_matrix/client/v3/login/sso/redirect?action=register` -n.b. we don't need to add this to the [Login Fallback](https://spec.matrix.org/v1.2/client-server-api/#login-fallback) as that isn't used for registration. +n.b. we don't need to add this to the [Login Fallback](https://spec.matrix.org/v1.15/client-server-api/#login-fallback) as that isn't used for registration. -### Definition of OIDC aware +### Definition of OAuth 2.0 aware -For a client to be considered fully *OIDC aware* it **must**: +For a client to be considered fully *OAuth 2.0 aware* it **must**: - support the `m.login.sso` auth flow - where a `delegated_oidc_compatibility` 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 -- link users to manage their account at the OpenID Provider web UI given by [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) instead of native UI -- check and honour the `m.3pid_changes` [capability](https://spec.matrix.org/v1.7/client-server-api/#m3pid_changes-capability) so that the user is not offered the ability to add or remove 3PIDs when OIDC is used +- link users to manage their account at the `account_management_uri` given by [MSC4191](https://github.com/matrix-org/matrix-spec-proposals/pull/4191) instead of native UI +- check and honour the `m.3pid_changes` [capability](https://spec.matrix.org/v1.15/client-server-api/#m3pid_changes-capability) so that the user is not offered the ability to add or remove 3PIDs when the server has the OAuth 2.0 API enabled - if the user wishes to sign out a device session other than it's own then the client **must**: - - link the user to the OpenID Provider web UI given by [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) if provided - - append the `action` and `device_id` to the web UI link parameters described by [MSC2965](https://github.com/sandhose/matrix-doc/blob/msc/sandhose/oidc-discovery/proposals/2965-oidc-discovery.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=session_end&device_id=` + - link the user to the `account_management_uri` given by [MSC4191](https://github.com/matrix-org/matrix-spec-proposals/pull/4191) 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=session_end&device_id=` -Optionally, an *OIDC aware* client **could**: +Optionally, an *OAuth 2.0 aware* client **could**: -- label the SSO button as "Continue" -- pass other [query parameters for context](https://github.com/sandhose/matrix-doc/blob/msc/sandhose/oidc-discovery/proposals/2965-oidc-discovery.md#account-management-url-parameters) when linking to the account web UI +- label the SSO button as "Continue" rather than "SSO". 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 an OIDC enabled homeserver to provide support for *OIDC aware* clients it **must**: +For an OIDC enabled homeserver to provide support for *OAuth 2.0 aware* clients it **must**: -- support OIDC delegation as per [MSC2964](https://github.com/matrix-org/matrix-spec-proposals/pull/2964) and others -- provide a compatibility layer for `m.login.password` and `m.login.sso` that wraps on to OIDC +- support the [OAuth 2.0 API](https://spec.matrix.org/v1.15/client-server-api/#oauth-20-api) +- provide a compatibility layer for `m.login.password` and `m.login.sso` - indicate that the `m.login.sso` is preferred by setting `delegated_oidc_compatibility` to `true` - make use of the `action` param on the SSO redirect endpoints Additionally, the homeserver **should**: -- advertise the account management UI in accordance with [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) +- advertise the account management UI in accordance with [MSC4191](https://github.com/matrix-org/matrix-spec-proposals/pull/4191) ## Potential issues @@ -87,11 +90,11 @@ None. ## Alternatives -Clients could assume that an `m.login.sso` is preferred directly from where [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) OpenID Provider discovery indicates OIDC is being used. However, this might hamper some more custom configuration. +Clients could assume that an `m.login.sso` is preferred directly from where the [server metadata discovery](https://spec.matrix.org/v1.15/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.2/client-server-api/#capabilities-negotiation) could be used to indicate that `m.login.sso` is preferred. +[Capabilities negotiation](https://spec.matrix.org/v1.15/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. @@ -103,13 +106,12 @@ None relevant. While this feature is in development the following unstable prefixes should be used: -- `delegated_oidc_compatibility` --> `org.matrix.msc3824.delegated_oidc_compatibility` -- `action` query param --> `org.matrix.msc3824.action` +- In the /login response body: `org.matrix.msc3824.delegated_oidc_compatibility` instead of `delegated_oidc_compatibility` +- On the SSO redirect: `org.matrix.msc3824.action` instead of `action` query parameter ## Dependencies This MSC depends on the following MSCs, which at the time of writing have not yet been accepted into the spec: -- [MSC2964](https://github.com/matrix-org/matrix-spec-proposals/pull/2964): Delegation of auth from homeserver to OIDC Provider -- [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965): OIDC Provider discovery +- [MSC4191](https://github.com/matrix-org/matrix-spec-proposals/pull/4191): Account management deep-linking From 7da4d88ef216898a64c80213f01aa53863563506 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Mon, 15 Sep 2025 15:28:06 +0100 Subject: [PATCH 19/37] Add note about session_end vs org.matrix.session_end --- proposals/3824-oidc-aware-clients.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index f577e3ffe72..9d745ea5c77 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -66,7 +66,8 @@ For a client to be considered fully *OAuth 2.0 aware* it **must**: - check and honour the `m.3pid_changes` [capability](https://spec.matrix.org/v1.15/client-server-api/#m3pid_changes-capability) so that the user is not offered the ability to add or remove 3PIDs when the server has the OAuth 2.0 API enabled - if the user wishes to sign out a device session other than it's own then the client **must**: - link the user to the `account_management_uri` given by [MSC4191](https://github.com/matrix-org/matrix-spec-proposals/pull/4191) 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=session_end&device_id=` + - 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.session_end&device_id=` + - n.b. an earlier version of this MSC used the `session_end` value instead of `org.matrix.session_end`. This has changed for consistency with MSC4191. Optionally, an *OAuth 2.0 aware* client **could**: @@ -109,6 +110,9 @@ While this feature is in development the following unstable prefixes should be u - In the /login response body: `org.matrix.msc3824.delegated_oidc_compatibility` instead of `delegated_oidc_compatibility` - 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](https://github.com/matrix-org/matrix-spec-proposals/pull/4191) +value `org.matrix.session_end`. 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 From d14579cc21ae6d39214623119a2565fd7cf2fe16 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Mon, 15 Sep 2025 15:30:35 +0100 Subject: [PATCH 20/37] Update proposals/3824-oidc-aware-clients.md --- proposals/3824-oidc-aware-clients.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index 9d745ea5c77..4757e0e388d 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -79,7 +79,7 @@ For an OIDC enabled homeserver to provide support for *OAuth 2.0 aware* clients - support the [OAuth 2.0 API](https://spec.matrix.org/v1.15/client-server-api/#oauth-20-api) - provide a compatibility layer for `m.login.password` and `m.login.sso` - indicate that the `m.login.sso` is preferred by setting `delegated_oidc_compatibility` to `true` -- make use of the `action` param on the SSO redirect endpoints +- provides a value for the `action` param on the SSO redirect endpoints as defined above Additionally, the homeserver **should**: From 595b00380cd4a3405ba986f5044a1335ed8ab506 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Mon, 15 Sep 2025 15:32:33 +0100 Subject: [PATCH 21/37] Add note on where action=login|register value might come from --- proposals/3824-oidc-aware-clients.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index 4757e0e388d..ed29cc20569 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -53,6 +53,8 @@ Add an optional query parameter `action` to `GET /_matrix/client/v3/login/sso/re 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.15/client-server-api/#login-fallback) as that isn't used for registration. ### Definition of OAuth 2.0 aware From 295f73f62e8bf8c61e61c83b7a429d87049dfc43 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Mon, 15 Sep 2025 15:40:53 +0100 Subject: [PATCH 22/37] Clarify what was meant by "compatibility layer" --- proposals/3824-oidc-aware-clients.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index ed29cc20569..a42d5376cd9 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -79,7 +79,7 @@ Optionally, an *OAuth 2.0 aware* client **could**: For an OIDC enabled homeserver to provide support for *OAuth 2.0 aware* clients it **must**: - support the [OAuth 2.0 API](https://spec.matrix.org/v1.15/client-server-api/#oauth-20-api) -- provide a compatibility layer for `m.login.password` and `m.login.sso` +- provide an implementation of the `m.login.password` and `m.login.sso` [authentication types](https://spec.matrix.org/v1.15/client-server-api/#authentication-types) from the Legacy API - indicate that the `m.login.sso` is preferred by setting `delegated_oidc_compatibility` to `true` - provides a value for the `action` param on the SSO redirect endpoints as defined above From 26710d103476bdae4ebce89dbee89ec012cba66b Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 17 Sep 2025 14:30:43 +0100 Subject: [PATCH 23/37] Add requirement about deactivating account --- proposals/3824-oidc-aware-clients.md | 1 + 1 file changed, 1 insertion(+) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index a42d5376cd9..dba663d474c 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -65,6 +65,7 @@ For a client to be considered fully *OAuth 2.0 aware* it **must**: - where a `delegated_oidc_compatibility` 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 - link users to manage their account at the `account_management_uri` given by [MSC4191](https://github.com/matrix-org/matrix-spec-proposals/pull/4191) 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 - check and honour the `m.3pid_changes` [capability](https://spec.matrix.org/v1.15/client-server-api/#m3pid_changes-capability) so that the user is not offered the ability to add or remove 3PIDs when the server has the OAuth 2.0 API enabled - if the user wishes to sign out a device session other than it's own then the client **must**: - link the user to the `account_management_uri` given by [MSC4191](https://github.com/matrix-org/matrix-spec-proposals/pull/4191) if provided From d5408a2afcd342ec642c00d7b9a9af9e9475d5e9 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Fri, 3 Oct 2025 10:29:29 +0100 Subject: [PATCH 24/37] Use org.matrix.device_delete from MSC4191 not org.matrix.session_end --- proposals/3824-oidc-aware-clients.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index dba663d474c..0ed8805fd1b 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -69,8 +69,8 @@ For a client to be considered fully *OAuth 2.0 aware* it **must**: - check and honour the `m.3pid_changes` [capability](https://spec.matrix.org/v1.15/client-server-api/#m3pid_changes-capability) so that the user is not offered the ability to add or remove 3PIDs when the server has the OAuth 2.0 API enabled - if the user wishes to sign out a device session other than it's own then the client **must**: - link the user to the `account_management_uri` given by [MSC4191](https://github.com/matrix-org/matrix-spec-proposals/pull/4191) 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.session_end&device_id=` - - n.b. an earlier version of this MSC used the `session_end` value instead of `org.matrix.session_end`. This has changed for consistency with MSC4191. + - 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**: @@ -114,7 +114,7 @@ While this feature is in development the following unstable prefixes should be u - 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](https://github.com/matrix-org/matrix-spec-proposals/pull/4191) -value `org.matrix.session_end`. This should be resolved once the feature gets stabilised. +value `org.matrix.device_delete`. This should be resolved once the feature gets stabilised. ## Dependencies From b06fefd8f8e1831df79d6670173b0b4630f3dc54 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 8 Oct 2025 10:34:08 +0100 Subject: [PATCH 25/37] Update proposals/3824-oidc-aware-clients.md Co-authored-by: David Baker --- proposals/3824-oidc-aware-clients.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index 0ed8805fd1b..f702a6444c1 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -8,7 +8,7 @@ As of spec 1.15 we now have two APIs for clients to authenticate: In this context we can define four types of client: 1. *OAuth 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 aware client* - This is a client that is aware of the OAuth 2.0 API but will still uses the Legacy PI (e.g. `m.login.sso`) to auth with an OAuth 2.0 API enabled homeserver. +1. *OAuth aware client* - This is a client that is aware 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` flow. 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 `m.login.sso` flow. Typically auth is done via `m.login.password` only. e.g. Fractal From 38cdbd81012a1e478f67130680cc344004bc481a Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 8 Oct 2025 12:48:50 +0100 Subject: [PATCH 26/37] Cleanup --- proposals/3824-oidc-aware-clients.md | 46 +++++++++++++++++----------- 1 file changed, 28 insertions(+), 18 deletions(-) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index f702a6444c1..882ba244bf8 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -2,25 +2,31 @@ As of spec 1.15 we now have two APIs for clients to authenticate: -- the [Legacy API](https://spec.matrix.org/v1.15/client-server-api/#legacy-api) -- the [OAuth 2.0 API](https://spec.matrix.org/v1.15/client-server-api/#oauth-20-api) +- the [Legacy API] +- the [OAuth 2.0 API] In this context we can define four types of client: -1. *OAuth 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 aware client* - This is a client that is aware 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` flow. 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 `m.login.sso` flow. Typically auth is done via `m.login.password` only. e.g. Fractal +1. *OAuth 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 aware client* - This is a client that is aware 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` flow 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. +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. -This proposal outlines changes to facilitate clients in becoming OAuth 2.0 API aware. +This proposal outlines changes to facilitate clients in becoming [OAuth 2.0 API] aware. ## Proposal -Firstly, 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. +Firstly, we make two backwards compatible changes to the [Legacy API]: -Secondly, the homeserver can optionally specify which auth type is `delegated_oidc_compatibility` are supported for an authentication type. +- 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. +- The homeserver can optionally specify which auth type is `delegated_oidc_compatibility` are supported for an authentication type. + +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 for compatibility @@ -64,13 +70,13 @@ For a client to be considered fully *OAuth 2.0 aware* it **must**: - support the `m.login.sso` auth flow - where a `delegated_oidc_compatibility` 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 -- link users to manage their account at the `account_management_uri` given by [MSC4191](https://github.com/matrix-org/matrix-spec-proposals/pull/4191) instead of native UI +- 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 - check and honour the `m.3pid_changes` [capability](https://spec.matrix.org/v1.15/client-server-api/#m3pid_changes-capability) so that the user is not offered the ability to add or remove 3PIDs when the server has the OAuth 2.0 API enabled - if the user wishes to sign out a device session other than it's own then the client **must**: - - link the user to the `account_management_uri` given by [MSC4191](https://github.com/matrix-org/matrix-spec-proposals/pull/4191) if provided + - 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. + - 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**: @@ -79,14 +85,14 @@ Optionally, an *OAuth 2.0 aware* client **could**: For an OIDC enabled homeserver to provide support for *OAuth 2.0 aware* clients it **must**: -- support the [OAuth 2.0 API](https://spec.matrix.org/v1.15/client-server-api/#oauth-20-api) +- support the [OAuth 2.0 API] - provide an implementation of the `m.login.password` and `m.login.sso` [authentication types](https://spec.matrix.org/v1.15/client-server-api/#authentication-types) from the Legacy API - indicate that the `m.login.sso` is preferred by setting `delegated_oidc_compatibility` to `true` - provides 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](https://github.com/matrix-org/matrix-spec-proposals/pull/4191) +- advertise the account management UI in accordance with [MSC4191] ## Potential issues @@ -94,7 +100,7 @@ None. ## Alternatives -Clients could assume that an `m.login.sso` is preferred directly from where the [server metadata discovery](https://spec.matrix.org/v1.15/client-server-api/#server-metadata-discovery) indicates the OAuth 2.0 API is being used. However, this might hamper some more custom configuration. +Clients could assume that an `m.login.sso` is preferred directly from where the [server metadata discovery](https://spec.matrix.org/v1.15/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. @@ -113,7 +119,7 @@ While this feature is in development the following unstable prefixes should be u - In the /login response body: `org.matrix.msc3824.delegated_oidc_compatibility` instead of `delegated_oidc_compatibility` - 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](https://github.com/matrix-org/matrix-spec-proposals/pull/4191) +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 @@ -121,4 +127,8 @@ value `org.matrix.device_delete`. This should be resolved once the feature gets This MSC depends on the following MSCs, which at the time of writing have not yet been accepted into the spec: -- [MSC4191](https://github.com/matrix-org/matrix-spec-proposals/pull/4191): Account management deep-linking +- [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.15/client-server-api/#legacy-api) +[OAuth 2.0 API]: (https://spec.matrix.org/v1.15/client-server-api/#oauth-20-api) From efc0af9e356075c227cf1f683c73aefac3cf3018 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 8 Oct 2025 12:51:27 +0100 Subject: [PATCH 27/37] Feedback from review Re https://github.com/matrix-org/matrix-spec-proposals/pull/3824#discussion_r2410559153 --- proposals/3824-oidc-aware-clients.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index 882ba244bf8..234a81b8695 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -8,7 +8,7 @@ As of spec 1.15 we now have two APIs for clients to authenticate: In this context we can define four types of client: 1. *OAuth 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 aware client* - This is a client that is aware 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. *OAuth 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` flow 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 From 4a27609ecddaf0fbedd412726ff6f4476aee58b7 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 8 Oct 2025 12:54:11 +0100 Subject: [PATCH 28/37] Linewrap --- proposals/3824-oidc-aware-clients.md | 75 +++++++++++++++++++--------- 1 file changed, 52 insertions(+), 23 deletions(-) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index 234a81b8695..82a7a484118 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -7,12 +7,17 @@ As of spec 1.15 we now have two APIs for clients to authenticate: In this context we can define four types of client: -1. *OAuth 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 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` flow 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. +1. *OAuth 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 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` flow 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. This proposal outlines changes to facilitate clients in becoming [OAuth 2.0 API] aware. @@ -20,8 +25,10 @@ This proposal outlines changes to facilitate clients in becoming [OAuth 2.0 API] Firstly, we make two backwards compatible changes to the [Legacy API]: -- 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. -- The homeserver can optionally specify which auth type is `delegated_oidc_compatibility` are supported for an authentication type. +- 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. +- The homeserver can optionally specify which auth type is `delegated_oidc_compatibility` are supported for an + authentication type. 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]. @@ -48,11 +55,13 @@ For example, if a homeserver is advertising password login for legacy clients on ``` -If the client finds `delegated_oidc_compatibility` to be `true` then, assuming it supports that auth type, it should present this as the only login/registration method available to the user. +If the client finds `delegated_oidc_compatibility` 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: +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 @@ -61,32 +70,44 @@ e.g. `https://matrix-client.matrix.org/_matrix/client/v3/login/sso/redirect?acti 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.15/client-server-api/#login-fallback) as that isn't used for registration. +n.b. we don't need to add this to the [Login Fallback](https://spec.matrix.org/v1.15/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 -- where a `delegated_oidc_compatibility` value of `true` is present on an `m.login.sso` then *only* offer that auth flow to the user +- where a `delegated_oidc_compatibility` 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 - 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 -- check and honour the `m.3pid_changes` [capability](https://spec.matrix.org/v1.15/client-server-api/#m3pid_changes-capability) so that the user is not offered the ability to add or remove 3PIDs when the server has the OAuth 2.0 API enabled +- do not offer the user the function to deactivate their account and instead refer them to the account management URL + described above +- check and honour the `m.3pid_changes` + [capability](https://spec.matrix.org/v1.15/client-server-api/#m3pid_changes-capability) so that the user is not + offered the ability to add or remove 3PIDs when the server has the OAuth 2.0 API enabled - if the user wishes to sign out a device session other than it's 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]. + - 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". 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 +- 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 an OIDC enabled homeserver to provide support for *OAuth 2.0 aware* clients it **must**: - support the [OAuth 2.0 API] -- provide an implementation of the `m.login.password` and `m.login.sso` [authentication types](https://spec.matrix.org/v1.15/client-server-api/#authentication-types) from the Legacy API +- provide an implementation of the `m.login.password` and `m.login.sso` + [authentication types](https://spec.matrix.org/v1.15/client-server-api/#authentication-types) from the Legacy API - indicate that the `m.login.sso` is preferred by setting `delegated_oidc_compatibility` to `true` - provides a value for the `action` param on the SSO redirect endpoints as defined above @@ -100,13 +121,20 @@ None. ## Alternatives -Clients could assume that an `m.login.sso` is preferred directly from where the [server metadata discovery](https://spec.matrix.org/v1.15/client-server-api/#server-metadata-discovery) indicates the [OAuth 2.0 API] is being used. However, this might hamper some more custom configuration. +Clients could assume that an `m.login.sso` is preferred directly from where the +[server metadata discovery](https://spec.matrix.org/v1.15/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. +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.15/client-server-api/#capabilities-negotiation) could be used to indicate that `m.login.sso` is preferred. +[Capabilities negotiation](https://spec.matrix.org/v1.15/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. +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 @@ -116,7 +144,8 @@ None relevant. 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 `delegated_oidc_compatibility` +- In the /login response body: `org.matrix.msc3824.delegated_oidc_compatibility` instead of + `delegated_oidc_compatibility` - 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] From 291004139d0f513e3c1b17dfae9d82252fc22fa9 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 8 Oct 2025 12:54:30 +0100 Subject: [PATCH 29/37] DItto --- proposals/3824-oidc-aware-clients.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index 82a7a484118..c93864ab8e2 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -98,7 +98,8 @@ For a client to be considered fully *OAuth 2.0 aware* it **must**: Optionally, an *OAuth 2.0 aware* client **could**: -- label the SSO button as "Continue" rather than "SSO". This is because after redirect the server may then offer a password and/or further upstream IdPs +- label the SSO button as "Continue" rather than "SSO". 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 From c2465f172070aabbec3f8821381eb3d58943ae83 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 8 Oct 2025 13:01:41 +0100 Subject: [PATCH 30/37] Links --- proposals/3824-oidc-aware-clients.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index c93864ab8e2..4f62431802a 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -37,7 +37,8 @@ These are detailed below. ### Homeserver indicates that an `m.login.sso` flow is for compatibility -Add an optional `delegated_oidc_compatibility` field to the response of `GET /_matrix/client/v3/login`: +Add an optional `delegated_oidc_compatibility` field to the response of +[`GET /_matrix/client/v3/login`](https://spec.matrix.org/v1.16/client-server-api/#get_matrixclientv3login): `"delegated_oidc_compatibility"?: boolean` @@ -60,8 +61,9 @@ 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: +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 @@ -70,7 +72,7 @@ e.g. `https://matrix-client.matrix.org/_matrix/client/v3/login/sso/redirect?acti 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.15/client-server-api/#login-fallback) +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 @@ -85,7 +87,7 @@ For a client to be considered fully *OAuth 2.0 aware* it **must**: - do not offer the user the function to deactivate their account and instead refer them to the account management URL described above - check and honour the `m.3pid_changes` - [capability](https://spec.matrix.org/v1.15/client-server-api/#m3pid_changes-capability) so that the user is not + [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 when the server has the OAuth 2.0 API enabled - if the user wishes to sign out a device session other than it's own then the client **must**: - link the user to the `account_management_uri` given by [MSC4191] if provided @@ -108,7 +110,7 @@ For an OIDC enabled homeserver to provide support for *OAuth 2.0 aware* clients - support the [OAuth 2.0 API] - provide an implementation of the `m.login.password` and `m.login.sso` - [authentication types](https://spec.matrix.org/v1.15/client-server-api/#authentication-types) from the Legacy API + [authentication types](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 `delegated_oidc_compatibility` to `true` - provides a value for the `action` param on the SSO redirect endpoints as defined above @@ -123,13 +125,13 @@ None. ## Alternatives Clients could assume that an `m.login.sso` is preferred directly from where the -[server metadata discovery](https://spec.matrix.org/v1.15/client-server-api/#server-metadata-discovery) indicates 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.15/client-server-api/#capabilities-negotiation) could be used to +[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 @@ -160,5 +162,5 @@ 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.15/client-server-api/#legacy-api) -[OAuth 2.0 API]: (https://spec.matrix.org/v1.15/client-server-api/#oauth-20-api) +[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) From 33cb64a5a8570fdfdebcd358acb88159c96ff23b Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 8 Oct 2025 13:07:28 +0100 Subject: [PATCH 31/37] Link to m.login.sso --- proposals/3824-oidc-aware-clients.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index 4f62431802a..f48aee8c3b0 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -10,11 +10,11 @@ In this context we can define four types of client: 1. *OAuth 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 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. + [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` flow from the [Legacy API]. e.g. Element Classic on iOS and Android + [`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 + 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. @@ -79,8 +79,8 @@ as that isn't used for registration. For a client to be considered fully *OAuth 2.0 aware* it **must**: -- support the `m.login.sso` auth flow -- where a `delegated_oidc_compatibility` value of `true` is present on an `m.login.sso` then *only* offer that auth flow +- support the [`m.login.sso`] auth flow +- where a `delegated_oidc_compatibility` 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 - link users to manage their account at the `account_management_uri` given by [MSC4191] instead of native UI @@ -109,9 +109,9 @@ Optionally, an *OAuth 2.0 aware* client **could**: For an OIDC enabled homeserver to provide support for *OAuth 2.0 aware* clients it **must**: - support the [OAuth 2.0 API] -- provide an implementation of the `m.login.password` and `m.login.sso` +- provide an implementation of the `m.login.password` and [`m.login.sso`] [authentication types](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 `delegated_oidc_compatibility` to `true` +- indicate that the [`m.login.sso`] is preferred by setting `delegated_oidc_compatibility` to `true` - provides a value for the `action` param on the SSO redirect endpoints as defined above Additionally, the homeserver **should**: @@ -124,15 +124,15 @@ None. ## Alternatives -Clients could assume that an `m.login.sso` is preferred directly from where the +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 +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. +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 @@ -164,3 +164,4 @@ been accepted into the spec: [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) From ce34bcccd482a165bd5085283def8b72e67b5008 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 8 Oct 2025 13:32:25 +0100 Subject: [PATCH 32/37] Attempt to clarify purpose/intent of MSC --- proposals/3824-oidc-aware-clients.md | 37 +++++++++++++++++----------- 1 file changed, 22 insertions(+), 15 deletions(-) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index f48aee8c3b0..974c4e3622c 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -5,7 +5,14 @@ As of spec 1.15 we now have two APIs for clients to authenticate: - the [Legacy API] - the [OAuth 2.0 API] -In this context we can define four types of client: +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 small 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 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 @@ -19,28 +26,27 @@ In this context we can define four types of client: 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. -This proposal outlines changes to facilitate clients in becoming [OAuth 2.0 API] aware. - ## 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 suppored, 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. -- The homeserver can optionally specify which auth type is `delegated_oidc_compatibility` are supported for an - authentication type. 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 for compatibility +### Homeserver indicates that an `m.login.sso` flow is preferred -Add an optional `delegated_oidc_compatibility` field to the response of +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): -`"delegated_oidc_compatibility"?: boolean` +- `"oauth_aware_preferred"?: boolean` For example, if a homeserver is advertising password login for legacy clients only then it could return the following: @@ -50,13 +56,13 @@ For example, if a homeserver is advertising password login for legacy clients on "type": "m.login.password" }, { "type": "m.login.sso", - "delegated_oidc_compatibility": true + "oauth_aware_preferred": true }] } ``` -If the client finds `delegated_oidc_compatibility` to be `true` then, assuming it supports that auth type, it should +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 @@ -80,7 +86,7 @@ as that isn't used for registration. For a client to be considered fully *OAuth 2.0 aware* it **must**: - support the [`m.login.sso`] auth flow -- where a `delegated_oidc_compatibility` value of `true` is present on an [`m.login.sso`] then *only* offer that auth flow +- 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 - link users to manage their account at the `account_management_uri` given by [MSC4191] instead of native UI @@ -110,8 +116,8 @@ For an OIDC enabled homeserver to provide support for *OAuth 2.0 aware* clients - support the [OAuth 2.0 API] - provide an implementation of the `m.login.password` and [`m.login.sso`] - [authentication types](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 `delegated_oidc_compatibility` to `true` + [authentication types](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` - provides a value for the `action` param on the SSO redirect endpoints as defined above Additionally, the homeserver **should**: @@ -120,7 +126,8 @@ Additionally, the homeserver **should**: ## Potential issues -None. +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 @@ -148,7 +155,7 @@ None relevant. 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 - `delegated_oidc_compatibility` + `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] From aa4c930ac4573b836fbad5621e06e65ea61309ce Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 8 Oct 2025 13:34:55 +0100 Subject: [PATCH 33/37] Fix links --- proposals/3824-oidc-aware-clients.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index 974c4e3622c..6470a2208fc 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -169,6 +169,6 @@ 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) +[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 From 44ccc6cb8b7eb4bff3c38472aa19598fd2acceef Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 8 Oct 2025 13:35:59 +0100 Subject: [PATCH 34/37] Spelling --- proposals/3824-oidc-aware-clients.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index 6470a2208fc..e0ffc533a5a 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -32,7 +32,7 @@ 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 suppored, that a specific [`m.login.sso`] auth type is preferred. + 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. From 761252b5d941a11a7a79a8e563671ee4cf886d4f Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 8 Oct 2025 13:46:32 +0100 Subject: [PATCH 35/37] Clarify that server discovery is needed + that the whole thing is optional --- proposals/3824-oidc-aware-clients.md | 51 ++++++++++++++++------------ 1 file changed, 29 insertions(+), 22 deletions(-) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index e0ffc533a5a..dd93625ddb8 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -8,15 +8,15 @@ As of spec 1.15 we now have two APIs for clients to authenticate: 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 small 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 +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 native client* - This is a client that, where the homeserver supports it, uses the [OAuth 2.0 API] for login +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 aware client* - This is a client that is "aware" (see below) of the [OAuth 2.0 API] but will still uses the +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 @@ -26,6 +26,9 @@ In this context it is helpful to distinguish four types of client: 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]: @@ -85,37 +88,41 @@ as that isn't used for registration. For a client to be considered fully *OAuth 2.0 aware* it **must**: -- support the [`m.login.sso`] auth flow +- 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 -- 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 - 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 when the server has the OAuth 2.0 API enabled -- if the user wishes to sign out a device session other than it's 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]. + 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 it's 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". This is because after redirect the server may then offer a - password and/or further upstream IdPs +- 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 an OIDC enabled homeserver to provide support for *OAuth 2.0 aware* clients it **must**: +For an 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.password` and [`m.login.sso`] +- provide an implementation of the `m.login.password` and [`m.login.sso`] [authentication types](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` - provides a value for the `action` param on the SSO redirect endpoints as defined above @@ -141,7 +148,7 @@ 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 +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. From 42ebdbbf45c88652401881d36df3c0877e337956 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 8 Oct 2025 13:52:30 +0100 Subject: [PATCH 36/37] Clarify that m.login.password is only required where homeserver previously supported it --- proposals/3824-oidc-aware-clients.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index dd93625ddb8..31124f38f66 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -122,8 +122,10 @@ Optionally, an *OAuth 2.0 aware* client **could**: For an 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.password` and [`m.login.sso`] - [authentication types](https://spec.matrix.org/v1.16/client-server-api/#authentication-types) from the [Legacy 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` - provides a value for the `action` param on the SSO redirect endpoints as defined above From 85a70c45012a4cdb9e71c0869f9abff4d340127d Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 15 Oct 2025 08:40:15 +0100 Subject: [PATCH 37/37] Apply suggestions from code review Co-authored-by: Hubert Chathi --- proposals/3824-oidc-aware-clients.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/3824-oidc-aware-clients.md b/proposals/3824-oidc-aware-clients.md index 31124f38f66..9c4886ef4a2 100644 --- a/proposals/3824-oidc-aware-clients.md +++ b/proposals/3824-oidc-aware-clients.md @@ -102,7 +102,7 @@ For a client to be considered fully *OAuth 2.0 aware* it **must**: - 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 it's own then the client **must**: + - 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) @@ -119,7 +119,7 @@ Optionally, an *OAuth 2.0 aware* client **could**: [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 an homeserver using [OAuth 2.0 API] to provide support for *OAuth 2.0 aware* clients it **must**: +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`] @@ -127,7 +127,7 @@ For an homeserver using [OAuth 2.0 API] to provide support for *OAuth 2.0 aware* - 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` -- provides a value for the `action` param on the SSO redirect endpoints as defined above +- provide a value for the `action` param on the SSO redirect endpoints as defined above Additionally, the homeserver **should**: