]> Amazon

pdellaer@amazon.com

Security Web Authorization Protocol OAuth Dynamic Client Registration Approval DCR This document specifies an extension to the OAuth 2.0 Dynamic Client Registration Protocol () that enables registration of a client with an authorization server through an explicit approval step performed by an approving party, typically the user running the client, without requiring the client to possess an Initial Access Token (IAT) beforehand. The client submits its desired metadata to the existing client registration endpoint and signals that it can accept a deferred, approval-based registration. When the authorization server requires approval, it defers completion of the registration and returns a 202 (Accepted) response carrying a registration code and a verification challenge. The client polls the same registration endpoint, presenting the registration code. The approving party, authenticated to the authorization server through a mechanism of the authorization server's choosing, responds to the verification challenge and approves or denies the registration. On approval, a subsequent poll returns a registered client identifier and, where applicable, a client secret. This extension preserves the authorization server operator's ability to require an authenticated, policy-controlled approval for every new client record, while removing the operational burden of issuing an Initial Access Token out of band. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction The OAuth 2.0 Dynamic Client Registration Protocol () defines a registration endpoint at which a client presents desired metadata and receives a client identifier and, where applicable, a client secret. supports two modes: open registration, in which any caller may register, and protected registration, in which the caller must present an Initial Access Token (IAT). Section 3 deliberately leaves the method by which an IAT is obtained out of scope. In practice, open registration is unacceptable to many authorization server operators because it permits unbounded database growth, enables denial of service against the registration endpoint, and places no authenticated trust anchor at the root of each client record. Protected registration requires the client to obtain an IAT through some other channel. A growing class of clients, including command-line tools, agentic software, and native applications distributed at scale, cannot feasibly obtain an IAT through a manual out-of-band process. Their authorization servers also cannot accept open registration. No standardized in-band mechanism exists today for these clients to register with an authenticated approval checkpoint. Registration binds a specific client instance to the approving party who authorized it and gives the authorization server a per-instance record it can later manage and revoke (see , and where supported). Making the client identifier self-describing, as the client identifier metadata document of does, can remove the need for a stored registration record but does not by itself establish that per-instance binding; this extension targets deployments that require it. This document specifies a third approach. The client submits its desired metadata to the client registration endpoint defined in and signals, in the request, that it is willing to accept a deferred, approval-based registration. When authorization server policy requires approval, the server defers completion of the registration and returns a 202 (Accepted) response that carries a registration code and a verification challenge, rather than a completed registration. The client polls the same registration endpoint for the result while an approving party (typically the user running the client), separately authenticated to the authorization server, responds to the verification challenge and approves or denies the request. On approval, the authorization server returns the completed registration in response to the next poll. This use of the registration endpoint's response to defer completion, and the requirement that the client signal its willingness before the server defers, follow the pattern of the deferred token response described in . The approving party's identity and authentication mechanism are determined by authorization server policy and are not constrained by this specification. The protocol is the same regardless of who approves. The polling pattern and short-code presentation are inspired by the OAuth 2.0 Device Authorization Grant () but this extension is not a device flow. The outcome is a registered client, not an access token. The initiating party is a client application, which may or may not correspond to a discrete device and may or may not run on a headless device. This specification governs only the registration exchange. It does not constrain where or how the client's metadata is hosted, nor the form of the resulting client_id and client_secret. Where authorization server policy allows, the issued client_id MAY be an HTTPS URL; the client identifier metadata document mechanism of is one such scheme, and its use with this extension is neither required nor precluded.

Protocol Flow

Approval-Based Dynamic Client Registration Flow ---(A)-- Registration Request: -->| | | | Client Metadata, | | | | registration_mode | | | | | | | |<---(B)-- 202 Accepted (pending) -<| | | | Registration Code, | | | | Verification Code, | | | | Verification URI | | | | | | | |>---(C)-- Polling Request -------->| | | |<---(D)-- 202 Accepted (pending) -<| | | | | | | Client | +-----------------+ | Authorization | | | | |>--(E)-->| Server | | | | Approving Party | Review | | | | | | + | | | | | | Approve | | | | +-----------------+ | | | | | | | |>---(F)-- Polling Request -------->| | | |<---(G)-- Registration Response --<| | +----------+ +---------------+ ]]>

The approval-based dynamic client registration flow illustrated in includes the following steps. All requests are made to the client registration endpoint of .

(A):

The client sends its desired client metadata to the registration endpoint, including registration_mode to signal that it can accept an approval-based registration.

(B):

Because approval is required, the authorization server defers the registration and returns a 202 (Accepted) response carrying a registration code, a verification code, and a verification URI.

(C):

The client polls the registration endpoint with the registration code.

(D):

The authorization server returns 202 (Accepted) until the approving party acts.

(E):

The approving party accesses the verification URI, authenticates to the authorization server, reviews the requested metadata or evaluates the client, and approves or denies.

(F):

After approval, the client polls the registration endpoint again with the registration code.

(G):

The authorization server returns the registration outcome.

Terminology 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. This document uses the following terms as defined in : "access token", "authorization code", "authorization endpoint", "authorization server", "client", "client identifier", "client secret", "resource owner", "scope". This document also uses the terms "client metadata" and "Initial Access Token" (IAT) as defined in . The verification_uri, verification_uri_complete, expires_in, and interval fields are reused from Section 3.2 with the same meaning. The registration_code and verification_code fields play the same protocol roles as the device_code and user_code fields of , scoped to client registration.

Approving Party:

An entity authenticated to the authorization server that responds to the verification challenge and approves or denies the client's registration request. The authentication strength and trust model applied to the approving party are determined by authorization server policy. The approving party is deliberately distinct from the "resource owner" and "end-user": this protocol approves the registration of a client, not access to a protected resource, and the approving party is not required to own or control any resource. The approving party's authenticated identity is bound to the resulting registration (see ).

Verification Code:

A short, transcribable code that the approving party presents at the verification URI to identify a specific pending registration.

Verification URI:

A URL at which an approving party completes the approval interaction.

Registration Code:

A long, opaque, high-entropy code that the client uses to poll the client registration endpoint for the outcome of a deferred registration.

Protocol This extension operates at the client registration endpoint defined in Section 3. All requests defined by this specification (registration, polling, and cancellation) MUST be sent to that endpoint. A client signals that it is willing to accept a deferred, approval-based registration through the registration_mode member of its registration request. When authorization server policy requires approval, the server defers the registration and returns a 202 (Accepted) response; the client then polls the same endpoint for the outcome. As required by Section 3, the registration endpoint MUST be protected by a transport-layer security mechanism, and the use of TLS MUST follow the recommendations in . The authorization server MUST NOT redirect requests for the registration endpoint to a URI whose scheme is not HTTPS. Clients MUST NOT follow redirects from the registration endpoint to non-HTTPS URIs.

Registration Request The client sends a client registration request as defined in Section 3.1. To request the approval-based flow defined in this specification, the client additionally includes the following member:

registration_mode:

REQUIRED to request the approval-based flow defined in this specification; otherwise OPTIONAL. A JSON array of registration mode values the client is willing to accept, drawn from the "OAuth Client Registration Modes" registry (). Including the value approval signals that the client is prepared to accept a deferred, approval-based registration and to poll for its outcome. The value immediate, denoting synchronous completion as in , is accepted by every client and need not be listed. Values the authorization server does not recognize MUST be ignored.

The authorization server MUST NOT defer a registration for a request whose registration_mode does not include approval. Including approval does not entitle the client to a deferred registration; the authorization server completes the request synchronously when its policy does not require approval. A registration request that omits registration_mode, or whose registration_mode does not include approval, is an ordinary request: the authorization server either completes it synchronously or rejects it with a registration error, and never defers it. This preserves compatibility with clients that expect a synchronous response. An authorization server that does not support this extension ignores the registration_mode member and processes the request per ; a client detects the absence of support from the resulting synchronous response, or in advance from authorization server metadata (). For example, the client makes the following request:

Registration Response The authorization server applies its policy to the registration request. It returns one of two outcomes.

Immediate Registration If authorization server policy does not require approval for this request (for example, open registration or a request accompanied by an Initial Access Token per ), the authorization server completes the registration synchronously and responds as defined in Section 3.2.1, with an HTTP 201 (Created) status code and the Client Information Response. No polling occurs. This is the ordinary behavior and is unchanged by this specification.

Deferred Registration If authorization server policy requires approval and the client's registration_mode includes approval, the authorization server defers the registration. A deferred registration has been accepted for processing but not yet completed. The authorization server creates a pending registration record and responds with an HTTP 202 (Accepted) status code ( Section 15.3.3), Content-Type: application/json, Cache-Control: no-store, and a JSON object () containing the following members:

registration_code:

REQUIRED. The long, opaque code the client uses to poll the registration endpoint for the outcome.

verification_code:

REQUIRED. The short, transcribable code presented to the approving party at the verification URI to identify a specific pending registration.

verification_uri:

REQUIRED. URL at which the approving party completes approval.

verification_uri_complete:

OPTIONAL. A verification URI that includes the verification_code (or other information with the same function as the verification_code), which is designed for non-textual transmission.

expires_in:

REQUIRED. Lifetime in seconds of the registration_code and the verification_code.

interval:

OPTIONAL. Minimum number of seconds the client MUST wait between polling requests. Defaults to 5. The client MUST retain this value for the lifetime of the registration_code, because subsequent 202 (Accepted) responses need not repeat it.

For example, the authorization server responds:

Registration Request Error Responses When a registration request is malformed or otherwise rejected before any pending registration is created, the authorization server returns an error response as defined in Section 3.2.2: an HTTP 400 (Bad Request) status code, a Content-Type of application/json, a Cache-Control: no-store response header, and a JSON object with error and OPTIONAL error_description members. The error codes invalid_redirect_uri, invalid_client_metadata, invalid_software_statement, and unapproved_software_statement are used as defined in Section 3.2.2. If authorization server policy requires approval but the client's registration_mode does not include approval, the authorization server cannot complete the registration synchronously and MUST NOT defer it (see ); it rejects the request with a registration error as described here, using invalid_client_metadata unless a more specific code applies.

Registration Polling After receiving a 202 (Accepted) response, the client polls for the outcome by sending further requests to the same client registration endpoint. The polling pattern is adopted from Section 3.4. Because this extension operates at the registration endpoint, whose success status is 201 (Created), a pending registration is conveyed with 202 (Accepted), a requirement to poll less frequently with 429 (Too Many Requests), and a failed registration with 400 (Bad Request).

Polling Request The client sends an HTTP POST to the registration endpoint. The request body MUST be a JSON object () and the Content-Type header MUST be application/json. The presence of a registration_code member distinguishes a polling request from a registration request.

registration_code:

REQUIRED. The value received in the deferred registration response.

The registration_code is a bearer credential: presenting it is sufficient to poll for and complete the pending registration it identifies. It MUST be protected accordingly, both in transit (all requests use TLS, see ) and by the authorization server (see ). For example, the client makes the following request:

Polling Response While Pending While the approving party has not yet completed the approval action, the authorization server responds to each poll with an HTTP 202 (Accepted) status code, indicating that the registration remains pending and the client SHOULD continue polling. Before each new polling request, the client MUST wait at least the number of seconds specified by the interval member of the deferred registration response, or 5 seconds if none was provided, and MUST respect any increase in the polling interval required by a 429 (Too Many Requests) response (see ). The 202 (Accepted) response body MAY be empty. The client retains the registration_code, interval, and expires_in values from the deferred registration response; a 202 response need not repeat them. The following is a non-normative example of a 202 (Accepted) response while the client polls before approval has completed:

Polling Rate Limiting When the authorization server requires the client to poll less frequently, it responds with an HTTP 429 (Too Many Requests) status code ( Section 4) and a Retry-After header ( Section 10.2.3) giving the minimum number of seconds the client MUST wait before its next poll. The client MUST increase its polling interval to at least the Retry-After value for this and all subsequent requests. A 429 response indicates that the registration remains pending; the client SHOULD continue polling. This response plays the role of the slow_down response of Section 3.5. The following is a non-normative example of a 429 (Too Many Requests) response:

Polling Response on Success Once the approving party has approved the registration, the next poll completes the registration. The authorization server responds with an HTTP 201 (Created) status code and a body identical in structure to the Client Information Response of Section 3.2.1. Where the authorization server supports the registration management protocol of , the response additionally includes the registration_access_token and registration_client_uri fields defined in Section 3, as shown in the example below. The registration_code is consumed and MUST NOT be usable again. The following is a non-normative example response body: Subsequent management of the registered client, including retrieval, update, and deletion, is performed as defined in using the registration_access_token and registration_client_uri returned above.

Polling Error Responses When the registration cannot be completed, the authorization server returns an error response with an HTTP 400 (Bad Request) status code, a Content-Type of application/json, a Cache-Control: no-store response header, and a JSON object using the error and OPTIONAL error_description members of the error response defined in Section 5.2, as also used by the registration error response of Section 3.2.2. A 400 (Bad Request) response is terminal: the client MUST stop polling. The error codes access_denied and expired_token are adopted from Section 3.5. The following error codes are defined for use when polling the registration endpoint under this specification:

access_denied:

The approving party denied the registration. The client MUST stop polling.

expired_token:

The registration_code has expired and the pending registration is no longer valid. The client MUST stop polling. The client MAY make a new registration request, but SHOULD wait for user interaction before doing so to avoid unnecessary polling.

invalid_registration:

The pending registration cannot be completed. The registration_code is unknown to the authorization server or has already been consumed. These conditions are deliberately not distinguished, to avoid leaking pending-registration state to unauthenticated callers. The client MUST stop polling. The client MAY make a new registration request, but SHOULD do so only in response to user action to avoid unnecessary polling.

On encountering a connection timeout or other transient transport error, clients MUST reduce their polling frequency before retrying, following the same guidance as documented in Section 3.5. The use of an exponential backoff algorithm, such as doubling the polling interval on each connection timeout, is RECOMMENDED. The following is a non-normative example of an invalid_registration response:

Cancellation A client that has initiated a deferred registration MAY cancel it before it is approved, for example when the user abandons the client. The client sends an HTTP POST to the registration endpoint with a JSON body containing the registration_code and a cancel_registration member set to true.

cancel_registration:

REQUIRED to request cancellation. Boolean. When true, the authorization server discards the pending registration identified by registration_code. A polling request omits this member (or sets it to false).

Presenting the registration_code authorizes cancellation, just as it authorizes polling. On success, the authorization server discards the pending registration and responds with an HTTP 204 (No Content) status code. For a registration_code that is unknown or already consumed, including one consumed by a prior cancellation or completion, the authorization server responds with invalid_registration as defined in and does not disclose whether a matching pending registration exists. Cancellation by the client is distinct from denial by the approving party; either results in the pending registration no longer being completable. For example, the client cancels a pending registration:

Approval Interaction The approving party interaction described in Section 3.3 of is applicable to the approval interaction of this protocol. The approving party is presented with the verification_uri and verification_code and asked to access the URI in a user agent of their choosing, such as a web browser or a native application capable of handling the URI. This can be on the same device, or on a different device. The authorization server MUST authenticate the approving party and MUST use a secure TLS-protected session. The approving party MUST provide the verification_code before the process can continue. The authorization server SHOULD present the approving party with a clear description of the action the client is trying to complete and request their approval or denial. The authorization server MUST present the approving party with the effective client metadata to be registered. In case verification_uri_complete is provided, clients MAY present this in a non-textual manner, including using a QR (Quick Response) code or NFC (Near Field Communication). The client SHOULD present the verification_uri and MUST present the verification_code. The authorization server SHOULD display the verification_code so the approving party is able to verify with the displayed code from the client. This flow does not change the authentication and approval requirements, it provides an approving party an optimization to not enter the code manually. This specification does not specify the mechanism by which the authorization server authenticates the approving party or the user agent through which approval is performed. The mechanism, authentication strength, and any additional policy applied to the approving party are determined by authorization server policy.

Approver Association A registration produced by this flow is associated with the specific authenticated approver who approved it. Authorization server implementations SHOULD retain this association so that the resulting client can later be managed or revoked through an approver-driven workflow. This specification does not define such a workflow; what is recorded, how the association is surfaced to the approver, and how revocation is exposed are determined by authorization server policy. Protocol-level management and revocation of a completed client registration remain as defined in , using the registration_access_token and registration_client_uri returned in the polling response.

Authorization Server Metadata This extension defines the following addition to the OAuth 2.0 Authorization Server Metadata () registry.

registration_modes_supported:

OPTIONAL. JSON array listing the client registration modes supported at the authorization server's registration_endpoint. Values are registered in the "OAuth Client Registration Modes" registry established by this document (). This document defines two values: immediate, indicating that a registration request may complete synchronously in the registration response as defined in ; and approval, indicating that the authorization server supports the deferred, approval-based flow defined in this specification. An authorization server supporting this specification MUST include approval in this array.

A client discovers support for the approval-based flow by the presence of approval in registration_modes_supported. A client MAY also include registration_mode with the value approval in its registration request without prior discovery; if the authorization server does not support this extension it ignores the member and the registration is processed per .

Security Considerations The Security Considerations of Section 5 are applicable to this protocol, in particular the requirement that the registration endpoint be protected by a transport-layer security mechanism ( Section 3 and Section 5, with for TLS configuration). Because this extension operates at the client registration endpoint, the general OAuth security recommendations of also apply.

Registration Endpoint Abuse The approval-based flow can be initiated without authentication. An attacker can submit a high volume of registration requests to exhaust the authorization server's pending-registration state or to mint many verification codes in the hope of a social engineering attack. The authorization server SHOULD apply rate-limiting to the registration endpoint.

Verification Code Phishing An attacker can initiate a registration, obtain a verification code, and trick a victim into approving the attacker's registration under the victim's account. The attacker's client then receives client credentials associated with the victim's approval at the authorization server. This is the registration equivalent of the device phishing attack in Section 5.4 and is not eliminated by this extension. To mitigate the risk, authorization servers MUST inform the approving party that they are registering a new client, including the client name, timestamp, and registration details. When the verification_uri_complete optimization is used, the authorization server MUST display the verification code for the approving party to verify the same code is shown by the client. The verification code SHOULD have a short lifetime and SHOULD be single-use to make it harder for an attacker to phish targets.

Verification Code Brute Forcing The verification code is short to allow human transcription. An attacker who can submit many verification codes against the verification URI could locate a pending registration not their own and attempt to trick another approving party into approving it. The authorization server MUST rate-limit verification code submission per source IP and per authenticated approver, MUST reject expired or already-consumed verification codes, and MUST require an explicit approval action (not auto-confirm on code entry). Guidance in Section 5.1 applies directly.

Registration Code Compromise The registration_code is a bearer credential: any party that possesses it can poll for and complete, or cancel, the pending registration it identifies. Unlike the device_code of , which the client presents together with its client_id and, where applicable, client authentication, the registration_code is presented on its own, because the client is not yet registered and has no credentials; the registration_code is therefore the sole protection for the pending registration. An attacker who guesses, intercepts, or otherwise obtains a registration_code (for example through a TLS-terminating intermediary, a server log, or a brute-force attempt) can therefore complete the registration in place of the legitimate client, receiving the issued client_id and, where applicable, client_secret. Protection of the registration_code is essential. Accordingly, the authorization server MUST protect the registration endpoint with a transport-layer security mechanism ( Section 3, with for TLS configuration). The registration_code MUST contain at least 128 bits of entropy (160 bits RECOMMENDED), drawn from a cryptographically secure random source per Section 10.10, and MUST NOT be guessable. It SHOULD have a short lifetime, bounded by the expires_in returned in the deferred registration response, and MUST be single-use, becoming unusable once the registration is completed, denied, cancelled, or expired. The authorization server SHOULD store the registration_code in hashed form, so that read access to its pending-registration store does not yield a usable code, and SHOULD apply the brute-force mitigations recommended in Section 5.2 to polling requests. Authorization servers MUST NOT treat possession of a registration_code as an authorization grant. It authorizes nothing beyond completing or cancelling the single pending registration it identifies.

Registration Cancellation Cancellation of a pending registration () is authorized by presenting the registration_code, exactly as polling is. It therefore inherits the same protection requirements as the registration_code itself (). A cancellation request only discards pending registration state; it returns no credentials and discloses no information about whether a matching pending registration existed, returning invalid_registration for an unknown or already-consumed code exactly as a poll does.

Privacy Considerations The privacy considerations of Section 6 apply to client metadata exchanged through this protocol. In addition, the verification URI approval interaction surfaces client metadata to the approving party, and client authors SHOULD assume all metadata in the registration request may be visible to the approving party and to the authorization server operator.

Approver Identity Linkability The authorization server learns, for every approved registration, which approver authenticated to approve it. Authorization server operators are therefore able to link a given approver to the set of clients that approver has registered. This linkage may be retained for audit, revocation, and management purposes (see ). Authorization servers SHOULD apply the same retention and access-control policies to this linkage as they do to other authorization decisions made by the same approver.

Denied and Expired Registrations Authorization servers MAY retain records of denied or expired registration requests for security monitoring (for example, to detect repeated phishing attempts as in Section 5.4). Such records may include the submitted client metadata, the approver who denied the request, and metadata about the approval session. Authorization servers SHOULD bound the retention of these records and SHOULD NOT use them for purposes beyond security operations.

Verification URI Access Logs Access to the verification URI typically generates server-side logs containing the approver's IP address, user-agent, authentication context, and timestamp. These logs may be more sensitive than logs for ordinary authorization endpoints because they tie a specific human approver to a specific newly registered client. Authorization server operators SHOULD treat these logs accordingly.

IANA Considerations

OAuth Authorization Server Metadata IANA is requested to register the following entries in the "OAuth Authorization Server Metadata" registry established by .

Registration Modes Supported

Metadata Name:

registration_modes_supported

Metadata Description:

JSON array containing a list of the client registration modes supported at the authorization server's registration endpoint.

Change Controller:

IESG

Specification Document(s):

This document

OAuth Dynamic Client Registration Metadata IANA is requested to register the following entry in the "OAuth Dynamic Client Registration Metadata" registry established by .

Registration Mode

Client Metadata Name:

registration_mode

Client Metadata Description:

A JSON array of client registration mode values the client is willing to accept for this registration request.

Change Controller:

IESG

Specification Document(s):

This document

The registration_code, verification_code, and cancel_registration members defined by this document are exchanged only within the flow defined here and are not registered as OAuth parameters, following the approach taken for the user_code and verification_uri fields of .

OAuth Client Registration Modes This document establishes the IANA "OAuth Client Registration Modes" registry. Client registration mode values, used in the registration_modes_supported authorization server metadata field, are registered with a Specification Required () after a two-week review period on the oauth-ext-review@ietf.org mailing list, on the advice of one or more Designated Experts. However, to allow for the allocation of values prior to publication, the Designated Experts may approve registration once they are satisfied that such a specification will be published, per . Registration requests sent to the mailing list for review should use an appropriate subject (e.g., "Request to register client registration mode: example"). Within the review period, the Designated Experts will either approve or deny the registration request, communicating this decision to the review list and IANA. Denials should include an explanation and, if applicable, suggestions as to how to make the request successful. IANA must only accept registry updates from the Designated Experts and should direct all requests for registration to the review mailing list.

Registration Template

Registration Mode Name:

The name requested (e.g., approval). This name is case sensitive. Names that match other registered names in a case-insensitive manner SHOULD NOT be accepted.

Registration Mode Description:

Brief description of the registration mode's behavior, including how and when the registration outcome is returned.

Change Controller:

For Standards Track RFCs, list "IESG". For others, give the name of the responsible party.

Specification Document(s):

Reference to the document or documents that specify the registration mode, preferably including a URI that can be used to retrieve a copy.

Initial Registry Contents

Immediate

Registration Mode Name:

immediate

Registration Mode Description:

The registration request may complete synchronously, with the Client Information Response returned directly in the registration response as defined in .

Change Controller:

IESG

Specification Document(s):

This document

Approval

Registration Mode Name:

approval

Registration Mode Description:

The authorization server may defer the registration for approval by an approving party, returning a 202 (Accepted) response that the client polls to obtain the outcome, as defined in this document.

Change Controller:

IESG

Specification Document(s):

This document

OAuth Extensions Error Registry IANA is requested to register the following entries in the "OAuth Extensions Error Registry" established by .

Invalid Registration

Name:

invalid_registration

Usage Location:

client registration polling response, client registration cancellation response

Protocol Extension:

OAuth 2.0 Approval-Based Dynamic Client Registration

Change Controller:

IESG

Reference:

This document

The access_denied and expired_token error codes used when polling are defined by and are not re-registered by this document.

References Normative References 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. This document specifies additional HyperText Transfer Protocol (HTTP) status codes for a variety of common situations. [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 memo describes the process for early allocation of code points by IANA from registries for which "Specification Required", "RFC Required", "IETF Review", or "Standards Action" policies apply. This process can be used to alleviate the problem where code point allocation is needed to facilitate desired or required implementation and deployment experience prior to publication of an RFC, which would normally trigger code point allocation. The procedures in this document are intended to apply only to IETF Stream documents. 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 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. Many protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA). To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry. This is the third edition of this document; it obsoletes RFC 5226. 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. 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 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 OAuth 2.0 device authorization grant is designed for Internet- connected devices that either lack a browser to perform a user-agent- based authorization or are input constrained to the extent that requiring the user to input text in order to authenticate during the authorization flow is impractical. It enables OAuth clients on such devices (like smart TVs, media consoles, digital picture frames, and printers) to obtain user authorization to access protected resources by using a user agent on a separate device. 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. Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) are used to protect data exchanged over a wide range of application protocols and can also form the basis for secure transport protocols. Over the years, the industry has witnessed several serious attacks on TLS and DTLS, including attacks on the most commonly used cipher suites and their modes of operation. This document provides the latest recommendations for ensuring the security of deployed services that use TLS and DTLS. These recommendations are applicable to the majority of use cases. RFC 7525, an earlier version of the TLS recommendations, was published when the industry was transitioning to TLS 1.2. Years later, this transition is largely complete, and TLS 1.3 is widely available. This document updates the guidance given the new environment and obsoletes RFC 7525. In addition, this document updates RFCs 5288 and 6066 in view of recent attacks. 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. Informative References 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. Idura Itaú Twilio This document defines the Deferred Token Response (DTR) extension for OAuth 2.1. In existing OAuth grants, the token endpoint either issues an access token or returns an error. DTR establishes a generic asynchronous token request mechanism that any OAuth grant may plug into. In DTR-aware flows, the authorization server returns a deferral_code and a polling interval, indicating that the final token response will be available at a later time. The client retrieves the eventual response by polling the token endpoint, or by receiving a callback from the authorization server when one is configured.

Example Use Cases

Minimal Registration with Human User Approval A client registers itself against an authorization server. The approving party is a human user who visits the verification URI in a browser tab already authenticated to the authorization server.

1. The client POSTs its metadata to the registration endpoint with registration_mode: ["approval"].
2. Because approval is required, the authorization server returns a 202 (Accepted) response with a registration_code, verification_code, and verification_uri.
3. The client displays: "Visit https://as.example.com/register-verification and enter code FBWS-TRGI".
4. The user visits the URI, enters the code, sees "Example Client wants to register. Approve?", and clicks Approve.
5. The client's next poll to the registration endpoint returns client_id and client_secret.

Registration Producing a URL Client Identifier A client registers against an authorization server whose policy issues an HTTPS URL as the client_id, which the authorization server later resolves as a client identifier metadata document (). The approval-based flow is unchanged; only the form of the issued client_id differs.

1. The client POSTs its metadata to the registration endpoint with registration_mode: ["approval"].
2. The authorization server returns a 202 (Accepted) response with a registration_code and verification data. The client encodes verification_uri_complete as a QR code.
3. The approving party scans the QR code, authenticates, reviews the client metadata, and approves.
4. The client's next poll returns a Client Information Response whose client_id is an HTTPS URL.

High-Assurance Approval via a Native Application A command-line client on a shared workstation registers against an authorization server whose policy requires a high level of assurance for the approving party. Approval is completed in the authorization server operator's own mobile application rather than a web browser, allowing the operator to combine account authentication, application attestation, and a biometric check in the approval step.

1. The client POSTs its metadata to the registration endpoint with registration_mode: ["approval"].
2. The authorization server returns a 202 (Accepted) response with a registration_code and a verification_uri_complete. The client renders the verification_uri_complete as a QR code and displays the verification_code alongside it.
3. The approving party opens the verification_uri_complete in the operator's mobile application, which handles the URI directly. The application verifies the approving party against their existing account, attests its own integrity to the authorization server, and requires a biometric confirmation.
4. The application displays the client name and the metadata to be registered together with the verification_code, which the approving party checks against the code shown by the client, and the approving party approves.
5. The client's next poll returns client_id and client_secret.

Acknowledgments This document draws structural inspiration and significant protocol mechanics from the OAuth 2.0 Device Authorization Grant () by William Denniss, John Bradley, Michael B. Jones, and Hannes Tschofenig. The polling pattern and verification code/URI presentation in this specification are direct adaptations of that work. The approach of deferring completion at an existing endpoint, rather than defining a new endpoint, follows the deferred token response described in . This document extends the OAuth 2.0 Dynamic Client Registration Protocol () by Justin Richer (Editor), Michael B. Jones, John Bradley, Maciej Machulak, and Phil Hunt, and is intended to interoperate with the OAuth 2.0 Dynamic Client Registration Management Protocol () by Justin Richer (Editor), Michael B. Jones, John Bradley, and Maciej Machulak. The author thanks Jeff Lombardo and Ashay Raut for their review and feedback.