mtls_endpoint_aliases

IESG

Registry Context

An optional authorization server metadata object that provides alternative endpoint URLs for OAuth clients intending to use mutual TLS.

Technical Summary

The value is a JSON object containing one or more endpoint parameters conventionally defined at the top level of authorization server metadata, such as token_endpoint, revocation_endpoint, and introspection_endpoint. For direct requests to the authorization server, a client intending to use mutual TLS uses a present alias in preference to the same-named top-level endpoint. If no alias is present, it uses the conventional top-level endpoint.

When Used

Used to isolate mutual-TLS endpoint behavior from conventional endpoints, including for mutual-TLS client authentication and acquiring or using certificate-bound tokens.

Normative Requirements

authorization server metadata

OPTIONAL

RFC 8705 - Section 5
Include mtls_endpoint_aliases as a JSON object containing one or more alternative authorization server endpoint parameters..
OPTIONAL. A JSON object containing alternative authorization server endpoints

authorization server supporting mutual-TLS and conventional clients

MAY

RFC 8705 - Section 5
Isolate server-side mutual-TLS behavior to clients intending to use mutual TLS..
Authorization servers supporting both clients using mutual TLS and conventional clients MAY chose to isolate the server side mutual-TLS behavior

OAuth client intending to use mutual TLS

MUST

RFC 8705 - Section 5
Use the alias URL within mtls_endpoint_aliases in preference to the same-named top-level metadata endpoint URL..
Condition: When making a request directly to the authorization server and the alias is present.
when making a request directly to the authorization server MUST use the alias URL of the endpoint within the mtls_endpoint_aliases, when present

OAuth client or authorization server metadata processor

SHOULD

RFC 8705 - Section 5
Ignore members of mtls_endpoint_aliases that do not define endpoints to which an OAuth client makes a direct request..
Condition: When such members are present.
Metadata parameters within mtls_endpoint_aliases that do not define endpoints to which an OAuth client makes a direct request have no meaning and SHOULD be ignored.

Validation Guidance

error

If mtls_endpoint_aliases is present, verify that it is a JSON object containing one or more alternative authorization server endpoint parameters.

error

For direct authorization server requests by a client intending to use mutual TLS, use a same-named endpoint alias when present.

info

When a requested endpoint has no member in mtls_endpoint_aliases, use the conventional same-named endpoint URL from the top level of the authorization server metadata.

warning

Ignore members that do not define endpoints to which OAuth clients make direct requests.

Reference

RFC8705 - Section 5

Details

Entry Id: mtls_endpoint_aliases
Metadata Name: mtls_endpoint_aliases
Metadata Description: JSON object containing alternative authorization server endpoints, which a client intending to do mutual TLS will use in preference to the conventional endpoints.
Change Controller: IESG
Reference: RFC8705 - Section 5