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/17] 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/17] 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/17] 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/17] 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/17] 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/17] 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/17] 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/17] 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/17] 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/17] 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/17] 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/17] 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/17] 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/17] 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/17] 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/17] 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/17] 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**: