idnits 2.17.1 draft-jones-oauth-resource-metadata-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (January 19, 2017) is 2626 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'I-D.ietf-oauth-mix-up-mitigation' is defined on line 743, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7525 (ref. 'BCP195') (Obsoleted by RFC 9325) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) -- Possible downref: Non-RFC (?) normative reference: ref. 'UNICODE' -- Possible downref: Non-RFC (?) normative reference: ref. 'USA15' Summary: 6 errors (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track P. Hunt 5 Expires: July 23, 2017 Oracle 6 January 19, 2017 8 OAuth 2.0 Protected Resource Metadata 9 draft-jones-oauth-resource-metadata-01 11 Abstract 13 This specification defines a metadata format that an OAuth 2.0 client 14 can use to obtain the information needed to interact with an OAuth 15 2.0 protected resource. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on July 23, 2017. 34 Copyright Notice 36 Copyright (c) 2017 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 1.1. Requirements Notation and Conventions . . . . . . . . . . 3 53 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 54 2. Protected Resource Metadata . . . . . . . . . . . . . . . . . 4 55 2.1. Signed Protected Resource Metadata . . . . . . . . . . . 5 56 3. Obtaining Protected Resource Metadata . . . . . . . . . . . . 6 57 3.1. Protected Resource Metadata Request . . . . . . . . . . . 6 58 3.2. Protected Resource Metadata Response . . . . . . . . . . 7 59 3.3. Protected Resource Metadata Validation . . . . . . . . . 8 60 4. Authorization Server Metadata . . . . . . . . . . . . . . . . 8 61 5. String Operations . . . . . . . . . . . . . . . . . . . . . . 8 62 6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 63 6.1. TLS Requirements . . . . . . . . . . . . . . . . . . . . 9 64 6.2. Impersonation Attacks . . . . . . . . . . . . . . . . . . 9 65 6.3. Publishing Metadata in a Standard Format . . . . . . . . 10 66 6.4. Authorization Servers . . . . . . . . . . . . . . . . . . 10 67 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 68 7.1. OAuth Protected Resource Metadata Registry . . . . . . . 11 69 7.1.1. Registration Template . . . . . . . . . . . . . . . . 12 70 7.1.2. Initial Registry Contents . . . . . . . . . . . . . . 12 71 7.2. OAuth Authorization Server Metadata Registry . . . . . . 14 72 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 14 73 7.3. Well-Known URI Registry . . . . . . . . . . . . . . . . . 14 74 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 14 75 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 76 8.1. Normative References . . . . . . . . . . . . . . . . . . 14 77 8.2. Informative References . . . . . . . . . . . . . . . . . 16 78 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 17 79 Appendix B. Document History . . . . . . . . . . . . . . . . . . 17 80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17 82 1. Introduction 84 This specification defines a metadata format enabling OAuth 2.0 85 clients to obtain information needed to interact with an OAuth 2.0 86 protected resource. This specification is intentionally as parallel 87 as possible to "OAuth 2.0 Dynamic Client Registration Protocol" 88 [RFC7591], which enables a client to provide metadata about itself to 89 an OAuth 2.0 authorization server and to OAuth 2.0 Authorization 90 Server Metadata [OAuth.AuthorizationMetadata], which enables a client 91 to obtain metadata about an OAuth 2.0 authorization server. 93 The metadata for a protected resource is retrieved from a well-known 94 location as a JSON [RFC7159] document, which declares information 95 about its capabilities and optionally, its relationships to other 96 services. This process is described in Section 3. 98 This metadata can either be communicated in a self-asserted fashion 99 or as a set of signed metadata values represented as claims in a JSON 100 Web Token (JWT) [JWT]. In the JWT case, the issuer is vouching for 101 the validity of the data about the protected resource. This is 102 analogous to the role that the Software Statement plays in OAuth 103 Dynamic Client Registration [RFC7591]. 105 Each protected resource publishing metadata about itself makes its 106 own metadata document available at a well-known location rooted at 107 the protect resource's URL, even when the resource server implements 108 multiple protected resources. This prevents attackers from 109 publishing metadata supposedly describing the protected resource, but 110 that is not actually authoritative for the protected resource, as 111 described in Section 6.2. 113 The means by which the client obtains the location of the protected 114 resource metadata document is out of scope. In some cases, the 115 location may be manually configured into the client. In other cases, 116 it may be dynamically discovered, for instance, through the use of 117 WebFinger [RFC7033], in a manner related to the description in 118 Section 2 of "OpenID Connect Discovery 1.0" [OpenID.Discovery]. 120 1.1. Requirements Notation and Conventions 122 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 123 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 124 "OPTIONAL" in this document are to be interpreted as described in RFC 125 2119 [RFC2119]. 127 All uses of JSON Web Signature (JWS) [JWS] and JSON Web Encryption 128 (JWE) [JWE] data structures in this specification utilize the JWS 129 Compact Serialization or the JWE Compact Serialization; the JWS JSON 130 Serialization and the JWE JSON Serialization are not used. 132 1.2. Terminology 134 This specification uses the terms "Access Token", "Authorization 135 Code", "Authorization Endpoint", "Authorization Grant", 136 "Authorization Server", "Client", "Client Authentication", "Client 137 Identifier", "Client Secret", "Grant Type", "Protected Resource", 138 "Redirection URI", "Refresh Token", "Resource Owner", "Resource 139 Server", "Response Type", and "Token Endpoint" defined by OAuth 2.0 140 [RFC6749], the terms "Claim Name", "Claim Value", and "JSON Web Token 141 (JWT)" defined by JSON Web Token (JWT) [JWT]. 143 2. Protected Resource Metadata 145 Protected resources can have metadata describing their configuration. 146 The following protected resource metadata values are used by this 147 specification and are registered in the IANA "OAuth Protected 148 Resource Metadata" registry established in Section 7.1: 150 resource 151 REQUIRED. The protected resource's resource identifier, which is 152 a URL that uses the "https" scheme and has no fragment components. 153 This is the location where ".well-known" RFC 5785 [RFC5785] 154 resources containing information about the protected resource are 155 published. Using these well-known resources is described in 156 Section 3. 158 authorization_servers 159 OPTIONAL. JSON array containing a list of OAuth authorization 160 server issuer identifiers, as defined in 161 [OAuth.AuthorizationMetadata], for authorization servers that can 162 be used with this protected resource. Protected resources MAY 163 choose not to advertise some supported authorization servers even 164 when this parameter is used. In some use cases, the set of 165 authorization servers will not be enumerable, in which case this 166 metadata parameter would not be used. 168 jwks_uri 169 OPTIONAL. URL of the protected resource's JWK Set [JWK] document. 170 This contains keys belonging to the protected resource. For 171 instance, this JWK Set MAY contain encryption key(s) that are used 172 to encrypt access tokens to the protected resource. When both 173 signing and encryption keys are made available, a "use" (public 174 key use) parameter value is REQUIRED for all keys in the 175 referenced JWK Set to indicate each key's intended usage. 177 scopes_provided 178 RECOMMENDED. JSON array containing a list of the OAuth 2.0 179 [RFC6749] "scope" values that are used in authorization requests 180 to request access to this protected resource. Protected resources 181 MAY choose not to advertise some scope values provided even when 182 this parameter is used. 184 bearer_methods_supported 185 OPTIONAL. JSON array containing a list of the OAuth 2.0 Bearer 186 Token [RFC6750] presentation methods that this protected resource 187 supports. Defined values are "["header", "fragment", "query"]", 188 corresponding to Sections 2.1, 2.2, and 2.3 of RFC 6750. 190 resource_signing_alg_values_supported 191 OPTIONAL. JSON array containing a list of the JWS [JWS] signing 192 algorithms ("alg" values) [JWA] supported by the protected 193 resource for signed content. The value "none" MAY be included. 195 resource_encryption_alg_values_supported 196 OPTIONAL. JSON array containing a list of the JWE [JWE] 197 encryption algorithms ("alg" values) [JWA] supported by the 198 protected resource for encrypted content. 200 resource_encryption_enc_values_supported 201 OPTIONAL. JSON array containing a list of the JWE encryption 202 algorithms ("enc" values) [JWA] supported by the protected 203 resource for encrypted content. 205 resource_documentation 206 OPTIONAL. URL of a page containing human-readable information 207 that developers might want or need to know when using the 208 protected resource 210 resource_policy_uri 211 OPTIONAL. URL that the protected resource provides to read about 212 the protected resource's requirements on how the client can use 213 the data provided by the protected resource 215 resource_tos_uri 216 OPTIONAL. URL that the protected resource provides to read about 217 the protected resource's terms of service 219 Additional protected resource metadata parameters MAY also be used. 221 2.1. Signed Protected Resource Metadata 223 In addition to JSON elements, metadata values MAY also be provided as 224 a "signed_metadata" value, which is a JSON Web Token (JWT) [JWT] that 225 asserts metadata values about the protected resource as a bundle. A 226 set of claims that can be used in signed metadata are defined in 227 Section 2. The signed metadata MUST be digitally signed or MACed 228 using JSON Web Signature (JWS) [JWS] and MUST contain an "iss" 229 (issuer) claim denoting the party attesting to the claims in the 230 signed metadata. Consumers of the metadata MAY ignore the signed 231 metadata if they do not support this feature. If the consumer of the 232 metadata supports signed metadata, metadata values conveyed in the 233 signed metadata MUST take precedence over those conveyed using plain 234 JSON elements. 236 Signed metadata is included in the protected resource metadata JSON 237 object using this OPTIONAL member: 239 signed_metadata 240 A JWT containing metadata values about the protected resource as 241 claims. This is a string value consisting of the entire signed 242 JWT. A "signed_metadata" metadata value SHOULD NOT appear as a 243 claim in the JWT. 245 3. Obtaining Protected Resource Metadata 247 Protected resources supporting metadata MUST make a JSON document 248 containing metadata as specified in Section 2 available at a path 249 formed by concatenating a well-known URI string such as "/.well- 250 known/oauth-protected-resource" to the protected resource's resource 251 identifier. The syntax and semantics of ".well-known" are defined in 252 RFC 5785 [RFC5785]. The well-known URI path suffix used MUST be 253 registered in the IANA "Well-Known URIs" registry [IANA.well-known]. 255 Different applications utilizing OAuth protected resources in 256 application-specific ways may define and register different well- 257 known URI path suffixes used to publish protected resource metadata 258 as used by those applications. For instance, if the Example 259 application uses an OAuth protected resource in an Example-specific 260 way, and there are Example-specific metadata values that it needs to 261 publish, then it might register and use the "example-resource- 262 configuration" URI path suffix and publish the metadata document at 263 the path formed by concatenating "/.well-known/example-resource- 264 configuration" to the protected resource's resource identifier. 266 An OAuth 2.0 application using this specification MUST specify what 267 well-known URI string it will use for this purpose. The same 268 protected resource MAY choose to publish its metadata at multiple 269 well-known locations relative to its resource identifier, for 270 example, publishing metadata at both "/.well-known/example-resource- 271 configuration" and "/.well-known/oauth-protected-resource". 273 3.1. Protected Resource Metadata Request 275 A protected resource metadata document MUST be queried using an HTTP 276 "GET" request at the previously specified path. 278 The consumer of the metadata would make the following request when 279 the resource identifier is "https://resource.example.com" and the 280 well-known URI path suffix is "oauth-protected-resource" to obtain 281 the metadata, since the resource identifier contains no path 282 component: 284 GET /.well-known/oauth-protected-resource HTTP/1.1 285 Host: resource.example.com 287 If the resource identifier value contains a path component, any 288 terminating "/" MUST be removed before appending "/.well-known/" and 289 the well-known URI path suffix. The consumer of the metadata would 290 make the following request when the resource identifier is 291 "https://resource.example.com/resource1" and the well-known URI path 292 suffix is "oauth-protected-resource" to obtain the metadata, since 293 the resource identifier contains a path component: 295 GET /resource1/.well-known/oauth-protected-resource HTTP/1.1 296 Host: resource.example.com 298 Using path components enables supporting multiple resources per host. 299 This is required in some multi-tenant hosting configurations. This 300 use of ".well-known" is for supporting multiple resources per host; 301 unlike its use in RFC 5785 [RFC5785], it does not provide general 302 information about the host. 304 3.2. Protected Resource Metadata Response 306 The response is a set of claims about the protected resource's 307 configuration. A successful response MUST use the 200 OK HTTP status 308 code and return a JSON object using the "application/json" content 309 type that contains a set of claims as its members that are a subset 310 of the metadata values defined in Section 2. Other claims MAY also 311 be returned. 313 Claims that return multiple values are represented as JSON arrays. 314 Claims with zero elements MUST be omitted from the response. 316 An error response uses the applicable HTTP status code value. 318 The following is a non-normative example response: 320 HTTP/1.1 200 OK 321 Content-Type: application/json 323 { 324 "resource": 325 "https://resource.example.com", 326 "authorization_servers": 327 ["https://as1.example.com", 328 "https://as2.example.net"], 329 "bearer_methods_supported": 330 ["header", "body"], 331 "resource_documentation": 332 "http://resource.example.com/resource_documentation.html" 333 } 335 3.3. Protected Resource Metadata Validation 337 The "resource" value returned MUST be identical to the protected 338 resource's resource identifier value that was concatenated with the 339 well-known URI path suffix to create the URL used to retrieve the 340 metadata. If these values are not identical, the data contained in 341 the response MUST NOT be used. 343 4. Authorization Server Metadata 345 To support use cases in which the set of legitimate protected 346 resources to use with the authorization server is fixed and 347 enumerable, this specification defines the "protected_resources" 348 metadata value, which enables explicitly listing them. Note that if 349 the set of legitimate authorization servers to use with a protected 350 resource is also fixed and enumerable, lists in the authorization 351 server metadata and protected resource metadata should be cross- 352 checked against one another for consistency when these lists are used 353 by the application profile. 355 The following authorization server metadata value is defined by this 356 specification and is registered in the IANA "OAuth Authorization 357 Server Metadata" registry established in OAuth 2.0 Authorization 358 Server Metadata [OAuth.AuthorizationMetadata]. 360 protected_resources 361 OPTIONAL. JSON array containing a list of resource identifiers 362 for OAuth protected resources for protected resources that can be 363 used with this authorization server. Authorization servers MAY 364 choose not to advertise some supported protected resources even 365 when this parameter is used. In some use cases, the set of 366 protected resources will not be enumerable, in which case this 367 metadata parameter would not be used. 369 5. String Operations 371 Processing some OAuth 2.0 messages requires comparing values in the 372 messages to known values. For example, the member names in the 373 metadata response might be compared to specific member names such as 374 "resource". Comparing Unicode [UNICODE] strings, however, has 375 significant security implications. 377 Therefore, comparisons between JSON strings and other Unicode strings 378 MUST be performed as specified below: 380 1. Remove any JSON applied escaping to produce an array of Unicode 381 code points. 383 2. Unicode Normalization [USA15] MUST NOT be applied at any point to 384 either the JSON string or to the string it is to be compared 385 against. 387 3. Comparisons between the two strings MUST be performed as a 388 Unicode code point to code point equality comparison. 390 6. Security Considerations 392 6.1. TLS Requirements 394 Implementations MUST support TLS. Which version(s) ought to be 395 implemented will vary over time, and depend on the widespread 396 deployment and known security vulnerabilities at the time of 397 implementation. The protected resource MUST support TLS version 1.2 398 [RFC5246] and MAY support additional transport-layer security 399 mechanisms meeting its security requirements. When using TLS, the 400 client MUST perform a TLS/SSL server certificate check, per RFC 6125 401 [RFC6125]. Implementation security considerations can be found in 402 Recommendations for Secure Use of TLS and DTLS [BCP195]. 404 To protect against information disclosure and tampering, 405 confidentiality protection MUST be applied using TLS with a 406 ciphersuite that provides confidentiality and integrity protection. 408 6.2. Impersonation Attacks 410 TLS certificate checking MUST be performed by the client, as 411 described in Section 6.1, when making a protected resource metadata 412 request. Checking that the server certificate is valid for the 413 resource identifier URL prevents man-in-middle and DNS-based attacks. 414 These attacks could cause a client to be tricked into using an 415 attacker's resource server, which would enable impersonation of the 416 legitimate protected resource. If an attacker can accomplish this, 417 they can access the resources that the affected client has access to 418 using the protected resource that they are impersonating. 420 An attacker may also attempt to impersonate a protected resource by 421 publishing a metadata document that contains a "resource" claim using 422 the resource identifier URL of the protected resource being 423 impersonated, but containing information of the attacker's choosing. 424 This would enable it to impersonate that protected resource, if 425 accepted by the client. To prevent this, the client MUST ensure that 426 the resource identifier URL it is using as the prefix for the 427 metadata request exactly matches the value of the "resource" metadata 428 value in the protected resource metadata document received by the 429 client. 431 6.3. Publishing Metadata in a Standard Format 433 Publishing information about the protected resource in a standard 434 format makes it easier for both legitimate clients and attackers to 435 use the protected resource. Whether a protected resource publishes 436 its metadata in an ad-hoc manner or in the standard format defined by 437 this specification, the same defenses against attacks that might be 438 mounted that use this information should be applied. 440 6.4. Authorization Servers 442 Secure determination of appropriate authorization servers to use with 443 a protected resource for all use cases is out of scope of this 444 specification. This specification assumes that the client has a 445 means of determining appropriate authorization servers to use with a 446 protected resource and that the client is using the correct metadata 447 for each protected resource. Implementers need to be aware that if 448 an inappropriate authorization server is used by the client, that an 449 attacker may be able to act as a man-in-the-middle proxy to a valid 450 authorization server without it being detected by the authorization 451 server or the client. 453 The ways to determine the appropriate authorization servers to use 454 with a protected resource are in general, application-dependent. For 455 instance, some protected resources are used with a fixed 456 authorization server or set of authorization servers, the locations 457 of which may be well known, or which could be published as metadata 458 values by the protected resource. In other cases, the set of 459 authorization servers that can be used with a protected resource can 460 by dynamically changed by administrative actions or by changes to the 461 set of authorization servers adhering to a trust framework. Many 462 other means of determining appropriate associations between protected 463 resources and authorization servers are also possible. 465 To support use cases in which the set of legitimate authorization 466 servers to use with the protected resource is fixed and enumerable, 467 this specification defines the "authorization_servers" metadata 468 value, which enables explicitly listing them. Note that if the set 469 of legitimate protected resources to use with an authorization server 470 is also fixed and enumerable, lists in the protected resource 471 metadata and authorization server metadata should be cross-checked 472 against one another for consistency when these lists are used by the 473 application profile. 475 7. IANA Considerations 477 The following registration procedure is used for the registry 478 established by this specification. 480 Values are registered on a Specification Required [RFC5226] basis 481 after a two-week review period on the oauth-ext-review@ietf.org 482 mailing list, on the advice of one or more Designated Experts. 483 However, to allow for the allocation of values prior to publication, 484 the Designated Experts may approve registration once they are 485 satisfied that such a specification will be published. 487 Registration requests sent to the mailing list for review should use 488 an appropriate subject (e.g., "Request to register OAuth Protected 489 Resource Metadata: example"). 491 Within the review period, the Designated Experts will either approve 492 or deny the registration request, communicating this decision to the 493 review list and IANA. Denials should include an explanation and, if 494 applicable, suggestions as to how to make the request successful. 495 Registration requests that are undetermined for a period longer than 496 21 days can be brought to the IESG's attention (using the 497 iesg@ietf.org mailing list) for resolution. 499 Criteria that should be applied by the Designated Experts includes 500 determining whether the proposed registration duplicates existing 501 functionality, determining whether it is likely to be of general 502 applicability or whether it is useful only for a single application, 503 and whether the registration makes sense. 505 IANA must only accept registry updates from the Designated Experts 506 and should direct all requests for registration to the review mailing 507 list. 509 It is suggested that multiple Designated Experts be appointed who are 510 able to represent the perspectives of different applications using 511 this specification, in order to enable broadly-informed review of 512 registration decisions. In cases where a registration decision could 513 be perceived as creating a conflict of interest for a particular 514 Expert, that Expert should defer to the judgment of the other 515 Experts. 517 7.1. OAuth Protected Resource Metadata Registry 519 This specification establishes the IANA "OAuth Protected Resource 520 Metadata" registry for OAuth 2.0 protected resource metadata names. 521 The registry records the protected resource metadata member and a 522 reference to the specification that defines it. 524 7.1.1. Registration Template 526 Metadata Name: 527 The name requested (e.g., "resource"). This name is case- 528 sensitive. Names may not match other registered names in a case- 529 insensitive manner unless the Designated Experts state that there 530 is a compelling reason to allow an exception. 532 Metadata Description: 533 Brief description of the metadata (e.g., "Resource identifier 534 URL"). 536 Change Controller: 537 For Standards Track RFCs, list the "IESG". For others, give the 538 name of the responsible party. Other details (e.g., postal 539 address, email address, home page URI) may also be included. 541 Specification Document(s): 542 Reference to the document or documents that specify the parameter, 543 preferably including URIs that can be used to retrieve copies of 544 the documents. An indication of the relevant sections may also be 545 included but is not required. 547 7.1.2. Initial Registry Contents 549 o Metadata Name: "resource" 550 o Metadata Description: Protected resource's resource identifier URL 551 o Change Controller: IESG 552 o Specification Document(s): Section 2 of [[ this specification ]] 554 o Metadata Name: "authorization_servers" 555 o Metadata Description: JSON array containing a list of OAuth 556 authorization server issuer identifiers 557 o Change Controller: IESG 558 o Specification Document(s): Section 2 of [[ this specification ]] 560 o Metadata Name: "jwks_uri" 561 o Metadata Description: URL of the protected resource's JWK Set 562 document 563 o Change Controller: IESG 564 o Specification Document(s): Section 2 of [[ this specification ]] 566 o Metadata Name: "scopes_provided" 567 o Metadata Description: JSON array containing a list of the OAuth 568 2.0 "scope" values that are used in authorization requests to 569 request access this protected resource 570 o Change Controller: IESG 571 o Specification Document(s): Section 2 of [[ this specification ]] 572 o Metadata Name: "bearer_methods_supported" 573 o Metadata Description: JSON array containing a list of the OAuth 574 2.0 Bearer Token presentation methods that this protected resource 575 supports 576 o Change Controller: IESG 577 o Specification Document(s): Section 2 of [[ this specification ]] 579 o Metadata Name: "resource_signing_alg_values_supported" 580 o Metadata Description: JSON array containing a list of the JWS 581 signing algorithms ("alg" values) supported by the protected 582 resource for signed content 583 o Change Controller: IESG 584 o Specification Document(s): Section 2 of [[ this specification ]] 586 o Metadata Name: "resource_encryption_alg_values_supported" 587 o Metadata Description: JSON array containing a list of the JWE 588 encryption algorithms ("alg" values) supported by the protected 589 resource for encrypted content 590 o Change Controller: IESG 591 o Specification Document(s): Section 2 of [[ this specification ]] 593 o Metadata Name: "resource_encryption_enc_values_supported" 594 o Metadata Description: JSON array containing a list of the JWE 595 encryption algorithms ("enc" values) supported by the protected 596 resource for encrypted content 597 o Change Controller: IESG 598 o Specification Document(s): Section 2 of [[ this specification ]] 600 o Metadata Name: "resource_documentation" 601 o Metadata Description: URL of a page containing human-readable 602 information that developers might want or need to know when using 603 the protected resource 604 o Change Controller: IESG 605 o Specification Document(s): Section 2 of [[ this specification ]] 607 o Metadata Name: "resource_policy_uri" 608 o Metadata Description: URL that the protected resource provides to 609 read about the protected resource's requirements on how the client 610 can use the data provided by the protected resource 611 o Change Controller: IESG 612 o Specification Document(s): Section 2 of [[ this specification ]] 614 o Metadata Name: "resource_tos_uri" 615 o Metadata Description: URL that the protected resource provides to 616 read about the protected resource's terms of service 617 o Change Controller: IESG 618 o Specification Document(s): Section 2 of [[ this specification ]] 620 7.2. OAuth Authorization Server Metadata Registry 622 The following authorization server metadata value is registered in 623 the IANA "OAuth Authorization Server Metadata" registry established 624 in OAuth 2.0 Authorization Server Metadata 625 [OAuth.AuthorizationMetadata]. 627 7.2.1. Registry Contents 629 o Metadata Name: "protected_resources" 630 o Metadata Description: JSON array containing a list of resource 631 identifiers for OAuth protected resources 632 o Change Controller: IESG 633 o Specification Document(s): Section 4 of [[ this specification ]] 635 7.3. Well-Known URI Registry 637 This specification registers the well-known URI defined in Section 3 638 in the IANA "Well-Known URIs" registry [IANA.well-known] established 639 by RFC 5785 [RFC5785]. 641 7.3.1. Registry Contents 643 o URI suffix: "oauth-protected-resource" 644 o Change controller: IESG 645 o Specification document: Section 3 of [[ this specification ]] 646 o Related information: (none) 648 8. References 650 8.1. Normative References 652 [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, 653 "Recommendations for Secure Use of Transport Layer 654 Security (TLS) and Datagram Transport Layer Security 655 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 656 2015, . 658 [JWA] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 659 DOI 10.17487/RFC7518, May 2015, 660 . 662 [JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 663 RFC 7516, DOI 10.17487/RFC7516, May 2015, 664 . 666 [JWK] Jones, M., "JSON Web Key (JWK)", RFC 7517, 667 DOI 10.17487/RFC7517, May 2015, 668 . 670 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 671 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 672 2015, . 674 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 675 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 676 . 678 [OAuth.AuthorizationMetadata] 679 Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 680 Authorization Server Metadata", draft-ietf-oauth- 681 discovery-05 (work in progress), January 2017, 682 . 685 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 686 Requirement Levels", BCP 14, RFC 2119, 687 DOI 10.17487/RFC2119, March 1997, 688 . 690 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 691 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 692 DOI 10.17487/RFC5226, May 2008, 693 . 695 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 696 (TLS) Protocol Version 1.2", RFC 5246, 697 DOI 10.17487/RFC5246, August 2008, 698 . 700 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 701 Uniform Resource Identifiers (URIs)", RFC 5785, 702 DOI 10.17487/RFC5785, April 2010, 703 . 705 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 706 Verification of Domain-Based Application Service Identity 707 within Internet Public Key Infrastructure Using X.509 708 (PKIX) Certificates in the Context of Transport Layer 709 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 710 2011, . 712 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 713 RFC 6749, DOI 10.17487/RFC6749, October 2012, 714 . 716 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 717 Framework: Bearer Token Usage", RFC 6750, 718 DOI 10.17487/RFC6750, October 2012, 719 . 721 [RFC7033] Jones, P., Salgueiro, G., Jones, M., and J. Smarr, 722 "WebFinger", RFC 7033, DOI 10.17487/RFC7033, September 723 2013, . 725 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 726 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 727 2014, . 729 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 730 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 731 RFC 7591, DOI 10.17487/RFC7591, July 2015, 732 . 734 [UNICODE] The Unicode Consortium, "The Unicode Standard", 735 . 737 [USA15] Davis, M. and K. Whistler, "Unicode Normalization Forms", 738 Unicode Standard Annex 15, June 2015, 739 . 741 8.2. Informative References 743 [I-D.ietf-oauth-mix-up-mitigation] 744 Jones, M., Bradley, J., and N. Sakimura, "OAuth 2.0 Mix-Up 745 Mitigation", draft-ietf-oauth-mix-up-mitigation-01 (work 746 in progress), July 2016. 748 [IANA.well-known] 749 IANA, "Well-Known URIs", 750 . 752 [OpenID.Discovery] 753 Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID 754 Connect Discovery 1.0", November 2014, 755 . 758 Appendix A. Acknowledgements 760 Thanks to George Fletcher and Tony Nadalin for their input on the 761 specification. 763 Appendix B. Document History 765 [[ to be removed by the RFC Editor before publication as an RFC ]] 767 -01 769 o Moved the "protected_resources" authorization server metadata 770 element here, removing it from draft-ietf-oauth-discovery. 772 -00 774 o Created the initial version. This draft reuses some text from 775 draft-ietf-oauth-discovery-03. 777 Authors' Addresses 779 Michael B. Jones 780 Microsoft 782 Email: mbj@microsoft.com 783 URI: http://self-issued.info/ 785 Phil Hunt 786 Oracle 788 Email: phil.hunt@yahoo.com