OAuth Client Metadata Lookup

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 24 April 2027.¶

Copyright Notice

Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

OAuth Client ID Metadata Documents (CIMD) [I-D.ietf-oauth-client-id-metadata-document] 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 [I-D.ietf-oauth-v2-1] 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 [RFC7592]. 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.¶

2. 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 [RFC2119] [RFC8174] 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 [I-D.ietf-oauth-client-id-metadata-document].¶

Effective configuration is the client metadata the AS uses after resolving the client's registration, applying defaults, and enforcing client configuration policy.¶

3. Use Cases

4. 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 (Section 5).¶

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 (Section 9.3.1 of [RFC9110]) 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 [RFC9700].¶

5. Endpoint Discovery

An AS supporting this specification MUST include the following member in its AS metadata [RFC8414]:¶

client_metadata_lookup_endpoint:

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

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.¶

6. 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 [RFC6749]. For a CIMD client, the value is its Client Identifier URL:¶

GET /lookup?client_id=https%3A%2F%2Fapp.example%2Fclient HTTP/1.1
Host: as.example
Accept: application/json

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.¶

7. Lookup Response

A successful response MUST use HTTP 200 and application/json [RFC8259]. 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 [RFC7591] and applicable extensions. The returned client_id MUST match the request using simple string comparison [RFC3986].¶

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:¶

{
  "client_id": "https://app.example/client",
  "client_name": "Example App",
  "redirect_uris": ["https://app.example/callback"]
}

The lookup response fills in the values the AS applies to the omitted members:¶

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=300
Access-Control-Allow-Origin: *

{
  "client_id": "https://app.example/client",
  "client_name": "Example App",
  "redirect_uris": ["https://app.example/callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

The grant_types and response_types values match the [RFC7591] 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.¶

8. 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 [RFC6749]. 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 [RFC7591] 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 [I-D.ietf-oauth-client-id-metadata-document] does not permit:¶

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Access-Control-Allow-Origin: *

{
  "error": "invalid_client_metadata",
  "error_description":
    "token_endpoint_auth_method client_secret_basic not permitted"
}

9. Caching

Following the CIMD caching model, successful lookup responses MAY be cached. The AS SHOULD provide HTTP cache headers [RFC9111] 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.¶

10. Security Considerations

TODO!¶

11. Privacy Considerations

TODO!¶

12. IANA Considerations

This document requests the following registration in the OAuth Authorization Server Metadata registry established by [RFC8414]:¶

Metadata Name:

client_metadata_lookup_endpoint¶

Metadata Description:

URL of the client metadata lookup endpoint.¶

Change Controller:

IETF¶

Specification Document:

Section 5 of this document.¶

13. References

Acknowledgments

TODO¶

Author's Address