RFC 8414

OAuth 2.0 Authorization Server Metadata

📅 published June 2018, from ietf

RFC 8414: OAuth 2.0 Authorization Server Metadata 💖

Okay bestie, so this is RFC 8414 🎀, a Standards Track doc from the IETF. It was published in June 2018 with ISSN 2070-1721, and the authors are M. Jones at Microsoft, N. Sakimura at NRI, and J. Bradley at Yubico. Nothing in its header says it obsoletes or updates another RFC, so it's standing on its own ✨.

Abstract 🌸

This spec defines a metadata format that an OAuth 2.0 client can use to grab everything it needs to talk to an OAuth 2.0 authorization server. That includes the server's endpoint locations and what the server is capable of 💅.

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 got 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 7841 🧚.

Info about the current status of this doc, any errata, and how to send feedback lives at https://www.rfc-editor.org/info/rfc8414 🔥.

Copyright Notice 🌈

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents, which are at https://trustee.ietf.org/license-info and are in effect on the date this document was published. Please read these carefully, because they spell out your rights and restrictions for this doc 🙈. 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 without warranty as described in the Simplified BSD License 🫶.

Table of Contents 📋

   1. Introduction ....................................................2
      1.1. Requirements Notation and Conventions ......................3
      1.2. Terminology ................................................3
   2. Authorization Server Metadata ...................................4
      2.1. Signed Authorization Server Metadata .......................8
   3. Obtaining Authorization Server Metadata .........................8
      3.1. Authorization Server Metadata Request ......................9
      3.2. Authorization Server Metadata Response ....................10
      3.3. Authorization Server Metadata Validation ..................11
   4. String Operations ..............................................11
   5. Compatibility Notes ............................................11
   6. Security Considerations ........................................12
      6.1. TLS Requirements ..........................................12
      6.2. Impersonation Attacks .....................................12
      6.3. Publishing Metadata in a Standard Format ..................13
      6.4. Protected Resources .......................................13
   7. IANA Considerations ............................................14
      7.1. OAuth Authorization Server Metadata Registry ..............14
           7.1.1. Registration Template ..............................15
           7.1.2. Initial Registry Contents ..........................16
      7.2. Updated Registration Instructions .........................19
      7.3. Well-Known URI Registry ...................................19
           7.3.1. Registry Contents ..................................19
   8. References .....................................................20
      8.1. Normative References ......................................20
      8.2. Informative References ....................................22
   Acknowledgements ..................................................23
   Authors' Addresses ................................................23

1. Introduction ✨

Okay so this spec takes the metadata format from "OpenID Connect Discovery 1.0" [OpenID.Discovery] and generalizes it. It stays compatible with OpenID Connect Discovery while working for a wider set of OAuth 2.0 use cases 💖. It's intentionally parallel to how "OAuth 2.0 Dynamic Client Registration Protocol" [RFC7591] generalized the dynamic client registration mechanisms from "OpenID Connect Dynamic Client Registration 1.0" [OpenID.Registration]. Same energy, same compatibility 👑.

The metadata for an authorization server gets fetched from a well-known location as a JSON [RFC8259] document. That document declares the server's endpoint locations and its capabilities. Section 3 explains how this whole process works 🦋.

This metadata can be shared in two ways. One is self-asserted by the server origin over HTTPS. The other is a set of signed metadata values, represented as claims in a JSON Web Token (JWT) [JWT]. In the JWT case, the issuer is vouching for the validity of the data about the authorization server, which is basically the same role the Software Statement plays in OAuth Dynamic Client Registration [RFC7591] 🔐.

How the client picks an authorization server is out of scope 🙈. Sometimes the issuer identifier gets manually configured into the client. Other times it can be discovered dynamically, for instance through WebFinger [RFC7033], as described in Section 2 of "OpenID Connect Discovery 1.0" [OpenID.Discovery] 🧚.

1.1. Requirements Notation and Conventions 🎀

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here 💅.

All uses of JSON Web Signature (JWS) [JWS] and JSON Web Encryption (JWE) [JWE] data structures in this spec use either the JWS Compact Serialization or the JWE Compact Serialization. The JWS JSON Serialization and the JWE JSON Serialization are not used 🌈.

1.2. Terminology 🍓

This spec uses the terms "Access Token", "Authorization Code", "Authorization Endpoint", "Authorization Grant", "Authorization Server", "Client", "Client Authentication", "Client Identifier", "Client Secret", "Grant Type", "Protected Resource", "Redirection URI", "Refresh Token", "Resource Owner", "Resource Server", "Response Type", and "Token Endpoint", all defined by OAuth 2.0 [RFC6749]. It also uses "Claim Name", "Claim Value", and "JSON Web Token (JWT)", defined by JSON Web Token (JWT) [JWT], and "Response Mode", defined by "OAuth 2.0 Multiple Response Type Encoding Practices" [OAuth.Responses] 💜.

2. Authorization Server Metadata ✨

okay so authorization servers can have metadata that describes how they're set up, and this spec uses a bunch of those values 💅 They're all registered in the IANA "OAuth Authorization Server Metadata" registry from Section 7.1, so they're official and not made up 🎀

issuer REQUIRED 👑 This is the authorization server's issuer identifier, and it's a URL that uses the "https" scheme and has no query or fragment components. The metadata gets published at a .well-known location per [RFC5785], and that location is derived from this issuer identifier (see Section 3) 🧚 The issuer identifier also helps stop authorization server mix-up attacks, which are explained in "OAuth 2.0 Mix-Up Mitigation" [MIX-UP]. Lowkey the most important one 😭

authorization_endpoint This is the URL of the authorization server's authorization endpoint [RFC6749]. It's REQUIRED unless no grant types are supported that use the authorization endpoint 🦋

token_endpoint This is the URL of the authorization server's token endpoint [RFC6749]. It's REQUIRED unless only the implicit grant type is supported 🌸

jwks_uri OPTIONAL 🔑 This is the URL of the authorization server's JWK Set [JWK] document. The doc has the signing key(s) that clients use to validate signatures from the server. This URL MUST use the "https" scheme, no exceptions bestie 🔒 The JWK Set MAY also hold the server's encryption key or keys, which clients use to encrypt requests to the server. Now, if both signing and encryption keys are in there, a "use" (public key use) parameter value is REQUIRED for every key in the referenced JWK Set so everyone knows what each key is for 💜

registration_endpoint OPTIONAL ✨ This is the URL of the authorization server's OAuth 2.0 Dynamic Client Registration endpoint [RFC7591].

scopes_supported RECOMMENDED 🎀 This is a JSON array listing the OAuth 2.0 [RFC6749] "scope" values this authorization server supports. Servers MAY choose not to advertise some supported scope values, even when this parameter is used. Main character choices 💅

response_types_supported REQUIRED 🍓 This is a JSON array listing the OAuth 2.0 "response_type" values this server supports. The array values are the same ones used with the "response_types" parameter from "OAuth 2.0 Dynamic Client Registration Protocol" [RFC7591], so it's all consistent 🫶

response_modes_supported OPTIONAL 🌈 This is a JSON array listing the OAuth 2.0 "response_mode" values this server supports, as specified in "OAuth 2.0 Multiple Response Type Encoding Practices" [OAuth.Responses]. If it's omitted, the default is "["query", "fragment"]". The response mode value "form_post" is also defined in "OAuth 2.0 Form Post Response Mode" [OAuth.Post] 🦋

grant_types_supported OPTIONAL 🧚 This is a JSON array listing the OAuth 2.0 grant type values this server supports. The array values match the ones used with the "grant_types" parameter from "OAuth 2.0 Dynamic Client Registration Protocol" [RFC7591]. If it's omitted, the default value is "["authorization_code", "implicit"]" 💖

token_endpoint_auth_methods_supported OPTIONAL 🔐 This is a JSON array listing the client authentication methods this token endpoint supports. The method values get used in the "token_endpoint_auth_method" parameter defined in Section 2 of [RFC7591]. If it's omitted, the default is "client_secret_basic" -- the HTTP Basic Authentication Scheme from Section 2.3.1 of OAuth 2.0 [RFC6749] 🙈

token_endpoint_auth_signing_alg_values_supported OPTIONAL 🖋️ This is a JSON array listing the JWS signing algorithms ("alg" values) the token endpoint supports for the signature on the JWT [JWT] used to authenticate the client at the token endpoint. This is for the "private_key_jwt" and "client_secret_jwt" authentication methods. This metadata entry MUST be present if either of these authentication methods is specified in the "token_endpoint_auth_methods_supported" entry. If it's omitted, no default algorithms are implied. Servers SHOULD support "RS256". The value "none" MUST NOT be used.

⚠️ Heads up: "none" is a hard no. It MUST NOT be used here, so don't even think about it 💀

service_documentation OPTIONAL 📚 This is the URL of a page with human-readable info that developers might want or need when using the authorization server. Especially if the server doesn't support Dynamic Client Registration, then info on how to register clients needs to be in this documentation 🌸

ui_locales_supported OPTIONAL 🌍 These are the languages and scripts supported for the user interface, as a JSON array of language tag values from BCP 47 [RFC5646]. If it's omitted, the set of supported languages and scripts is unspecified 🤷‍♀️

op_policy_uri OPTIONAL 📜 This is a URL the authorization server gives to the person registering the client, so they can read the server's requirements about how the client can use the data the server provides. The registration process SHOULD display this URL to that person if it's given. As described in Section 5, the name op_policy_uri sounds OpenID-specific, but in this spec it actually refers to a general OAuth 2.0 feature that isn't tied to OpenID Connect. Not confusing at all 🙃

op_tos_uri OPTIONAL 🎀 This is a URL the authorization server gives to the person registering the client, so they can read the server's terms of service. The registration process SHOULD display this URL to that person if it's given. As described in Section 5, even though the identifier "op_tos_uri" looks OpenID-specific, its use in this spec actually refers to a general OAuth 2.0 feature that isn't specific to OpenID Connect 💅

revocation_endpoint OPTIONAL 🗑️ This is the URL of the authorization server's OAuth 2.0 revocation endpoint [RFC7009].

revocation_endpoint_auth_methods_supported OPTIONAL 🔓 This is a JSON array listing the client authentication methods this revocation endpoint supports. The valid client authentication method values are the ones registered in the IANA "OAuth Token Endpoint Authentication Methods" registry [IANA.OAuth.Parameters]. If it's omitted, the default is "client_secret_basic" -- the HTTP Basic Authentication Scheme from Section 2.3.1 of OAuth 2.0 [RFC6749] 🍓

revocation_endpoint_auth_signing_alg_values_supported OPTIONAL 🖊️ This is a JSON array listing the JWS signing algorithms ("alg" values) the revocation endpoint supports for the signature on the JWT [JWT] used to authenticate the client at the revocation endpoint. This is for the "private_key_jwt" and "client_secret_jwt" authentication methods. This metadata entry MUST be present if either of these authentication methods is specified in the "revocation_endpoint_auth_methods_supported" entry. If it's omitted, no default algorithms are implied. The value "none" MUST NOT be used. Still no "none", bestie 🙅‍♀️

introspection_endpoint OPTIONAL 🔍 This is the URL of the authorization server's OAuth 2.0 introspection endpoint [RFC7662].

introspection_endpoint_auth_methods_supported OPTIONAL 🕵️‍♀️ This is a JSON array listing the client authentication methods this introspection endpoint supports. The valid client authentication method values are the ones registered in the IANA "OAuth Token Endpoint Authentication Methods" registry [IANA.OAuth.Parameters], or the ones registered in the IANA "OAuth Access Token Types" registry [IANA.OAuth.Parameters]. (These values are and will remain distinct, due to Section 7.2 🫶) If it's omitted, the set of supported authentication methods MUST be determined by other means 🌈

introspection_endpoint_auth_signing_alg_values_supported OPTIONAL ✍️ This is a JSON array listing the JWS signing algorithms ("alg" values) the introspection endpoint supports for the signature on the JWT [JWT] used to authenticate the client at the introspection endpoint. This is for the "private_key_jwt" and "client_secret_jwt" authentication methods. This metadata entry MUST be present if either of these authentication methods is specified in the "introspection_endpoint_auth_methods_supported" entry. If it's omitted, no default algorithms are implied. The value "none" MUST NOT be used. 🚫

code_challenge_methods_supported OPTIONAL 🧩 This is a JSON array listing the Proof Key for Code Exchange (PKCE) [RFC7636] code challenge methods this authorization server supports. The code challenge method values are used in the "code_challenge_method" parameter defined in Section 4.3 of [RFC7636]. The valid code challenge method values are the ones registered in the IANA "PKCE Code Challenge Methods" registry [IANA.OAuth.Parameters]. If it's omitted, the authorization server does not support PKCE 🥺

Additional authorization server metadata parameters MAY also be used ✨ Some are defined by other specs, like OpenID Connect Discovery 1.0 [OpenID.Discovery] 💜

2.1. Signed Authorization Server Metadata 🔐

okay this part is so cool 😭 In addition to JSON elements, metadata values MAY also be provided as a "signed_metadata" value. That's a JSON Web Token (JWT) [JWT] that asserts metadata values about the authorization server as one bundle 📦 A set of claims that can be used in signed metadata is defined in Section 2. The signed metadata MUST be digitally signed or MACed using JSON Web Signature (JWS) [JWS], and it MUST contain an "iss" (issuer) claim that says which party is vouching for the claims in the signed metadata 🫡 Consumers of the metadata MAY ignore the signed metadata if they don't support this feature. But if the consumer does support signed metadata, metadata values in the signed metadata MUST take precedence over the matching values given in plain JSON elements 👑

Signed metadata gets included in the authorization server metadata JSON object using this OPTIONAL member:

signed_metadata OPTIONAL 🎀 This is a JWT containing metadata values about the authorization server as claims. It's a string value made of the entire signed JWT. A "signed_metadata" metadata value SHOULD NOT appear as a claim in the JWT. Don't nest it like that, bestie 🙃

3. Obtaining Authorization Server Metadata ✨

Okay so bestie, authorization servers that support metadata MUST make a JSON document with that metadata (the stuff from Section 2) available at a path made by slotting a well-known URI string into the server's issuer identifier, between the host part and the path part if there is one 🗺️. By default that string is "/.well-known/oauth-authorization-server" 🎀. This path MUST use the "https" scheme 🔒. The rules for ".well-known" live in RFC 5785 [RFC5785] 📖. And the well-known URI suffix you use MUST be registered in the IANA "Well-Known URIs" registry [IANA.well-known] 💅.

Different apps using OAuth authorization servers in their own special ways can define and register their own suffixes to publish the metadata they care about 🦋. Like, if the example application needs example-specific metadata, it might register "example-configuration" and publish the document at "/.well-known/example-configuration" between the host and path components of the issuer identifier 🌸. Or, and honestly this is the move for most people, lots of apps just use the default "/.well-known/oauth-authorization-server" 💖, which is the right pick for general-purpose OAuth servers, so they never register their own 🙌.

An OAuth 2.0 application using this spec MUST say which well-known URI suffix it's going to use 📝. The same authorization server MAY publish its metadata at multiple well-known locations built from its issuer identifier, like "/.well-known/example-configuration" AND "/.well-known/oauth-authorization-server" at the same time 👯‍♀️.

Some OAuth apps will pick the suffix "openid-configuration" 🧚. Section 5 explains this, but even though "/.well-known/openid-configuration" sounds OpenID-only, here it's actually a general OAuth 2.0 feature, not just for OpenID Connect 🫶.

3.1. Authorization Server Metadata Request

An authorization server metadata document MUST be requested with an HTTP "GET" request at the path we just talked about 🍓.

Say the issuer identifier is "https://example.com" and the suffix is "oauth-authorization-server". Since there's no path component, the client sends this to get the metadata 👀:

GET /.well-known/oauth-authorization-server HTTP/1.1
Host: example.com

If the issuer identifier has a path component, any terminating "/" MUST be removed before "/.well-known/" and the suffix get inserted between the host component and the path component 🧩. So for "https://example.com/issuer1" with the same suffix, the client sends this, since there IS a path component 💜:

GET /.well-known/oauth-authorization-server/issuer1 HTTP/1.1
Host: example.com

Putting path components in lets you support multiple issuers on one host 🏠. This is REQUIRED in some multi-tenant hosting setups 🙌. And ngl, this use of ".well-known" is for supporting multiple issuers per host. Unlike its use in RFC 5785 [RFC5785], it does NOT give general info about the host 🙈. Not me being specific about it, but it's giving "different job than you think" 💅.

3.2. Authorization Server Metadata Response

The response is a bunch of claims about the server's setup, including all the necessary endpoints and where to find its public keys 🔑. A successful response MUST use the 200 OK HTTP status code and return a JSON object with the "application/json" content type. That object holds a set of claims as members, which are a subset of the metadata values from Section 2 ✨. Other claims MAY also be returned 🌈.

Claims that have multiple values get shown as JSON arrays 🎀. Claims with zero elements MUST be left out of the response 🙅‍♀️.

An error response just uses the applicable HTTP status code value 😭.

Here's a non-normative example response 🦋:

HTTP/1.1 200 OK
Content-Type: application/json

{
 "issuer":
   "https://server.example.com",
 "authorization_endpoint":
   "https://server.example.com/authorize",
 "token_endpoint":
   "https://server.example.com/token",
 "token_endpoint_auth_methods_supported":
   ["client_secret_basic", "private_key_jwt"],
 "token_endpoint_auth_signing_alg_values_supported":
   ["RS256", "ES256"],
 "userinfo_endpoint":
   "https://server.example.com/userinfo",
 "jwks_uri":
   "https://server.example.com/jwks.json",
 "registration_endpoint":
   "https://server.example.com/register",
 "scopes_supported":
   ["openid", "profile", "email", "address",
    "phone", "offline_access"],
 "response_types_supported":
   ["code", "code token"],
 "service_documentation":
   "http://server.example.com/service_documentation.html",
 "ui_locales_supported":
   ["en-US", "en-GB", "en-CA", "fr-FR", "fr-CA"]
}

3.3. Authorization Server Metadata Validation

The "issuer" value that comes back MUST be identical to the issuer identifier value the well-known URI string was inserted into to make the metadata URL 🔍. If these values are NOT identical, the data in the response MUST NOT be used 🚫. Do not skip this, bestie 😤.

4. String Operations 🧵

Processing some OAuth 2.0 messages means comparing their values to known values 🔎. For example, member names in the metadata response might get compared to names like "issuer" 🫧. Comparing Unicode [UNICODE] strings has real security implications, though 😬.

So comparisons between JSON strings and other Unicode strings MUST be done like this 📋:

Remove any JSON-applied escaping to get an array of Unicode code points.
Unicode Normalization [USA15] MUST NOT be applied at any point to either the JSON string or the string it's compared against.
The comparison between the two strings MUST be a Unicode code-point-to-code-point equality comparison.

Fun fact, this is the same equality comparison procedure as Section 8.3 of [RFC8259] 🤓.

5. Compatibility Notes 🌷

The identifiers "/.well-known/openid-configuration", "op_policy_uri", and "op_tos_uri" contain strings that refer to the OpenID Connect [OpenID.Core] family of specs, which were first defined by "OpenID Connect Discovery 1.0" [OpenID.Discovery] 🪄. Even though these identifiers look OpenID-specific, here they refer to general OAuth 2.0 features that have nothing to do with OpenID Connect 💅.

The transformation from Section 3 that turns an issuer identifier into an authorization server metadata location is equivalent to the matching transformation in Section 4 of "OpenID Connect Discovery 1.0" [OpenID.Discovery], as long as the issuer identifier has no path component 🫶. But they're different when there IS a path component 😳. OpenID Connect Discovery 1.0 appends the well-known URI string to the issuer identifier (like "https://example.com/issuer1/.well-known/openid-configuration"), whereas this spec inserts it before the path component (like "https://example.com/.well-known/openid-configuration/issuer1") 🧠.

Going forward, OAuth authorization server metadata locations SHOULD use the transformation defined in this spec 💖. Hmm, wait, let me be precise: the text says "should" here, so use the transformation from this spec 💖. However, in legacy environments where the OpenID Connect Discovery 1.0 transformation is already in use, it MAY be necessary, during a transition period, to publish metadata for issuer identifiers with a path component at both locations 🕰️. During that transition, applications SHOULD first apply the transformation defined in this spec and try to retrieve the metadata from the resulting location 🎯. ONLY if that retrieval fails should they fall back to the alternate location from the OpenID Connect Discovery 1.0 transformation 🔁. This backwards-compatible behavior SHOULD only be needed when the suffix the app uses is "openid-configuration" 🌈.

6. Security Considerations 🔐

Okay bestie, this part is SERIOUS 😭💀.

6.1. TLS Requirements

Implementations MUST support TLS 🔒. Which version(s) ought to be implemented will change over time, and depends on widespread deployment and known security vulnerabilities at the time of implementation ⏳. The authorization server MUST support TLS version 1.2 [RFC5246] and MAY support additional TLS mechanisms that meet its security requirements 🛡️. When using TLS, the client MUST perform a TLS/SSL server certificate check, per RFC 6125 [RFC6125] 🧐. Implementation security considerations can be found in "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)" [BCP195] 📚.

To protect against information disclosure and tampering, confidentiality protection MUST be applied using TLS with a ciphersuite that provides confidentiality and integrity protection 🫣.

6.2. Impersonation Attacks

TLS certificate checking MUST be performed by the client, as described in Section 6.1, when making an authorization server metadata request 🕵️‍♀️. Checking that the server certificate is valid for the issuer identifier URL prevents man-in-the-middle and DNS-based attacks 🚨. These attacks could trick a client into using an attacker's keys and endpoints, which would let the attacker impersonate the legit authorization server 😱. If an attacker pulls this off, they can access whatever resources the affected client can reach through the server they're impersonating 💀.

An attacker may also try to impersonate an authorization server by publishing a metadata document with an "issuer" claim that uses the issuer identifier URL of the server being impersonated, but with its own endpoints and signing keys 👻. That would let it impersonate the server, if the client accepts it 🙈. To prevent this, the client MUST ensure that the issuer identifier URL it uses as the prefix for the metadata request EXACTLY matches the value of the "issuer" metadata value in the authorization server metadata document it received 🎯.

6.3. Publishing Metadata in a Standard Format

Publishing info about the authorization server in a standard format makes it easier for both legit clients AND attackers to use the server 🫠. Whether a server publishes its metadata ad hoc or in the standard format this spec defines, the same defenses against attacks that use this info SHOULD be applied 🛡️✨.

6.4. Protected Resources 🛡️

Okay bestie, this one is a little plot twist 😭 Picking the right protected resources for an authorization server is out of scope for this spec, so it isn't defined here. The spec just assumes the client already has a way to figure out which protected resources go with which authorization server, and that it's using the correct metadata for each one. 🫶

But here's the scary part 💀: if a client uses the wrong protected resource, an attacker could act as a man-in-the-middle proxy in front of a valid protected resource, and neither the authorization server nor the client would notice. Implementers, please be careful!! 🙈

How you pick the right resources is pretty much application dependent ✨. Some authorization servers are used with one fixed resource (or a set of them), and those locations might be well known or published as metadata values by the authorization server. Other times, admins can change which resources an authorization server can work with on the fly through administrative actions. There are honestly lots of other ways to link authorization servers and protected resources too 🌈.

7. IANA Considerations ✨

Here's how the registry set up by this specification gets its values 📝.

Values are registered on a Specification Required [RFC8126] basis. That means there's a two-week review period on the oauth-ext-review@ietf.org mailing list, with the advice of one or more Designated Experts. BUT, to let people claim values before publication, the Designated Experts can approve a registration once they're convinced that the specification will get published 🔥.

When you send a registration request to the mailing list for review, use a clear subject, like "Request to register OAuth Authorization Server Metadata: example" 💌.

During the review period, the Designated Experts will either approve or deny the request and tell both the review list and IANA what they decided. Denials should come with an explanation and, if it makes sense, tips on how to make the request work next time 🦋. If a request sits undetermined for longer than 21 days, it can be escalated to the IESG's attention using the iesg@ietf.org mailing list 👑.

The Designated Experts should check a few things: whether the registration duplicates existing functionality, whether it's likely to be generally applicable or only useful for a single application, and whether the registration actually makes sense 🧠.

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

It's suggested that several Designated Experts be appointed, each able to represent the different applications that use this specification, so that reviews are broadly informed 🌸. If a decision could look like a conflict of interest for a particular Designated Expert, that expert should defer to the judgment of the others 🫶.

7.1. OAuth Authorization Server Metadata Registry

This specification sets up the IANA "OAuth Authorization Server Metadata" registry for OAuth 2.0 authorization server metadata names 🎀. Each entry records the authorization server metadata member along with a reference to the specification that defines it.

The Designated Experts must either:

(a) require that metadata names and values being registered use only printable ASCII characters excluding double quote ('"') and backslash ('\') (the Unicode characters with code points U+0021, U+0023 through U+005B, and U+005D through U+007E), or
(b) if new metadata members or values are defined that use other code points, require that their definitions specify the exact sequences of Unicode code points used to represent them. Furthermore, proposed registrations that use Unicode code points that can only be represented in JSON strings as escaped characters must not be accepted 🚫.

7.1.1. Registration Template

Here's the template you fill in when you register something 📋:

   Metadata Name:
      The name requested (e.g., "issuer").  This name is case-sensitive.
      Names may not match other registered names in a case-insensitive
      manner (one that would cause a match if the Unicode toLowerCase()
      operation were applied to both strings) unless the Designated
      Experts state that there is a compelling reason to allow an
      exception.

   Metadata Description:
      Brief description of the metadata (e.g., "Issuer identifier URL").

   Change Controller:
      For Standards Track RFCs, list the "IESG".  For others, give the
      name of the responsible party.  Other details (e.g., postal
      address, email address, home page URI) may also be included.

   Specification Document(s):
      Reference to the document or documents that specify the parameter,
      preferably including URIs that can be used to retrieve copies of
      the documents.  An indication of the relevant sections may also be
      included but is not required.

7.1.2. Initial Registry Contents

These are the entries that get registered right away 🌈. Every one of them is controlled by the IESG and points back to Section 2 of RFC 8414, except signed_metadata, which points to Section 2.1 ✨.

   o  Metadata Name: issuer
   o  Metadata Description: Authorization server's issuer identifier URL
   o  Change Controller: IESG
   o  Specification Document(s): Section 2 of RFC 8414

   o  Metadata Name: authorization_endpoint
   o  Metadata Description: URL of the authorization server's
      authorization endpoint
   o  Change Controller: IESG
   o  Specification Document(s): Section 2 of RFC 8414

   o  Metadata Name: token_endpoint
   o  Metadata Description: URL of the authorization server's token
      endpoint
   o  Change Controller: IESG
   o  Specification Document(s): Section 2 of RFC 8414

   o  Metadata Name: jwks_uri
   o  Metadata Description: URL of the authorization server's JWK Set
      document
   o  Change Controller: IESG
   o  Specification Document(s): Section 2 of RFC 8414

   o  Metadata Name: registration_endpoint
   o  Metadata Description: URL of the authorization server's OAuth 2.0
      Dynamic Client Registration Endpoint
   o  Change Controller: IESG
   o  Specification Document(s): Section 2 of RFC 8414

   o  Metadata Name: scopes_supported
   o  Metadata Description: JSON array containing a list of the OAuth
      2.0 "scope" values that this authorization server supports
   o  Change Controller: IESG
   o  Specification Document(s): Section 2 of RFC 8414

   o  Metadata Name: response_types_supported
   o  Metadata Description: JSON array containing a list of the OAuth
      2.0 "response_type" values that this authorization server supports
   o  Change Controller: IESG
   o  Specification Document(s): Section 2 of RFC 8414

   o  Metadata Name: response_modes_supported
   o  Metadata Description: JSON array containing a list of the OAuth
      2.0 "response_mode" values that this authorization server supports
   o  Change Controller: IESG
   o  Specification Document(s): Section 2 of RFC 8414
   o  Metadata Name: grant_types_supported
   o  Metadata Description: JSON array containing a list of the OAuth
      2.0 grant type values that this authorization server supports
   o  Change Controller: IESG
   o  Specification Document(s): Section 2 of RFC 8414

   o  Metadata Name: token_endpoint_auth_methods_supported
   o  Metadata Description: JSON array containing a list of client
      authentication methods supported by this token endpoint
   o  Change Controller: IESG
   o  Specification Document(s): Section 2 of RFC 8414

   o  Metadata Name: token_endpoint_auth_signing_alg_values_supported
   o  Metadata Description: JSON array containing a list of the JWS
      signing algorithms supported by the token endpoint for the
      signature on the JWT used to authenticate the client at the token
      endpoint
   o  Change Controller: IESG
   o  Specification Document(s): Section 2 of RFC 8414

   o  Metadata Name: service_documentation
   o  Metadata Description: URL of a page containing human-readable
      information that developers might want or need to know when using
      the authorization server
   o  Change Controller: IESG
   o  Specification Document(s): Section 2 of RFC 8414

   o  Metadata Name: ui_locales_supported
   o  Metadata Description: Languages and scripts supported for the user
      interface, represented as a JSON array of language tag values from
      BCP 47
   o  Change Controller: IESG
   o  Specification Document(s): Section 2 of RFC 8414

   o  Metadata Name: op_policy_uri
   o  Metadata Description: URL that the authorization server provides
      to the person registering the client to read about the
      authorization server's requirements on how the client can use the
      data provided by the authorization server
   o  Change Controller: IESG
   o  Specification Document(s): Section 2 of RFC 8414

   o  Metadata Name: op_tos_uri
   o  Metadata Description: URL that the authorization server provides
      to the person registering the client to read about the
      authorization server's terms of service
   o  Change Controller: IESG
   o  Specification Document(s): Section 2 of RFC 8414
   o  Metadata Name: revocation_endpoint
   o  Metadata Description: URL of the authorization server's OAuth 2.0
      revocation endpoint
   o  Change Controller: IESG
   o  Specification Document(s): Section 2 of RFC 8414

   o  Metadata Name: revocation_endpoint_auth_methods_supported
   o  Metadata Description: JSON array containing a list of client
      authentication methods supported by this revocation endpoint
   o  Change Controller: IESG
   o  Specification Document(s): Section 2 of RFC 8414

   o  Metadata Name:
      revocation_endpoint_auth_signing_alg_values_supported
   o  Metadata Description: JSON array containing a list of the JWS
      signing algorithms supported by the revocation endpoint for the
      signature on the JWT used to authenticate the client at the
      revocation endpoint
   o  Change Controller: IESG
   o  Specification Document(s): Section 2 of RFC 8414

   o  Metadata Name: introspection_endpoint
   o  Metadata Description: URL of the authorization server's OAuth 2.0
      introspection endpoint
   o  Change Controller: IESG
   o  Specification Document(s): Section 2 of RFC 8414

   o  Metadata Name: introspection_endpoint_auth_methods_supported
   o  Metadata Description: JSON array containing a list of client
      authentication methods supported by this introspection endpoint
   o  Change Controller: IESG
   o  Specification Document(s): Section 2 of RFC 8414

   o  Metadata Name:
      introspection_endpoint_auth_signing_alg_values_supported
   o  Metadata Description: JSON array containing a list of the JWS
      signing algorithms supported by the introspection endpoint for the
      signature on the JWT used to authenticate the client at the
      introspection endpoint
   o  Change Controller: IESG
   o  Specification Document(s): Section 2 of RFC 8414

   o  Metadata Name: code_challenge_methods_supported
   o  Metadata Description: PKCE code challenge methods supported by
      this authorization server
   o  Change Controller: IESG
   o  Specification Document(s): Section 2 of RFC 8414
   o  Metadata Name: signed_metadata
   o  Metadata Description: Signed JWT containing metadata values about
      the authorization server as claims
   o  Change Controller: IESG
   o  Specification Document(s): Section 2.1 of RFC 8414

7.2. Updated Registration Instructions 📝✨

okay so this bit adds some extra rules for the Designated Experts 👑 of two registries that both live in the "OAuth Parameters" registry [IANA.OAuth.Parameters]:

OAuth Access Token Types 🎟️
OAuth Token Endpoint Authentication Methods 🔐

IANA has already put a link to this spec in the Reference sections of both registries 🔗

here's the big rule 🚨: the Designated Experts MUST reject any registration request in one registry if the value is already in the other one. why? bc the "introspection_endpoint_auth_methods_supported" parameter is allowed to use values from either registry 🫶 so if the two registries never overlap, there's zero confusion. no ambiguities, periodt 💅

7.3. Well-Known URI Registry 🌸

this spec registers the well-known URI from Section 3 in the IANA "Well-Known URIs" registry [IANA.well-known], which was set up by RFC 5785 [RFC5785] 🦋

7.3.1. Registry Contents 📋

o  URI suffix: oauth-authorization-server
o  Change controller: IESG
o  Specification document: Section 3 of RFC 8414
o  Related information: (none)

8. References 📚

8.1. Normative References 💜

[BCP195]   Sheffer, Y., Holz, R., and P. Saint-Andre,
           "Recommendations for Secure Use of Transport Layer
           Security (TLS) and Datagram Transport Layer Security
           (DTLS)", BCP 195, RFC 7525, May 2015,
           <http://www.rfc-editor.org/info/bcp195>.

[IANA.OAuth.Parameters]
           IANA, "OAuth Parameters",
           <https://www.iana.org/assignments/oauth-parameters>.

[JWE]      Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
           RFC 7516, DOI 10.17487/RFC7516, May 2015,
           <https://www.rfc-editor.org/info/rfc7516>.

[JWK]      Jones, M., "JSON Web Key (JWK)", RFC 7517,
           DOI 10.17487/RFC7517, May 2015,
           <https://www.rfc-editor.org/info/rfc7517>.

[JWS]      Jones, M., Bradley, J., and N. Sakimura, "JSON Web
           Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
           2015, <https://www.rfc-editor.org/info/rfc7515>.

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

[OAuth.Post]
           Jones, M. and B. Campbell, "OAuth 2.0 Form Post Response
           Mode", April 2015, <http://openid.net/specs/
           oauth-v2-form-post-response-mode-1_0.html>.

[OAuth.Responses]
           de Medeiros, B., Ed., Scurtescu, M., Tarjan, P., and M.
           Jones, "OAuth 2.0 Multiple Response Type Encoding
           Practices", February 2014, <http://openid.net/specs/
           oauth-v2-multiple-response-types-1_0.html>.

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

[RFC5246]  Dierks, T. and E. Rescorla, "The Transport Layer Security
           (TLS) Protocol Version 1.2", RFC 5246,
           DOI 10.17487/RFC5246, August 2008,
           <https://www.rfc-editor.org/info/rfc5246>.

[RFC5646]  Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying
           Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646,
           September 2009, <https://www.rfc-editor.org/info/rfc5646>.

[RFC5785]  Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known
           Uniform Resource Identifiers (URIs)", RFC 5785,
           DOI 10.17487/RFC5785, April 2010,
           <https://www.rfc-editor.org/info/rfc5785>.

[RFC6125]  Saint-Andre, P. and J. Hodges, "Representation and
           Verification of Domain-Based Application Service Identity
           within Internet Public Key Infrastructure Using X.509
           (PKIX) Certificates in the Context of Transport Layer
           Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March
           2011, <https://www.rfc-editor.org/info/rfc6125>.

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

[RFC7009]  Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth
           2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009,
           August 2013, <https://www.rfc-editor.org/info/rfc7009>.

[RFC7033]  Jones, P., Salgueiro, G., Jones, M., and J. Smarr,
           "WebFinger", RFC 7033, DOI 10.17487/RFC7033, September
           2013, <https://www.rfc-editor.org/info/rfc7033>.

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

[RFC7636]  Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key
           for Code Exchange by OAuth Public Clients", RFC 7636,
           DOI 10.17487/RFC7636, September 2015,
           <https://www.rfc-editor.org/info/rfc7636>.

[RFC7662]  Richer, J., Ed., "OAuth 2.0 Token Introspection",
           RFC 7662, DOI 10.17487/RFC7662, October 2015,
           <https://www.rfc-editor.org/info/rfc7662>.

[RFC8126]  Cotton, M., Leiba, B., and T. Narten, "Guidelines for
           Writing an IANA Considerations Section in RFCs", BCP 26,
           RFC 8126, DOI 10.17487/RFC8126, June 2017,
           <https://www.rfc-editor.org/info/rfc8126>.

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

[RFC8259]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
           Interchange Format", STD 90, RFC 8259,
           DOI 10.17487/RFC8259, December 2017,
           <https://www.rfc-editor.org/info/rfc8259>.

[UNICODE]  The Unicode Consortium, "The Unicode Standard",
           <http://www.unicode.org/versions/latest/>.

[USA15]    Davis, M., Ed. and K. Whistler, Ed., "Unicode
           Normalization Forms", Unicode Standard Annex #15, May
           2018, <http://www.unicode.org/reports/tr15/>.

8.2. Informative References 🔍

[IANA.well-known]
           IANA, "Well-Known URIs",
           <https://www.iana.org/assignments/well-known-uris>.

[MIX-UP]   Jones, M., Bradley, J., and N. Sakimura, "OAuth 2.0 Mix-Up
           Mitigation", Work in Progress, draft-ietf-oauth-mix-up-
           mitigation-01, July 2016.

[OpenID.Core]
           Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and
           C. Mortimore, "OpenID Connect Core 1.0", November 2014,
           <http://openid.net/specs/openid-connect-core-1_0.html>.

[OpenID.Discovery]
           Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID
           Connect Discovery 1.0", November 2014,
           <http://openid.net/specs/
           openid-connect-discovery-1_0.html>.

[OpenID.Registration]
           Sakimura, N., Bradley, J., and M. Jones, "OpenID Connect
           Dynamic Client Registration 1.0", November 2014,
           <http://openid.net/specs/
           openid-connect-registration-1_0.html>.

Acknowledgements 🫶

This specification is based on the OpenID Connect Discovery 1.0 specification, which was produced by the OpenID Connect working group of the OpenID Foundation. This specification standardizes the de facto usage of the metadata format defined by OpenID Connect Discovery to publish OAuth authorization server metadata.

The authors would like to thank the following people for their reviews of this specification: Shwetha Bhandari, Ben Campbell, Brian Campbell, Brian Carpenter, William Denniss, Vladimir Dzhuvinov, Donald Eastlake, Samuel Erdtman, George Fletcher, Dick Hardt, Phil Hunt, Alexey Melnikov, Tony Nadalin, Mark Nottingham, Eric Rescorla, Justin Richer, Adam Roach, Hannes Tschofenig, and Hans Zandbelt. 💖

Authors' Addresses 🎀

Michael B. Jones
Microsoft

Email: mbj@microsoft.com
URI:   http://self-issued.info/


Nat Sakimura
Nomura Research Institute, Ltd.

Email: n-sakimura@nri.co.jp
URI:   http://nat.sakimura.org/


John Bradley
Yubico

Email: RFC8414@ve7jtb.com
URI:   http://www.thread-safe.com/

📦 where this page comes from

ietf: rfc8414 2018-06
💖 girlified by claude-haiku-5-5 on 2026-10-18: a language model's rewrite of the original, under its terms