Client ID Metadata Document Software Statement Registration

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 6 May 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

[STATEMENT] defines a software statement binding an issuer's review to the exact octets of a Client ID Metadata Document (CIMD) [CIMD], and admission on that review without registration. This specification serves deployments retaining [RFC7591] registration, for example to assign their own client identifiers or manage registrations under [RFC7592].¶

[RFC7591] already supports software statements whose metadata takes precedence over the registration request (Sections 2.3 and 3.1.1 of [RFC7591]). A statement under [STATEMENT], however, carries a document digest instead of metadata. Verifying it under [RFC7591] alone would leave the request's unreviewed redirection URIs and keys as the registered metadata. [RFC7591] also defines no registration expiry or renewal tied to the statement.¶

This specification defines how servers derive registrations from the reviewed document (Section 3), bound their validity by the statement (Section 4), and renew them with later statements that also update their metadata (Section 6). The same review can therefore govern both registered clients and runtime admission. It extends [STATEMENT], which does not depend on it.¶

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

This specification uses terminology from [RFC6749] (OAuth), [RFC7591] (client metadata and software statements), and [CIMD] (Client ID Metadata Documents), and the terms defined in Section 2 of [STATEMENT].¶

This specification defines the following terms.¶

Delivery:

Carrying a statement in a request under a statement-governed registration, in one of the locations Section 6 lists, so that it can renew the registration. A delivery is not a runtime presentation.¶

Governing Statement:

The statement that bounds a statement-governed registration: the one consumed at registration or, after a renewal, the replacement that renewed it most recently (Section 6). The authorization server identifies it by its iss and jti claims.¶

Replacement:

A statement with the governing statement's iss and sub claims and a later iat, delivered under the registration (Section 6) or carried in a repeated public-client registration request (Section 3.3).¶

Statement-Governed Registration:

An [RFC7591] client registration created from a statement under this specification (Section 3).¶

3. Consumption at Registration

The statement is consumed in the software_statement member of an [RFC7591] registration request. The authorization server validates it under Section 3.2 of [STATEMENT] and registers the client under its ordinary registration policy. If a required issuer covers the statement's sub in the request's tenant (Section 4 of [STATEMENT]), the authorization server MUST NOT create a registration on a statement from another issuer.¶

A required issuer constrains only registrations made on statements, because a registration made without a statement names no client identifier URL for a required issuer to cover. A deployment that needs every registration in a tenant reviewed requires a statement for every registration there and rejects a request that carries none with unapproved_software_statement (Section 7).¶

The retrieval requirements of Sections 3.1 and 5.3 of [STATEMENT] apply to retrieving the document as they apply to a runtime presentation, and a server can apply the bounds of Section 11.2 of [STATEMENT]. Following the order of Section 5.1 of [STATEMENT], the authorization server completes every check that needs no client-controlled retrieval before resolving the document.¶

The reviewed document takes the role that [RFC7591] gives a statement's own values. In deriving a registration's metadata, at registration or for a replacement (Section 6), the authorization server:¶

• MUST obtain the CIMD at the statement's sub claim and compare its digest with the cimd_digest claim as Section 5.2 of [STATEMENT] requires, rejecting the request if the digests differ, and MUST derive the registered metadata from the octets whose digest matched.¶

• MUST validate the document as [CIMD] requires, including that its client_id member matches the statement's sub claim.¶

• MUST take every client metadata value from that document, except the values the authorization server issues (such as client_id and client_id_issued_at), the token_endpoint_auth_method member, which the next item determines, and the document's software_statements_uri member, which is not meaningful in a registration (Section 5.5 of [STATEMENT]).¶

• At registration, MUST register as token_endpoint_auth_method a method that the document permits (Section 2 of [STATEMENT]) and that the server supports and its policy allows, and MUST NOT register none if the document permits another such method. A replacement keeps the registered method (Section 6).¶

• MUST NOT take any client metadata value from the request, or from any [RFC7592] update request for the registration, whether or not the document carries the corresponding member.¶

Client metadata in a registration or update request does not contribute to the registration. The registration's software_statement is its governing statement (Section 6). The registered client_id is assigned as [RFC7591] provides, and the document's own client_id member is the URL recorded as the governing statement's sub. The authorization server MUST NOT assign that URL as the registered client_id, which would make a request carrying it ambiguous between the registration and the CIMD client the URL identifies ([CIMD]). A member the document omits takes its [RFC7591] default, except token_endpoint_auth_method, which is registered as above. The registration's metadata changes only when a replacement is applied (Section 6).¶

The authorization server MUST reject the registration, or a replacement (Section 6), if any of the following holds:¶

• The document permits a method based on a shared symmetric secret, such as client_secret_basic, which Section 4.1 of [CIMD] forbids.¶

• The document permits no method that the server supports and its policy allows.¶

• The method the server would register is none, unless the authorization server registers the client under Section 3.2.¶

• Any of the document's redirection URIs could be claimed by another application on the same device (Section 5.6.3 of [STATEMENT]), whatever methods the document permits.¶

Unlike runtime presentation (Section 5 of [STATEMENT]), registration has no review-only form: the rejections above cover the document conditions that make a presentation review-only.¶

Software that the server would register with none but does not register under Section 3.2 can instead use runtime presentation if it meets the public-client binding requirements of Section 5.6.2 of [STATEMENT].¶

4. Registration Validity

The following validity model applies to every statement-governed registration:¶

• The registration's effective expiry (Section 2 of [STATEMENT]) is that of its governing statement.¶

• The registration is valid until its governing statement ceases to be current (Section 2 of [STATEMENT]), and so at most until that effective expiry.¶

• Once the registration has ceased to be valid, the authorization server MUST reject, at step 4 of Section 5, authorization, token, and pushed authorization requests and [RFC7592] update requests under it, unless a replacement the request delivers has restored it at step 3.¶

• The authorization server SHOULD retain a registration that has ceased to be valid, so that a replacement can restore it.¶

• Ceasing to be valid does not expire the registration's credentials, including its registration access token, and does not by itself revoke access tokens already issued under the registration.¶

• Removing the governing statement's issuer from trust configuration, or narrowing what it can attest, does not by itself end the registration. A server ends it by its own means, such as deleting it.¶

If a request that carries no replacement is rejected because the registration has ceased to be valid, the rejection MUST NOT by itself cause the authorization server to revoke refresh tokens as it does on detecting refresh-token replay (Section 4.14.2 of [RFC9700]).¶

If the authorization server records a required issuer for a tenant (Section 4 of [STATEMENT]), it MUST reject an authorization, token, or pushed authorization request, or an [RFC7592] update request, in that tenant under any statement-governed registration whose governing statement's sub falls within a covered namespace, unless a current statement from the required issuer governs the registration as step 3 of Section 5 leaves it. This rule applies whatever tenant the registration was created in and whenever the requirement was configured. Without this rule, withholding the required issuer's statement would keep such a registration in use after the issuer withdrew or stopped renewing its decision. A registration whose governing statement is from another issuer cannot meet this rule, since a replacement keeps the governing statement's iss (Section 6). Its client registers again with a statement from the required issuer.¶

Neither the validity model nor the required-issuer rule rejects [RFC7592] read and delete requests.¶

The registration_expires_at member is a NumericDate (Section 2 of [RFC7519]) giving the latest time the registration remains valid or, for a registration that has ceased to be valid, the time it ceased. The authorization server:¶

• MUST return registration_expires_at in the [RFC7591] registration response and in the successful response to any request that renews the registration or carries its governing statement (Section 6).¶

• SHOULD return it in any other [RFC7592] read or update response it supports.¶

5. Requests Under a Registration

The authorization server MUST process an authorization, token, or pushed authorization request, or an [RFC7592] update request, under a statement-governed registration in the following order, stopping at the first step that rejects the request or treats it as from a client the server has not registered:¶

1. If the registration is restricted to a tenant (Section 3.1) and the request, including one that delivers a statement, is made in another tenant, it MUST treat the request as from a client it has not registered.¶

2. It authenticates a token or pushed authorization request under the registration's own client authentication method, and an [RFC7592] update request as [RFC7592] requires, against the retained registration even if the registration has ceased to be valid. A token or pushed authorization request under a public-client registration has no client credential to authenticate (Section 3.2).¶

3. It classifies any statement the request delivers by its claims, before validating it, and evaluates a replacement (Section 6). A replacement applied at this step stands even if a later step, or the request's grant, rejects the request.¶

4. It applies the rejections of Section 4 to the registration as step 3 leaves it. If the request is made in a tenant where the authorization server requires a tenant-scoped decision (Section 3.2 of [STATEMENT]) and the registration, as step 3 leaves it, carries no tenant restriction, it MUST treat the request as from a client it has not registered.¶

5. It evaluates the request against the registration's metadata.¶

6. Renewal

A client renews a statement-governed registration by delivering a replacement statement in one of the following, authenticated as step 2 of Section 5 provides:¶

• The software_statement parameter of a token request under the registration.¶

• The software_statement parameter of a pushed authorization request [RFC9126] under the registration.¶

• The software_statement member of an [RFC7592] update request, if the deployment offers registration management.¶

A delivery is a registration use of the statement (Section 3 of [STATEMENT]). A registration request is not a delivery, and renews an existing registration only as Section 3.3 provides for a public-client registration. A statement neither renews nor alters a registration that is not statement-governed, and runtime presentation (Section 5 of [STATEMENT]) alters no registration's metadata.¶

The authorization server treats a delivered statement as the first matching row of the following table provides:¶

An [RFC7592] update request repeats the statement a previous response returned (Section 3.2.1 of [RFC7591]; Section 2.2 of [RFC7592]), which can be older than the governing statement. An [RFC7592] read or update response returns the governing statement as its software_statement member.¶

The replacement MUST satisfy the following:¶

• It validates under Section 3.2 of [STATEMENT].¶

• The iss and sub claims equal those of the governing statement.¶

• The iat claim is later than that of the governing statement.¶

• Its document permits the registration's token_endpoint_auth_method (Section 2 of [STATEMENT]).¶

• For a public-client registration that carries no tenant restriction, its decision is not confined to a tenant (Section 3.1).¶

• Its document, from which the registration's metadata is derived, satisfies the rules of Section 3.¶

Renewing on the statement alone would leave in the registration a key, redirection URI, or scope that the new review removed.¶

A request whose replacement fails the rules above is rejected (Section 7) whether or not the registration has ceased to be valid. A rejected delivery leaves the governing statement unchanged.¶

When a replacement satisfies these rules, the authorization server MUST, in a single atomic update, make it the governing statement and give the registration the replacement's effective expiry, the metadata derived from its document (Section 3), and any tenant restriction it adds (Section 3.1). Concurrent deliveries resolve to the most recently issued statement. A valid replacement restores a registration that has ceased to be valid.¶

Access issued under the registration after that update, including on refresh of a grant issued before it, MUST fall within the re-derived metadata.¶

If every grant a confidential-client registration permits needs an authorization request or a refresh token, and the authorization server does not support [RFC7592] update requests for the registration, the server MUST support pushed authorization requests [RFC9126] for the registration. Otherwise such a client, if it holds no refresh token, could not restore a registration that has ceased to be valid. A public-client registration also renews through a repeated registration request (Section 3.3).¶

7. Error Responses

A rejection this specification defines, at a client registration endpoint or at the client configuration endpoint of [RFC7592], uses the error response of Section 3.2.2 of [RFC7591], with the HTTP status code that section specifies, except that an authorization server SHOULD respond with HTTP status code 503 to a request it rejects with the temporarily_unavailable error code. Such a rejection uses the following error codes:¶

invalid_software_statement:

Any of the following:¶

• The statement is malformed, fails signature or claim validation for a reason unapproved_software_statement does not cover, is expired or otherwise not current (Section 2 of [STATEMENT]), or is superseded under an extension the server implements.¶

• The document's digest does not equal the statement's cimd_digest claim (Section 3).¶

• An [RFC7592] update request is rejected under Section 4.¶

• A statement delivered at the client configuration endpoint, or the statement of a repeated public-client registration request evaluated as a replacement (Section 3.3), fails the replacement rules of Section 6 where this section assigns no other code, such as a document that does not permit the registration's token_endpoint_auth_method.¶

• The statement of a repeated public-client registration request is not the governing statement and has an iat no later than the governing statement's (Section 3.3).¶

unapproved_software_statement:

The statement is well formed but not acceptable here: its issuer is not configured, its aud excludes this server, its sub is outside the client identifier namespaces the issuer can attest, its aud_tenant is not this request's tenant or is absent when required, its issuer is confined to another tenant, or its statement_uses excludes this use. This code is also used if a statement this server requires is absent from a registration request, if Section 3 forbids creating the registration because a required issuer covers the statement's sub and the statement is from another issuer, or if the server's policy refuses a repeated registration request (Section 3.3).¶

invalid_client_metadata:

Any of the following holds for the reviewed document:¶

• It contains duplicate member names (Section 5.2 of [STATEMENT]).¶

• It fails validation as [CIMD] requires (Section 3).¶

• It carries metadata this server's policy refuses.¶

• It cannot be obtained, including over the server's size bound, for a reason other than a retrieval that did not complete (Section 5.3 of [STATEMENT]).¶

• It permits a method based on a shared symmetric secret (Section 3).¶

• It permits no method that the server supports and its policy allows (Section 3).¶

• The server would register the client with none (Section 3) and does not register it under Section 3.2.¶

invalid_redirect_uri:

The reviewed document carries a redirection URI another application could claim (Section 3), or the server would register the client with none and the document lists no redirection URI (Section 3.2).¶

temporarily_unavailable:

A retrieval the request needs did not complete (Section 5.3 of [STATEMENT]).¶

Rejections at other endpoints use the error responses of Section 6 of [STATEMENT]. At the token and pushed authorization request endpoints, a request that fails the authentication of step 2 of Section 5 is rejected with invalid_client. Subject to the order of Section 6 of [STATEMENT], a token, pushed authorization, or authorization request is rejected with statement_required (Section 6.1 of [STATEMENT]) if:¶

• its registration has ceased to be valid, or the required-issuer rule rejects it (Section 4), or¶

• its delivered statement is earlier than the governing statement or fails the replacement rules (Section 6).¶

At the authorization endpoint, the redirect_uri is validated against the registration's redirection URIs before an error is redirected (Section 4.1.2.1 of [RFC6749]).¶

Rejections of a registration management request for other reasons use the responses [RFC7592] specifies, such as the HTTP 403 Forbidden response that Section 3.1 requires.¶

8. Example

The following is a non-normative example of a registered client, whose client_id is s6BhdRkqt3, renewing its registration by delivering a replacement statement on an ordinary refresh, authenticated under its registered private_key_jwt method (line breaks for display purposes only):¶

POST /token HTTP/1.1
Host: as.example
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA
&client_id=s6BhdRkqt3
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3A
client-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6IjIwMjYtMDgifQ...
&software_statement=eyJ0eXAiOiJzb2Z0d2FyZS1zdGF0ZW1l...

The authorization server validates the replacement and re-derives the registration's metadata (Section 6), returning the registration's new expiry in the registration_expires_at member of the token response. Once the registration has ceased to be valid, the same request without a replacement is rejected with statement_required (Section 7).¶

9. Authorization Server Metadata

This specification defines the following authorization server metadata [RFC8414] value:¶

software_statement_registration_supported:

OPTIONAL. Boolean value indicating whether the authorization server supports this specification. If omitted, the default value is false. A value of true means every registration the server creates from a statement of the profile in Section 3 of [STATEMENT] is statement-governed, and does not imply support for runtime presentation.¶

10. Deployment Considerations

This section gives guidance to operators. It adds no requirement.¶

An issuer outage longer than a statement-governed registration's remaining lifetime makes the registration cease to be valid (Section 4) until the client delivers a replacement (Section 6). The lifetimes an issuer chooses set the renewal cadence (Section 12.3 of [STATEMENT]). A deployment ought to have clients renew well before effective expiry, and ought to weigh that cadence against how quickly a narrowed or withdrawn review needs to take effect.¶

A client that delivers a replacement at the token or pushed authorization request endpoint authenticates against the retained registration (step 2 of Section 5). If it rotates a key carried inline in its document's jwks, it authenticates such a request with the outgoing key until a replacement over the new document has been applied, and with the new key afterward. It retires the outgoing key only after that renewal succeeds. An [RFC7592] update request authenticates with the registration access token instead (Section 2 of [RFC7592]).¶

11. Security Considerations

The security considerations of Section 13 of [STATEMENT] and Section 5 of [RFC7591] apply.¶

12. Privacy Considerations

The privacy considerations of Section 14 of [STATEMENT] and Section 6 of [RFC7591] apply. A registration request reveals to the authorization server the same information as a runtime presentation.¶

13. IANA Considerations

14. Normative References

[CIMD]

Parecki, A. and E. Smith, "OAuth Client ID Metadata Document", Work in Progress, Internet-Draft, draft-ietf-oauth-client-id-metadata-document-03, 2 November 2026, <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-03>.

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC6749]

Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, <https://www.rfc-editor.org/rfc/rfc6749>.

[RFC7519]

Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, <https://www.rfc-editor.org/rfc/rfc7519>.

[RFC7591]

Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", RFC 7591, DOI 10.17487/RFC7591, July 2015, <https://www.rfc-editor.org/rfc/rfc7591>.

[RFC7592]

Richer, J., Ed., Jones, M., Bradley, J., and M. Machulak, "OAuth 2.0 Dynamic Client Registration Management Protocol", RFC 7592, DOI 10.17487/RFC7592, July 2015, <https://www.rfc-editor.org/rfc/rfc7592>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

[RFC8414]

Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, June 2018, <https://www.rfc-editor.org/rfc/rfc8414>.

[RFC9126]

Lodderstedt, T., Campbell, B., Sakimura, N., Tonge, D., and F. Skokan, "OAuth 2.0 Pushed Authorization Requests", RFC 9126, DOI 10.17487/RFC9126, September 2021, <https://www.rfc-editor.org/rfc/rfc9126>.

[RFC9700]

Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, "Best Current Practice for OAuth 2.0 Security", BCP 240, RFC 9700, DOI 10.17487/RFC9700, January 2025, <https://www.rfc-editor.org/rfc/rfc9700>.

[STATEMENT]

McGuinness, K., "Client ID Metadata Document Software Statement", Work in Progress, Internet-Draft, draft-mcguinness-oauth-cimd-sw-stmt-00, 2 November 2026, <https://datatracker.ietf.org/doc/html/draft-mcguinness-oauth-cimd-sw-stmt-00>.

Document History

[[ To be removed from the final specification ]]¶

-01¶

• Aligned authentication methods with draft -03 of [CIMD]. The registered token_endpoint_auth_method is a method the reviewed document permits, and a replacement keeps it (Section 6).¶

• A document that declares no authentication method permits only none and is no longer rejected.¶

-00¶

• Initial version.¶

Author's Address