From 67cd0fe960978846da04f5780409f248455ad68c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Sat, 24 May 2025 16:17:52 +0200 Subject: [PATCH 1/3] Add the OAuth 2.0 server metadata discovery endpoint MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit As per MSC2965. Signed-off-by: Kévin Commaille --- content/client-server-api/_index.md | 4 + .../client-server/oauth_server_metadata.yaml | 176 ++++++++++++++++++ 2 files changed, 180 insertions(+) create mode 100644 data/api/client-server/oauth_server_metadata.yaml diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 855e8df9e..3fab625f8 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1481,6 +1481,10 @@ MAY reject weak passwords with an error code `M_WEAK_PASSWORD`. ### OAuth 2.0 API +#### Server metadata discovery + +{{% http-api spec="client-server" api="oauth_server_metadata" %}} + ### Account moderation #### Account locking diff --git a/data/api/client-server/oauth_server_metadata.yaml b/data/api/client-server/oauth_server_metadata.yaml new file mode 100644 index 000000000..633c68ee8 --- /dev/null +++ b/data/api/client-server/oauth_server_metadata.yaml @@ -0,0 +1,176 @@ +# Copyright 2025 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +openapi: 3.1.0 +info: + title: Matrix Client-Server OAuth 2.0 Server Metadata Discovery API + version: 1.0.0 +paths: + "/auth_metadata": + get: + summary: Get the OAuth 2.0 authorization server metadata. + description: |- + Gets the OAuth 2.0 authorization server metadata, as defined in + [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414), including the + endpoint URLs and the supported parameters that can be used by the + clients. + + The definition of this endpoint includes only the fields that are + meaningful in the context of the Matrix specification. The full list of + possible fields is available in the [OAuth Authorization Server Metadata + registry](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#authorization-server-metadata), + and normative definitions of them are available in their respective + RFCs. + + {{% boxes/note %}} + The authorization server metadata is relatively large and may change + over time. Clients should: + + - Cache the metadata appropriately based on HTTP caching headers + - Refetch the metadata if it is stale + {{% /boxes/note %}} + operationId: getAuthMetadata + responses: + "200": + description: The OAuth 2.0 authorization server metadata. + content: + application/json: + schema: + type: object + properties: + issuer: + type: string + format: uri + description: |- + The authorization server's issuer identifier, which is a URL that uses the + `https` scheme and has no query or fragment components. + + This is not used in the context of the Matrix specification, but is required + by [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414). + authorization_endpoint: + type: string + format: uri + description: |- + URL of the authorization endpoint, necessary to use the authorization code + grant. + token_endpoint: + type: string + format: uri + description: |- + URL of the token endpoint, necessary to use the authorization code grant and + the refresh token grant. + revocation_endpoint: + type: string + format: uri + description: |- + URL of the revocation endpoint, necessary to log out a client by invalidating + its access and refresh tokens. + registration_endpoint: + type: string + format: uri + description: |- + URL of the client registration endpoint, necessary to perform dynamic + registration of a client. + response_types_supported: + type: array + description: |- + List of OAuth 2.0 response type strings that the server supports at the + authorization endpoint. + + This array MUST contain at least the `code` value, for clients to be able to + use the authorization code grant. + items: + type: string + description: A response type that the server supports. + grant_types_supported: + type: array + description: |- + List of OAuth 2.0 grant type strings that the server supports at the token + endpoint. + + This array MUST contain at least the `authorization_code` and `refresh_token` + values, for clients to be able to use the authorization code grant and refresh + token grant, respectively. + items: + type: string + description: A grant type that the server supports. + response_modes_supported: + type: array + description: |- + List of OAuth 2.0 response mode strings that the server supports at the + authorization endpoint. + + This array MUST contain at least the `query` and `fragment` values, for + improved security in the authorization code grant. + items: + type: string + description: A response mode that the server supports. + code_challenge_methods_supported: + type: array + description: |- + List of OAuth 2.0 Proof Key for Code Exchange (PKCE) code challenge methods + that the server supports at the authorization endpoint. + + This array MUST contain at least the `s256` value, for improved security in + the authorization code grant. + items: + type: string + description: A PKCE code challenge method that the server supports. + prompt_values_supported: + type: array + description: |- + List of OpenID Connect prompt values that the server supports at the + authorization endpoint. + + Only the `create` value defined in [Initiating User Registration via OpenID + Connect](https://openid.net/specs/openid-connect-prompt-create-1_0.html) is + supported, for a client to signal to the server that the user desires to + register a new account. + items: + type: string + description: A prompt value that the server supports. + required: + - issuer + - authorization_endpoint + - token_endpoint + - revocation_endpoint + - registration_endpoint + - response_types_supported + - grant_types_supported + - response_modes_supported + - code_challenge_methods_supported + example: { + "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", + "revocation_endpoint": "https://account.example.com/oauth2/revoke", + "response_types_supported": ["code"], + "grant_types_supported": ["authorization_code", "refresh_token"], + "response_modes_supported": ["query", "fragment"], + "code_challenge_methods_supported": ["S256"], + } + tags: + - Session management +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v1 From 693e9f73c0106b40c72638daee4f327414c050a8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Sat, 24 May 2025 16:22:50 +0200 Subject: [PATCH 2/3] Add changelog MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- changelogs/client_server/newsfragments/2147.new | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/2147.new diff --git a/changelogs/client_server/newsfragments/2147.new b/changelogs/client_server/newsfragments/2147.new new file mode 100644 index 000000000..c72bf35ea --- /dev/null +++ b/changelogs/client_server/newsfragments/2147.new @@ -0,0 +1 @@ +Add `GET /_matrix/client/v1/auth_metadata`, as per [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965). From 468ddf9d1577abdd86ac4fa74812af038d8685eb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Mon, 16 Jun 2025 10:23:36 +0200 Subject: [PATCH 3/3] Fix typos MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- data/api/client-server/oauth_server_metadata.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/data/api/client-server/oauth_server_metadata.yaml b/data/api/client-server/oauth_server_metadata.yaml index 633c68ee8..4cdb3aa67 100644 --- a/data/api/client-server/oauth_server_metadata.yaml +++ b/data/api/client-server/oauth_server_metadata.yaml @@ -25,9 +25,9 @@ paths: endpoint URLs and the supported parameters that can be used by the clients. - The definition of this endpoint includes only the fields that are - meaningful in the context of the Matrix specification. The full list of - possible fields is available in the [OAuth Authorization Server Metadata + This endpoint definition includes only the fields that are meaningful in + the context of the Matrix specification. The full list of possible + fields is available in the [OAuth Authorization Server Metadata registry](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#authorization-server-metadata), and normative definitions of them are available in their respective RFCs. @@ -121,7 +121,7 @@ paths: List of OAuth 2.0 Proof Key for Code Exchange (PKCE) code challenge methods that the server supports at the authorization endpoint. - This array MUST contain at least the `s256` value, for improved security in + This array MUST contain at least the `S256` value, for improved security in the authorization code grant. items: type: string