RFC 7591

OAuth 2.0 Dynamic Client Registration Protocol

📅 published July 2015, from ietf

RFC 7591: OAuth 2.0 Dynamic Client Registration Protocol 🦋

Okay bestie, let's get the deets first 💅 This is RFC 7591, published by the IETF in July 2015. It's on the Standards Track, and its ISSN is 2070-1721. The editor is J. Richer, and the co-authors are M. Jones (Microsoft), J. Bradley (Ping Identity), M. Machulak (Newcastle University), and P. Hunt (Oracle Corporation). The title block doesn't list anything it obsoletes or updates, so it's not marked as replacing or amending any other RFC ✨

Abstract

Okay so this spec is all about how an OAuth 2.0 client can sign itself up with an authorization server 🫶 Instead of doing it by hand, the client sends a registration request with the client metadata values it wants. The server replies with a client identifier it'll use for that client, plus the metadata values it actually registered. Then the client can talk to the authorization server using OAuth 2.0 with all that info in hand. The spec also defines a set of common client metadata fields and values for clients to use while registering. It's giving organization, honestly 🌸

Status of This Memo

This is an Internet Standards Track document 👑

It's a product of the Internet Engineering Task Force (IETF) and represents the consensus of the IETF community. It went through public review and was approved for publication by the Internet Engineering Steering Group (IESG). If you want more on Internet Standards, check out Section 2 of RFC 5741 📚

For info on the current status of this document, any errata, and how to send feedback, go to http://www.rfc-editor.org/info/rfc7591 🔗

Copyright (c) 2015 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 (http://trustee.ietf.org/license-info) as they're in effect on the date this document was published. Please read these carefully, because they describe your rights and restrictions for this document 🥹 Code Components pulled out of this document must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come with no warranty, as described in the Simplified BSD License ⚖️

Table of Contents

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   4
  1.1.  Notational Conventions  . . . . . . . . . . . . . . . . .   4
  1.2.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   4
  1.3.  Protocol Flow . . . . . . . . . . . . . . . . . . . . . .   7
2.  Client Metadata . . . . . . . . . . . . . . . . . . . . . . .   8
  2.1.  Relationship between Grant Types and Response Types . . .  12
  2.2.  Human-Readable Client Metadata  . . . . . . . . . . . . .  13
  2.3.  Software Statement  . . . . . . . . . . . . . . . . . . .  14
3.  Client Registration Endpoint  . . . . . . . . . . . . . . . .  15
  3.1.  Client Registration Request . . . . . . . . . . . . . . .  16
    3.1.1.  Client Registration Request Using a Software
            Statement . . . . . . . . . . . . . . . . . . . . . .  18
  3.2.  Responses . . . . . . . . . . . . . . . . . . . . . . . .  19
    3.2.1.  Client Information Response . . . . . . . . . . . . .  19
    3.2.2.  Client Registration Error Response  . . . . . . . . .  21
4.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  23
  4.1.  OAuth Dynamic Client Registration Metadata Registry . . .  22
    4.1.1.  Registration Template . . . . . . . . . . . . . . . .  24
    4.1.2.  Initial Registry Contents . . . . . . . . . . . . . .  24
  4.2.  OAuth Token Endpoint Authentication Methods Registry  . .  27
    4.2.1.  Registration Template . . . . . . . . . . . . . . . .  28
    4.2.2.  Initial Registry Contents . . . . . . . . . . . . . .  28
5.  Security Considerations . . . . . . . . . . . . . . . . . . .  28
6.  Privacy Considerations  . . . . . . . . . . . . . . . . . . .  32
7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  33
  7.1.  Normative References  . . . . . . . . . . . . . . . . . .  33
  7.2.  Informative References  . . . . . . . . . . . . . . . . .  35
Appendix A.  Use Cases  . . . . . . . . . . . . . . . . . . . . .  33
  A.1.  Open versus Protected Dynamic Client Registration . . . .  34
    A.1.1.  Open Dynamic Client Registration  . . . . . . . . . .  34
    A.1.2.  Protected Dynamic Client Registration . . . . . . . .  34
  A.2.  Registration without or with Software Statements  . . . .  34
    A.2.1.  Registration without a Software Statement . . . . . .  34
    A.2.2.  Registration with a Software Statement  . . . . . . .  34
  A.3.  Registration by the Client or Developer . . . . . . . . .  34
    A.3.1.  Registration by the Client  . . . . . . . . . . . . .  35
    A.3.2.  Registration by the Developer . . . . . . . . . . . .  35
  A.4.  Client ID per Client Instance or per Client Software  . .  35
    A.4.1.  Client ID per Client Software Instance  . . . . . . .  35
    A.4.2.  Client ID Shared among All Instances of Client
            Software  . . . . . . . . . . . . . . . . . . . . . .  35
  A.5.  Stateful or Stateless Registration  . . . . . . . . . . .  35
    A.5.1.  Stateful Client Registration  . . . . . . . . . . . .  36
    A.5.2.  Stateless Client Registration . . . . . . . . . . . .  36
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .  36
Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  36

1. Introduction ✨

Okay so, for an OAuth 2.0 [RFC6749] client to use an OAuth 2.0 authorization server, it needs specific info to talk to that server. That includes an OAuth 2.0 client identifier to use at that server 🧚 This spec explains how an OAuth 2.0 client can register itself dynamically with an authorization server to get that info.

As part of registering, this spec also gives the client a way to hand the authorization server a set of metadata, like a list of valid redirection URIs 💜 That metadata can either be self-asserted, meaning the client just says it, or it can come as a set of metadata called a software statement. A software statement is digitally signed or protected with a Message Authentication Code (MAC). With a software statement, the issuer is basically vouching that the data about the client is legit 🫶

Traditionally, registering a client with an authorization server is done manually, which is giving tedious energy 🙄 The mechanisms in this spec can be used either by a client that wants to register itself with authorization servers, or by a client developer who wants to register the client with authorization servers programmatically. Lots of OAuth 2.0 apps already came up with their own ways of doing these registrations. This spec generalizes the registration mechanisms from "OpenID Connect Dynamic Client Registration 1.0" [OpenID.Registration], which "User Managed Access (UMA) Profile of OAuth 2.0" [UMA-Core] also uses. It's designed to work with both, and it's applicable to a wider set of OAuth 2.0 use cases 🌈

1.1. Notational Conventions

The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this document are to be interpreted as described in [RFC2119] 📖

Unless otherwise noted, all the protocol parameter names and values are case sensitive 🔠

1.2. Terminology ✨

okay so this spec borrows a bunch of words from OAuth 2.0 [RFC6749] like "access token", "authorization code", "authorization endpoint", "authorization grant", "authorization server", "client", "client identifier", "client secret", "grant type", "protected resource", "redirection URI", "refresh token", "resource owner", "resource server", "response type", and "token endpoint" 🧚 It also grabs the word "Claim" from JSON Web Token (JWT) [RFC7519]. no need to reinvent the wheel bestie 💅

ok now the new terms this spec actually defines 🦋

Client Software Software that implements an OAuth 2.0 client. 💻

Client Instance A deployed instance of a piece of client software. 🚀

Client Developer The person or organization that builds a client software package and prepares it for distribution. at the time the client gets built, the developer is often not aware of who the deploying service provider organizations will be 😭 client developers will need to use dynamic registration when they can't predict parts of the software, like the deployment URLs, at compile time. this can happen when the software API publisher and the deploying organization are not the same. it's giving "we don't know who's hosting this yet" energy 🎀

Client Registration Endpoint An OAuth 2.0 endpoint where a client can get registered at an authorization server. how you find out the URL for this endpoint is out of scope for this spec 🙈

Initial Access Token An OAuth 2.0 access token that an authorization server can optionally issue to a developer or client, used to authorize calls to the client registration endpoint. the type and format of this token are likely service specific and out of scope for this spec. how the authorization server issues it, and how the registration endpoint validates it, are both out of scope too 🫶 use of an initial access token is required when the authorization server limits the parties that can register a client. main character gatekeeping 👑

Deployment Organization An administrative security domain under which a software API (service) is deployed and protected by an OAuth 2.0 framework. in some OAuth scenarios, the deployment organization and the software API publisher are the same. in those cases, the deploying organization will often have a close relationship with client software developers. but in lots of other cases, the definer of the service might be an independent third-party publisher or a standards organization. when you're working to a published specification for an API, the client software developer can't have a prior relationship with the potentially many deployment organizations deploying the software API (service) 🌸

Software API Deployment A deployed instance of a software API that's protected by OAuth 2.0 (a protected resource) inside a particular deployment organization domain. for any given software API, there can be one or more deployments. a software API deployment typically comes with an associated OAuth 2.0 authorization server and a client registration endpoint. how those endpoints get obtained is out of scope for this spec ✨

Software API Publisher The organization that defines a particular web-accessible API that might be deployed in one or more deployment environments. a publisher can be any standards body, commercial, public, private, or open source organization responsible for publishing and distributing software and API specifications that may be protected via OAuth 2.0. sometimes a software API publisher and a client developer are the same organization. when a web-accessible API gets published, the software publisher often doesn't have a prior relationship with the deploying organizations 🍓

Software Statement A digitally signed or MACed JSON Web Token (JWT) [RFC7519] that asserts metadata values about the client software. sometimes a software statement is issued directly by the client developer. other times, a third-party organization issues it for the client developer to use. either way, the trust relationship the authorization server has with the issuer of the software statement is meant to be used as an input when deciding whether the registration request gets accepted. a software statement can be presented to an authorization server as part of a client registration request 🔥

1.3. Protocol Flow 🌈

        +--------(A)- Initial Access Token (OPTIONAL)
        |
        |   +----(B)- Software Statement (OPTIONAL)
        |   |
        v   v
    +-----------+                                      +---------------+
    |           |--(C)- Client Registration Request -->|    Client     |
    | Client or |                                      | Registration  |
    | Developer |<-(D)- Client Information Response ---|   Endpoint    |
    |           |        or Client Error Response      +---------------+
    +-----------+

Figure 1: Abstract Dynamic Client Registration Flow

okay so Figure 1 is the big picture of the abstract OAuth 2.0 client dynamic registration flow 🦋 it shows the back and forth between the client or developer and the endpoint this spec defines. the figure doesn't show error conditions, so don't look for those here 🙈 the flow has these steps:

(A) Optionally, the client or developer gets issued an initial access token that gives access to the client registration endpoint. how the initial access token gets issued to the client or developer is out of scope for this spec 🎀

(B) Optionally, the client or developer gets issued a software statement for use with the client registration endpoint. how the software statement gets issued to the client or developer is also out of scope 💅

(C) The client or developer calls the client registration endpoint with the client's desired registration metadata, optionally including the initial access token from (A) if the authorization server requires one 🫶

(D) The authorization server registers the client and returns:

  • the client's registered metadata,
  • a client identifier that's unique at the server, and
  • a set of client credentials, such as a client secret, if that's applicable for this client. ✨

Examples of different configurations and usages are included in Appendix A. go check those out, they're iconic 💖

2. Client Metadata ✨

okay so registered clients get a whole bundle of metadata tied to their client_id at an authorization server 🎀 think of it like a profile: the list of valid redirection URIs, a display name, the works 💅

these metadata values do two jobs, bestie 🫶:

  • they're input values in registration requests, and
  • they're output values in registration responses.

here are the client metadata fields this spec defines 🦋 implementing and using every one of them is OPTIONAL, unless the spec says otherwise. all data member types (strings, arrays, numbers) are defined in terms of their JSON [RFC7159] representations 💖

redirect_uris

an array of redirection URI strings for redirect-based flows like the authorization code and implicit flows 🌸 as [RFC6749] Section 2 asks, clients using flows with redirection MUST register their redirection URI values 😭 and authorization servers that support dynamic registration for redirect-based flows MUST implement support for this metadata value 💅

token_endpoint_auth_method

a string that says which authentication method the client wants at the token endpoint 🧚 the values this spec defines are:

  • "none": the client is a public client as defined in OAuth 2.0, Section 2.1, and doesn't have a client secret 🍓
  • "client_secret_post": the client uses the HTTP POST parameters as defined in OAuth 2.0, Section 2.3.1 💜
  • "client_secret_basic": the client uses HTTP Basic as defined in OAuth 2.0, Section 2.3.1 🔥

more values can be added through the IANA "OAuth Token Endpoint Authentication Methods" registry set up in Section 4.2 ✨ absolute URIs can also be used as values for this parameter without being registered 🌈 if it's unspecified or omitted, the default is "client_secret_basic", which is the HTTP Basic authentication scheme from Section 2.3.1 of OAuth 2.0 👑

grant_types

an array of OAuth 2.0 grant type strings the client can use at the token endpoint 🦋 the grant types are:

  • "authorization_code": the authorization code grant type from OAuth 2.0, Section 4.1 💖
  • "implicit": the implicit grant type from OAuth 2.0, Section 4.2 🌸
  • "password": the resource owner password credentials grant type from OAuth 2.0, Section 4.3 ✨
  • "client_credentials": the client credentials grant type from OAuth 2.0, Section 4.4 🎀
  • "refresh_token": the refresh token grant type from OAuth 2.0, Section 6 🫶
  • "urn:ietf:params:oauth:grant-type:jwt-bearer": the JWT Bearer Token Grant Type from OAuth JWT Bearer Token Profiles [RFC7523] 🔥
  • "urn:ietf:params:oauth:grant-type:saml2-bearer": the SAML 2.0 Bearer Assertion Grant from OAuth SAML 2 Bearer Token Profiles [RFC7522] 💅

if the token endpoint is used by the grant type, this parameter's value MUST be the same as the "grant_type" parameter passed to the token endpoint in the grant type's definition 😭 authorization servers MAY allow other values through the grant type extension process in OAuth 2.0, Section 4.5 🌈 if it's omitted, the default is that the client only uses the "authorization_code" grant type 💜

response_types

an array of OAuth 2.0 response type strings the client can use at the authorization endpoint 🌸 the response types are:

  • "code": the authorization code response type from OAuth 2.0, Section 4.1 🦋
  • "token": the implicit response type from OAuth 2.0, Section 4.2 ✨

if the grant type uses the authorization endpoint, this parameter's value MUST be the same as the "response_type" parameter passed to the authorization endpoint in the grant type's definition 🍓 authorization servers MAY allow other values through the grant type extension process described in OAuth 2.0, Section 4.5 🎀 if omitted, the default is that the client only uses the "code" response type 🧚

client_name

a human-readable name for the client, shown to the end-user during authorization 💖 if it's omitted, the authorization server MAY show the raw "client_id" value to the end-user instead 🙈 clients RECOMMENDED to always send this field, so it's RECOMMENDED that clients always send it ✨ the value of this field MAY be internationalized, as described in Section 2.2 🌈

client_uri

a URL string pointing to a web page with info about the client 🫶 if it's present, the server SHOULD display this URL to the end-user as a clickable link 💅 it's RECOMMENDED that clients always send this field 🔥 the value of this field MUST point to a valid web page 😭 and it MAY be internationalized, as described in Section 2.2 🌸

logo_uri

a URL string referencing a logo for the client 🦋 if it's present, the server SHOULD display this image to the end-user during approval ✨ the value of this field MUST point to a valid image file 👑 and it MAY be internationalized, as described in Section 2.2 💖

scope

a string holding a space-separated list of scope values (as described in Section 3.3 of OAuth 2.0 [RFC6749]) that the client can use when requesting access tokens 🎀 what the values in this list mean is service specific 🧚 if it's omitted, an authorization server MAY register the client with a default set of scopes 🌈

contacts

an array of strings for ways to reach the people responsible for this client, typically email addresses 💜 the authorization server MAY make these contact addresses available to end-users for support requests about the client 🫶 see Section 6 for Privacy Considerations 🔒

tos_uri

a URL string pointing to a human-readable terms of service document for the client 📜 it describes the contractual relationship between the end-user and the client, which the end-user accepts when authorizing the client 💅 the authorization server SHOULD display this URL to the end-user if it's provided 🌸 the value of this field MUST point to a valid web page ✨ and it MAY be internationalized, as described in Section 2.2 🦋

policy_uri

a URL string pointing to a human-readable privacy policy document 🫧 it explains how the deployment organization collects, uses, retains, and discloses personal data 🎀 the authorization server SHOULD display this URL to the end-user if it's provided 💖 the value of this field MUST point to a valid web page 🔥 and it MAY be internationalized, as described in Section 2.2 👑

jwks_uri

a URL string referencing the client's JSON Web Key (JWK) Set [RFC7517] document, which holds the client's public keys 🔑 the value of this field MUST point to a valid JWK Set document 😭 these keys can be used by higher-level protocols that use signing or encryption 🧚 for example, some applications might use them to validate signed requests made to the token endpoint when JWTs are used for client authentication [RFC7523] 💜 using this parameter is preferred over the "jwks" parameter, because it makes key rotation easier 🌈 the "jwks_uri" and "jwks" parameters MUST NOT both be present in the same request or response 🙅

jwks

the client's JSON Web Key Set [RFC7517] document value, which holds the client's public keys 🫶 the value of this field MUST be a JSON object containing a valid JWK Set 💅 these keys can be used by higher-level protocols that use signing or encryption 🦋 this parameter is meant for clients that can't use "jwks_uri", like native clients that can't host public URLs 🌸 the "jwks_uri" and "jwks" parameters MUST NOT both be present in the same request or response ✨

software_id

a unique identifier string (for example, a Universally Unique Identifier (UUID)) that the client developer or software publisher assigns 🎀 registration endpoints use it to identify the client software being dynamically registered 🧚 unlike "client_id", which the authorization server issues and SHOULD vary between instances, the "software_id" SHOULD stay the same for all instances of the client software 💖 it SHOULD also stay the same across multiple updates or versions of the same software 🌈 this value isn't meant to be human readable and is usually opaque to the client and authorization server 🔐

software_version

a version identifier string for the client software identified by "software_id" 🍓 the value of "software_version" SHOULD change on any update to the client software identified by the same "software_id" 🔥 it's meant to be compared using string equality matching, and this spec doesn't define any other comparison semantics 💜 what the value is and what counts as an update is outside this spec and specific to the software itself 🫶 like "software_id", it isn't meant to be human readable and is usually opaque to the client and authorization server 👑

Extensions and profiles of this spec can add more metadata names and descriptions, registered under the IANA Considerations in Section 4 of this document 🦋 the authorization server MUST ignore any client metadata the client sends that it doesn't understand (for instance, by quietly removing unknown metadata from the client's registration record during processing) 🙈 the authorization server MAY reject any requested client metadata values by replacing them with suitable defaults, as described in Section 3.2.1, or by returning an error response, as described in Section 3.2.2 💅

client metadata can go directly in the body of a registration request, as described in Section 3.1, or as claims in a software statement, as described in Section 2.3, and you can mix both 🎀 if the same client metadata name shows up in both places and the authorization server trusts the software statement, the value of the claim in the software statement MUST take precedence 👑

2.1. Relationship between Grant Types and Response Types ✨

okay so "grant_types" and "response_types" are kinda partially orthogonal 🦋 because they get passed as arguments to different endpoints in OAuth. BUT they're still connected, bestie. The "grant_types" a client has affects which "response_types" it's allowed to use, and vice versa. For example, a "grant_types" value that includes "authorization_code" implies a "response_types" value that includes "code", since both are part of the OAuth 2.0 authorization code grant. 💅 So a server that supports these fields SHOULD take steps to make sure a client can't register itself into an inconsistent state. One way is returning an invalid_client_metadata error response to an inconsistent registration request. No messy registrations allowed 🙅‍♀️

The correlation between the two fields is in the table below, iykyk 👑

+-----------------------------------------------+-------------------+
| grant_types value includes:                   | response_types    |
|                                               | value includes:   |
+-----------------------------------------------+-------------------+
| authorization_code                            | code              |
| implicit                                      | token             |
| password                                      | (none)            |
| client_credentials                            | (none)            |
| refresh_token                                 | (none)            |
| urn:ietf:params:oauth:grant-type:jwt-bearer   | (none)            |
| urn:ietf:params:oauth:grant-type:saml2-bearer | (none)            |
+-----------------------------------------------+-------------------+

Extensions and profiles of this document that introduce new values to either the "grant_types" or "response_types" parameter MUST document all correspondences between these two parameter types. Main character rules, literally 🎀

2.2. Human-Readable Client Metadata 🌸

Human-readable client metadata values, and client metadata values that reference human-readable values, MAY be represented in multiple languages and scripts 🌈 For example, fields like "client_name", "tos_uri", "policy_uri", "logo_uri", and "client_uri" might have multiple locale-specific values in some registrations, so the app works nicely in different places.

To specify the languages and scripts, BCP 47 [RFC5646] language tags get added to client metadata member names, separated by a "#" character. Since JSON [RFC7159] member names are case sensitive, it is RECOMMENDED that language tag values used in Claim Names be spelled with the character case they're registered with in the "IANA Language Subtag" registry [IANA.Language]. Basically: language names are usually lowercase, region names are uppercase, and languages are mixed-case. BUT, since BCP 47 language tag values are case-insensitive, implementations SHOULD interpret the language tag values they get in a case insensitive way 🫶 Also per BCP 47, language tag values in metadata member names should only be as specific as necessary. So "fr" might be enough in lots of contexts, rather than "fr-CA" or "fr-FR". Don't overcomplicate it, bestie 💖

Here's a cute example: a client could represent its name in English as "client_name#en": "My Client" and its name in Japanese as "client_name#ja-Jpan-JP": "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D", both within the same registration request ✨ The authorization server MAY display any or all of these names to the resource owner during the authorization step, choosing which one to show based on system configuration, user preferences, or other factors.

If any human-readable field is sent without a language tag, parties using it MUST NOT make any assumptions about the language, character set, or script of the string value, and the string value MUST be used as is wherever it's presented in a user interface. Hard rule, no exceptions 🙅‍♀️ To keep things interoperable, it is RECOMMENDED that clients and servers use a human-readable field without any language tags in addition to any language-specific fields. And it is RECOMMENDED that any human-readable fields sent without language tags contain values suitable for display on a wide variety of systems. Universally legible energy 🌍

Implementer's Note: Lots of JSON libraries let you reference members of a JSON object as members of an object construct in the native programming environment of the library 🧚 However, while the "#" character is valid inside a JSON object's member names, it is not a valid character for an object member name in many programming environments. So implementations will need to use alternative access forms for these claims. For instance, in JavaScript, if you parse the JSON like this, var j = JSON.parse(json);, then as a workaround the member "client_name#en-us" can be accessed with the JavaScript syntax j["client_name#en-us"]. Plot twist: the # is valid JSON, it's just a little rude to some languages 😭

2.3. Software Statement 💜

A software statement is a JSON Web Token (JWT) [RFC7519] that asserts metadata values about the client software as a bundle 🎀 A set of claims that can be used in a software statement are defined in Section 2. When it's presented to the authorization server as part of a client registration request, the software statement MUST be digitally signed or MACed using JSON Web Signature (JWS) [RFC7515], and MUST contain an "iss" (issuer) claim denoting the party attesting to the claims in the software statement. Trust me on this one, the "iss" claim is non-negotiable 🙈 It is RECOMMENDED that software statements be digitally signed using the "RS256" signature algorithm, although particular applications MAY specify the use of different algorithms. It is also RECOMMENDED that software statements contain the "software_id" claim, so authorization servers can correlate different instances of software using the same software statement. Iconic for tracking 🔥

For example, a software statement could contain these claims:

  {
   "software_id": "4NRB1-0XZABZI9E6-5SM3R",
   "client_name": "Example Statement-based Client",
   "client_uri": "https://client.example.net/"
  }

The following non-normative example JWT includes these claims and has been asymmetrically signed using "RS256" (with line breaks for display purposes only) 🦋

  eyJhbGciOiJSUzI1NiJ9.
  eyJzb2Z0d2FyZV9pZCI6IjROUkIxLTBYWkFCWkk5RTYtNVNNM1IiLCJjbGll
  bnRfbmFtZSI6IkV4YW1wbGUgU3RhdGVtZW50LWJhc2VkIENsaWVudCIsImNs
  aWVudF91cmkiOiJodHRwczovL2NsaWVudC5leGFtcGxlLm5ldC8ifQ.
  GHfL4QNIrQwL18BSRdE595T9jbzqa06R9BT8w409x9oIcKaZo_mt15riEXHa
  zdISUvDIZhtiyNrSHQ8K4TvqWxH6uJgcmoodZdPwmWRIEYbQDLqPNxREtYn0
  5X3AR7ia4FRjQ2ojZjk5fJqJdQ-JcfxyhK-P8BAWBd6I2LLA77IG32xtbhxY
  fHX7VhuU5ProJO8uvu3Ayv4XRhLZJY4yKfmyjiiKiPNe-Ia4SMy_d_QSWxsk
  U5XIQl5Sa2YRPMbDRXttm2TfnZM1xx70DoYi8g6czz-CPGRi4SW_S2RKHIJf
  IjoI3zTJ0Y2oe0_EJAiXbL6OyF9S5tKxDXV8JIndSA

The software statement is typically distributed with all instances of a client application 📦 The means by which a client or developer obtains a software statement are outside the scope of this specification. Some common methods could include a client developer generating a client-specific JWT by registering with a software API publisher to get a software statement for a class of clients. Not our department, bestie 🧚

The criteria by which authorization servers decide whether to trust and use the information in a software statement are also outside the scope of this specification.

In some cases, authorization servers MAY choose to accept a software statement value directly as a client identifier in an authorization request, without a prior dynamic client registration having been performed 🌸 The circumstances under which an authorization server would do that, and the specific software statement characteristics required in this case, are outside the scope of this specification.

3. Client Registration Endpoint 🧚

The client registration endpoint is an OAuth 2.0 endpoint defined in this document that's designed to let a client get registered with the authorization server 💖 The client registration endpoint MUST accept HTTP POST messages with request parameters encoded in the entity body using the "application/json" format. It MUST also be protected by a transport-layer security mechanism, as described in Section 5. No unprotected vibes allowed 🔒

The client registration endpoint MAY be an OAuth 2.0 [RFC6749] protected resource, and it MAY accept an initial access token in the form of an OAuth 2.0 access token, to limit registration to only previously authorized parties 👑 How the client or developer gets that initial access token is generally out of band and out of scope for this specification. How the client registration endpoint verifies and validates it is also out of scope.

To support open registration and make interoperability easier, the client registration endpoint SHOULD allow registration requests with no authorization (which is to say, with no initial access token in the request) 🌈 These requests MAY be rate-limited or otherwise limited to prevent a denial-of-service attack on the client registration endpoint. Be open, but not a pushover 💅

3.1. Client Registration Request

This operation registers a client with the authorization server 🎀 The server hands the client a unique client identifier, optionally gives it a client secret, and links the metadata from the request to that brand new client ID. The request carries whatever client metadata parameters the client wants set during registration. The authorization server MAY provision default values for any items omitted in the client metadata ✨

Okay so, to register, the client or developer sends an HTTP POST to the client registration endpoint with a content type of "application/json" 💖 The HTTP Entity Payload is a JSON [RFC7159] document: a JSON object where all the requested client metadata values are top-level members of that object 🧚

For example, if the server supports open registration (with no initial access token), the client could send the following registration request to the client registration endpoint 🦋

The following is a non-normative example request not using an initial access token:

POST /register HTTP/1.1 Content-Type: application/json Accept: application/json Host: server.example.com

{ "redirect_uris": [ "https://client.example.org/callback", "https://client.example.org/callback2"], "client_name": "My Example Client", "client_name#ja-Jpan-JP": "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D", "token_endpoint_auth_method": "client_secret_basic", "logo_uri": "https://client.example.org/logo.png", "jwks_uri": "https://client.example.org/my_public_keys.jwks", "example_extension_parameter": "example_value" }

Alternatively, if the server supports authorized registration, the developer or the client will be provisioned with an initial access token 🔥 (How they get that token is out of scope for this spec, so we're not going there, bestie 🙈) The developer or client then sends the following authorized registration request to the client registration endpoint. Note that the initial access token in this example is sent as an OAuth 2.0 Bearer Token [RFC6750], but any OAuth 2.0 token type could be used by an authorization server 💅

The following is a non-normative example request using an initial access token and registering a JWK Set by value (with line breaks within values for display purposes only) 🌈

POST /register HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer ey23f2.adfj230.af32-developer321 Host: server.example.com

{ "redirect_uris": ["https://client.example.org/callback", "https://client.example.org/callback2"], "client_name": "My Example Client", "client_name#ja-Jpan-JP": "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D", "token_endpoint_auth_method": "client_secret_basic", "policy_uri": "https://client.example.org/policy.html", "jwks": {"keys": [{ "e": "AQAB", "n": "nj3YJwsLUFl9BmpAbkOswCNVx17Eh9wMO-_AReZwBqfaWFcfG HrZXsIV2VMCNVNU8Tpb4obUaSXcRcQ-VMsfQPJm9IzgtRdAY8NN8Xb7PEcYyk lBjvTtuPbpzIaqyiUepzUXNDFuAOOkrIol3WmflPUUgMKULBN0EUd1fpOD70p RM0rlp_gg_WNUKoW1V-3keYUJoXH9NztEDm_D2MQXj9eGOJJ8yPgGL8PAZMLe 2R7jb9TxOCPDED7tY_TU4nFPlxptw59A42mldEmViXsKQt60s1SLboazxFKve qXC_jpLUt22OC6GUG63p-REw-ZOr3r845z50wMuzifQrMI9bQ", "kty": "RSA" }]}, "example_extension_parameter": "example_value" }

3.1.1. Client Registration Request Using a Software Statement

In addition to JSON elements, client metadata values MAY also be provided in a software statement, as described in Section 2.3 ✨ The authorization server MAY ignore the software statement if it does not support this feature. If the server does support software statements, client metadata values conveyed in the software statement MUST take precedence over those conveyed using plain JSON elements. Main character energy for the software statement, honestly 👑

Software statements are included in the requesting JSON object using this OPTIONAL member:

  • software_statement: A software statement containing client metadata values about the client software as claims. This is a string value containing the entire signed JWT 🍓

In the following example, some registration parameters are conveyed as claims in a software statement from the example in Section 2.3, while some values specific to the client instance are conveyed as regular parameters (with line breaks within values for display purposes only) 💜

POST /register HTTP/1.1 Content-Type: application/json Accept: application/json Host: server.example.com

{ "redirect_uris": [ "https://client.example.org/callback", "https://client.example.org/callback2" ], "software_statement": "eyJhbGciOiJSUzI1NiJ9. eyJzb2Z0d2FyZV9pZCI6IjROUkIxLTBYWkFCWkk5RTYtNVNNM1IiLCJjbGll bnRfbmFtZSI6IkV4YW1wbGUgU3RhdGVtZW50LWJhc2VkIENsaWVudCIsImNs aWVudF91cmkiOiJodHRwczovL2NsaWVudC5leGFtcGxlLm5ldC8ifQ. GHfL4QNIrQwL18BSRdE595T9jbzqa06R9BT8w409x9oIcKaZo_mt15riEXHa zdISUvDIZhtiyNrSHQ8K4TvqWxH6uJgcmoodZdPwmWRIEYbQDLqPNxREtYn0 5X3AR7ia4FRjQ2ojZjk5fJqJdQ-JcfxyhK-P8BAWBd6I2LLA77IG32xtbhxY fHX7VhuU5ProJO8uvu3Ayv4XRhLZJY4yKfmyjiiKiPNe-Ia4SMy_d_QSWxsk U5XIQl5Sa2YRPMbDRXttm2TfnZM1xx70DoYi8g6czz-CPGRi4SW_S2RKHIJf IjoI3zTJ0Y2oe0_EJAiXbL6OyF9S5tKxDXV8JIndSA", "scope": "read write", "example_extension_parameter": "example_value" }

3.2. Responses

Upon a successful registration request, the authorization server returns a client identifier for the client 🦋 The server responds with an HTTP 201 Created status code and a body of type "application/json" with content as described in Section 3.2.1 ✨

Upon an unsuccessful registration request, the authorization server responds with an error, as described in Section 3.2.2 💀

3.2.1. Client Information Response

The response contains the client identifier as well as the client secret, if the client is a confidential client 🫶 The response MAY contain additional fields as specified by extensions to this specification.

  • client_id: REQUIRED. OAuth 2.0 client identifier string. It SHOULD NOT be currently valid for any other registered client, though an authorization server MAY issue the same client identifier to multiple instances of a registered client at its discretion 🌸
  • client_secret: OPTIONAL. OAuth 2.0 client secret string. If issued, this MUST be unique for each "client_id" and SHOULD be unique for multiple instances of a client using the same "client_id". This value is used by confidential clients to authenticate to the token endpoint, as described in OAuth 2.0 [RFC6749], Section 2.3.1 🔐
  • client_id_issued_at: OPTIONAL. Time at which the client identifier was issued. The time is represented as the number of seconds from 1970-01-01T00:00:00Z as measured in UTC until the date/time of issuance ⏰
  • client_secret_expires_at: REQUIRED if "client_secret" is issued. Time at which the client secret will expire or 0 if it will not expire. The time is represented as the number of seconds from 1970-01-01T00:00:00Z as measured in UTC until the date/time of expiration 🗓️

Additionally, the authorization server MUST return all registered metadata about this client, including any fields provisioned by the authorization server itself. The authorization server MAY reject or replace any of the client's requested metadata values submitted during the registration and substitute them with suitable values. The client or developer can check the values in the response to determine if the registration is sufficient for use (e.g., the registered "token_endpoint_auth_method" is supported by the client software) and determine a course of action appropriate for the client software 🧐 The response to such a situation is out of scope for this specification but could include filing a report with the application developer or authorization server provider, attempted re-registration with different metadata values, or various other methods. For instance, if the server also supports a registration management mechanism such as that defined in [RFC7592], the client or developer could attempt to update the registration with different metadata values. This process could also be aided by a service discovery protocol, such as [OpenID.Discovery], which can list a server's capabilities, allowing a client to make a more informed registration request. The use of any such management or discovery system is optional and outside the scope of this specification 🌈

The successful registration response uses an HTTP 201 Created status code with a body of type "application/json" consisting of a single JSON object [RFC7159] with all parameters as top-level members of the object 🎀

If a software statement was used as part of the registration, its value MUST be returned unmodified in the response along with other metadata using the "software_statement" member name. Client metadata elements used from the software statement MUST also be returned directly as top-level client metadata values in the registration response (possibly with different values, since the values requested and the values used may differ) ✨

The following is a non-normative example response of a successful registration:

HTTP/1.1 201 Created Content-Type: application/json Cache-Control: no-store Pragma: no-cache

{ "client_id": "s6BhdRkqt3", "client_secret": "cf136dc3c1fc93f31185e5885805d", "client_id_issued_at": 2893256800, "client_secret_expires_at": 2893276800, "redirect_uris": [ "https://client.example.org/callback", "https://client.example.org/callback2"], "grant_types": ["authorization_code", "refresh_token"], "client_name": "My Example Client", "client_name#ja-Jpan-JP": "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D", "token_endpoint_auth_method": "client_secret_basic", "logo_uri": "https://client.example.org/logo.png", "jwks_uri": "https://client.example.org/my_public_keys.jwks", "example_extension_parameter": "example_value" }

3.2.2. Client Registration Error Response ✨

Okay so when an OAuth 2.0 error happens, like the client showing up with a bogus initial access token 🙅‍♀️, the authorization server sends back an error response that matches the OAuth 2.0 token type. Simple, right? 💅

When a registration error happens, the server sends back an HTTP 400 status code (unless something else is specified) with application/json as the content type 🎀. The body is a JSON object [RFC7159] that describes what went wrong.

There are two members you can put in that JSON object:

  • error: REQUIRED. It's a single ASCII error code string. Non-negotiable, bestie 🙅‍♀️
  • error_description: OPTIONAL. It's a human-readable ASCII text description of the error, used for debugging 🔍

Other members MAY also be included. If the client doesn't understand them, they MUST be ignored 🫶

This spec defines these error codes 💜

  • invalid_redirect_uri: One or more redirection URIs has an invalid value 💀
  • invalid_client_metadata: One of the client metadata fields has an invalid value, so the server rejected the request. Heads up, an authorization server MAY choose to substitute a valid value for any requested parameter of a client's metadata 🌸
  • invalid_software_statement: The software statement presented is invalid 🥀
  • unapproved_software_statement: The software statement presented is not approved for use by this authorization server 🚫

Here's a non-normative example of an error response from a redirection URI that got blacklisted by the server (the line breaks are just for display 📱):

  HTTP/1.1 400 Bad Request
  Content-Type: application/json
  Cache-Control: no-store
  Pragma: no-cache

  {
   "error": "invalid_redirect_uri",
   "error_description": "The redirection URI
     http://sketchy.example.com is not allowed by this server."
  }

And here's another non-normative example, this time from an inconsistent combo of response_types and grant_types values (line breaks again just for display 🎀):

  HTTP/1.1 400 Bad Request
  Content-Type: application/json
  Cache-Control: no-store
  Pragma: no-cache

  {
   "error": "invalid_client_metadata",
   "error_description": "The grant type 'authorization_code' must be
     registered along with the response type 'code' but found only
    'implicit' instead."
  }

4. IANA Considerations 🦋

4.1. OAuth Dynamic Client Registration Metadata Registry 🌈

This spec sets up the "OAuth Dynamic Client Registration Metadata" registry 📚

So, new OAuth registration client metadata names and descriptions get added through Specification Required ([RFC5226]). That means a two-week review on the oauth-ext-review@ietf.org mailing list, with advice from one or more Designated Experts 💌 Plot twist: the Designated Experts can approve a name early, so names can get allocated before the spec is published, as long as they're confident the spec will be published, per [RFC7120] ✨

Registration requests sent to the list for review should use a clear subject, like "Request to register OAuth Dynamic Client Registration Metadata name: example" 💅

During the review period, the Designated Experts will either approve or deny the request and tell the review list and IANA what they decided. Denials should come with an explanation and, if it applies, suggestions for how to make the request work next time 🫶

IANA must only accept registry updates from the Designated Experts, and it should send all registration requests to the review mailing list 🙌

4.1.1. Registration Template 🎀

Here's what each registration needs to include 📝

  • Client Metadata Name: The name being requested, like "example". This name is case sensitive. Names that match other registered names in a case-insensitive manner SHOULD NOT be accepted 🙅‍♀️
  • Client Metadata Description: A brief description of the metadata value, like "Example description" 📣
  • Change Controller: For Standards Track RFCs, put "IESG" here. For everything else, name the responsible party. You can also add other details, like a postal address, email address, or home page URI 🏠
  • Specification Document(s): A reference to the document or documents that specify the client metadata definition, ideally with a URI where people can grab a copy. You can point to the relevant sections too, but you don't have to 📖

4.1.2. Initial Registry Contents 🍓

Here's what the "OAuth Dynamic Client Registration Metadata" registry starts out with 💖

  o  Client Metadata Name: "redirect_uris"
  o  Client Metadata Description: Array of redirection URIs for use in
     redirect-based flows
  o  Change Controller: IESG
  o  Specification Document(s): RFC 7591
  o  Client Metadata Name: "token_endpoint_auth_method"
  o  Client Metadata Description: Requested authentication method for
     the token endpoint
  o  Change Controller: IESG
  o  Specification Document(s): RFC 7591

  o  Client Metadata Name: "grant_types"
  o  Client Metadata Description: Array of OAuth 2.0 grant types that
     the client may use
  o  Change Controller: IESG
  o  Specification Document(s): RFC 7591

  o  Client Metadata Name: "response_types"
  o  Client Metadata Description: Array of the OAuth 2.0 response types
     that the client may use
  o  Change Controller: IESG
  o  Specification Document(s): RFC 7591

  o  Client Metadata Name: "client_name"
  o  Client Metadata Description: Human-readable name of the client to
     be presented to the user
  o  Change Controller: IESG
  o  Specification Document(s): RFC 7591

  o  Client Metadata Name: "client_uri"
  o  Client Metadata Description: URL of a web page providing
     information about the client
  o  Change Controller: IESG
  o  Specification Document(s): RFC 7591

  o  Client Metadata Name: "logo_uri"
  o  Client Metadata Description: URL that references a logo for the
     client
  o  Change Controller: IESG
  o  Specification Document(s): RFC 7591

  o  Client Metadata Name: "scope"
  o  Client Metadata Description: Space-separated list of OAuth 2.0
     scope values
  o  Change Controller: IESG
  o  Specification Document(s): RFC 7591
  o  Client Metadata Name: "contacts"
  o  Client Metadata Description: Array of strings representing ways to
     contact people responsible for this client, typically email
     addresses
  o  Change Controller: IESG
  o  Specification Document(s): RFC 7591

  o  Client Metadata Name: "tos_uri"
  o  Client Metadata Description: URL that points to a human-readable
     terms of service document for the client
  o  Change Controller: IESG
  o  Specification Document(s): RFC 7591

  o  Client Metadata Name: "policy_uri"
  o  Client Metadata Description: URL that points to a human-readable
     policy document for the client
  o  Change Controller: IESG
  o  Specification Document(s): RFC 7591

  o  Client Metadata Name: "jwks_uri"
  o  Client Metadata Description: URL referencing the client's JSON Web
     Key Set [RFC7517] document representing the client's public keys
  o  Change Controller: IESG
  o  Specification Document(s): RFC 7591

  o  Client Metadata Name: "jwks"
  o  Client Metadata Description: Client's JSON Web Key Set [RFC7517]
     document representing the client's public keys
  o  Change Controller: IESG
  o  Specification Document(s): RFC 7591

  o  Client Metadata Name: "software_id"
  o  Client Metadata Description: Identifier for the software that
     comprises a client
  o  Change Controller: IESG
  o  Specification Document(s): RFC 7591

  o  Client Metadata Name: "software_version"
  o  Client Metadata Description: Version identifier for the software
     that comprises a client
  o  Change Controller: IESG
  o  Specification Document(s): RFC 7591

  o  Client Metadata Name: "client_id"
  o  Client Metadata Description: Client identifier
  o  Change Controller: IESG
  o  Specification Document(s): RFC 7591
  o  Client Metadata Name: "client_secret"
  o  Client Metadata Description: Client secret
  o  Change Controller: IESG
  o  Specification Document(s): RFC 7591

  o  Client Metadata Name: "client_id_issued_at"
  o  Client Metadata Description: Time at which the client identifier
     was issued
  o  Change Controller: IESG
  o  Specification Document(s): RFC 7591

  o  Client Metadata Name: "client_secret_expires_at"
  o  Client Metadata Description: Time at which the client secret will
     expire
  o  Change Controller: IESG
  o  Specification Document(s): RFC 7591

4.2. OAuth Token Endpoint Authentication Methods Registry 🔐

This spec sets up the "OAuth Token Endpoint Authentication Methods" registry 🗝️

More values for token_endpoint_auth_method go in through Specification Required ([RFC5226]), with a two-week review on the oauth-ext-review@ietf.org mailing list and advice from one or more Designated Experts 💜 Same early-approval trick applies: the Designated Experts may approve a value before publication so it can be allocated, once they're satisfied the spec will be published, per [RFC7120] 🦋

Registration requests must be sent to the oauth-ext-review@ietf.org mailing list for review and comment, with an appropriate subject, like "Request to register token_endpoint_auth_method value: example" 📬

During the review period, the Designated Experts will either approve or deny the request, and they'll share that decision with the review list and IANA. Denials should include an explanation and, if relevant, suggestions for making the request successful next time 🌸

IANA must only accept registry updates from the Designated Experts, and it should send all registration requests to the review mailing list 🫶

4.2.1. Registration Template 🎀

Here's what each token endpoint authentication method entry needs 📝

  • Token Endpoint Authentication Method Name: The name being requested, like "example". This name is case sensitive. Names that match other registered names in a case-insensitive manner SHOULD NOT be accepted 🙅‍♀️
  • Change Controller: For Standards Track RFCs, put "IESG" here. For everything else, name the responsible party. Other details, like a postal address, email address, or home page URI, can be included too 🏠
  • Specification Document(s): A reference to the document or documents that specify the token endpoint authentication method, ideally with a URI where people can get a copy. Pointing to the relevant sections is optional, not required 📖

4.2.2. Initial Registry Contents 🍓

Here's what the "OAuth Token Endpoint Authentication Methods" registry starts with 💖

  o  Token Endpoint Authentication Method Name: "none"
  o  Change Controller: IESG
  o  Specification Document(s): RFC 7591

  o  Token Endpoint Authentication Method Name: "client_secret_post"
  o  Change Controller: IESG
  o  Specification Document(s): RFC 7591

  o  Token Endpoint Authentication Method Name: "client_secret_basic"
  o  Change Controller: IESG
  o  Specification Document(s): RFC 7591

5. Security Considerations 🔐✨

okay bestie, this section is SERIOUS 😭 Requests to the client registration endpoint carry clear-text credentials (in both the HTTP request and the response), so the authorization server MUST require a transport-layer security mechanism for requests to the registration endpoint. It MUST support TLS 1.2 [RFC5246] and MAY support other transport-layer security mechanisms that meet its security requirements. When using TLS, the client MUST perform a TLS/SSL server certificate check, per RFC 6125 [RFC6125]. For implementation security advice, check out Recommendations for Secure Use of TLS and DTLS [BCP195] 💖

For clients that use redirect-based grant types like authorization_code and implicit, the authorization server MUST require clients to register their redirection URI values. This helps block attacks where a rogue actor injects and impersonates a validly registered client, then steals its authorization code or tokens through a sketchy redirection URI or an open redirector 🙅‍♀️ Also, to stop anyone from hijacking the return values of the redirection, registered redirection URI values MUST be one of these:

Public clients MAY register with an authorization server using this protocol, as long as the authorization server's policy allows it. Public clients use a none value for the token_endpoint_auth_method metadata field and are usually paired with the implicit grant type 🦋 These are often short-lived in-browser apps asking for access to a user's resources, and their access is tied to the user's active session at the authorization server. Since these clients often don't have long-term storage, they might need to re-register every time the browser app loads. To avoid a pile-up of dead client identifiers (ew 💀), an authorization server MAY decide to expire registrations for existing clients that meet certain criteria after a period of time has passed. Another option is to register such clients on the server where the in-browser app's code is served from, so the client's configuration can be pushed to the browser alongside the code ✨

Different OAuth 2.0 grant types have different security and usage properties, so an authorization server MAY require separate registrations for a piece of software to support multiple grant types. For example, a server might require that every client using the authorization_code grant type use a client secret for token_endpoint_auth_method, while any clients using the implicit grant type don't use any authentication at the token endpoint. In that kind of setup, a server MAY disallow clients from registering for both the authorization_code and implicit grant types at the same time. The authorization_code grant type represents access on behalf of an end-user, while the client_credentials grant type represents access on behalf of the client itself 👑 For security reasons, an authorization server could require different scopes for these different use cases, and as a result, it MAY disallow the same client from registering these two grant types together. In all of these cases, the authorization server would respond with an invalid_client_metadata error response 🙈

Unless it's used as a claim in a software statement, the authorization server MUST treat all client metadata as self-asserted. A rogue client might, for example, use the name and logo of a legit client it's trying to impersonate 😤 A rogue client could also try to use the software identifier or software version of a legitimate client to link itself, on the authorization server, with instances of that legitimate client. To counter this, the authorization server MUST take appropriate steps to reduce this risk by looking at the entire registration request and the client configuration. For instance, the server could issue a warning if the domain or site of the logo doesn't match the domain or site of the redirection URIs. It could also refuse registration requests from a known software identifier that asks for different redirection URIs or a different client URI. The authorization server can also show warning messages to end-users about dynamically registered clients in all cases, especially if those clients were recently registered or haven't been trusted by any users at the authorization server before 🚨

When the authorization server supports open client registration, it must be extremely careful with any URL the client provides that will be displayed to the user (for example, logo_uri, tos_uri, client_uri, and policy_uri). A rogue client could, for instance, register with a reference to a drive-by download in the policy_uri, tempting the user to click it during authorization 💀 The authorization server SHOULD check that logo_uri, tos_uri, client_uri, and policy_uri have the same host and scheme as the ones defined in the redirect_uris array, and that all of these URIs resolve to valid web pages. Because these URI values are meant to be displayed to the user on the authorization page, the authorization server SHOULD protect the user from malicious content hosted at those URLs where possible. For example, before showing the URLs to the user on the authorization page, the server could download the content hosted there, check it against a malware scanner and a blacklist filter, determine whether there's mixed secure and non-secure content at the URL, and try other possible server-side mitigations. Note that the content at these URLs can change at any time, so the authorization server can't have complete confidence that the URLs are safe, but these practices could help 🧚 To further reduce this kind of threat, the authorization server can also warn the user that the URL links were provided by a third party, should be treated with caution, and aren't hosted by the authorization server itself. For example, instead of putting the links directly in an HTML anchor, the server can send the user to an interstitial warning page before letting them continue to the target URL 🫣

Clients MAY use both the direct JSON object and the JWT-encoded software statement to present client metadata to the authorization server as part of the registration request. A software statement is cryptographically protected and represents claims made by the issuer of the statement, while the JSON object represents the self-asserted claims made by the client or developer directly. If the software statement is valid and signed by an acceptable authority (such as the software API publisher), the values of client metadata within the software statement MUST take precedence over the metadata values in the plain JSON object, since the plain JSON object could have been intercepted and modified 🔥

Like all metadata values, the software statement is self-asserted by the client, even though its contents have been digitally signed or MACed by the issuer of the software statement. So, in most cases, presenting the software statement isn't enough on its own to fully identify a piece of client software 🤔 An initial access token, on the other hand, doesn't necessarily contain information about a particular piece of client software. Instead, it represents authorization to use the registration endpoint. An authorization server MUST consider the full registration request, including the software statement, initial access token, and JSON client metadata values, when deciding whether to honor a given registration request 💜

If an authorization server gets a registration request for a client that isn't meant to have multiple instances registered at the same time, and the server can infer a duplicate registration (for example, it sees the same software_id and software_version values as another existing client), the server SHOULD treat the new registration as suspect and reject it. The new client might be trying to impersonate the existing client to trick users into authorizing it, or the original registration might simply no longer be valid 👀 How to manage this situation depends on the authorization server deployment and is outside the scope of this specification.

A client identifier is a public value that can be used to impersonate a client at the authorization endpoint, so an authorization server that decides to issue the same client identifier to multiple instances of a registered client has to be very particular about when that happens 🌸 For instance, the authorization server can limit a given client identifier to clients using the same redirect-based flow and the same redirection URIs. An authorization server SHOULD NOT issue the same client secret to multiple instances of a registered client, even if they're issued the same client identifier. Otherwise, the client secret could leak, letting malicious impostors impersonate a confidential client. Stay safe out there, bestie 💅🎀

6. Privacy Considerations 🦋

okay so bestie, this spec is almost all about info about software, not people 💅 so privacy concerns are super low key. the big exception is the "contacts" field from Section 2 🫶 it holds contact info for the devs or whoever is responsible for the client software. those values are meant to be shown to end-users, and the admins of the authorization server can see them too 👀. so a dev might want an email address that's just for supporting the client, instead of their personal or work address 💖. or they could use a collective address, so support keeps going even after the original dev moves on and someone else takes over 🌸

in general, the client metadata (like the client name and software identifier) is the same across every copy of a piece of client software, so it's not really a privacy issue for end-users 🧚. client identifiers are different though ✨ they're often unique to one specific instance of a client. for stuff like websites used by tons of people, there's probably not a big privacy concern about the client ID. but for native apps installed on one person's device, the client ID could be uniquely tracked during OAuth 2.0 transactions and tied to that single end-user 😭. and here's the twist: the client software still needs to be authorized by a resource owner through an OAuth 2.0 authorization grant, so this tracking can happen whether or not the client ID is unique, by correlating the authenticated resource owner with the requesting client ID 💀

clients are forbidden by this specification from creating their own client identifier 🙅. if they could, one client instance could be tracked across multiple colluding authorization servers, and that leads to privacy and security issues 😬. also, client IDs are generally issued uniquely per registration request, even for the same instance of software. so an app could marginally improve its privacy by registering multiple times and looking like completely separate apps 🎭. but ngl that comes with a lot of usability cost, since it means multiple authorizations per resource owner, so it's unlikely anyone does it in practice 🙈

7. References 📚

7.1. Normative References

7.2. Informative References

Appendix A. Use Cases 🎀

this appendix walks through different ways this spec can be used 🧩, including some of the choices you might need to make. some choices are independent and can be mixed together, and some are interrelated, so they go hand in hand 💜

A.1. Open versus Protected Dynamic Client Registration

A.1.1. Open Dynamic Client Registration

authorization servers that support open registration let you make registrations with no initial access token 🌈. that means all client software can register with the authorization server 🫶

A.1.2. Protected Dynamic Client Registration

authorization servers that support protected registration require that an initial access token be used when making registration requests 🔒. how the client or developer gets this initial access token, and how the authorization server validates it, are out of scope for this spec 🙅. a common approach is for the developer to use a manual preregistration portal at the authorization server, which issues an initial access token to the developer 🍓

A.2. Registration without or with Software Statements

A.2.1. Registration without a Software Statement

when a software statement isn't used in the registration request, the authorization server must be willing to use client metadata values without them being digitally signed or MACed (and thereby attested to) by any authority 🤷‍♀️. (note that this choice is independent of the Open versus Protected choice, and that an initial access token is another possible form of attestation 💅)

A.2.2. Registration with a Software Statement

a software statement can be used in a registration request to provide attestation by an authority for a set of client metadata values 📜. this is useful when the authorization server wants to restrict registration to client software attested to by a set of authorities, or when it wants to know that multiple registration requests refer to the same piece of client software 🔍

A.3. Registration by the Client or Developer

A.3.1. Registration by the Client

in some use cases, client software registers itself dynamically with an authorization server to get a client identifier and other info it needs to interact with the authorization server 🧚. in this case, no client identifier for the authorization server is packaged with the client software ✨

A.3.2. Registration by the Developer

in some cases, the developer (or the development software they're using) preregisters the client software with the authorization server, or a set of authorization servers 🛠️. in this case, the client identifier value(s) for the authorization server(s) can be packaged with the client software 📦

A.4. Client ID per Client Instance or per Client Software

A.4.1. Client ID per Client Software Instance

sometimes each deployed instance of a piece of client software registers dynamically and gets its own distinct client identifier values 🦋. this can be a glow-up, for example if the code flow is being used, because it also lets each client instance have its own client secret 👑. this is useful for native clients, which can't keep a client secret packaged with the software a secret, but which may be able to keep a per-instance client secret secret 🤫

A.4.2. Client ID Shared among All Instances of Client Software

other times, each deployed instance of a piece of client software shares one common client identifier value 🌸. this is often the case for in-browser clients using the implicit flow, where no client secret is involved 🌐. particular authorization servers might choose to maintain a mapping between software statement values and client identifier values, and return the same client identifier value for all registration requests for a particular piece of software 🗂️. the circumstances under which an authorization server would do that, and the specific software statement characteristics required in this case, are beyond the scope of this specification 🙈

A.5. Stateful or Stateless Registration

A.5.1. Stateful Client Registration

okay so bestie, some authorization servers keep a little notebook 📓 on every registered client, and they usually look things up by the client identifier value 🆔✨ that notebook entry typically has the client metadata values from the registration, plus maybe other stuff that's specific to how that server is built 💅 when a server does stateful registration, it can also support operations for retrieving and/or updating that state 🫶 one possible set of those operations is described in [RFC7592] 🔥 it's giving organized, honestly 😭

A.5.2. Stateless Client Registration

okay now the opposite, which is lowkey iconic 🦋 some authorization servers are built so they don't keep any local state about registered clients at all 🧠💀 one way to pull that off is to put the whole registration state inside the client identifier value you hand back 🆔 and you can even encrypt that state to the authorization server, so the state stays confidential and its integrity is protected 🔐 main character energy, no notes 👑

Acknowledgments

the authors want to thank the OAuth Working Group, the User-Managed Access Working Group, and the OpenID Connect Working Group participants for their input on this doc 🫶🌈 super grateful to everyone who helped out 💖 especially these legends, who were instrumental in reviewing and contributing to various draft versions: Amanda Anganes, Derek Atkins, Tim Bray, Domenico Catalano, Donald Coffin, Vladimir Dzhuvinov, George Fletcher, Thomas Hardjono, William Kim, Torsten Lodderstedt, Eve Maler, Josh Mandel, Nov Matake, Tony Nadalin, Nat Sakimura, Christian Scholz, and Hannes Tschofenig 👑✨ absolutely iconic crew 😭

Authors' Addresses

Justin Richer (editor) 🎀 Email: ietf@justin.richer.org

Michael B. Jones 🦋 Microsoft Email: mbj@microsoft.com URI: http://self-issued.info/

John Bradley 🌸 Ping Identity Email: ve7jtb@ve7jtb.com

Maciej Machulak 🧚 Newcastle University Email: maciej.machulak@gmail.com

Phil Hunt 💜 Oracle Corporation Email: phil.hunt@yahoo.com

and that's a wrap on RFC 7591, bestie 🌈💅🫶

📦 where this page comes from