From ef474ee343f6b16dd25ca316c6494c19920cdda8 Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Thu, 14 Jan 2021 18:11:16 +0100 Subject: [PATCH 01/34] OIDC discovery MSC --- proposals/2965-oidc-discovery.md | 123 +++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 proposals/2965-oidc-discovery.md diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md new file mode 100644 index 00000000000..81ce2b019da --- /dev/null +++ b/proposals/2965-oidc-discovery.md @@ -0,0 +1,123 @@ +# MSC2965: OIDC Provider discovery + +To be able to initiate an OAuth 2.0 login flow to use a Matrix server, the client needs to know the location of the authentication server in use. + +## Proposal + +Clients already discover the homeserver when doing a server discovery via the well-known document. +A new field is added to this document to discover what the issuer is trusted by the homeserver. + +``` +GET /.well-known/matrix/client +Host: example.com +Accept: application/json +``` + +``` +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +{ + "m.homeserver": { + "base_url": "https://matrix-client.example.com" + }, + "m.identity_server": { + "base_url": "https://identity.example.com" + }, + "m.authentication": { + "issuer": "https://account.example.com" + } +} +``` + +The authentication server metadata can then be discovered by the client using [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html). + +``` +GET /.well-known/openid-configuration +Host: account.example.com +Accept: application/json +``` + +``` +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +{ + "issuer": "https://account.example.com/", + "authorization_endpoint": "https://account.example.com/oauth2/auth", + "token_endpoint": "https://account.example.com/oauth2/token", + "registration_endpoint": "https://account.example.com/oauth2/clients/register", + "end_session_edntpoint": "https://account.example.com/oauth2/logout", + "jwks_uri": "https://account.example.com/.well-known/jwks.json", + "response_types_supported": ["code"], + "grant_types_sypported": ["authorization_code", "refresh_token"], + "response_mode_sypported": ["query", "fragment"], + "//": "some fields omitted" +} +``` + +## Potential issues + +Not all Matrix servers have the well-known client discovery mechanism setup. +Unlike the identity server, the authentication server is necessary to login against a Matrix server. +Being unable to discover the authorization server from the Matrix Client API might be an issue in some cases. + +## Alternatives + +The authorization server discovery could be done by other mechanisms. + +### Discovery via a new client API endpoint + +The Matrix Client API could have a new endpoint to discover the issuer, e.g. `/_matrix/client/r0/auth_issuer`. + +### Discovery via the `m.login.oauth2` authentication method + +The spec already defines a `m.login.oauth2` authentication method, but it was never implemented. +The downside of this approach is that the plan is to deprecate the old login mechanism and it does not make sense to keep it just to discover the issuer. + +### Discovery via WebFinger + +OIDC already has a standard way to discover OP from an identifier: WebFinger. This is already adopted by Mastodon, and might help solving logging in via 3PIDs like emails. + +Sample exchange: + +``` +GET /.well-known/webfinger? + resource= mxid:@john:example.com & + rel= http://openid.net/specs/connect/1.0/issuer +Host: example.com +``` + +```json +{ + "subject": "mxid:@john:matrix.org", + "links": [ + { + "rel": "http://openid.net/specs/connect/1.0/issuer", + "href": "https://account.example.com" + } + ] +} +``` + +The `mxid` scheme is a bit arbitrary here. +The parameters in the URL should be percent-encoded, this was left unencoded for clarity. + +The benefits of this approach are that it is standard and decouples the authentication server from the Matrix server: different authentication servers could be used by accounts on the server. + +The downsides of this approach are: + +- the `.well-known` resource is dynamic, which can be harder to host/delegate & might conflict with other services like Mastodon +- this does not cover discovering the authentication server for user registration + +## Security considerations + +None relevant. + +## Unstable prefix + +While this MSC is not in a released version of the specification, clients should use the `org.matrix.msc2965.authentication` field in the client well-known discovery document instead of `m.authentication`. From 4d9345cd001705b5000e307f198e578526a959d7 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Mon, 2 May 2022 15:09:56 -0400 Subject: [PATCH 02/34] Add `account` field --- proposals/2965-oidc-discovery.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index 81ce2b019da..e2fd35540c7 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -27,12 +27,13 @@ Content-Type: application/json "base_url": "https://identity.example.com" }, "m.authentication": { - "issuer": "https://account.example.com" + "issuer": "https://account.example.com", + "account": "https://account.example.com/myaccount" } } ``` -The authentication server metadata can then be discovered by the client using [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html). +The authentication server metadata can then be discovered by the client using [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) against the `issuer` field. ``` GET /.well-known/openid-configuration @@ -60,6 +61,8 @@ Content-Type: application/json } ``` +The optional `account` field specifies the URL where the user is able to access the account management capabilities of the issuer. + ## Potential issues Not all Matrix servers have the well-known client discovery mechanism setup. From 4a24cf61da02615cb5ad12f929ebfec9107ad7d9 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Fri, 6 May 2022 14:28:49 -0400 Subject: [PATCH 03/34] Add id_token_hint to account management URL --- proposals/2965-oidc-discovery.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index e2fd35540c7..e00b3817cd7 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -5,7 +5,13 @@ To be able to initiate an OAuth 2.0 login flow to use a Matrix server, the clien ## Proposal Clients already discover the homeserver when doing a server discovery via the well-known document. -A new field is added to this document to discover what the issuer is trusted by the homeserver. + +Two new fields are added to this document to support OIDC Provider discovery: + +- REQUIRED `issuer` - the OIDC Provider that is trusted by the homeserver +- OPTIONAL `account` - the URL where the user is able to access the account management capabilities of the OIDC Provider + +For example: ``` GET /.well-known/matrix/client @@ -61,7 +67,10 @@ Content-Type: application/json } ``` -The optional `account` field specifies the URL where the user is able to access the account management capabilities of the issuer. +The account management URL may accept the following additional query parameters: + +- RECOMMENDED `id_token_hint` - ID Token (as previously issued by the issuer to the client) as a hint about the current authenticated user that is requesting to be able to manage their account. This may be used by the issuer to: if not logged in then used as a login hint; if already logged in, but for a different user/identity then warn the user that they are accessing account. + ## Potential issues @@ -117,6 +126,10 @@ The downsides of this approach are: - the `.well-known` resource is dynamic, which can be harder to host/delegate & might conflict with other services like Mastodon - this does not cover discovering the authentication server for user registration +### + +There is no standard in OIDC for the `account` field. If one was to be standardised in future then it would make sense to use that instead. + ## Security considerations None relevant. From f5b54bf79df4df0e1aee1f3cdf8fec66fcb6f7b6 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Fri, 5 Aug 2022 09:43:56 +0100 Subject: [PATCH 04/34] Add reference to MSC3861 --- proposals/2965-oidc-discovery.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index e00b3817cd7..02788b80137 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -1,5 +1,7 @@ # MSC2965: OIDC Provider discovery +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). + To be able to initiate an OAuth 2.0 login flow to use a Matrix server, the client needs to know the location of the authentication server in use. ## Proposal From 1cc49762c3b899ca5e46219a9fcfd1ccbcc2ac92 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Thu, 22 Sep 2022 17:07:56 +0100 Subject: [PATCH 05/34] Add missing heading --- proposals/2965-oidc-discovery.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index 02788b80137..87382e2b111 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -128,7 +128,7 @@ The downsides of this approach are: - the `.well-known` resource is dynamic, which can be harder to host/delegate & might conflict with other services like Mastodon - this does not cover discovering the authentication server for user registration -### +### Account management URL There is no standard in OIDC for the `account` field. If one was to be standardised in future then it would make sense to use that instead. From 6455b1fa5939a0903753225387f5c6a856371f83 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 8 Feb 2023 17:52:54 +0000 Subject: [PATCH 06/34] Fix reference to MSC3861 --- proposals/2965-oidc-discovery.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index 87382e2b111..7957bf6ca72 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -1,6 +1,6 @@ # MSC2965: OIDC Provider discovery -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). +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/3861). To be able to initiate an OAuth 2.0 login flow to use a Matrix server, the client needs to know the location of the authentication server in use. From 2a242bb75cb3f25e86bfede83b8bd5697dddf00a Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Mon, 21 Aug 2023 05:52:29 -0400 Subject: [PATCH 07/34] Update proposals/2965-oidc-discovery.md Co-authored-by: Patrick Cloke --- proposals/2965-oidc-discovery.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index 7957bf6ca72..98a74f68836 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -8,7 +8,8 @@ To be able to initiate an OAuth 2.0 login flow to use a Matrix server, the clien Clients already discover the homeserver when doing a server discovery via the well-known document. -Two new fields are added to this document to support OIDC Provider discovery: +A new `m.authentication` field is added to this document to support OIDC Provider discovery. +It is an object containing two fields: - REQUIRED `issuer` - the OIDC Provider that is trusted by the homeserver - OPTIONAL `account` - the URL where the user is able to access the account management capabilities of the OIDC Provider From ae920ad405fba3a6ac0047c64338a164fc53fbf2 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Mon, 21 Aug 2023 05:52:59 -0400 Subject: [PATCH 08/34] Fix typo --- proposals/2965-oidc-discovery.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index 98a74f68836..d862c79d616 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -61,7 +61,7 @@ Content-Type: application/json "authorization_endpoint": "https://account.example.com/oauth2/auth", "token_endpoint": "https://account.example.com/oauth2/token", "registration_endpoint": "https://account.example.com/oauth2/clients/register", - "end_session_edntpoint": "https://account.example.com/oauth2/logout", + "end_session_endpoint": "https://account.example.com/oauth2/logout", "jwks_uri": "https://account.example.com/.well-known/jwks.json", "response_types_supported": ["code"], "grant_types_sypported": ["authorization_code", "refresh_token"], From d9d56f33426fe9070613e93b7242123c09f10eb6 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Mon, 21 Aug 2023 05:54:49 -0400 Subject: [PATCH 09/34] Update 2965-oidc-discovery.md --- proposals/2965-oidc-discovery.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index d862c79d616..17abb9964b4 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -55,7 +55,7 @@ HTTP/1.1 200 OK Content-Type: application/json ``` -```json +```json5 { "issuer": "https://account.example.com/", "authorization_endpoint": "https://account.example.com/oauth2/auth", @@ -65,8 +65,8 @@ Content-Type: application/json "jwks_uri": "https://account.example.com/.well-known/jwks.json", "response_types_supported": ["code"], "grant_types_sypported": ["authorization_code", "refresh_token"], - "response_mode_sypported": ["query", "fragment"], - "//": "some fields omitted" + "response_mode_sypported": ["query", "fragment"] + // some fields omitted } ``` From 74b29e0c53e597d60e32ead2c0ef6d6a3f1676bd Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Mon, 21 Aug 2023 05:55:34 -0400 Subject: [PATCH 10/34] Update proposals/2965-oidc-discovery.md Co-authored-by: Patrick Cloke --- proposals/2965-oidc-discovery.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index 17abb9964b4..95c8df4119b 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -122,7 +122,7 @@ Host: example.com The `mxid` scheme is a bit arbitrary here. The parameters in the URL should be percent-encoded, this was left unencoded for clarity. -The benefits of this approach are that it is standard and decouples the authentication server from the Matrix server: different authentication servers could be used by accounts on the server. +The benefits of this approach are that it is standard and decouples the authentication server from the Matrix server: different authentication servers could be used by different accounts on the server. The downsides of this approach are: From 610c22cdcf8de13dbac470b1f28bd4f59a3cec90 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Mon, 21 Aug 2023 05:55:59 -0400 Subject: [PATCH 11/34] Update proposals/2965-oidc-discovery.md Co-authored-by: Patrick Cloke --- proposals/2965-oidc-discovery.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index 95c8df4119b..2a6063acb21 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -72,7 +72,7 @@ Content-Type: application/json The account management URL may accept the following additional query parameters: -- RECOMMENDED `id_token_hint` - ID Token (as previously issued by the issuer to the client) as a hint about the current authenticated user that is requesting to be able to manage their account. This may be used by the issuer to: if not logged in then used as a login hint; if already logged in, but for a different user/identity then warn the user that they are accessing account. +- RECOMMENDED `id_token_hint` - An ID Token that was previously issued to the client; the issuer uses it as a hint for which user is requesting to manage their account. If the requesting user is not logged in then it is used as a login hint; if a different user/identity is already logged in then warn the user that they are accessing a different account. ## Potential issues From eed9e607629717e2a2428ef78455f7a25b8a7228 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Mon, 21 Aug 2023 05:57:37 -0400 Subject: [PATCH 12/34] OIDC Provider -> OpenID Provider --- proposals/2965-oidc-discovery.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index 2a6063acb21..d1bc543c3f6 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -8,11 +8,11 @@ To be able to initiate an OAuth 2.0 login flow to use a Matrix server, the clien Clients already discover the homeserver when doing a server discovery via the well-known document. -A new `m.authentication` field is added to this document to support OIDC Provider discovery. +A new `m.authentication` field is added to this document to support OpenID Provider (OP) discovery. It is an object containing two fields: -- REQUIRED `issuer` - the OIDC Provider that is trusted by the homeserver -- OPTIONAL `account` - the URL where the user is able to access the account management capabilities of the OIDC Provider +- REQUIRED `issuer` - the OpenID Provider that is trusted by the homeserver +- OPTIONAL `account` - the URL where the user is able to access the account management capabilities of the OpenID Provider For example: From fdcde60a3d904d2ee251e8addb5098e81353a6e5 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Mon, 21 Aug 2023 06:15:16 -0400 Subject: [PATCH 13/34] Define account management URL params --- proposals/2965-oidc-discovery.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index d1bc543c3f6..e206f042a04 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -16,13 +16,13 @@ It is an object containing two fields: For example: -``` +```http GET /.well-known/matrix/client Host: example.com Accept: application/json ``` -``` +```http HTTP/1.1 200 OK Content-Type: application/json ``` @@ -44,13 +44,13 @@ Content-Type: application/json The authentication server metadata can then be discovered by the client using [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) against the `issuer` field. -``` +```http GET /.well-known/openid-configuration Host: account.example.com Accept: application/json ``` -``` +```http HTTP/1.1 200 OK Content-Type: application/json ``` @@ -72,8 +72,15 @@ Content-Type: application/json The account management URL may accept the following additional query parameters: -- RECOMMENDED `id_token_hint` - An ID Token that was previously issued to the client; the issuer uses it as a hint for which user is requesting to manage their account. If the requesting user is not logged in then it is used as a login hint; if a different user/identity is already logged in then warn the user that they are accessing a different account. +- `id_token_hint` - An ID Token that was previously issued to the client; the issuer uses it as a hint for which user is requesting to manage their account. If the requesting user is not logged in then it is used as a login hint; if a different user/identity is already logged in then warn the user that they are accessing a different account. +- `action` - Can be used to indicate the action that the user wishes to take: + - `profile` - The user wishes to view their profile (name, avatar, contact details). + - `sessions_list` - The user wishes to view a list of their sessions. + - `session_view` - The user wishes to view the details of a session. + - `session_end` - The user wishes to end/logout a session. +- `device_id` - This can be used to identify a particular session for `session_view` and `session_end`. This is the Matrix device ID. +For example, if a user wishes to sign out a session for the device `ABCDEFGH` where the advertised account management URL was `https://account.example.com/myaccount` the client could open a link to `https://account.example.com/myaccount?action=session_end&device_id=ABCDEFGH`. ## Potential issues From c0b256536fd4a8d86927397438e4a8ff1af3178b Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Mon, 21 Aug 2023 06:16:13 -0400 Subject: [PATCH 14/34] Link for account management URLs --- proposals/2965-oidc-discovery.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index e206f042a04..974153a6d9f 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -70,6 +70,8 @@ Content-Type: application/json } ``` +### Account management URL parameters + The account management URL may accept the following additional query parameters: - `id_token_hint` - An ID Token that was previously issued to the client; the issuer uses it as a hint for which user is requesting to manage their account. If the requesting user is not logged in then it is used as a login hint; if a different user/identity is already logged in then warn the user that they are accessing a different account. From e9e3ee19be70327fde44154b021b667a5250b622 Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Wed, 29 Nov 2023 12:13:50 +0100 Subject: [PATCH 15/34] MSC2965: move from well-known discovery to a dedicated C-S endpoint --- proposals/2965-oidc-discovery.md | 110 +++++++++++++++++++++++-------- 1 file changed, 81 insertions(+), 29 deletions(-) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index 974153a6d9f..d2305acd127 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -6,18 +6,26 @@ To be able to initiate an OAuth 2.0 login flow to use a Matrix server, the clien ## Proposal -Clients already discover the homeserver when doing a server discovery via the well-known document. +This introduces a new Client-Server API endpoint to discover the authentication server used by the homeserver. -A new `m.authentication` field is added to this document to support OpenID Provider (OP) discovery. -It is an object containing two fields: -- REQUIRED `issuer` - the OpenID Provider that is trusted by the homeserver -- OPTIONAL `account` - the URL where the user is able to access the account management capabilities of the OpenID Provider +### `GET /auth_issuer` + +A request on this endpoint should return a JSON object with the following fields: + + - *REQUIRED* `issuer`: the OpenID Connect Provider that is trusted by the homeserver + - *OPTIONAL* `account`: an object describing the account management capabilities of the OpenID Connect Provider, with the following fields: + - `uri`: the absolute URI where the user is able to access the account management capabilities of the OpenID Connect Provider + - `actions_supported`: a list of well-known actions supported by the account management URL. The following actions are defined: + - `profile`: the user wishes to view their profile (name, avatar, contact details). + - `sessions_list`: the user wishes to view a list of their sessions. + - `session_view`: the user wishes to view the details of a session. + - `session_end`: the user wishes to end/logout a session. For example: ```http -GET /.well-known/matrix/client +GET /_matrix/client/v3/auth_issuer Host: example.com Accept: application/json ``` @@ -29,20 +37,15 @@ Content-Type: application/json ```json { - "m.homeserver": { - "base_url": "https://matrix-client.example.com" - }, - "m.identity_server": { - "base_url": "https://identity.example.com" - }, - "m.authentication": { - "issuer": "https://account.example.com", - "account": "https://account.example.com/myaccount" - } + "issuer": "https://account.example.com/", + "account": { + "uri": "https://account.example.com/myaccount", + "actions_supported": ["profile", "sessions_list", "session_view", "session_end"] + } } ``` -The authentication server metadata can then be discovered by the client using [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) against the `issuer` field. +The Matrix client can then discover the OpenID Connect Provider configuration by using [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html). ```http GET /.well-known/openid-configuration @@ -62,7 +65,7 @@ Content-Type: application/json "token_endpoint": "https://account.example.com/oauth2/token", "registration_endpoint": "https://account.example.com/oauth2/clients/register", "end_session_endpoint": "https://account.example.com/oauth2/logout", - "jwks_uri": "https://account.example.com/.well-known/jwks.json", + "jwks_uri": "https://account.example.com/oauth2/keys", "response_types_supported": ["code"], "grant_types_sypported": ["authorization_code", "refresh_token"], "response_mode_sypported": ["query", "fragment"] @@ -74,7 +77,8 @@ Content-Type: application/json The account management URL may accept the following additional query parameters: -- `id_token_hint` - An ID Token that was previously issued to the client; the issuer uses it as a hint for which user is requesting to manage their account. If the requesting user is not logged in then it is used as a login hint; if a different user/identity is already logged in then warn the user that they are accessing a different account. +- `id_token_hint` - An ID Token that was previously issued to the client; the issuer uses it as a hint for which user is requesting to manage their account. + If the requesting user is not logged in then it is used as a login hint; if a different user/identity is already logged in then warn the user that they are accessing a different account. - `action` - Can be used to indicate the action that the user wishes to take: - `profile` - The user wishes to view their profile (name, avatar, contact details). - `sessions_list` - The user wishes to view a list of their sessions. @@ -84,19 +88,63 @@ The account management URL may accept the following additional query parameters: For example, if a user wishes to sign out a session for the device `ABCDEFGH` where the advertised account management URL was `https://account.example.com/myaccount` the client could open a link to `https://account.example.com/myaccount?action=session_end&device_id=ABCDEFGH`. +Not all actions need to be supported by the account management URL, and the client should only use the actions advertised in the `actions_supported` field. + ## Potential issues -Not all Matrix servers have the well-known client discovery mechanism setup. -Unlike the identity server, the authentication server is necessary to login against a Matrix server. -Being unable to discover the authorization server from the Matrix Client API might be an issue in some cases. +Using a separate endpoint for discovery makes the request chain to initiate a login flow longer. +A full discovery flow would be as follows: + + - `GET [domain]/.well-known/matrix/client` to discover the homeserver + - `GET [homeserver]/_matrix/client/v3/auth_issuer` to discover the issuer + - `GET [issuer]/.well-known/openid-configuration` to discover the OpenID Connect Provider configuration + - `POST [issuer client registration endpoint]` to register the OAuth 2.0 client + (see [MSC2966](https://github.com/matrix-org/matrix-spec-proposals/pull/2966)) + - Redirect to `[issuer authorization endpoint]` to initiate the login flow ## Alternatives -The authorization server discovery could be done by other mechanisms. +The authentication server discovery could be done by other mechanisms. + +### Discovery via the well-known client discovery + +A previous version of this proposal suggested using the well-known client discovery mechanism to discover the authentication server. +Clients already discover the homeserver when doing a server discovery via the well-known document. + +A new `m.authentication` field is added to this document to support OpenID Connect Provider (OP) discovery. +It is an object containing two fields: + +- REQUIRED `issuer` - the OpenID Connect Provider that is trusted by the homeserver +- OPTIONAL `account` - the URL where the user is able to access the account management capabilities of the OpenID Connect Provider + +For example: -### Discovery via a new client API endpoint +```http +GET /.well-known/matrix/client +Host: example.com +Accept: application/json +``` + +```http +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +{ + "m.homeserver": { + "base_url": "https://matrix-client.example.com" + }, + "m.identity_server": { + "base_url": "https://identity.example.com" + }, + "m.authentication": { + "issuer": "https://account.example.com", + "account": "https://account.example.com/myaccount" + } +} +``` -The Matrix Client API could have a new endpoint to discover the issuer, e.g. `/_matrix/client/r0/auth_issuer`. ### Discovery via the `m.login.oauth2` authentication method @@ -105,7 +153,8 @@ The downside of this approach is that the plan is to deprecate the old login mec ### Discovery via WebFinger -OIDC already has a standard way to discover OP from an identifier: WebFinger. This is already adopted by Mastodon, and might help solving logging in via 3PIDs like emails. +OIDC already has a standard way to discover OP from an identifier: WebFinger. +This is already adopted by Mastodon, and might help solve logging in via 3PIDs like emails. Sample exchange: @@ -131,7 +180,8 @@ Host: example.com The `mxid` scheme is a bit arbitrary here. The parameters in the URL should be percent-encoded, this was left unencoded for clarity. -The benefits of this approach are that it is standard and decouples the authentication server from the Matrix server: different authentication servers could be used by different accounts on the server. +The benefits of this approach are that it is standard and decouples the authentication server from the Matrix server: +different authentication servers could be used by different accounts on the server. The downsides of this approach are: @@ -140,7 +190,7 @@ The downsides of this approach are: ### Account management URL -There is no standard in OIDC for the `account` field. If one was to be standardised in future then it would make sense to use that instead. +There is no standard in OIDC for the `account` field. If one was to be standardised in the future then it would make sense to use that instead. ## Security considerations @@ -148,4 +198,6 @@ None relevant. ## Unstable prefix -While this MSC is not in a released version of the specification, clients should use the `org.matrix.msc2965.authentication` field in the client well-known discovery document instead of `m.authentication`. +While this MSC is not in a released version of the specification, +clients should use the `org.matrix.msc2965` unstable prefix for the endpoint, +e.g. `GET /_matrix/client/unstable/org.matrix.msc2965/auth_issuer`. From a36c44aca03a421384a89bc6e77075097205d56c Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Thu, 30 Nov 2023 11:45:13 +0100 Subject: [PATCH 16/34] MSC2965: add a note about why the well-known alternative has been discarded --- proposals/2965-oidc-discovery.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index d2305acd127..fb2dcb0cb4a 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -145,6 +145,10 @@ Content-Type: application/json } ``` +This proposal, although implemented in some clients and in Synapse, has the downside of making the well-known discovery mandatory. +When implemented in clients, in many circumstances it was hard to go back and use well-known discovery, as they may already know the homeserver URL. +Since the authentication server is always tightly coupled to the homeserver (as opposed to the identity server), it makes sense to discover it via a Client-Server API endpoint. + ### Discovery via the `m.login.oauth2` authentication method From 7642a60b28eb43d0d2086845e532738623e135e0 Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Tue, 5 Dec 2023 11:54:14 +0100 Subject: [PATCH 17/34] MSC2965: move the account management URL to the provider metadata --- proposals/2965-oidc-discovery.md | 76 +++++++++++++++++++------------- 1 file changed, 46 insertions(+), 30 deletions(-) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index fb2dcb0cb4a..7b264578270 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -7,20 +7,13 @@ To be able to initiate an OAuth 2.0 login flow to use a Matrix server, the clien ## Proposal This introduces a new Client-Server API endpoint to discover the authentication server used by the homeserver. - +It also introduces new OpenID Connect Provider metadata to allow clients to deep-link to the account management capabilities of the authentication server. ### `GET /auth_issuer` -A request on this endpoint should return a JSON object with the following fields: +A request on this endpoint should return a JSON object with one field: - - *REQUIRED* `issuer`: the OpenID Connect Provider that is trusted by the homeserver - - *OPTIONAL* `account`: an object describing the account management capabilities of the OpenID Connect Provider, with the following fields: - - `uri`: the absolute URI where the user is able to access the account management capabilities of the OpenID Connect Provider - - `actions_supported`: a list of well-known actions supported by the account management URL. The following actions are defined: - - `profile`: the user wishes to view their profile (name, avatar, contact details). - - `sessions_list`: the user wishes to view a list of their sessions. - - `session_view`: the user wishes to view the details of a session. - - `session_end`: the user wishes to end/logout a session. +- _REQUIRED_ `issuer`: the OpenID Connect Provider that is trusted by the homeserver For example: @@ -37,11 +30,7 @@ Content-Type: application/json ```json { - "issuer": "https://account.example.com/", - "account": { - "uri": "https://account.example.com/myaccount", - "actions_supported": ["profile", "sessions_list", "session_view", "session_end"] - } + "issuer": "https://account.example.com/" } ``` @@ -68,39 +57,65 @@ Content-Type: application/json "jwks_uri": "https://account.example.com/oauth2/keys", "response_types_supported": ["code"], "grant_types_sypported": ["authorization_code", "refresh_token"], - "response_mode_sypported": ["query", "fragment"] + "response_mode_sypported": ["query", "fragment"], + "account_management_uri": "https://account.example.com/myaccount", + "account_management_actions_supported": ["org.matrix.profile", "org.matrix.sessions_list", "org.matrix.session_view", "org.matrix.session_end"], // some fields omitted } ``` -### Account management URL parameters +### Account management deep-linking + +This also adds the capability to deep-link to the account management capabilities of the authentication server. +To do so, OpenID Connect Providers advertise a URL where the user is able to access the account management capabilities of the OpenID Connect Provider, as well as a list of actions that the URL supports. +The client can then redirect their user to this URL to perform account management actions. + +#### Possible actions + +The following actions are defined by this MSC: + +- `org.matrix.profile` - The user wishes to view their profile (name, avatar, contact details). +- `org.matrix.sessions_list` - The user wishes to view a list of their sessions. +- `org.matrix.session_view` - The user wishes to view the details of a specific session. +- `org.matrix.session_end` - The user wishes to end/logout a specific session. +- `org.matrix.account_deactivate` - The user wishes to deactivate their account. + +Subsequent MSCs may extend this list. + +#### OpenID Connect Provider metadata + +In the OpenID Connect Provider metadata, the following fields are added: + +- `account_management_uri`: the URL where the user is able to access the account management capabilities of the OpenID Connect Provider +- `account_management_actions_supported`: a JSON array of actions that the account management URL supports + +Note that the intent of this proposal is to potentially end up in a standard OpenID Connect specifications, or at least formally registered in the [IANA Registry for Server Metadata](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#authorization-server-metadata). +This is why the metadata fields are not prefixed with `org.matrix.`, as this proposal can make sense outside of Matrix, but the actions themselves are. + +#### Account management URL parameters The account management URL may accept the following additional query parameters: - `id_token_hint` - An ID Token that was previously issued to the client; the issuer uses it as a hint for which user is requesting to manage their account. If the requesting user is not logged in then it is used as a login hint; if a different user/identity is already logged in then warn the user that they are accessing a different account. -- `action` - Can be used to indicate the action that the user wishes to take: - - `profile` - The user wishes to view their profile (name, avatar, contact details). - - `sessions_list` - The user wishes to view a list of their sessions. - - `session_view` - The user wishes to view the details of a session. - - `session_end` - The user wishes to end/logout a session. +- `action` - Can be used to indicate the action that the user wishes to take, as defined above. - `device_id` - This can be used to identify a particular session for `session_view` and `session_end`. This is the Matrix device ID. -For example, if a user wishes to sign out a session for the device `ABCDEFGH` where the advertised account management URL was `https://account.example.com/myaccount` the client could open a link to `https://account.example.com/myaccount?action=session_end&device_id=ABCDEFGH`. +For example, if a user wishes to sign out a session for the device `ABCDEFGH` where the advertised account management URL was `https://account.example.com/myaccount` the client could open a link to `https://account.example.com/myaccount?action=org.matrix.session_end&device_id=ABCDEFGH`. -Not all actions need to be supported by the account management URL, and the client should only use the actions advertised in the `actions_supported` field. +Not all actions need to be supported by the account management URL, and the client should only use the actions advertised in the `account_management_actions_supported` server metadata field. ## Potential issues Using a separate endpoint for discovery makes the request chain to initiate a login flow longer. A full discovery flow would be as follows: - - `GET [domain]/.well-known/matrix/client` to discover the homeserver - - `GET [homeserver]/_matrix/client/v3/auth_issuer` to discover the issuer - - `GET [issuer]/.well-known/openid-configuration` to discover the OpenID Connect Provider configuration - - `POST [issuer client registration endpoint]` to register the OAuth 2.0 client - (see [MSC2966](https://github.com/matrix-org/matrix-spec-proposals/pull/2966)) - - Redirect to `[issuer authorization endpoint]` to initiate the login flow +- `GET [domain]/.well-known/matrix/client` to discover the homeserver +- `GET [homeserver]/_matrix/client/v3/auth_issuer` to discover the issuer +- `GET [issuer]/.well-known/openid-configuration` to discover the OpenID Connect Provider configuration +- `POST [issuer client registration endpoint]` to register the OAuth 2.0 client + (see [MSC2966](https://github.com/matrix-org/matrix-spec-proposals/pull/2966)) +- Redirect to `[issuer authorization endpoint]` to initiate the login flow ## Alternatives @@ -149,6 +164,7 @@ This proposal, although implemented in some clients and in Synapse, has the down When implemented in clients, in many circumstances it was hard to go back and use well-known discovery, as they may already know the homeserver URL. Since the authentication server is always tightly coupled to the homeserver (as opposed to the identity server), it makes sense to discover it via a Client-Server API endpoint. +The account management URL was also part of this proposal, but it was moved to the OpenID Connect Provider metadata because it makes more sense for the provider to advertise it, and not the homeserver. ### Discovery via the `m.login.oauth2` authentication method From a0218df7175ebc3e043b6c97624f481e45ab7773 Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Tue, 5 Dec 2023 11:55:47 +0100 Subject: [PATCH 18/34] MSC2965: line breaks --- proposals/2965-oidc-discovery.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index 7b264578270..614360ab3da 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -59,7 +59,8 @@ Content-Type: application/json "grant_types_sypported": ["authorization_code", "refresh_token"], "response_mode_sypported": ["query", "fragment"], "account_management_uri": "https://account.example.com/myaccount", - "account_management_actions_supported": ["org.matrix.profile", "org.matrix.sessions_list", "org.matrix.session_view", "org.matrix.session_end"], + "account_management_actions_supported": ["org.matrix.profile", "org.matrix.sessions_list", + "org.matrix.session_view", "org.matrix.session_end"], // some fields omitted } ``` From e8529632e61f93a471d6a53761e7a23c0fd615fa Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Tue, 5 Dec 2023 12:02:55 +0100 Subject: [PATCH 19/34] MSC2965: update note about the account endpoint metadata --- proposals/2965-oidc-discovery.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index 614360ab3da..34923835228 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -211,7 +211,8 @@ The downsides of this approach are: ### Account management URL -There is no standard in OIDC for the `account` field. If one was to be standardised in the future then it would make sense to use that instead. +There is no current OIDC standard for account management URLs. +If one gets defined, this proposal could be extended to use it instead of defining a new one. ## Security considerations From 1bb6dded296ff555bbd785eadad759e572070471 Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Wed, 21 Feb 2024 11:28:38 +0100 Subject: [PATCH 20/34] Move the /auth_issuer endpoint to the v1 prefix --- proposals/2965-oidc-discovery.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index 34923835228..731da669cdd 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -18,7 +18,7 @@ A request on this endpoint should return a JSON object with one field: For example: ```http -GET /_matrix/client/v3/auth_issuer +GET /_matrix/client/v1/auth_issuer Host: example.com Accept: application/json ``` @@ -112,7 +112,7 @@ Using a separate endpoint for discovery makes the request chain to initiate a lo A full discovery flow would be as follows: - `GET [domain]/.well-known/matrix/client` to discover the homeserver -- `GET [homeserver]/_matrix/client/v3/auth_issuer` to discover the issuer +- `GET [homeserver]/_matrix/client/v1/auth_issuer` to discover the issuer - `GET [issuer]/.well-known/openid-configuration` to discover the OpenID Connect Provider configuration - `POST [issuer client registration endpoint]` to register the OAuth 2.0 client (see [MSC2966](https://github.com/matrix-org/matrix-spec-proposals/pull/2966)) From e70cd3d13685c60588aad10e3c4096bffd257df5 Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Wed, 21 Feb 2024 11:32:24 +0100 Subject: [PATCH 21/34] Add the `org.matrix.cross_signing_reset` action --- proposals/2965-oidc-discovery.md | 1 + 1 file changed, 1 insertion(+) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index 731da669cdd..95a907f46e6 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -80,6 +80,7 @@ The following actions are defined by this MSC: - `org.matrix.session_view` - The user wishes to view the details of a specific session. - `org.matrix.session_end` - The user wishes to end/logout a specific session. - `org.matrix.account_deactivate` - The user wishes to deactivate their account. +- `org.matrix.cross_signing_reset` - The user wishes to reset their cross-signing keys. Subsequent MSCs may extend this list. From 754b290dc868fe8294076b09346d0bd45e4c5dbc Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Wed, 21 Feb 2024 14:47:43 +0100 Subject: [PATCH 22/34] Typo --- proposals/2965-oidc-discovery.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index 95a907f46e6..4710b571ad6 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -56,8 +56,8 @@ Content-Type: application/json "end_session_endpoint": "https://account.example.com/oauth2/logout", "jwks_uri": "https://account.example.com/oauth2/keys", "response_types_supported": ["code"], - "grant_types_sypported": ["authorization_code", "refresh_token"], - "response_mode_sypported": ["query", "fragment"], + "grant_types_supported": ["authorization_code", "refresh_token"], + "response_mode_supported": ["query", "fragment"], "account_management_uri": "https://account.example.com/myaccount", "account_management_actions_supported": ["org.matrix.profile", "org.matrix.sessions_list", "org.matrix.session_view", "org.matrix.session_end"], From 45e906313ca5a3dec8549e93f789878f6d45ddb2 Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Wed, 4 Sep 2024 18:33:42 +0200 Subject: [PATCH 23/34] Rename MSC --- proposals/2965-oidc-discovery.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index 4710b571ad6..dd4e607dcf9 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -1,6 +1,6 @@ -# MSC2965: OIDC Provider discovery +# MSC2965: Usage of OpenID Connect Discovery for authentication server metadata discovery -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/3861). +This proposal is part of the broader [MSC3861: Next-generation auth for Matrix, based on OAuth 2.0/OIDC](https://github.com/matrix-org/matrix-spec-proposals/pull/3861). To be able to initiate an OAuth 2.0 login flow to use a Matrix server, the client needs to know the location of the authentication server in use. From 27bb30868eb25b6b7aa8516b33d0e365b4eab32f Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Wed, 4 Sep 2024 18:34:01 +0200 Subject: [PATCH 24/34] Remove account-related URLs --- proposals/2965-oidc-discovery.md | 55 ++------------------------------ 1 file changed, 2 insertions(+), 53 deletions(-) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index dd4e607dcf9..230361688cc 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -7,7 +7,6 @@ To be able to initiate an OAuth 2.0 login flow to use a Matrix server, the clien ## Proposal This introduces a new Client-Server API endpoint to discover the authentication server used by the homeserver. -It also introduces new OpenID Connect Provider metadata to allow clients to deep-link to the account management capabilities of the authentication server. ### `GET /auth_issuer` @@ -47,7 +46,7 @@ HTTP/1.1 200 OK Content-Type: application/json ``` -```json5 +```json { "issuer": "https://account.example.com/", "authorization_endpoint": "https://account.example.com/oauth2/auth", @@ -58,55 +57,10 @@ Content-Type: application/json "response_types_supported": ["code"], "grant_types_supported": ["authorization_code", "refresh_token"], "response_mode_supported": ["query", "fragment"], - "account_management_uri": "https://account.example.com/myaccount", - "account_management_actions_supported": ["org.matrix.profile", "org.matrix.sessions_list", - "org.matrix.session_view", "org.matrix.session_end"], - // some fields omitted + "...": "some fields omitted" } ``` -### Account management deep-linking - -This also adds the capability to deep-link to the account management capabilities of the authentication server. -To do so, OpenID Connect Providers advertise a URL where the user is able to access the account management capabilities of the OpenID Connect Provider, as well as a list of actions that the URL supports. -The client can then redirect their user to this URL to perform account management actions. - -#### Possible actions - -The following actions are defined by this MSC: - -- `org.matrix.profile` - The user wishes to view their profile (name, avatar, contact details). -- `org.matrix.sessions_list` - The user wishes to view a list of their sessions. -- `org.matrix.session_view` - The user wishes to view the details of a specific session. -- `org.matrix.session_end` - The user wishes to end/logout a specific session. -- `org.matrix.account_deactivate` - The user wishes to deactivate their account. -- `org.matrix.cross_signing_reset` - The user wishes to reset their cross-signing keys. - -Subsequent MSCs may extend this list. - -#### OpenID Connect Provider metadata - -In the OpenID Connect Provider metadata, the following fields are added: - -- `account_management_uri`: the URL where the user is able to access the account management capabilities of the OpenID Connect Provider -- `account_management_actions_supported`: a JSON array of actions that the account management URL supports - -Note that the intent of this proposal is to potentially end up in a standard OpenID Connect specifications, or at least formally registered in the [IANA Registry for Server Metadata](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#authorization-server-metadata). -This is why the metadata fields are not prefixed with `org.matrix.`, as this proposal can make sense outside of Matrix, but the actions themselves are. - -#### Account management URL parameters - -The account management URL may accept the following additional query parameters: - -- `id_token_hint` - An ID Token that was previously issued to the client; the issuer uses it as a hint for which user is requesting to manage their account. - If the requesting user is not logged in then it is used as a login hint; if a different user/identity is already logged in then warn the user that they are accessing a different account. -- `action` - Can be used to indicate the action that the user wishes to take, as defined above. -- `device_id` - This can be used to identify a particular session for `session_view` and `session_end`. This is the Matrix device ID. - -For example, if a user wishes to sign out a session for the device `ABCDEFGH` where the advertised account management URL was `https://account.example.com/myaccount` the client could open a link to `https://account.example.com/myaccount?action=org.matrix.session_end&device_id=ABCDEFGH`. - -Not all actions need to be supported by the account management URL, and the client should only use the actions advertised in the `account_management_actions_supported` server metadata field. - ## Potential issues Using a separate endpoint for discovery makes the request chain to initiate a login flow longer. @@ -210,11 +164,6 @@ The downsides of this approach are: - the `.well-known` resource is dynamic, which can be harder to host/delegate & might conflict with other services like Mastodon - this does not cover discovering the authentication server for user registration -### Account management URL - -There is no current OIDC standard for account management URLs. -If one gets defined, this proposal could be extended to use it instead of defining a new one. - ## Security considerations None relevant. From acabca8e82ad812bf55ca2bcdaef5eeafb72203b Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Wed, 4 Sep 2024 18:34:33 +0200 Subject: [PATCH 25/34] Mention RFC8414 as alternative --- proposals/2965-oidc-discovery.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index 230361688cc..bba471ab8c4 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -77,6 +77,11 @@ A full discovery flow would be as follows: The authentication server discovery could be done by other mechanisms. +### Discovery via [RFC8414](https://tools.ietf.org/html/rfc8414) + +[RFC8414](https://tools.ietf.org/html/rfc8414): OAuth 2.0 Authorization Server Metadata is a standard similar to OpenID Connect Discovery. +The main differences is that the well-known endpoint is under `.well-known/oauth-authorization-server` and this standard is defined by the IETF and not the OpenID Foundation. + ### Discovery via the well-known client discovery A previous version of this proposal suggested using the well-known client discovery mechanism to discover the authentication server. From 61fc092df09d443659868752e1ab22b5b2baea01 Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Fri, 17 Jan 2025 10:32:46 +0100 Subject: [PATCH 26/34] Outline another alternative: publish the metadata through a C-S API --- proposals/2965-oidc-discovery.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index bba471ab8c4..5754511b9f3 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -80,7 +80,21 @@ The authentication server discovery could be done by other mechanisms. ### Discovery via [RFC8414](https://tools.ietf.org/html/rfc8414) [RFC8414](https://tools.ietf.org/html/rfc8414): OAuth 2.0 Authorization Server Metadata is a standard similar to OpenID Connect Discovery. -The main differences is that the well-known endpoint is under `.well-known/oauth-authorization-server` and this standard is defined by the IETF and not the OpenID Foundation. +The main difference is that the well-known endpoint is under `.well-known/oauth-authorization-server` and this standard is defined by the IETF and not the OpenID Foundation. + +One consideration of using this RFC is that it explicitly states that an application leveraging this standard should define its own application-specific endpoint, e.g. `/.well-known/matrix-authorization-server`, and *not* use the `.well-known/oauth-authorization-server` endpoint. + +### Publish the server metadata through a new C-S API + +To eliminate one roundtrip, the server metadata could be published directly through a new C-S API endpoint. +A theoretical endpoint could be `/_matrix/client/v1/auth_metadata`, which would directly return the server metadata, as defined in [RFC8414](https://tools.ietf.org/html/rfc8414). + +The full discovery flow would be as follows: + +- `GET [domain]/_matrix/client/v1/auth_metadata` to discover the homeserver +- `GET [homeserver]/_matrix/client/v1/auth_metadata` to discover the authorization server metadata +- `POST [issuer client registration endpoint]` to register the OAuth 2.0 client +- Redirect to `[issuer authorization endpoint]` to initiate the login flow ### Discovery via the well-known client discovery From 331ac7947c070aff6115cdf3df7f7bb436db90ce Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Fri, 17 Jan 2025 15:37:53 +0100 Subject: [PATCH 27/34] Fix the alternative flow --- proposals/2965-oidc-discovery.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index 5754511b9f3..c6120580a55 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -91,7 +91,7 @@ A theoretical endpoint could be `/_matrix/client/v1/auth_metadata`, which would The full discovery flow would be as follows: -- `GET [domain]/_matrix/client/v1/auth_metadata` to discover the homeserver +- `GET [domain]/.well-known/matrix/client` to discover the Client-Server API endpoint - `GET [homeserver]/_matrix/client/v1/auth_metadata` to discover the authorization server metadata - `POST [issuer client registration endpoint]` to register the OAuth 2.0 client - Redirect to `[issuer authorization endpoint]` to initiate the login flow From 76dfb12a2cb113344a502ef1950a7706a0510789 Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Fri, 17 Jan 2025 17:07:00 +0100 Subject: [PATCH 28/34] Publish the auth server metadata through a new C-S API endpoint This removes the depdency on OIDC specs --- proposals/2965-oidc-discovery.md | 112 ++++++++++++++++--------------- 1 file changed, 58 insertions(+), 54 deletions(-) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-oidc-discovery.md index c6120580a55..da23d6e300a 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-oidc-discovery.md @@ -1,23 +1,21 @@ -# MSC2965: Usage of OpenID Connect Discovery for authentication server metadata discovery +# MSC2965: OAuth 2.0 Authorization Server Metadata discovery -This proposal is part of the broader [MSC3861: Next-generation auth for Matrix, based on OAuth 2.0/OIDC](https://github.com/matrix-org/matrix-spec-proposals/pull/3861). +This proposal is part of the broader [MSC3861: Next-generation auth for Matrix, based on OAuth 2.0/OIDC][MSC3861]. -To be able to initiate an OAuth 2.0 login flow to use a Matrix server, the client needs to know the location of the authentication server in use. +To be able to initiate an OAuth 2.0 login flow to use a Matrix server, the client needs to know the authorization server metadata, as defined in [RFC8414]. ## Proposal -This introduces a new Client-Server API endpoint to discover the authentication server used by the homeserver. +This introduces a new Client-Server API endpoint to discover the authorization server metadata used by the homeserver. -### `GET /auth_issuer` +### `GET /auth_metadata` -A request on this endpoint should return a JSON object with one field: - -- _REQUIRED_ `issuer`: the OpenID Connect Provider that is trusted by the homeserver +A request on this endpoint should return a JSON object containing the authorization server metadata as defined in [RFC8414]. For example: ```http -GET /_matrix/client/v1/auth_issuer +GET /_matrix/client/v1/auth_metadata Host: example.com Accept: application/json ``` @@ -25,76 +23,78 @@ Accept: application/json ```http HTTP/1.1 200 OK Content-Type: application/json +Cache-Control: public, max-age=3600 ``` ```json { - "issuer": "https://account.example.com/" -} -``` - -The Matrix client can then discover the OpenID Connect Provider configuration by using [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html). - -```http -GET /.well-known/openid-configuration -Host: account.example.com -Accept: application/json -``` - -```http -HTTP/1.1 200 OK -Content-Type: application/json -``` - -```json -{ - "issuer": "https://account.example.com/", "authorization_endpoint": "https://account.example.com/oauth2/auth", "token_endpoint": "https://account.example.com/oauth2/token", "registration_endpoint": "https://account.example.com/oauth2/clients/register", - "end_session_endpoint": "https://account.example.com/oauth2/logout", + "revocation_endpoint": "https://account.example.com/oauth2/revoke", "jwks_uri": "https://account.example.com/oauth2/keys", "response_types_supported": ["code"], "grant_types_supported": ["authorization_code", "refresh_token"], - "response_mode_supported": ["query", "fragment"], + "response_modes_supported": ["query", "fragment"], + "code_challenge_methods_supported": ["S256"], "...": "some fields omitted" } ``` +**Note**: The fields required for the main flow outlined by [MSC3861] and its sub-proposals are: + + - `authorization_endpoint` + - `token_endpoint` + - `revocation_endpoint` + - `response_types_supported` including the value `code` + - `grant_types_supported` including the values `authorization_code` and `refresh_token` + - `response_modes_supported` including the values `query` and `fragment` + - `code_challenge_methods_supported` including the value `S256` + +See individual proposals for more details on each field. + ## Potential issues -Using a separate endpoint for discovery makes the request chain to initiate a login flow longer. -A full discovery flow would be as follows: +The authorization server metadata is relatively large and may change over time. The client should: -- `GET [domain]/.well-known/matrix/client` to discover the homeserver -- `GET [homeserver]/_matrix/client/v1/auth_issuer` to discover the issuer -- `GET [issuer]/.well-known/openid-configuration` to discover the OpenID Connect Provider configuration -- `POST [issuer client registration endpoint]` to register the OAuth 2.0 client - (see [MSC2966](https://github.com/matrix-org/matrix-spec-proposals/pull/2966)) -- Redirect to `[issuer authorization endpoint]` to initiate the login flow +- Cache the metadata appropriately based on HTTP caching headers +- Refetch the metadata if it is stale ## Alternatives -The authentication server discovery could be done by other mechanisms. +### Discovery via OpenID Connect Discovery -### Discovery via [RFC8414](https://tools.ietf.org/html/rfc8414) +Instead of directly exposing the metadata through a Client-Server API endpoint, the homeserver could expose only the issuer URL and let clients discover the metadata using OpenID Connect Discovery. -[RFC8414](https://tools.ietf.org/html/rfc8414): OAuth 2.0 Authorization Server Metadata is a standard similar to OpenID Connect Discovery. -The main difference is that the well-known endpoint is under `.well-known/oauth-authorization-server` and this standard is defined by the IETF and not the OpenID Foundation. +In this approach, a new endpoint `/_matrix/client/v1/auth_issuer` would return just the issuer URL: -One consideration of using this RFC is that it explicitly states that an application leveraging this standard should define its own application-specific endpoint, e.g. `/.well-known/matrix-authorization-server`, and *not* use the `.well-known/oauth-authorization-server` endpoint. +```http +GET /_matrix/client/v1/auth_issuer +Host: example.com +Accept: application/json +``` -### Publish the server metadata through a new C-S API +```http +HTTP/1.1 200 OK +Content-Type: application/json +``` -To eliminate one roundtrip, the server metadata could be published directly through a new C-S API endpoint. -A theoretical endpoint could be `/_matrix/client/v1/auth_metadata`, which would directly return the server metadata, as defined in [RFC8414](https://tools.ietf.org/html/rfc8414). +```json +{ + "issuer": "https://account.example.com/" +} +``` + +The Matrix client would then discover the OpenID Connect Provider configuration by using [OpenID Connect Discovery]. -The full discovery flow would be as follows: +The downside of this approach is that it requires an extra roundtrip to get the metadata. +It also introduces a dependency on an OpenID Connect specification: [MSC3861] proposals tries to build on OAuth 2.0/IETF standards as much as possible. -- `GET [domain]/.well-known/matrix/client` to discover the Client-Server API endpoint -- `GET [homeserver]/_matrix/client/v1/auth_metadata` to discover the authorization server metadata -- `POST [issuer client registration endpoint]` to register the OAuth 2.0 client -- Redirect to `[issuer authorization endpoint]` to initiate the login flow +### Discovery via [RFC8414] well-known endpoint + +[RFC8414] OAuth 2.0 Authorization Server Metadata already defines a standard well-known endpoint, under `.well-known/oauth-authorization-server`. +However, the RFC states that an application leveraging this standard should define its own application-specific endpoint, e.g. `/.well-known/matrix-authorization-server`, and *not* use the `.well-known/oauth-authorization-server` endpoint. +This is why this proposal suggests defining a new C-S API endpoint instead. ### Discovery via the well-known client discovery @@ -180,7 +180,7 @@ different authentication servers could be used by different accounts on the serv The downsides of this approach are: -- the `.well-known` resource is dynamic, which can be harder to host/delegate & might conflict with other services like Mastodon +- the `.well-known/webfinger` resource is dynamic, which can be harder to host/delegate & might conflict with other services leveraging it like Mastodon - this does not cover discovering the authentication server for user registration ## Security considerations @@ -191,4 +191,8 @@ None relevant. While this MSC is not in a released version of the specification, clients should use the `org.matrix.msc2965` unstable prefix for the endpoint, -e.g. `GET /_matrix/client/unstable/org.matrix.msc2965/auth_issuer`. +e.g. `GET /_matrix/client/unstable/org.matrix.msc2965/auth_metadata`. + +[RFC8414]: https://tools.ietf.org/html/rfc8414 +[MSC3861]: https://github.com/matrix-org/matrix-spec-proposals/pull/3861 +[OpenID Connect Discovery]: https://openid.net/specs/openid-connect-discovery-1_0.html From abd969a16687a6285ca15fdf8df3a397975b5cb0 Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Fri, 17 Jan 2025 17:22:32 +0100 Subject: [PATCH 29/34] renamed 2965-oidc-discovery.md -> 2965-auth-metadata.md --- proposals/{2965-oidc-discovery.md => 2965-auth-metadata.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename proposals/{2965-oidc-discovery.md => 2965-auth-metadata.md} (98%) diff --git a/proposals/2965-oidc-discovery.md b/proposals/2965-auth-metadata.md similarity index 98% rename from proposals/2965-oidc-discovery.md rename to proposals/2965-auth-metadata.md index da23d6e300a..98f7a41412d 100644 --- a/proposals/2965-oidc-discovery.md +++ b/proposals/2965-auth-metadata.md @@ -94,7 +94,7 @@ It also introduces a dependency on an OpenID Connect specification: [MSC3861] pr [RFC8414] OAuth 2.0 Authorization Server Metadata already defines a standard well-known endpoint, under `.well-known/oauth-authorization-server`. However, the RFC states that an application leveraging this standard should define its own application-specific endpoint, e.g. `/.well-known/matrix-authorization-server`, and *not* use the `.well-known/oauth-authorization-server` endpoint. -This is why this proposal suggests defining a new C-S API endpoint instead. +To avoid confusion with the existing `.well-known/matrix/*` documents, this proposal suggests defining a new C-S API endpoint instead. ### Discovery via the well-known client discovery From 0e7cea03d86994e4ad48cbcc7eb4fafe89d5ff12 Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Wed, 22 Jan 2025 14:10:39 +0100 Subject: [PATCH 30/34] Clarify auth & rate limiting requirements Co-authored-by: Travis Ralston --- proposals/2965-auth-metadata.md | 1 + 1 file changed, 1 insertion(+) diff --git a/proposals/2965-auth-metadata.md b/proposals/2965-auth-metadata.md index 98f7a41412d..53412bb243e 100644 --- a/proposals/2965-auth-metadata.md +++ b/proposals/2965-auth-metadata.md @@ -11,6 +11,7 @@ This introduces a new Client-Server API endpoint to discover the authorization s ### `GET /auth_metadata` A request on this endpoint should return a JSON object containing the authorization server metadata as defined in [RFC8414]. +This endpoint does *not* require authentication, and MAY be rate limited per usual. For example: From 2aed234c4f4f98c78386ec50f9592e389ae63983 Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Wed, 22 Jan 2025 14:37:15 +0100 Subject: [PATCH 31/34] Mention the MSCs using each metadata value --- proposals/2965-auth-metadata.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/proposals/2965-auth-metadata.md b/proposals/2965-auth-metadata.md index 53412bb243e..e6f64ba2219 100644 --- a/proposals/2965-auth-metadata.md +++ b/proposals/2965-auth-metadata.md @@ -44,13 +44,14 @@ Cache-Control: public, max-age=3600 **Note**: The fields required for the main flow outlined by [MSC3861] and its sub-proposals are: - - `authorization_endpoint` - - `token_endpoint` - - `revocation_endpoint` - - `response_types_supported` including the value `code` - - `grant_types_supported` including the values `authorization_code` and `refresh_token` - - `response_modes_supported` including the values `query` and `fragment` - - `code_challenge_methods_supported` including the value `S256` + - `authorization_endpoint` ([MSC2964]) + - `token_endpoint` ([MSC2964]) + - `revocation_endpoint` ([MSC4254]) + - `registration_endpoint` ([MSC2966]) + - `response_types_supported` including the value `code` ([MSC2964]) + - `grant_types_supported` including the values `authorization_code` and `refresh_token` ([MSC2964]) + - `response_modes_supported` including the values `query` and `fragment` ([MSC2964]) + - `code_challenge_methods_supported` including the value `S256` ([MSC2964]) See individual proposals for more details on each field. @@ -195,5 +196,8 @@ clients should use the `org.matrix.msc2965` unstable prefix for the endpoint, e.g. `GET /_matrix/client/unstable/org.matrix.msc2965/auth_metadata`. [RFC8414]: https://tools.ietf.org/html/rfc8414 +[MSC2964]: https://github.com/matrix-org/matrix-spec-proposals/pull/2964 +[MSC2966]: https://github.com/matrix-org/matrix-spec-proposals/pull/2966 [MSC3861]: https://github.com/matrix-org/matrix-spec-proposals/pull/3861 +[MSC4254]: https://github.com/matrix-org/matrix-spec-proposals/pull/4254 [OpenID Connect Discovery]: https://openid.net/specs/openid-connect-discovery-1_0.html From 93d1b0941214a610a2fc161953876966cb9eb270 Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Wed, 22 Jan 2025 14:38:01 +0100 Subject: [PATCH 32/34] Explain what to do when next-gen auth is not available --- proposals/2965-auth-metadata.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/proposals/2965-auth-metadata.md b/proposals/2965-auth-metadata.md index e6f64ba2219..3f13b9d861c 100644 --- a/proposals/2965-auth-metadata.md +++ b/proposals/2965-auth-metadata.md @@ -55,6 +55,12 @@ Cache-Control: public, max-age=3600 See individual proposals for more details on each field. +### Fallback + +If the homeserver does not offer next-generation authentication as described in [MSC3861], this endpoint should return a 404 with the `M_UNRECOGNIZED` error code. + +In this case, clients should fall back to using the User-Interactive Authentication flows instead to authenticate the user. + ## Potential issues The authorization server metadata is relatively large and may change over time. The client should: From ee1c23d91e3a05d6457e359e22ff5ad49da95ac2 Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Wed, 22 Jan 2025 15:22:07 +0100 Subject: [PATCH 33/34] Add rationale for not using a .well-known endpoint --- proposals/2965-auth-metadata.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/proposals/2965-auth-metadata.md b/proposals/2965-auth-metadata.md index 3f13b9d861c..8d5894746e5 100644 --- a/proposals/2965-auth-metadata.md +++ b/proposals/2965-auth-metadata.md @@ -61,6 +61,20 @@ If the homeserver does not offer next-generation authentication as described in In this case, clients should fall back to using the User-Interactive Authentication flows instead to authenticate the user. +## Rationale for not using a `.well-known` document + +[RFC8414] suggests using an application-specific well-known endpoint instead of the `.well-known/oauth-authorization-server` endpoint. + +Considering the rest of the client-server API, there are two potential locations where this could be hosted: + +1. On the server name domain, with well-known delegation, e.g. `https://example.com/.well-known/matrix/auth-metadata` +2. On the client-server API endpoint root, e.g. `https://matrix-client.example.com/.well-known/matrix/auth-metadata` + +The first option would require making well-known documents mandatory on the server name domain, with a document that may need to be updated more frequently than existing ones. +This isn't practical for some server deployments, and clients may find it challenging to consistently perform this discovery. + +The second option is also impractical, as all other Matrix APIs on this domain are prefixed with `/_matrix`, and it could easily be confused with the set of well-known documents hosted on the server name domain. + ## Potential issues The authorization server metadata is relatively large and may change over time. The client should: From 885a50fa2a81b7fbb34ccbb8d07ea1aa95ce04f4 Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Wed, 22 Jan 2025 15:22:17 +0100 Subject: [PATCH 34/34] Reformat with prettier --- proposals/2965-auth-metadata.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/proposals/2965-auth-metadata.md b/proposals/2965-auth-metadata.md index 8d5894746e5..96baaf0b1fb 100644 --- a/proposals/2965-auth-metadata.md +++ b/proposals/2965-auth-metadata.md @@ -11,7 +11,7 @@ This introduces a new Client-Server API endpoint to discover the authorization s ### `GET /auth_metadata` A request on this endpoint should return a JSON object containing the authorization server metadata as defined in [RFC8414]. -This endpoint does *not* require authentication, and MAY be rate limited per usual. +This endpoint does _not_ require authentication, and MAY be rate limited per usual. For example: @@ -44,14 +44,14 @@ Cache-Control: public, max-age=3600 **Note**: The fields required for the main flow outlined by [MSC3861] and its sub-proposals are: - - `authorization_endpoint` ([MSC2964]) - - `token_endpoint` ([MSC2964]) - - `revocation_endpoint` ([MSC4254]) - - `registration_endpoint` ([MSC2966]) - - `response_types_supported` including the value `code` ([MSC2964]) - - `grant_types_supported` including the values `authorization_code` and `refresh_token` ([MSC2964]) - - `response_modes_supported` including the values `query` and `fragment` ([MSC2964]) - - `code_challenge_methods_supported` including the value `S256` ([MSC2964]) +- `authorization_endpoint` ([MSC2964]) +- `token_endpoint` ([MSC2964]) +- `revocation_endpoint` ([MSC4254]) +- `registration_endpoint` ([MSC2966]) +- `response_types_supported` including the value `code` ([MSC2964]) +- `grant_types_supported` including the values `authorization_code` and `refresh_token` ([MSC2964]) +- `response_modes_supported` including the values `query` and `fragment` ([MSC2964]) +- `code_challenge_methods_supported` including the value `S256` ([MSC2964]) See individual proposals for more details on each field. @@ -115,7 +115,7 @@ It also introduces a dependency on an OpenID Connect specification: [MSC3861] pr ### Discovery via [RFC8414] well-known endpoint [RFC8414] OAuth 2.0 Authorization Server Metadata already defines a standard well-known endpoint, under `.well-known/oauth-authorization-server`. -However, the RFC states that an application leveraging this standard should define its own application-specific endpoint, e.g. `/.well-known/matrix-authorization-server`, and *not* use the `.well-known/oauth-authorization-server` endpoint. +However, the RFC states that an application leveraging this standard should define its own application-specific endpoint, e.g. `/.well-known/matrix-authorization-server`, and _not_ use the `.well-known/oauth-authorization-server` endpoint. To avoid confusion with the existing `.well-known/matrix/*` documents, this proposal suggests defining a new C-S API endpoint instead. ### Discovery via the well-known client discovery