Skip to content

Commit 51ccbbd

Browse files
zecakehzecakeh
authored
Add the OAuth 2.0 server metadata discovery endpoint (#2147)
As per MSC2965.
1 parent a2a9a02 commit 51ccbbd

File tree

3 files changed

+181
-0
lines changed

3 files changed

+181
-0
lines changed

‎changelogs/client_server/newsfragments/2147.new‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Add `GET /_matrix/client/v1/auth_metadata`, as per [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965).

‎content/client-server-api/_index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1481,6 +1481,10 @@ MAY reject weak passwords with an error code `M_WEAK_PASSWORD`.
14811481

14821482
### OAuth 2.0 API
14831483

1484+
#### Server metadata discovery
1485+
1486+
{{% http-api spec="client-server" api="oauth_server_metadata" %}}
1487+
14841488
#### Scope
14851489

14861490
The client requests a scope in the OAuth 2.0 authorization flow, which is then

‎data/api/client-server/oauth_server_metadata.yaml‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# Copyright 2025 The Matrix.org Foundation C.I.C.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
openapi: 3.1.0
15+
info:
16+
title: Matrix Client-Server OAuth 2.0 Server Metadata Discovery API
17+
version: 1.0.0
18+
paths:
19+
"/auth_metadata":
20+
get:
21+
summary: Get the OAuth 2.0 authorization server metadata.
22+
description: |-
23+
Gets the OAuth 2.0 authorization server metadata, as defined in
24+
[RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414), including the
25+
endpoint URLs and the supported parameters that can be used by the
26+
clients.
27+
28+
This endpoint definition includes only the fields that are meaningful in
29+
the context of the Matrix specification. The full list of possible
30+
fields is available in the [OAuth Authorization Server Metadata
31+
registry](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#authorization-server-metadata),
32+
and normative definitions of them are available in their respective
33+
RFCs.
34+
35+
{{% boxes/note %}}
36+
The authorization server metadata is relatively large and may change
37+
over time. Clients should:
38+
39+
- Cache the metadata appropriately based on HTTP caching headers
40+
- Refetch the metadata if it is stale
41+
{{% /boxes/note %}}
42+
operationId: getAuthMetadata
43+
responses:
44+
"200":
45+
description: The OAuth 2.0 authorization server metadata.
46+
content:
47+
application/json:
48+
schema:
49+
type: object
50+
properties:
51+
issuer:
52+
type: string
53+
format: uri
54+
description: |-
55+
The authorization server's issuer identifier, which is a URL that uses the
56+
`https` scheme and has no query or fragment components.
57+
58+
This is not used in the context of the Matrix specification, but is required
59+
by [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414).
60+
authorization_endpoint:
61+
type: string
62+
format: uri
63+
description: |-
64+
URL of the authorization endpoint, necessary to use the authorization code
65+
grant.
66+
token_endpoint:
67+
type: string
68+
format: uri
69+
description: |-
70+
URL of the token endpoint, necessary to use the authorization code grant and
71+
the refresh token grant.
72+
revocation_endpoint:
73+
type: string
74+
format: uri
75+
description: |-
76+
URL of the revocation endpoint, necessary to log out a client by invalidating
77+
its access and refresh tokens.
78+
registration_endpoint:
79+
type: string
80+
format: uri
81+
description: |-
82+
URL of the client registration endpoint, necessary to perform dynamic
83+
registration of a client.
84+
response_types_supported:
85+
type: array
86+
description: |-
87+
List of OAuth 2.0 response type strings that the server supports at the
88+
authorization endpoint.
89+
90+
This array MUST contain at least the `code` value, for clients to be able to
91+
use the authorization code grant.
92+
items:
93+
type: string
94+
description: A response type that the server supports.
95+
grant_types_supported:
96+
type: array
97+
description: |-
98+
List of OAuth 2.0 grant type strings that the server supports at the token
99+
endpoint.
100+
101+
This array MUST contain at least the `authorization_code` and `refresh_token`
102+
values, for clients to be able to use the authorization code grant and refresh
103+
token grant, respectively.
104+
items:
105+
type: string
106+
description: A grant type that the server supports.
107+
response_modes_supported:
108+
type: array
109+
description: |-
110+
List of OAuth 2.0 response mode strings that the server supports at the
111+
authorization endpoint.
112+
113+
This array MUST contain at least the `query` and `fragment` values, for
114+
improved security in the authorization code grant.
115+
items:
116+
type: string
117+
description: A response mode that the server supports.
118+
code_challenge_methods_supported:
119+
type: array
120+
description: |-
121+
List of OAuth 2.0 Proof Key for Code Exchange (PKCE) code challenge methods
122+
that the server supports at the authorization endpoint.
123+
124+
This array MUST contain at least the `S256` value, for improved security in
125+
the authorization code grant.
126+
items:
127+
type: string
128+
description: A PKCE code challenge method that the server supports.
129+
prompt_values_supported:
130+
type: array
131+
description: |-
132+
List of OpenID Connect prompt values that the server supports at the
133+
authorization endpoint.
134+
135+
Only the `create` value defined in [Initiating User Registration via OpenID
136+
Connect](https://openid.net/specs/openid-connect-prompt-create-1_0.html) is
137+
supported, for a client to signal to the server that the user desires to
138+
register a new account.
139+
items:
140+
type: string
141+
description: A prompt value that the server supports.
142+
required:
143+
- issuer
144+
- authorization_endpoint
145+
- token_endpoint
146+
- revocation_endpoint
147+
- registration_endpoint
148+
- response_types_supported
149+
- grant_types_supported
150+
- response_modes_supported
151+
- code_challenge_methods_supported
152+
example: {
153+
"issuer": "https://account.example.com/",
154+
"authorization_endpoint": "https://account.example.com/oauth2/auth",
155+
"token_endpoint": "https://account.example.com/oauth2/token",
156+
"registration_endpoint": "https://account.example.com/oauth2/clients/register",
157+
"revocation_endpoint": "https://account.example.com/oauth2/revoke",
158+
"response_types_supported": ["code"],
159+
"grant_types_supported": ["authorization_code", "refresh_token"],
160+
"response_modes_supported": ["query", "fragment"],
161+
"code_challenge_methods_supported": ["S256"],
162+
}
163+
tags:
164+
- Session management
165+
servers:
166+
- url: "{protocol}://{hostname}{basePath}"
167+
variables:
168+
protocol:
169+
enum:
170+
- http
171+
- https
172+
default: https
173+
hostname:
174+
default: localhost:8008
175+
basePath:
176+
default: /_matrix/client/v1

0 commit comments

Comments
 (0)