You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
177 lines
8.0 KiB
YAML
177 lines
8.0 KiB
YAML
# 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.
|
|
|
|
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.
|
|
|
|
{{% 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
|