RFC 9728

📜 RFC 9728: OAuth 2.0 Protected Resource Metadata 🎀

okay so bestie, let's get into this one 💅 it's an IETF Standards Track doc (category: Standards Track, ISSN 2070-1721), published April 2025, and it's giving main character energy because it's the official spec for how a protected resource can tell clients what it needs. 🦋

The authors are M.B. Jones (Self-Issued Consulting), P. Hunt (Independent Identity, Inc.), and A. Parecki (Okta). 🫶 Nothing here obsoletes or updates another RFC, so it's a fresh drop with zero drama. 🌸

Part 1 of 6 is the intro, the requirements notation, and the terminology. More parts coming, so stay tuned! ✨

1. Introduction ✨

okay so this spec defines a metadata format that lets OAuth 2.0 clients and authorization servers find out what they need to interact with an OAuth 2.0 protected resource. 💖 it's built to be super parallel to two other specs: "OAuth 2.0 Dynamic Client Registration Protocol" [RFC7591], which lets a client tell an authorization server about itself, and "OAuth 2.0 Authorization Server Metadata" [RFC8414], which lets a client learn about an authorization server. the vibe is "same energy, different target" 🙈

how the client actually gets the location of the protected resource? not this doc's problem 🤷‍♀️ it's out of scope. sometimes it's manually configured, like an email client where you type in the URL of your JSON Meta Application Protocol (JMAP) server [RFC8620]. other times it's dynamically discovered, like typing your email address and the client doing WebFinger discovery [RFC7033] (kinda like Section 2 of [OpenID.Discovery]) to find the resource server, then grabbing its metadata to find the authorization server it should use to get access to your email. 📬🧚

the metadata itself is a JSON [RFC8259] document pulled from a well-known location. it declares the resource's capabilities and, optionally, its relationships with other services. the retrieval process is in Section 3. 🍓

this metadata can come in two flavors: self-asserted, or a set of signed metadata values carried as claims in a JSON Web Token (JWT) [JWT]. in the JWT case, the issuer is vouching for the data about the protected resource. it's basically the same role the software statement plays in OAuth Dynamic Client Registration [RFC7591]. 🔥

every protected resource that publishes metadata about itself puts its own document at a well-known location that's deterministically derived from the resource's URL, even when one server hosts multiple protected resources. this stops attackers from publishing metadata that claims to describe a resource but isn't actually authoritative for it, as covered in Section 7.3. 👑 no sneaky impersonation, bestie 🚫

Section 2 defines the metadata parameters a protected resource can publish: things like which scopes are supported, how a client can present an access token, and more. some of these values, like the jwks_uri (see Section 2), can be used with other specs. for example, the public keys published at the jwks_uri can verify signed resource responses, as described in [FAPI.MessageSigning]. 🌈

Section 5 describes how protected resources use WWW-Authenticate to dynamically tell clients where their protected resource metadata lives. that WWW-Authenticate signal can also mean the metadata may have changed, so keep an eye out 👀✨

1.1. Requirements Notation and Conventions

okay this is the important part for the keywords, so pay attention 🎀 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, exactly as shown here. so lowercase "must" is just a regular word, no cap 💅

also, every use of JSON Web Signature (JWS) data structures [JWS] and JSON Web Encryption (JWE) data structures [JWE] in this spec uses the JWS Compact Serialization or the JWE Compact Serialization. the JWS JSON Serialization and the JWE JSON Serialization are not used. picking a single serialization is meant to make interoperability easier 🫶

1.2. Terminology

this spec borrows a bunch of terms from OAuth 2.0 [RFC6749]: "access token", "authorization code", "authorization server", "client", "client authentication", "client identifier", "protected resource", and "resource server". it also borrows "Claim Name" and "JSON Web Token (JWT)" from the JWT spec [JWT]. 🦋

this spec also defines its own term:

• Resource Identifier: the protected resource's resource identifier, which is a URL that uses the https scheme and has no fragment component. as specified in Section 2 of [RFC8707], it also SHOULD NOT include a query component, but it's acknowledged there are cases where a query component is a useful and necessary part of a resource identifier. protected resource metadata is published at a .well-known location [RFC8615] derived from this resource identifier, as described in Section 3. 💜

⚠️ tiny reminder: that SHOULD NOT is a real requirement, so don't add a query component unless you actually have a good reason, bestie 🙈

---

to be continued in part 2 🧚✨ don't go anywhere!

2. Protected Resource Metadata ✨

okay bestie, so protected resources can have metadata that describes how they're set up 🎀 this spec uses the following parameters, and they're all registered in the "OAuth Protected Resource Metadata" registry from Section 8.1 💅

• resource: REQUIRED 🔑 This is the protected resource's resource identifier, the one defined in Section 1.2. No resource identifier, no party 🥲
• authorization_servers: OPTIONAL 🏰 This is a JSON array listing OAuth authorization server issuer identifiers (see [RFC8414]) that can work with this protected resource. Protected resources MAY choose not to advertise some of their supported authorization servers, even when this parameter is used 🙈 Sometimes the set of authorization servers can't be listed out, and in that case this parameter just wouldn't be used.
• jwks_uri: OPTIONAL 🗝️ This is the URL of the protected resource's JSON Web Key (JWK) Set [JWK] document. It holds public keys that belong to the protected resource, like the signing keys the resource server uses to sign its responses. This URL MUST use the https scheme 🔒 When both signing and encryption keys are published, 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 🧚
• scopes_supported: RECOMMENDED 🌈 This is a JSON array of scope values (from OAuth 2.0 [RFC6749]) that get used in authorization requests to ask for access to this protected resource. Protected resources MAY choose not to advertise some of the supported scope values, even when this parameter is used 🫶
• bearer_methods_supported: OPTIONAL 🎟️ This is a JSON array of the supported ways to send an OAuth 2.0 bearer token [RFC6750] to the protected resource. The defined values are ["header", "body", "query"], which line up with Sections 2.1, 2.2, and 2.3 of [RFC6750]. An empty array, [], can be used to say that no bearer methods are supported. If this entry is left out, no default bearer methods are implied, and its absence doesn't mean they're unsupported either 🤷‍♀️
• resource_signing_alg_values_supported: OPTIONAL ✍️ This is a JSON array of the JWS [JWS] signing algorithms (alg values) [JWA] that the protected resource supports for signing its resource responses, like the ones described in [FAPI.MessageSigning]. No default algorithms are implied if this entry is omitted. The value none MUST NOT be used 🚫 absolutely not, no cap
• resource_name: This is a human-readable name for the protected resource, meant to be shown to the end user 🎀 It is RECOMMENDED that protected resource metadata include this field. The value of this field MAY be internationalized, as described in Section 2.1 🌍
• resource_documentation: OPTIONAL 📚 This is a URL for a page with human-readable info that developers might want or need when they're using the protected resource. The value of this field MAY be internationalized, as described in Section 2.1 💖
• resource_policy_uri: OPTIONAL 📜 This is a URL for a page with human-readable info about the protected resource's requirements on how the client can use the data the protected resource provides. The value of this field MAY be internationalized, as described in Section 2.1 🦋
• resource_tos_uri: OPTIONAL 🧾 This is a URL for a page with human-readable info about the protected resource's terms of service. The value of this field MAY be internationalized, as described in Section 2.1 ✨
• tls_client_certificate_bound_access_tokens: OPTIONAL 🔐 This is a boolean that says whether the protected resource supports mutual-TLS client certificate-bound access tokens [RFC8705]. If it's omitted, the default value is false 💅
• authorization_details_types_supported: OPTIONAL 🧩 This is a JSON array of the authorization details type values the resource server supports when the authorization_details request parameter [RFC9396] is used.
• dpop_signing_alg_values_supported: OPTIONAL 🌸 This is a JSON array of the JWS alg values (taken from the "JSON Web Signature and Encryption Algorithms" registry [IANA.JOSE]) that the resource server supports for validating Demonstrating Proof of Possession (DPoP) proof JWTs [RFC9449] 🪄
• dpop_bound_access_tokens_required: OPTIONAL 💜 This is a boolean that specifies whether the protected resource always requires DPoP-bound access tokens [RFC9449]. If it's omitted, the default value is false 🙌

Additional protected resource metadata parameters MAY also be used. The list isn't a closed club 🎉

2.1. Human-Readable Resource Metadata

Human-readable resource metadata values, and resource metadata values that point to human-readable content, MAY be represented in multiple languages and scripts 🌏 For example, fields like resource_name, resource_documentation, resource_tos_uri, and resource_policy_uri might have several locale-specific values so they work in different places 🗺️

To say which languages and scripts you mean, language tags [BCP47] get added to the resource metadata parameter names, separated from the name by a # character 🏷️ JSON member names (see [RFC8259]) are case sensitive, so it is RECOMMENDED that language tag values in Claim Names be spelled with the same character case they're registered with in the "Language Subtag Registry" [IANA.Language]. Usually that means language names are lowercase, region names are uppercase, and languages are mixed-case 🧐 However, language tag values are case insensitive per [BCP47], so implementations SHOULD treat language tag values in a case-insensitive way 🤓 Per the recommendations in [BCP47], language tag values used in metadata parameter names should only be as specific as is necessary. For example, fr might be enough in lots of contexts, so you don't need fr-CA or fr-FR 🇫🇷

Here's an example. A resource could list its name in English as "resource_name#en": "My Resource" and its name in Italian as "resource_name#it": "La mia bella risorsa" within its metadata 🇮🇹 Any or all of these names MAY be displayed to the end user, and the choice of which to show can depend 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 shown in a user interface 🙅‍♀️ To keep things interoperable, it is RECOMMENDED that each kind of human-readable metadata include an instance of its parameter without any language tags, in addition to the language-specific ones. It is also RECOMMENDED that any human-readable fields sent without language tags contain values that look good on a wide variety of systems 🌈

2.2. Signed Protected Resource Metadata

Metadata values MAY also be provided as a signed_metadata value 🔏 This is a JSON Web Token (JWT) [JWT] that asserts metadata values about the protected resource as one bundle. The set of metadata parameters that can be used as claims in signed metadata is defined in Section 2 💅 The signed metadata MUST be digitally signed or MACed (protected with a Message Authentication Code) using a JSON Web Signature (JWS) [JWS], and it MUST contain an iss (issuer) claim that names the party vouching for the claims in the signed metadata 🫡 Consumers of the metadata MAY ignore the signed metadata if they don't support this feature. If a consumer does support signed metadata, the metadata values conveyed in the signed metadata MUST take precedence over the corresponding values conveyed using plain JSON elements 👑

Signed metadata gets included in the protected resource metadata JSON object using this OPTIONAL metadata parameter:

• signed_metadata: This is a JWT containing metadata parameters about the protected resource as claims 🧾 The value is a string made up of the entire signed JWT. A signed_metadata parameter SHOULD NOT appear as a claim in the JWT. It is RECOMMENDED to reject any metadata in which this occurs 🚨

3. Obtaining Protected Resource Metadata

Protected resources that support metadata MUST make a JSON document containing metadata, as specified in Section 2, available at a URL 🗺️ That URL gets formed by inserting a well-known URI string into the protected resource's resource identifier, between the host component and the path and/or query components (if there are any) ✨ By default, the well-known URI string is /.well-known/oauth-protected-resource. The syntax and semantics of .well-known are defined in [RFC8615]. The well-known URI path suffix that gets used MUST be registered in the "Well-Known URIs" registry [IANA.well-known]. Examples of this construction can be found in Section 3.1 🎀

The term "application", as used below (and as used in [RFC8414]), covers all the components used to accomplish the task for the use case 🧩 That can include OAuth clients, authorization servers, protected resources, and non-OAuth components, including the code running in each of them. Applications are built to solve particular problems and may use lots of components and services 🛠️

Different applications that use OAuth protected resources in application-specific ways MAY define and register different well-known URI path suffixes for publishing the protected resource metadata they use 🌷 For instance, say the Example application uses an OAuth protected resource in an Example-specific way and has Example-specific metadata values it needs to publish. Then it might register and use the example-protected-resource URI path suffix, and publish the metadata document at the URL formed by inserting /.well-known/example-protected-resource between the host and path and/or query components of the protected resource's resource identifier 🦋 Alternatively, lots of these applications will just use the default well-known URI string, /.well-known/oauth-protected-resource. That's the right choice for general-purpose OAuth protected resources, and they don't need to register an application-specific one 💜

An OAuth 2.0 application using this specification MUST specify which well-known URI suffix it will use for this purpose 📌 The same protected resource MAY choose to publish its metadata at multiple well-known locations derived from its resource identifier. For example, it could publish metadata at both /.well-known/example-protected-resource and /.well-known/oauth-protected-resource 🌈

3.1. Protected Resource Metadata Request

Okay so the metadata doc MUST be fetched with an HTTP GET at the URL we already talked about 💅 no other method, bestie.

Here's the vibe when the resource identifier is https://resource.example.com. It has no path, so the consumer just does this 👇

  GET /.well-known/oauth-protected-resource HTTP/1.1
  Host: resource.example.com

Now if the resource identifier has a path or query component, any terminating slash (/) after the host MUST be removed first 🫶 then you insert /.well-known/ plus the well-known URI path suffix between the host and the path and/or query. Like, when the resource identifier is https://resource.example.com/resource1, the request becomes:

  GET /.well-known/oauth-protected-resource/resource1 HTTP/1.1
  Host: resource.example.com

(The original example is written with a line break, but it's the same URL, I promise 🌸)

Why is this so iconic? Paths let you support multiple resources on one host 🦋 which is REQUIRED in some multi-tenant hosting setups. This use of .well-known is all about supporting multiple resources per host. Unlike its use in [RFC8615], it does NOT give general info about the host 🙈

3.2. Protected Resource Metadata Response

The response is a set of metadata parameters about the protected resource's configuration ✨ A successful response MUST use the 200 OK HTTP status code and return a JSON object using the application/json content type. The members are a subset of the metadata parameters defined in Section 2. Additional metadata parameters MAY be defined and used, and any metadata parameters that are not understood MUST be ignored 💜

Parameters with multiple values are represented as JSON arrays. Parameters with zero values MUST be omitted from the response 🍓

An error response uses the applicable HTTP status code value.

Here's a non-normative example response, so it's just a vibe check, not a rule 🧚

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

  {
   "resource":
     "https://resource.example.com",
   "authorization_servers":
     ["https://as1.example.com",
      "https://as2.example.net"],
   "bearer_methods_supported":
     ["header", "body"],
   "scopes_supported":
     ["profile", "email", "phone"],
   "resource_documentation":
     "https://resource.example.com/resource_documentation.html"
  }

3.3. Protected Resource Metadata Validation

Okay this part is so important, bestie 😭 The resource value returned MUST be identical to the protected resource's resource identifier value, the one the well-known suffix got inserted into to build the URL we fetched. If they don't match, the data in the response MUST NOT be used. Period 💀

If the metadata was retrieved from a URL the protected resource gave you through the WWW-Authenticate resource_metadata parameter, then the resource value returned MUST be identical to the URL the client used to hit the resource server. If those aren't identical either, the data MUST NOT be used 🔥

These validation steps can thwart impersonation attacks, as described in Section 7.3 🕵️‍♀️

The recipient MUST validate that any signed metadata was signed by a key belonging to the issuer, and that the signature is valid. If the signature doesn't validate or the issuer isn't trusted, the recipient SHOULD treat this as an error condition 🥺

4. Authorization Server Metadata ✨

To support use cases where the set of legit protected resources for an authorization server can be enumerated, this spec defines the authorization server metadata parameter protected_resources 👑 It lets the authorization server explicitly list the protected resources.

Note that if the set of legit authorization servers for a protected resource is also enumerable, the lists in the authorization server metadata and the protected resource metadata SHOULD be cross-checked against each other for consistency when the application profile uses them 🦋

The following authorization server metadata parameter is defined here and registered in the "OAuth Authorization Server Metadata" registry, which was established in "OAuth 2.0 Authorization Server Metadata" [RFC8414] 💅

protected_resources OPTIONAL. JSON array containing a list of resource identifiers for OAuth protected resources that can be used with this authorization server. Authorization servers MAY choose not to advertise some supported protected resources, even when this parameter is used. In some use cases the set of protected resources won't be enumerable, in which case this metadata parameter will not be present 🌈

5. Use of WWW-Authenticate for Protected Resource Metadata ✨

A protected resource MAY use the WWW-Authenticate HTTP response header field, as discussed in [RFC9110], to return a URL to its protected resource metadata to the client. The client can then retrieve that metadata as described in Section 3. The client might then, for instance, figure out which authorization server to use for the resource based on the metadata it retrieved 🧚

Here's a typical end-to-end flow. Note that while this example uses the OAuth 2.0 authorization code flow, a similar sequence could also be implemented with any other OAuth flow 🎀

     +----------+              +----------+    +---------------+
     |  Client  |              | Resource |    | Authorization |
     |          |              |  Server  |    |    Server     |
     +----+-----+              +----+-----+    +-------+-------+
          |                         |                  |
          |  1. Resource Request    |                  |
          | ----------------------> |                  |
          |  Without Access Token   |                  |
          |                         |                  |
          |                         |                  |
          |   2. WWW-Authenticate   |                  |
          | <---------------------- |                  |
          |                         |                  |
          |                         |                  |
          |   3. Fetch RS Metadata  |                  |
          | ----------------------> |                  |
          |                         |                  |
          |                         |                  |
          | 4. RS Metadata Response |                  |
          | <---------------------- |                  |
          |                         |                  |
+---------+---------------+         |                  |
| 5. Validate RS Metadata |         |                  |
| Build AS Metadata URL   |         |                  |
+---------+---------------+         |                  |
          |                         |                  |
          |   6. Fetch AS Metadata  |                  |
          | ------------------------+----------------> |
          |                         |                  |
          |                         |                  |
          | 7. AS Metadata Response |                  |
          | <-----------------------+----------------- |
          |                         |                  |
        +-+-------------------------+------------------+-+
        |       8-9. OAuth Authorization Code Flow       |
        |            Client Obtains Access Token         |
        +-+-------------------------+------------------+-+
          |                         |                  |
          |  10. Resource Request   |                  |
          | ----------------------> |                  |
          |  With Access Token      |                  |
          |                         |                  |
          |                         |                  |
          |  11. Resource Response  |                  |
          | <---------------------- |                  |
          |                         |                  |
     +----+-----+              +----+-----+    +-------+-------+
     |  Client  |              | Resource |    | Authorization |
     |          |              |  Server  |    |    Server     |
     +----------+              +----------+    +---------------+

                      Figure 1: Sequence Diagram

Here's the step-by-step, bestie 📝

1. The client makes a request to a protected resource without presenting an access token.
2. The resource server responds with a WWW-Authenticate header including the URL of the protected resource metadata.
3. The client fetches the protected resource metadata from this URL.
4. The resource server responds with the protected resource metadata according to Section 3.2.
5. The client validates the protected resource metadata, as described in Section 3.3, and builds the authorization server metadata URL from an issuer identifier in the resource metadata according to [RFC8414].
6. The client makes a request to fetch the authorization server metadata.
7. The authorization server responds with the authorization server metadata document according to [RFC8414].
8. The client directs the user agent to the authorization server to begin the authorization flow.
9. The authorization exchange is completed and the authorization server returns an access token to the client.
10. The client repeats the resource request from step 1, presenting the newly obtained access token.
11. The resource server returns the requested protected resource.

5.1. WWW-Authenticate Response

This spec introduces a new parameter in the WWW-Authenticate HTTP response header field to indicate the protected resource metadata URL 🦋

resource_metadata: The URL of the protected resource metadata.

Here's an example of a WWW-Authenticate header that includes the resource identifier 👇

  HTTP/1.1 401 Unauthorized
  WWW-Authenticate: Bearer resource_metadata=
    "https://resource.example.com/.well-known/oauth-protected-resource"

The HTTP status code in that example is defined by [RFC6750] ✨

This parameter MAY also be used in WWW-Authenticate responses that use authorization schemes other than "Bearer" [RFC6750], such as the DPoP scheme defined by [RFC9449] 💜

The resource_metadata parameter MAY be combined with other parameters defined in other extensions, such as the max_age parameter defined by [RFC9470] 🌸

5.2. Changes to Resource Metadata

At any point, for any reason the resource server decides, the protected resource MAY respond with a new WWW-Authenticate challenge that includes a value for the protected resource metadata URL, to indicate that its metadata may have changed. If the client gets such a WWW-Authenticate response, it SHOULD retrieve the updated protected resource metadata and use the new values after validating them as described in Section 3.3. Among other things, this lets a resource server change which authorization servers it uses without any other coordination with clients 🫧

5.3. Client Identifier and Client Authentication 🎀

okay so how the client's identifier gets set up at the authorization server? totally out of scope for this spec 🙈 that's a whole other party's problem.

this spec is built for the vibe where the client has zero prior knowledge about the resource server, and the resource server might or might not already know the client. 🧚

there are already some ways an unrecognized client can still use an authorization server, like using Dynamic Client Registration [RFC7591] to register the client before starting the authorization flow 💅. future OAuth extensions might come up with alternatives too, like using URLs to identify clients 🦋.

5.4. Compatibility with Other Authentication Methods 🌈

resource servers MAY return other WWW-Authenticate headers for different authentication schemes ✨. this lets the resource server support clients that may or may not implement this spec, and it lets clients choose whichever authentication scheme they prefer 💜. main character energy for everyone 👑.

6. String Operations 💅

processing some OAuth 2.0 messages means comparing values inside them to known values 🔍. for example, the member names in the metadata response might get compared to specific names like resource. but comparing Unicode strings [UNICODE] is lowkey dangerous with significant security implications 😭🔥.

so comparisons between JSON strings and other Unicode strings MUST be performed as follows:

1. Remove any JSON-applied escaping to produce an array of Unicode code points.
2. Unicode Normalization [USA15] MUST NOT be applied at any point to either the JSON string or the string it is to be compared against. no normalization, no exceptions 🙅‍♀️.
3. Comparisons between the two strings MUST be performed as a Unicode code-point-to-code-point equality comparison.

note that this is the same equality comparison procedure as the one in Section 8.3 of [RFC8259] ✨. same energy, same rules 🫶.

7. Security Considerations 🚨

7.1. TLS Requirements 🔐

implementations MUST support TLS. they MUST also follow the guidance in [BCP195], which gives recommendations and requirements for leveling up the security of deployed services that use TLS 💖.

using TLS at the protected resource metadata URLs protects against information disclosure and tampering 🛡️.

7.2. Scopes 🧁

the scopes_supported parameter is the list of scopes the resource server is willing to disclose that it supports. it is NOT meant to mean that an OAuth client should request every scope on the list 🙅‍♀️. the client SHOULD still follow OAuth best practices and request tokens with as limited a scope as possible for the given operation, as described in Section 2.3 of "Best Current Practice for OAuth 2.0 Security" [RFC9700] 🎀.

7.3. Impersonation Attacks 👀

TLS certificate checking MUST be performed by the client as described in [RFC9525] when making a protected resource metadata request. checking that the server certificate is valid for the resource identifier URL prevents adversary-in-the-middle and DNS-based attacks 🕵️‍♀️. these attacks could trick a client into using an attacker's resource server, which would enable impersonation of the legitimate protected resource. if an attacker pulls that off, they can access whatever resources the affected client has access to, using the protected resource they're impersonating 😱.

an attacker may also try to impersonate a protected resource by publishing a metadata document that contains a resource metadata parameter using the resource identifier URL of the protected resource being impersonated, but with information the attacker chose. this would enable them to impersonate that protected resource, if the client accepts it 💀. to prevent this, the client MUST ensure that the resource identifier URL it is using as the prefix for the metadata request exactly matches the value of the resource metadata parameter in the protected resource metadata document it received, as described in Section 3.3 🚫.

7.4. Audience-Restricted Access Tokens 🦋

if a client expects to interact with multiple resource servers, the client SHOULD request audience-restricted access tokens using [RFC8707], and the authorization server SHOULD support audience-restricted access tokens too ✨.

without audience-restricted access tokens, a malicious resource server (RS1) may be able to use the WWW-Authenticate header to get a client to request an access token with a scope used by a legitimate resource server (RS2). then, after the client sends a request to RS1, RS1 could reuse the access token at RS2 💀😭.

this attack isn't explicitly enabled by this specification, and it's possible in a plain OAuth 2.0 deployment too 🙈. but it's made somewhat more likely by the use of dynamically configured clients. so the use of audience-restricted access tokens and Resource Indicators [RFC8707] is RECOMMENDED when using the features in this specification 🫶🔥.

7.5. Publishing Metadata in a Standard Format 📚

publishing info about the protected resource in a standard format makes it easier for both legitimate clients AND attackers to use the protected resource 👀. whether a protected resource publishes its metadata in an ad hoc way or in the standard format defined by this specification, the same defenses against attacks that might use this information should be applied 🛡️.

7.6. Authorization Servers 🏰

to support use cases where the set of legitimate authorization servers to use with the protected resource is enumerable, this specification defines the authorization_servers metadata parameter, which lets you explicitly list them 📝. note that if the set of legitimate protected resources to use with an authorization server is also enumerable, the lists in the protected resource metadata and the authorization server metadata should be cross-checked against each other for consistency when the application profile uses them 🔍.

secure determination of appropriate authorization servers for a protected resource, for all use cases, is out of scope for this specification 🙈. this spec assumes the client has a way of figuring out which authorization servers to use with a protected resource, and that the client is using the correct metadata for each protected resource. implementers need to know that if the client uses an inappropriate authorization server, an attacker may be able to act as an adversary-in-the-middle proxy to a valid authorization server, and neither the authorization server nor the client would notice 😱.

the ways to determine the appropriate authorization servers for a protected resource are, in general, application dependent 🧩. for instance, some protected resources are used with a fixed authorization server or a set of them, and their locations may be known via out-of-band mechanisms. alternatively, as this specification describes, the protected resource could publish the locations of its authorization servers as metadata values 💅. in other cases, the set of authorization servers that can be used with a protected resource may change dynamically through administrative actions, or through changes to the set of authorization servers adhering to a trust framework. many other ways of determining appropriate associations between protected resources and authorization servers are also possible ✨.

7.7. Server-Side Request Forgery (SSRF) 🕸️

the OAuth client is expected to fetch the authorization server metadata based on the value of the issuer in the resource server metadata. since this specification lets clients interoperate with RSs and ASes they have no prior knowledge of, this opens a risk for Server-Side Request Forgery (SSRF) attacks by malicious users or malicious resource servers 😬. clients SHOULD take appropriate precautions against SSRF attacks, such as blocking requests to internal IP address ranges 🚧. further recommendations can be found in the Open Worldwide Application Security Project (OWASP) SSRF Prevention Cheat Sheet [OWASP.SSRF] 📖.

7.8. Phishing 🎣

this specification may be deployed in a scenario where the desired HTTP resource is identified by a user-selected URL. if that resource is malicious or compromised, it could mislead the user into revealing their account credentials or authorizing unwanted access to OAuth-controlled capabilities 😱. this risk is reduced, but NOT eliminated, by following best practices for OAuth user interfaces, such as providing clear notice to the user, displaying the authorization server's domain name, supporting origin-bound phishing-resistant authenticators, supporting the use of password managers, and applying heuristic checks such as domain reputation 🛡️💜.

7.9. Differences Between Unsigned and Signed Metadata 🔏

unsigned metadata is integrity protected by the use of TLS at the site where it is hosted. this means its security depends on the Internet Public Key Infrastructure using X.509 (PKIX), as described in [RFC9525]. signed metadata is additionally integrity protected by the JWS signature applied by the issuer, and that does NOT depend on the Internet PKI 🙌.

when using unsigned metadata, the party issuing the metadata is the protected resource itself, which is represented by the resource value in the metadata. when using signed metadata, the party issuing the metadata is represented by the iss (issuer) claim in the signed metadata 🪪. with signed metadata, applications can make trust decisions based on the issuer that did the signing, which is information that is NOT available with unsigned metadata 🤯. how these trust decisions get made is out of scope for this specification 🙈.

7.10. Metadata Caching 🗂️

protected resource metadata is retrieved using an HTTP GET request, as specified in Section 3.1. normal HTTP caching behaviors apply, which means the GET request may retrieve a cached copy of the content rather than the latest copy 🕰️. implementations should use HTTP caching directives such as Cache-Control with max-age, as defined in [RFC9111], to enable caching of retrieved metadata for appropriate time periods ✨🍓.

8. IANA Considerations ✨

okay bestie, this is the registry section and it is SO important 🗂️💅 Values get registered via Specification Required [RFC8126] 🎀 Registration requests go to <oauth-ext-review@ietf.org> to kick off a two-week review period ⏳ BUT, to let people grab values before the final spec is published, the designated experts MAY approve a registration once they're satisfied the spec will be completed and published 🦋 And if the spec isn't completed and published in a timely manner (as the designated experts decide), the designated experts MAY ask IANA to withdraw the registration 💀

Registration requests sent to the mailing list for review should use an appropriate subject, like "Request to register OAuth Protected Resource Metadata: example" 💌

Within the review period, the designated experts will either approve or deny, and they'll tell the review list and IANA which one 📣 Denials should include an explanation and, if it applies, suggestions for making the request work next time 🌸 If the designated experts are not responsive, the registration requesters SHOULD contact IANA to escalate things 🚨

Designated experts should check proposed registrations against these criteria: they MUST be unique (no duplicating existing functionality) 👑, they are likely generally applicable rather than being for a single application 🌈, and they are clear and fit the purpose of the registry ✨

IANA MUST only accept registry updates from the designated experts, and it SHOULD direct all registration requests to the review mailing list 📬

So the review is broadly informed, there SHOULD be multiple designated experts representing the perspectives of different applications using this specification 🧚 If registering something could look like a conflict of interest for a particular expert, that expert SHOULD defer to the judgment of the other experts 🫶

The mailing list enables public review of registration requests, so both designated experts and other interested people can give feedback on proposals 💜 Designated experts MAY allocate values before the final specification is published 🍓 That way authors get early guidance, and any issues can be fixed before publication 🌟

---

8.1. OAuth Protected Resource Metadata Registry 🎀

This specification establishes the "OAuth Protected Resource Metadata" registry for OAuth 2.0 protected resource metadata names 📚 The registry records the protected resource metadata parameter and a reference to the specification that defines it 🔖

8.1.1. Registration Template 📝

Metadata Name: The name requested (e.g., "resource"). This name is case sensitive 🔠 Names MUST NOT match other registered names in a case-insensitive manner unless the designated experts state that there is a compelling reason to allow an exception 🙈

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

Change Controller: For IETF Stream RFCs, list "IETF". 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 📖

8.1.2. Initial Registry Contents 🌈

Here's the starter pack of parameters ✨ Every one of them has Change Controller IETF and points at Section 2 of RFC 9728, except for signed_metadata, which points at Section 2.2 💜

Metadata Name:  resource
Metadata Description:  Protected resource's resource identifier URL
Change Controller:  IETF
Specification Document(s):  Section 2 of RFC 9728

Metadata Name:  authorization_servers
Metadata Description:  JSON array containing a list of OAuth
   authorization server issuer identifiers
Change Controller:  IETF
Specification Document(s):  Section 2 of RFC 9728

Metadata Name:  jwks_uri
Metadata Description:  URL of the protected resource's JWK Set
   document
Change Controller:  IETF
Specification Document(s):  Section 2 of RFC 9728

Metadata Name:  scopes_supported
Metadata Description:  JSON array containing a list of the OAuth 2.0
   scope values that are used in authorization requests to request
   access to this protected resource
Change Controller:  IETF
Specification Document(s):  Section 2 of RFC 9728

Metadata Name:  bearer_methods_supported
Metadata Description:  JSON array containing a list of the OAuth 2.0
   bearer token presentation methods that this protected resource
   supports
Change Controller:  IETF
Specification Document(s):  Section 2 of RFC 9728

Metadata Name:  resource_signing_alg_values_supported
Metadata Description:  JSON array containing a list of the JWS
   signing algorithms (alg values) supported by the protected
   resource for signed content
Change Controller:  IETF
Specification Document(s):  Section 2 of RFC 9728

Metadata Name:  resource_name
Metadata Description:  Human-readable name of the protected resource
Change Controller:  IETF
Specification Document(s):  Section 2 of RFC 9728

Metadata Name:  resource_documentation
Metadata Description:  URL of a page containing human-readable
   information that developers might want or need to know when using
   the protected resource
Change Controller:  IETF
Specification Document(s):  Section 2 of RFC 9728

Metadata Name:  resource_policy_uri
Metadata Description:  URL of a page containing human-readable
   information about the protected resource's requirements on how the
   client can use the data provided by the protected resource
Change Controller:  IETF
Specification Document(s):  Section 2 of RFC 9728

Metadata Name:  resource_tos_uri
Metadata Description:  URL of a page containing human-readable
   information about the protected resource's terms of service
Change Controller:  IETF
Specification Document(s):  Section 2 of RFC 9728

Metadata Name:  tls_client_certificate_bound_access_tokens
Metadata Description:  Boolean value indicating protected resource
   support for mutual-TLS client certificate-bound access tokens
Change Controller:  IETF
Specification Document(s):  Section 2 of RFC 9728

Metadata Name:  authorization_details_types_supported
Metadata Description:  JSON array containing a list of the
   authorization details type values supported by the resource server
   when the authorization_details request parameter is used
Change Controller:  IETF
Specification Document(s):  Section 2 of RFC 9728

Metadata Name:  dpop_signing_alg_values_supported
Metadata Description:  JSON array containing a list of the JWS alg
   values supported by the resource server for validating DPoP proof
   JWTs
Change Controller:  IETF
Specification Document(s):  Section 2 of RFC 9728

Metadata Name:  dpop_bound_access_tokens_required
Metadata Description:  Boolean value specifying whether the protected
   resource always requires the use of DPoP-bound access tokens
Change Controller:  IETF
Specification Document(s):  Section 2 of RFC 9728

Metadata Name:  signed_metadata
Metadata Description:  Signed JWT containing metadata parameters
   about the protected resource as claims
Change Controller:  IETF
Specification Document(s):  Section 2.2 of RFC 9728

---

8.2. OAuth Authorization Server Metadata Registry 🌸

IANA has registered the following authorization server metadata parameter in the "OAuth Authorization Server Metadata" registry, which was established in "OAuth 2.0 Authorization Server Metadata" [RFC8414] 🫧

8.2.1. Registry Contents 💖

Metadata Name:  protected_resources
Metadata Description:  JSON array containing a list of resource
   identifiers for OAuth protected resources
Change Controller:  IETF
Specification Document(s):  Section 4 of RFC 9728

---

8.3. Well-Known URIs Registry 🦋

This specification registers the well-known URI defined in Section 3 in the "Well-Known URIs" registry [IANA.well-known] 🧚

8.3.1. Registry Contents 🎀

URI Suffix:  oauth-protected-resource
Reference:  Section 3 of RFC 9728
Status:  permanent
Change Controller:  IETF
Related Information:  (none)

---

9. References 📚

9.1. Normative References 📚✨

okay bestie, these are the essential reads 💅

[BCP195] Best Current Practice 195, https://www.rfc-editor.org/info/bcp195. At the time of writing, this BCP comprises the following:

Moriarty, K. and S. Farrell, "Deprecating TLS 1.0 and TLS 1.1", BCP 195, RFC 8996, DOI 10.17487/RFC8996, March 2021, https://www.rfc-editor.org/info/rfc8996.

Sheffer, Y., Saint-Andre, P., and T. Fossati, "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)", BCP 195, RFC 9325, DOI 10.17487/RFC9325, November 2022, https://www.rfc-editor.org/info/rfc9325.

[BCP47] Best Current Practice 47, https://www.rfc-editor.org/info/bcp47. At the time of writing, this BCP comprises the following:

Phillips, A., Ed. and M. Davis, Ed., "Matching of Language Tags", BCP 47, RFC 4647, DOI 10.17487/RFC4647, September 2006, https://www.rfc-editor.org/info/rfc4647.

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.

[IANA.Language] IANA, "Language Subtag Registry", https://www.iana.org/assignments/language-subtag-registry.

[JWA] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, DOI 10.17487/RFC7518, May 2015, https://www.rfc-editor.org/info/rfc7518.

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

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

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

[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/RFC6750, October 2012, https://www.rfc-editor.org/info/rfc6750.

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

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

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

[RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, https://www.rfc-editor.org/info/rfc8615.

[RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T. Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens", RFC 8705, DOI 10.17487/RFC8705, February 2020, https://www.rfc-editor.org/info/rfc8705.

[RFC8707] Campbell, B., Bradley, J., and H. Tschofenig, "Resource Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, February 2020, https://www.rfc-editor.org/info/rfc8707.

[RFC9110] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022, https://www.rfc-editor.org/info/rfc9110.

[RFC9111] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Caching", STD 98, RFC 9111, DOI 10.17487/RFC9111, June 2022, https://www.rfc-editor.org/info/rfc9111.

[RFC9396] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 Rich Authorization Requests", RFC 9396, DOI 10.17487/RFC9396, May 2023, https://www.rfc-editor.org/info/rfc9396.

[RFC9449] Fett, D., Campbell, B., Bradley, J., Lodderstedt, T., Jones, M., and D. Waite, "OAuth 2.0 Demonstrating Proof of Possession (DPoP)", RFC 9449, DOI 10.17487/RFC9449, September 2023, https://www.rfc-editor.org/info/rfc9449.

[RFC9525] Saint-Andre, P. and R. Salz, "Service Identity in TLS", RFC 9525, DOI 10.17487/RFC9525, November 2023, https://www.rfc-editor.org/info/rfc9525.

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

[USA15] Whistler, K., Ed., "Unicode Normalization Forms", Unicode Standard Annex #15, 14 August 2024, https://www.unicode.org/reports/tr15/.

9.2. Informative References 🌸

These are the bonus reads, the "good to know" 🧚

[FAPI.MessageSigning] Tonge, D. and D. Fett, "FAPI 2.0 Message Signing (Draft)", 24 March 2023, https://openid.net/specs/fapi-2_0-message-signing.html.

[IANA.JOSE] IANA, "JSON Web Signature and Encryption Algorithms", https://www.iana.org/assignments/jose.

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

[OpenID.Discovery] Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID Connect Discovery 1.0 incorporating errata set 2", 15 December 2023, https://openid.net/specs/openid-connect-discovery-1_0.html.

[OWASP.SSRF] OWASP Foundation, "OWASP Server-Side Request Forgery Prevention Cheat Sheet", https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html.

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

[RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July 2019, https://www.rfc-editor.org/info/rfc8620.

[RFC9470] Bertocci, V. and B. Campbell, "OAuth 2.0 Step Up Authentication Challenge Protocol", RFC 9470, DOI 10.17487/RFC9470, September 2023, https://www.rfc-editor.org/info/rfc9470.

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

Acknowledgements 🫶

Big thank-yous, bestie! The authors of this specification would like to thank the attendees of the IETF 115 OAuth and HTTP API Working Group meetings and the attendees of subsequent OAuth Working Group meetings for their input on this specification. They also want to thank Amanda Baber, Mike Bishop, Ralph Bragg, Brian Campbell, Deb Cooley, Gabriel Corona, Roman Danyliw, Vladimir Dzhuvinov, George Fletcher, Arnt Gulbrandsen, Pieter Kasselman, Murray Kucherawy, David Mandelberg, Tony Nadalin, Francesca Palombini, John Scudder, Rifaat Shekh-Yusef, Filip Skokan, Orie Steele, Atul Tulshibagwale, Éric Vyncke, Paul Wouters, and Bo Wu for their contributions to the specification 💜

Authors' Addresses 🦋

Michael B. Jones
Self-Issued Consulting
Email: michael_b_jones@hotmail.com
URI:   https://self-issued.info/

Phil Hunt
Independent Identity, Inc.
Email: phil.hunt@yahoo.com

Aaron Parecki
Okta
Email: aaron@parecki.com
URI:   https://aaronparecki.com/