]> Twilio

mgerber@twilio.com

Security Web Authorization Protocol This document defines an OAuth endpoint for retrieving a public subset of a client's effective configuration at an authorization server, including applied defaults. It enables clients to check that their configuration is accepted by an authorization server before an authorization attempt. It also enables authorization servers to progressively roll out features to their client base. While the endpoint chiefly serves Client ID Metadata Document clients, it can also be used by clients registered through other means. Discussion Venues Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (oauth@ietf.org), which is archived at . Source for this draft and an issue tracker can be found at .

Introduction OAuth Client ID Metadata Documents (CIMD) enable clients to publish metadata at a URL used as their client identifier. The published document represents a client's view of itself and its own capabilities. The published document does not tell a client which values a given authorization server accepts or if the server applies additional defaults. Incompatibility is only discovered when an authorization attempt fails. That failure is often invisible to the client. When the client identifier or redirect URI is the problem, Section 4.1.2.1 of requires the AS not to redirect back to the client. The user is left at an AS error page, and the client never learns why the flow stopped. This document defines an unauthenticated client metadata lookup operation. CIMD clients are the principal motivation, but the operation also applies to clients registered through other means, including statically registered public clients. RFC 7592 Section 2.1 defines a similar Client Read Request at a Client Configuration Endpoint . That operation requires a registration access token and can return credentials. The operation defined here is separately discoverable, returns only public configuration, and does not require the client to be created through DCR.

Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. Client Identifier URL and Client ID Metadata Document have the meanings defined in . Effective configuration is the client metadata the AS uses after resolving the client's registration, applying defaults, and enforcing client configuration policy.

Use Cases

Clients of Unfamiliar Authorization Servers The Model Context Protocol (MCP) authorization specification uses CIMD as its preferred registration mechanism for clients with no prior relationship to a server. An MCP client, such as a desktop agent or an IDE, publishes one metadata document and presents it to whichever authorization servers protect the MCP servers its users add. The client's developer cannot test against each of those authorization servers in advance, and each authorization server may apply its own policy to the same document. With this endpoint, the client can look up whether its configuration is accepted at an authorization server before sending the user to the authorization endpoint. A rejected document becomes an error the client can show, log, or report, instead of a runtime error presented to the user during the authorization flow.

Progressive Feature Rollout An AS can change a client's configuration as part of rolling out a new requirement and expose the result through this endpoint, so clients can adapt without first failing a user's request. For example, an AS rolling out sender-constrained access tokens with DPoP can set the dpop_bound_access_tokens client metadata value, defined in Section 5.2 of , for one cohort of clients at a time. When the value is true, the AS rejects token requests from the client that lack a DPoP proof. No AS metadata parameter signals this requirement: dpop_signing_alg_values_supported advertises support for DPoP, not whether it is required. A client that finds true in its lookup response knows it must use DPoP at this AS. Without the lookup, the first signal is a rejected token request, after the user has already authenticated and consented. Rollout through this endpoint suits fields whose values reflect AS policy, such as requirements the AS enforces on the client. It is not a way for an AS to change values that only describe the client, such as its redirect URIs or the algorithms it signs with. dpop_bound_access_tokens is phrased as a client declaration, but it obliges the AS to reject non-DPoP token requests, and Section 5.2 of anticipates AS-managed client configuration. An AS that sets the value for a client reports it here. Whether AS policy can set a given field is governed by that field's definition, not by this specification. Clients learn of changes only by repeating the lookup; this specification defines no change notification.

Relationship to Client-Specific AS Metadata proposes a client_id parameter on AS metadata requests so an AS can tailor its advertised capabilities to a client. The mechanisms are complementary: AS metadata describes the AS using AS metadata fields; this endpoint describes the client using client registration metadata fields. For example, dpop_signing_alg_values_supported (Section 5.1 of ) is AS metadata, stating which algorithms the AS accepts for DPoP proofs. dpop_bound_access_tokens (Section 5.2 of ) is client metadata, stating whether the AS requires DPoP of one client. Client-specific AS metadata can tailor the first, but has no field to carry the second. Deployments using both mechanisms MUST keep the two views consistent. Neither mechanism requires the other.

Client Metadata Lookup Endpoint The client metadata lookup endpoint is used by a client to retrieve its effective configuration at an authorization server. The client calls the endpoint directly, typically before redirecting an end user to the authorization endpoint. The client obtains the URL of the endpoint from the client_metadata_lookup_endpoint member of the authorization server's metadata (). The endpoint URL MUST use the https scheme and MUST NOT include a fragment component or query component. The authorization server MUST support the use of the HTTP GET method () at this endpoint. The endpoint MUST accept requests without client authentication. A client identifier is not proof of the requester's identity, and the response MUST NOT depend on an ambient user session or cookies. Because clients access this endpoint directly, including from browsers, the authorization server SHOULD support Cross-Origin Resource Sharing (CORS) at this endpoint, consistent with Section 2.6 of .

Endpoint Discovery An AS supporting this specification MUST include the following member in its AS metadata :

client_metadata_lookup_endpoint:

URL of the client metadata lookup endpoint, as described in .

This member is OPTIONAL for authorization servers generally. Its presence advertises the operation defined here. Neither registration_endpoint nor client_id_metadata_document_supported alone implies support.

Lookup Request The client sends an HTTP GET request to the advertised endpoint with exactly one client_id query parameter. Its value is the client identifier defined in RFC 6749 Section 2.2, encoded according to Appendix B of . For a CIMD client, the value is its Client Identifier URL: The AS MUST resolve the client's configuration using the same registration rules and policy it uses at other endpoints. For CIMD clients, CIMD validation, retrieval, and caching requirements apply. Other clients use their existing registration.

Lookup Response A successful response MUST use HTTP 200 and application/json . The body is an object containing client_id and a public subset of effective client metadata as top-level members. Metadata names and types follow and applicable extensions. The returned client_id MUST match the request using simple string comparison . For supported fields safe to disclose, the AS MUST return effective values, including defaults it applies. This specification does not change those defaults. Unsupported or non-public members MUST be omitted. An omitted member does not mean an empty value or acceptance of a submitted value. Clients MUST NOT infer an effective value by applying registration-time defaults to an omitted member. The AS MUST NOT return secrets, private keys, tokens, user data, usage history, or internal administrative information. In particular, client_secret, client_secret_expires_at, and registration_access_token MUST NOT appear. Other sensitive metadata MUST also be omitted. Suppose the CIMD client in the request above publishes a minimal document at its Client Identifier URL: The lookup response fills in the values the AS applies to the omitted members: The grant_types and response_types values match the defaults. token_endpoint_auth_method does not: RFC 7591 defaults it to client_secret_basic, a shared-secret method CIMD clients cannot use, so this AS treats the client as public and applies none. A client that applied RFC 7591 defaults to its own document would get this wrong, which is why clients MUST NOT infer effective values from omitted members. Success describes current configuration, not endorsement, user consent, or a promise of token issuance. The AS MUST independently validate subsequent requests. Configuration can change between lookup and protocol use.

Error Response Errors MUST use the JSON representation from RFC 6749 Section 5.2, with required error and optional error_description and error_uri members, including that section's syntax restrictions . Responses MUST use HTTP 400 and application/json unless another HTTP status is specified below. The following error codes apply at this endpoint:

invalid_request:

The request is malformed, including a missing or repeated client_id.

invalid_client:

Configuration is unavailable because the client is unknown, disallowed, or cannot safely be acknowledged. This reuses the RFC 6749 error name for this endpoint; it does not indicate a failed authentication attempt.

invalid_client_metadata:

Client metadata could not be retrieved or accepted, including an unreachable CIMD URL, malformed document, identifier mismatch, or unacceptable value. This extends the use of the error name defined by to this endpoint.

Unknown, disallowed, and non-disclosable clients MUST receive indistinguishable invalid_client responses. A Client ID Metadata Document is public and its Client Identifier URL is self-asserted, so explaining why the AS rejected the document discloses little the requester could not already see. When the AS rejects a CIMD client's document, it SHOULD return invalid_client_metadata with an error_description identifying the failing member or check. For other clients, metadata diagnostics MAY be returned only when safe for an unauthenticated requester; otherwise the AS MUST return invalid_client without explanatory detail. For example, when a CIMD client's document declares a shared-secret authentication method, which does not permit:

Caching Following the CIMD caching model, successful lookup responses MAY be cached. The AS SHOULD provide HTTP cache headers reflecting source freshness and configuration policy; it MUST NOT blindly copy a source CIMD's cache headers. Clients MUST NOT cache errors or invalid or malformed responses. The AS MUST send Cache-Control: no-store on errors.

Security Considerations TODO!

Privacy Considerations TODO!

IANA Considerations This document requests the following registration in the OAuth Authorization Server Metadata registry established by :

Metadata Name:

client_metadata_lookup_endpoint

Metadata Description:

URL of the client metadata lookup endpoint.

Change Controller:

IETF

Specification Document:

of this document.

References Normative References A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849. [STANDARDS-TRACK] This specification defines mechanisms for dynamically registering OAuth 2.0 clients with authorization servers. Registration requests send a set of desired client metadata values to the authorization server. The resulting registration responses return a client identifier to use at the authorization server and the client metadata values registered for the client. The client can then use this registration information to communicate with the authorization server using the OAuth 2.0 protocol. This specification also defines a set of common client metadata fields and values for clients to use during registration. This specification defines a metadata format that an OAuth 2.0 client can use to obtain the information needed to interact with an OAuth 2.0 authorization server, including its endpoint locations and authorization server capabilities. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document defines HTTP caches and the associated header fields that control cache behavior or indicate cacheable response messages. This document obsoletes RFC 7234. JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. This document describes best current security practice for OAuth 2.0. It updates and extends the threat model and security advice given in RFCs 6749, 6750, and 6819 to incorporate practical experiences gathered since OAuth 2.0 was published and covers new threats relevant due to the broader application of OAuth 2.0. Further, it deprecates some modes of operation that are deemed less secure or even insecure. Okta This specification defines a mechanism through which an OAuth client can identify itself to authorization servers, without prior dynamic client registration or other existing registration. This is through the usage of a URL as a client_id in an OAuth flow, where the URL refers to a document containing the necessary client metadata, enabling the authorization server to fetch the metadata about the client as needed. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References This specification defines methods for management of OAuth 2.0 dynamic client registrations for use cases in which the properties of a registered client may need to be changed during the lifetime of the client. Not all authorization servers supporting dynamic client registration will support these management methods. This document describes a mechanism for sender-constraining OAuth 2.0 tokens via a proof-of-possession mechanism on the application level. This mechanism allows for the detection of replay attacks with access and refresh tokens. Hellō Okta SPRIND The OAuth 2.1 authorization framework enables an application to obtain limited access to a protected resource, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and an authorization service, or by allowing the application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 2.0 Authorization Framework described in RFC 6749 and the Bearer Token Usage in RFC 6750. Model Context Protocol n.d.

Acknowledgments TODO