What is Matrix 2.0 authentication?

Matrix 2.0 replaces the homeserver's built-in login system with a delegated OIDC (OpenID Connect) provider. Instead of your homeserver handling passwords and sessions directly, it points clients to a separate service — such as Matrix Authentication Service (MAS) — which issues tokens using standard OAuth 2.0 / OIDC flows.

Why it matters

OIDC delegation is a separate service that can fail independently of your homeserver. Common problems include:

• The OIDC provider is reachable from the homeserver but not from the client's browser (CORS or firewall)
• The provider does not advertise the matrix scope, which clients need to obtain a Matrix access token
• The provider doesn't advertise PKCE with S256, which Matrix clients require

The connectivity tester validates the full chain from homeserver advertisement to OIDC provider configuration.

Discovery

Unlike the old MSC3861/MSC2965 draft flow, discovery is now a single request — there is no separate well-known field and no second discovery document to fetch:

1. Auth metadata endpoint

GET /_matrix/client/v1/auth_metadata

The tester also tries the pre-stabilization unstable path (/_matrix/client/unstable/org.matrix.msc2965/auth_metadata) for homeservers that haven't upgraded yet.

If the homeserver does not support OIDC delegation, this returns 404 M_UNRECOGNIZED. If it does, the response body is the OAuth 2.0 Authorization Server Metadata document itself (per RFC 8414) — no further discovery round-trip needed:

{
  "issuer": "https://auth.example.com/",
  "authorization_endpoint": "https://auth.example.com/authorize",
  "token_endpoint": "https://auth.example.com/token",
  "code_challenge_methods_supported": ["S256"]
}

What each check means

Issuer

The issuer field from the auth_metadata response — the base URL of the OIDC provider.

PKCE S256

Matrix clients require PKCE (Proof Key for Code Exchange) with the S256 challenge method. This protects against authorization code interception. If your OIDC provider does not advertise S256 in code_challenge_methods_supported, Matrix clients cannot safely complete the login flow.

Common issues

OIDC CORS blocked

The browser cannot reach /_matrix/client/v1/auth_metadata because CORS headers are missing. It needs Access-Control-Allow-Origin: * (or your specific origin) — the endpoint is served by the homeserver itself.

MAS serves these headers by default. If you are using a different provider or homeserver, check its CORS configuration.

Testing manually

# Check the auth metadata endpoint (Matrix 1.19+)
curl https://matrix.example.com/_matrix/client/v1/auth_metadata | jq '{issuer, code_challenge_methods_supported}'

# Check CORS on it
curl -I -H "Origin: https://element.example.com" https://matrix.example.com/_matrix/client/v1/auth_metadata

Or run the connectivity tester which walks the full chain automatically.