idnits 2.17.1 draft-ietf-regext-rdap-openid-09.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 (18 January 2022) is 828 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'OIDC' -- Possible downref: Non-RFC (?) normative reference: ref. 'OIDCC' -- Possible downref: Non-RFC (?) normative reference: ref. 'OIDCD' -- Possible downref: Non-RFC (?) normative reference: ref. 'OIDCR' ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 REGEXT Working Group S. Hollenbeck 3 Internet-Draft Verisign Labs 4 Intended status: Standards Track 18 January 2022 5 Expires: 22 July 2022 7 Federated Authentication for the Registration Data Access Protocol 8 (RDAP) using OpenID Connect 9 draft-ietf-regext-rdap-openid-09 11 Abstract 13 The Registration Data Access Protocol (RDAP) provides "RESTful" web 14 services to retrieve registration metadata from domain name and 15 regional internet registries. RDAP allows a server to make access 16 control decisions based on client identity, and as such it includes 17 support for client identification features provided by the Hypertext 18 Transfer Protocol (HTTP). Identification methods that require 19 clients to obtain and manage credentials from every RDAP server 20 operator present management challenges for both clients and servers, 21 whereas a federated authentication system would make it easier to 22 operate and use RDAP without the need to maintain server-specific 23 client credentials. This document describes a federated 24 authentication system for RDAP based on OpenID Connect. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at https://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on 22 July 2022. 43 Copyright Notice 45 Copyright (c) 2022 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 50 license-info) in effect on the date of publication of this document. 51 Please review these documents carefully, as they describe your rights 52 and restrictions with respect to this document. Code Components 53 extracted from this document must include Revised BSD License text as 54 described in Section 4.e of the Trust Legal Provisions and are 55 provided without warranty as described in the Revised BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.1. Problem Statement . . . . . . . . . . . . . . . . . . . . 3 61 1.2. Proposal . . . . . . . . . . . . . . . . . . . . . . . . 3 62 2. Conventions Used in This Document . . . . . . . . . . . . . . 4 63 3. Federated Authentication for RDAP . . . . . . . . . . . . . . 4 64 3.1. RDAP and OpenID Connect . . . . . . . . . . . . . . . . . 4 65 3.1.1. Terminology . . . . . . . . . . . . . . . . . . . . . 5 66 3.1.2. Overview . . . . . . . . . . . . . . . . . . . . . . 5 67 3.1.3. RDAP Authentication and Authorization Steps . . . . . 6 68 3.1.3.1. Provider Discovery . . . . . . . . . . . . . . . 6 69 3.1.3.2. Authentication Request . . . . . . . . . . . . . 6 70 3.1.3.3. End-User Authorization . . . . . . . . . . . . . 7 71 3.1.3.4. Authorization Response and Validation . . . . . . 7 72 3.1.3.5. Token Processing . . . . . . . . . . . . . . . . 7 73 3.1.3.6. Delivery of User Information . . . . . . . . . . 8 74 3.1.4. Specialized Claims for RDAP . . . . . . . . . . . . . 8 75 3.1.4.1. Stated Purpose . . . . . . . . . . . . . . . . . 8 76 3.1.4.2. Do Not Track . . . . . . . . . . . . . . . . . . 9 77 4. Protocol Parameters . . . . . . . . . . . . . . . . . . . . . 10 78 4.1. Client Authentication Request and Response . . . . . . . 10 79 4.2. Token Request and Response . . . . . . . . . . . . . . . 11 80 4.3. Token Refresh and Revocation . . . . . . . . . . . . . . 13 81 4.4. Token Exchange . . . . . . . . . . . . . . . . . . . . . 15 82 4.5. Parameter Processing . . . . . . . . . . . . . . . . . . 15 83 4.6. RDAP Conformance . . . . . . . . . . . . . . . . . . . . 16 84 5. Clients with Limited User Interfaces . . . . . . . . . . . . 16 85 5.1. OAuth 2.0 Device Authorization Grant . . . . . . . . . . 16 86 5.2. Manual Token Management . . . . . . . . . . . . . . . . . 17 87 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 88 6.1. RDAP Extensions Registry . . . . . . . . . . . . . . . . 17 89 6.2. JSON Web Token Claims Registry . . . . . . . . . . . . . 18 90 6.3. RDAP Query Purpose Registry . . . . . . . . . . . . . . . 18 91 7. Implementation Status . . . . . . . . . . . . . . . . . . . . 21 92 8. Security Considerations . . . . . . . . . . . . . . . . . . . 21 93 8.1. Authentication and Access Control . . . . . . . . . . . . 22 94 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 22 95 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 22 96 10.1. Normative References . . . . . . . . . . . . . . . . . . 22 97 10.2. Informative References . . . . . . . . . . . . . . . . . 24 98 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 25 99 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 25 101 1. Introduction 103 The Registration Data Access Protocol (RDAP) provides "RESTful" web 104 services to retrieve registration metadata from domain name and 105 regional internet registries. RDAP allows a server to make access 106 control decisions based on client identity, and as such it includes 107 support for client identification features provided by the Hypertext 108 Transfer Protocol (HTTP) [RFC7230]. 110 RDAP is specified in multiple documents, including "HTTP Usage in the 111 Registration Data Access Protocol (RDAP)" [RFC7480], "Security 112 Services for the Registration Data Access Protocol (RDAP)" [RFC7481], 113 "Registration Data Access Protocol Query Format" [RFC9082], and "JSON 114 Responses for the Registration Data Access Protocol (RDAP)" 115 [RFC9083]. RFC 7481 describes client identification and 116 authentication services that can be used with RDAP, but it does not 117 specify how any of these services can (or should) be used with RDAP. 119 1.1. Problem Statement 121 The traditional "user name and password" authentication method does 122 not scale well in the RDAP ecosystem. Assuming that all domain name 123 and address registries will eventually provide RDAP service, it is 124 impractical and inefficient for users to secure login credentials 125 from the hundreds of different server operators. Authentication 126 methods based on user names and passwords do not provide information 127 that describes the user in sufficient detail (while protecting the 128 personal privacy of the user) for server operators to make fine- 129 grained access control decisions based on the user's identity. The 130 authentication system used for RDAP needs to address all of these 131 needs. 133 1.2. Proposal 135 A basic level of RDAP service can be provided to users who possess an 136 identifier issued by a recognized provider who is able to 137 authenticate and validate the user. The identifiers issued by social 138 media services, for example, can be used. Users who require higher 139 levels of service (and who are willing to share more information 140 about them self to gain access to that service) can secure 141 identifiers from specialized providers who are or will be able to 142 provide more detailed information about the user. Server operators 143 can then make access control decisions based on the identification 144 information provided by the user. 146 A federated authentication system would make it easier to operate and 147 use RDAP by re-using existing identifiers to provide a basic level of 148 access. It can also provide the ability to collect additional user 149 identification information, and that information can be shared with 150 the consent of the user. This document describes a federated 151 authentication system for RDAP based on OpenID Connect [OIDC] that 152 meets all of these needs. 154 2. Conventions Used in This Document 156 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 157 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 158 "OPTIONAL" in this document are to be interpreted as described in BCP 159 14 [RFC2119] [RFC8174] when, and only when, they appear in all 160 capitals, as shown here. 162 3. Federated Authentication for RDAP 164 RDAP itself does not include native security services. Instead, RDAP 165 relies on features that are available in other protocol layers to 166 provide needed security services including access control, 167 authentication, authorization, availability, data confidentiality, 168 data integrity, and identification. A description of each of these 169 security services can be found in "Internet Security Glossary, 170 Version 2" [RFC4949]. This document focuses on a federated 171 authentication system for RDAP that provides services for 172 authentication, authorization, and identification, allowing a server 173 operator to make access control decisions. Section 3 of RFC 7481 174 [RFC7481] describes general considerations for RDAP access control, 175 authentication, and authorization. 177 The traditional client-server authentication model requires clients 178 to maintain distinct credentials for every RDAP server. This 179 situation can become unwieldy as the number of RDAP servers 180 increases. Federated authentication mechanisms allow clients to use 181 one credential to access multiple RDAP servers and reduce client 182 credential management complexity. 184 3.1. RDAP and OpenID Connect 186 OpenID Connect 1.0 [OIDCC] is a decentralized, single sign-on (SSO) 187 federated authentication system that allows users to access multiple 188 web resources with one identifier instead of having to create 189 multiple server-specific identifiers. Users acquire identifiers from 190 OpenID Providers, or OPs. Relying Parties, or RPs, are applications 191 (such as RDAP) that outsource their user authentication function to 192 an OP. OpenID Connect is built on top of the authorization framework 193 provided by the OAuth 2.0 [RFC6749] protocol. 195 The OAuth authorization framework describes a method for users to 196 access protected web resources without having to hand out their 197 credentials. Instead, clients are issued Access Tokens by 198 authorization servers with the permission of the resource owners. 199 Using OpenID Connect and OAuth, multiple RDAP servers can form a 200 federation and clients can access any server in the federation by 201 providing one credential registered with any OP in that federation. 202 The OAuth authorization framework is designed for use with HTTP and 203 thus can be used with RDAP. 205 3.1.1. Terminology 207 This document uses the terms "client" and "server" defined by RDAP 208 [RFC7480]. An RDAP client performs the role of an OpenID Connect 209 Core [OIDCC] Entity or End-User. An RDAP server performs the role of 210 an OpenID Connect Core Relying Party (RP). Additional terms from 211 Section 1.2 of the OpenID Connect Core specification are incorporated 212 by reference. 214 3.1.2. Overview 216 At a high level, RDAP authentication of a browser-based client using 217 OpenID Connect requires completion of the following steps: 219 1. An RDAP client sends an RDAP "help" query to an RDAP server to 220 determine the type of OpenID Authorization Server that's used by 221 the RDAP server. This information is returned in the 222 rdapConformance section of the response. A value of 223 "rdap_openidc_local_level_0" indicates that the server uses a 224 local Authorization Server. A value of 225 "rdap_openidc_remote_level_0" indicates that the server uses a 226 remote Authorization Server. 227 2. An RDAP client (acting as an OpenID End-User) sends a "tokens" 228 request (see Section 4.2) to an RDAP server. The request MUST 229 include an "id" parameter if the server uses only a remote 230 Authorization Server. The "id" parameter is OPTIONAL if the 231 server uses a local Authorization Server. 232 3. The RDAP server (acting as an OpenID Relying Party (RP)) 233 prepares an Authentication Request containing the desired 234 request parameters. 235 4. The RDAP server sends the RDAP client and Authentication Request 236 to an Authorization Server operated by an OpenID Provider (OP) 237 using an HTTP redirect. 238 5. The Authorization Server authenticates the RDAP Client. 240 6. The Authorization Server obtains RDAP Client consent/ 241 authorization. 242 7. The Authorization Server sends the RDAP Client back to the RDAP 243 server with an Authorization Code using an HTTP redirect. 244 8. The RDAP server requests a response using the Authorization Code 245 at the Token Endpoint. 246 9. The RDAP server receives a response that contains an ID Token 247 and Access Token in the response body. 248 10. The RDAP server validates the ID Token and retrieves the RDAP 249 client's Subject Identifier. 251 The RDAP server can then make identification, authorization, and 252 access control decisions based on local policies, the ID Token 253 received from the OP, and the received Claims. Note that OpenID 254 Connect describes different process flows for other types of clients, 255 such as script-based or command line clients. 257 3.1.3. RDAP Authentication and Authorization Steps 259 End-Users MUST possess an identifier (an OpenID) issued by an OP to 260 use OpenID Connect with RDAP. An OP SHOULD include support for the 261 claims described in Section 3.1.4 to provide additional information 262 needed for RDAP End-User authorization. OpenID Connect requires RPs 263 to register with OPs to use OpenID Connect services for an End-User. 264 That process is described by the "OpenID Connect Dynamic Client 265 Registration" protocol [OIDCR]. 267 3.1.3.1. Provider Discovery 269 An RDAP server/RP needs to receive an identifier from an End-User 270 that can be used to discover the End-User's OP. That process is 271 required and is documented in the "OpenID Connect Discovery" protocol 272 [OIDCD]. 274 3.1.3.2. Authentication Request 276 Once the OP is known, an RP MUST form an Authentication Request and 277 send it to the OP as described in Section 3 of the OpenID Connect 278 Core protocol [OIDCC]. The authentication path followed 279 (authorization, implicit, or hybrid) will depend on the 280 Authentication Request response_type set by the RP. The remainder of 281 the processing steps described here assume that the Authorization 282 Code Flow is being used by setting "response_type=code" in the 283 Authentication Request. 285 The benefits of using the Authorization Code Flow for authenticating 286 a human user are described in Section 3.1 of the OpenID Connect Core 287 protocol. The Implicit Flow is more commonly used by clients 288 implemented in a web browser using a scripting language; it is 289 described in Section 3.2 of the OpenID Connect Core protocol. The 290 Hybrid Flow (described in Section 3.3 of the OpenID Connect Core 291 protocol) combines elements of the Authorization and Implicit Flows 292 by returning some tokens from the Authorization Endpoint and others 293 from the Token Endpoint. 295 An Authentication Request can contain several parameters. REQUIRED 296 parameters are specified in Section 3.1.2.1 of the OpenID Connect 297 Core protocol [OIDCC]. Apart from these parameters, it is 298 RECOMMENDED that the RP include the optional "login_hint" parameter 299 in the request, with the value being that of the "id" from the query 300 component of the end user's RDAP request. Passing "login_hint" 301 allows a client to pre-fill login form information, so logging in can 302 be more convenient for users. Other parameters MAY be included. 304 The OP receives the Authentication Request and attempts to validate 305 it as described in Section 3.1.2.2 of the OpenID Connect Core 306 protocol [OIDCC]. If the request is valid, the OP attempts to 307 authenticate the End-User as described in Section 3.1.2.3 of the 308 OpenID Connect Core protocol [OIDCC]. The OP returns an error 309 response if the request is not valid or if any error is encountered. 311 3.1.3.3. End-User Authorization 313 After the End-User is authenticated, the OP MUST obtain authorization 314 information from the End-User before releasing information to the 315 RDAP Server/RP. This process is described in Section 3.1.2.4 of the 316 OpenID Connect Core protocol [OIDCC]. 318 3.1.3.4. Authorization Response and Validation 320 After the End-User is authenticated, the OP will send a response to 321 the RP that describes the result of the authorization process in the 322 form of an Authorization Grant. The RP MUST validate the response. 323 This process is described in Sections 3.1.2.5 - 3.1.2.7 of the OpenID 324 Connect Core protocol [OIDCC]. 326 3.1.3.5. Token Processing 328 The RP sends a Token Request using the Authorization Grant to a Token 329 Endpoint to obtain a Token Response containing an Access Token, ID 330 Token, and an OPTIONAL Refresh Token. The RP MUST validate the Token 331 Response. This process is described in Section 3.1.3 of the OpenID 332 Connect Core protocol [OIDCC]. 334 3.1.3.6. Delivery of User Information 336 The set of Claims can be retrieved by sending a request to a UserInfo 337 Endpoint using the Access Token. The Claims MAY be returned in the 338 ID Token. The process of retrieving Claims from a UserInfo Endpoint 339 is described in Section 5.3 of the OpenID Connect Core protocol 340 [OIDCC]. 342 OpenID Connect specified a set of standard Claims in Section 5.1. 343 Additional Claims for RDAP are described in Section 3.1.4. 345 3.1.4. Specialized Claims for RDAP 347 OpenID Connect claims are pieces of information used to make 348 assertions about an entity. Section 5 of the OpenID Connect Core 349 protocol [OIDCC] describes a set of standard claims that can be used 350 to identify a person. Section 5.1.2 notes that additional claims MAY 351 be used, and it describes a method to create them. 353 3.1.4.1. Stated Purpose 355 There are communities of RDAP users and operators who wish to make 356 and validate claims about a user's "need to know" when it comes to 357 requesting access to a resource. For example, a law enforcement 358 agent or a trademark attorney may wish to be able to assert that they 359 have a legal right to access a protected resource, and a server 360 operator will need to be able to receive and validate that claim. 361 These needs can be met by defining and using an additional "purpose" 362 claim. 364 The "purpose" claim identifies the purpose for which access to a 365 protected resource is being requested. Use of the "purpose" claim is 366 OPTIONAL; processing of this claim is subject to server acceptance of 367 the purpose and successful authentication of the End-User. 368 Unrecognized purpose values MUST be ignored and the associated query 369 MUST be processed as if the unrecognized purpose value was not 370 present at all. 372 The "purpose" value is a case-sensitive string containing a 373 StringOrURI value as specified in Section 2 of the JSON Web Token 374 (JWT) specification ([RFC7519]). An example: 376 {"purpose" : "domainNameControl"} 378 Purpose values are themselves registered with IANA. Each entry in 379 the registry contains the following fields: 381 Value: the purpose string value being registered. Value strings can 382 contain upper case characters from "A" to "Z", lower case ASCII 383 characters from "a" to "z", and the underscore ("_") character. 384 Value strings contain at least one character and no more than 64 385 characters. 387 Description: a one- or two-sentence description of the meaning of the 388 purpose value, how it might be used, and/or how it should be 389 interpreted by clients and servers. 391 This registry is operated under the "Specification Required" policy 392 defined in RFC 5226 ([RFC5226]). The set of initial values used to 393 populate the registry as described in Section 6.3 are taken from the 394 final report (https://www.icann.org/en/system/files/files/final- 395 report-06jun14-en.pdf) produced by the Expert Working Group on gTLD 396 Directory Services chartered by the Internet Corporation for Assigned 397 Names and Numbers (ICANN). 399 3.1.4.2. Do Not Track 401 There are also communities of RDAP users and operators who wish to 402 make and validate claims about a user's wish to not have their 403 queries logged, tracked, or recorded. For example, a law enforcement 404 agent may wish to be able to assert that their queries are part of a 405 criminal investigation and should not be tracked due to a risk of 406 query exposure compromising the investigation, and a server operator 407 will need to be able to receive and validate that claim. These needs 408 can be met by defining and using an additional "do not track" claim. 410 The "do not track" ("dnt") claim can be used to identify an End-User 411 that is authorized to perform queries without the End-User's 412 association with those queries being logged, tracked, or recorded by 413 the server. Client use of the "dnt" claim is OPTIONAL. Server 414 operators MUST NOT log, track, or record any association of the query 415 and the End-User's identity if the End-User is successfully 416 identified and authorized, the "dnt" claim is present, the value of 417 the claim is "true", and accepting the claim complies with local 418 regulations regarding logging and tracking. 420 The "dnt" value is represented as a JSON boolean literal. An 421 example: 423 {"dnt" : true} 424 No special query tracking processing is required if this claim is not 425 present or if the value of the claim is "false". Use of this claim 426 MUST be limited to End-Users who are granted "do not track" 427 privileges in accordance with service policies and regulations. 428 Specification of these policies and regulations is beyond the scope 429 of this document. 431 4. Protocol Parameters 433 This specification adds the following protocol parameters to RDAP: 435 1. A query parameter to request authentication for a specific end- 436 user identity. 437 2. A path segment to request an tokens for a specific end-user 438 identity. 439 3. A query parameter to deliver an Access Token for use with an RDAP 440 query. 442 4.1. Client Authentication Request and Response 444 Client authentication is requested using one of three methods: 446 1. by adding a query component to an RDAP request URI using the 447 syntax described in Section 3.4 of RFC 3986 [RFC3986], 448 2. by including an HTTP authorization header for the Basic 449 authentication scheme as described in RFC 7617 [RFC7617], or 450 3. by including an HTTP authorization header with a Bearer token as 451 described in RFC 6750 [RFC6750]. 453 Clients can use any of these methods. Servers MUST support all 454 methods. 456 The query used to request client authentication is represented as an 457 OPTIONAL "key=value" pair using a key value of "id" and a value 458 component that contains the client identifier issued by an OP. An 459 example for client identifier "user.idp.example": 461 https://example.com/rdap/domain/example.com?id=user.idp.example 463 The authorization header for the Basic authentication scheme contains 464 a Base64-encoded representation of the client identifier issued by an 465 OP. No password is provided. An example for client identifier 466 "user.idp.example": 468 https://example.com/rdap/domain/example.com 470 Authorization: Basic dXNlci5pZHAuZXhhbXBsZQ== 471 The HTTP Bearer authorization header contains a Base64url-encoded 472 representation of the Access Token issued by an OP. An example that 473 has been abbreviated for clarity: 475 https://example.com/rdap/domain/example.com 477 Authorization: Bearer eyJ0...NiJ9 479 The response to an authenticated query MUST use the response 480 structures specified in RFC 9083 [RFC9083]. Information that the 481 end-user is not authorized to receive MUST be omitted from the 482 response. 484 4.2. Token Request and Response 486 Clients MAY send a request to an RDAP server to authenticate an end- 487 user and return tokens (an ID Token, an Access Token, and a Refresh 488 Token) from an OP that can be then be passed to the RP/RDAP server to 489 authenticate and process subsequent queries. An Access Token can be 490 refreshed as described in Section 12 of the OpenID Connect Core 491 protocol [OIDCC] and Section 6 of RFC 6749 [RFC6749]. Clients can 492 take advantage of this functionality if it is supported by the OP and 493 accepted by the RDAP server. Identity provider authentication is 494 requested using a "tokens" path segment and an OPTIONAL query 495 parameter (the query parameter isn't needed if the RDAP server is 496 using a local OP) with a key value of "id" and a value component that 497 contains the client identifier issued by an OP. An example for use 498 with a remote OP: 500 https://example.com/rdap/tokens?id=user.idp.example 502 An example for use with a local OP: 504 https://example.com/rdap/tokens 505 In addition to any core RDAP response elements, the response to this 506 query MUST contain five name-value pairs, in any order, representing 507 the returned ID Token, Access Token, and Refresh Token. The ID Token 508 is represented using a key value of "id_token". The Access Token is 509 represented using a key value of "access_token". The Access Token 510 type is represented using a key value of "token_type" and a value of 511 "bearer" as described in Sections 4.2.2 and 7.1 of RFC 6749 512 [RFC6749]. The lifetime of the Access Token is represented using a 513 key value of "expires_in" and a numerical value that describes the 514 lifetime in seconds of the Access Token as described in Section 4.2.2 515 of RFC 6749 [RFC6749]. The Refresh Token is represented using a key 516 value of "refresh_token". The token values returned in the RDAP 517 server response MUST be Base64url-encoded as described in RFCs 7515 518 [RFC7515] and 7519 [RFC7519]. 520 An example (the encoded tokens have been abbreviated for clarity): 522 { 523 "access_token" : "eyJ0...NiJ9", 524 "id_token" : "eyJ0...EjXk", 525 "token_type" : "bearer", 526 "expires_in" : "3600", 527 "refresh_token" : "eyJ0...c8da" 528 } 530 Figure 1 532 An RDAP server that processes this type of query MUST determine if 533 the identifier is associated with an OP that is recognized and 534 supported by the server. Servers MUST reject queries that include an 535 identifier associated with an unsupported OP with an HTTP 501 (Not 536 Implemented) response. An RDAP server that receives a query 537 containing an identifier associated with a recognized OP MUST perform 538 the steps required to authenticate the user with the OP using a 539 browser or browser-like client and return encoded tokens to the 540 client. Note that tokens are typically valid for a limited period of 541 time and new tokens will be required when an existing token's 542 validity period has expired. 544 The Access Token can then be passed to the server for use with an 545 RDAP query by including the encoded token in an HTTP Bearer 546 authorization header [RFC6750]. An example (the encoded token has 547 been abbreviated for clarity): 549 https://example.com/rdap/domain/example.com?id=user.idp.example 551 Authorization: Bearer eyJ0...NiJ9 552 The RDAP server can retrieve user information (such as claims 553 associated with the user) from the OP by querying the UserInfo 554 endpoint using the given Access Token. The user information can then 555 be used to determine if the uiser is authorized to receive the 556 requested information. The response to an authenticated query MUST 557 use the response structures specified in RFC 9083 [RFC9083]. 558 Information that the end-user is not authorized to receive MUST be 559 omitted from the response. 561 4.3. Token Refresh and Revocation 563 The refresh token returned in the token response can be used to 564 refresh an Access Token. An Access Token is refreshed using a 565 "tokens" path segment and a query parameter. The query parameter 566 includes a key value of "refresh_token" and a Base64url-encoded value 567 that represents the refresh token. An example: 569 https://example.com/rdap/tokens?refresh_token=eyJ0...c8da 571 In addition to any core RDAP response elements, the response to this 572 query MUST contain four name-value pairs, in any order, representing 573 a returned Refresh Token and Access Token. The Refresh Token is 574 represented using a key value of "refresh_token". The Access Token 575 is represented using a key value of "access_token". The Access Token 576 type is represented using a key value of "token_type" and a value of 577 "bearer" as described in Sections 4.2.2 and 7.1 of RFC 6749 578 [RFC6749]. The lifetime of the Access Token is represented using a 579 key value of "expires_in" and a numerical value that describes the 580 lifetime in seconds of the Access Token as described in Section 4.2.2 581 of RFC 6749 [RFC6749]. The token values returned in the RDAP server 582 response MUST be Base64url-encoded as described in RFCs 7515 583 [RFC7515] and 7519 [RFC7519]. 585 Example Access Token refresh response (the encoded tokens have been 586 abbreviated for clarity): 588 { 589 "access_token" : "0dac...13b0", 590 "refresh_token" : "f735...d30c", 591 "token_type" : "bearer", 592 "expires_in" : "3600" 593 } 595 Figure 2 597 Access and refresh tokens can be revoked as described in RFC 7009 598 [RFC7009] by sending a request to an RDAP server that contains a 599 "tokens/revoke" path segment and a query parameter. The query 600 parameter includes a key value of "token" and a Base64url-encoded 601 value that represents the current refresh token. An example: 603 https://example.com/rdap/tokens/revoke?token=f735...d30c 605 Note that this command will revoke both access and refresh tokens at 606 the same time. In addition to any core RDAP response elements, the 607 response to this query MUST contain a description of the result of 608 processing the revocation request within the RDAP "notices" data 609 structure. 611 Example token revocation success: 613 "notices" : 614 [ 615 { 616 "title" : "Token Revocation Result", 617 "description" : "Token revocation succeeded.", 618 } 619 ], 620 "lang" : "en-US" 622 Figure 3 624 Example token revocation failure: 626 "notices" : 627 [ 628 { 629 "title" : "Token Revocation Result", 630 "description" : "Token revocation failed.", 631 } 632 ], 633 "errorCode" : 400, 634 "lang" : "en-US" 636 Figure 4 638 4.4. Token Exchange 640 ID tokens include an audience parameter that contains the OAuth 2.0 641 client_id of the RP as an audience value. In some operational 642 scenarios (such as a client that is providing a proxy service), an RP 643 can receive tokens with an audience value that does not include the 644 RP's client_id. These tokens might not be trusted by the RP, and the 645 RP might refuse to accept the tokens. This situation can be remedied 646 by having the RP exchange these tokens with the OP for a set of 647 trusted tokens that reset the audience parameter. This token 648 exchange protocol is described in RFC 8693 [RFC8693]. 650 4.5. Parameter Processing 652 Unrecognized query parameters MUST be ignored. An RDAP server that 653 processes an authenticated query MUST determine if the end-user 654 identification information is associated with an OP that is 655 recognized and supported by the server. Servers MUST reject queries 656 that include identification information that is not associated with a 657 supported OP by returning an HTTP 501 (Not Implemented) response. An 658 RDAP server that receives a query containing identification 659 information associated with a recognized OP MUST perform the steps 660 required to authenticate the user with the OP, process the query, and 661 return an RDAP response that is appropriate for the end user's level 662 of authorization and access. 664 An RDAP server that receives a query containing tokens associated 665 with a recognized OP and authenticated end user MUST process the 666 query and return an RDAP response that is appropriate for the end 667 user's level of authorization and access. Errors based on processing 668 either the ID Token or the Access Token MUST be signaled with an 669 appropriate HTTP status code as described in Section 3.1 of RFC 6750 670 [RFC6750]. 672 On receiving a query containing tokens, the RDAP server MUST validate 673 the identity information received from a UserInfo endpoint. It can 674 do this independently of the OP, because the response is a JSON 675 object that contains all the data necessary for validation. The 676 Access Token can be validated by sending a request using it to the 677 UserInfo Endpoint and confirming that a successful response is 678 received. This is different from the OpenID Connect Authorization 679 Code and Implicit flows, where the Access Token can be validated 680 against the at_hash claim from the ID Token. With a query containing 681 tokens, the Access Token might not validate against the at_hash claim 682 because the Access Token may have been refreshed since the ID Token 683 was issued. 685 An RDAP server that processes requests without needing the UserInfo 686 claims does not need to retrieve the claims merely in order to 687 validate the Access Token. Similarly, an RDAP server that has cached 688 the UserInfo claims for an end user, in accordance with the HTTP 689 headers of a previous UserInfo Endpoint response, does not need to 690 retrieve those claims again in order to re-validate the Access Token. 692 4.6. RDAP Conformance 694 RDAP responses that contain values described in this document MUST 695 indicate conformance with this specification by including an 696 rdapConformance ([RFC9083]) value of "rdap_openidc_remote_level_0" or 697 "rdap_openidc_local_level_0". Both values MAY be present if a server 698 supports both local and remote OpenID Authorization Servers. The 699 information needed to register this value in the RDAP Extensions 700 Registry is described in Section 6.1. 702 Example rdapConformance structure with extension specified: 704 "rdapConformance" : 705 [ 706 "rdap_level_0", 707 "rdap_openidc_remote_level_0" 708 ] 710 Figure 5 712 5. Clients with Limited User Interfaces 714 The flow described in Section 3.1.3 requires an end-user to interact 715 with a server using a user interface that can process HTTP. This 716 will not work well in situations where the client is automated or an 717 end-user is using a command line user interface such as curl 718 (http://curl.haxx.se/) or wget (https://www.gnu.org/software/wget/). 719 There are multiple ways to address this limitation using a web 720 browser on a second device. Two are described here. 722 5.1. OAuth 2.0 Device Authorization Grant 724 The "OAuth 2.0 Device Authorization Grant" [RFC8628] provides one 725 method to request user authorization from devices that have an 726 Internet connection, but lack a suitable browser for a more 727 traditional OAuth flow. This method requires a client to use a 728 second device (such as a smart telephone) that has access to a web 729 browser for entry of a code sequence that is presented on the 730 constrained device. 732 5.2. Manual Token Management 734 A second method of requesting user authorization from a constrained 735 device is possible by producing and managing tokens manually as 736 follows: 738 1. Authenticate with the OP as described in Section 4.2 using a 739 browser or browser-like client. 740 2. Store the returned ID Token, Access Token, and Refresh Token 741 locally. 742 3. Send a request to the content provider/RP along with the client 743 ID and Access Token received from the OP. 745 The Access Token MUST be passed to the RP in an HTTP "Authorization" 746 header [RFC7235]. The Access Token MUST be specified using the 747 "Bearer" authentication scheme [RFC6750]. 749 Here are two examples using the curl and wget utilities. Start by 750 authenticating with the OP: 752 https://example.com/rdap/tokens?id=user.idp.example 754 Save the token information and pass it to the RP along with the URI 755 representing the RDAP query. Using curl (encoded tokens have been 756 abbreviated for clarity: 758 curl -H "Authorization: Bearer eyJ0...NiJ9"\-k 759 https://example.com/rdap/domain/example.com\?id=user.idp.example 761 Using wget: 763 wget --header="Authorization: Bearer 764 eyJ0...NiJ9"\https://example.com/rdap/domain/ 765 example.com\id=user.idp.example 767 Refresh tokens can be useful to automated or command line clients who 768 wish to continue a session without explicitly re-authenticating an 769 end user. See Section 4.3 for more information. 771 6. IANA Considerations 773 6.1. RDAP Extensions Registry 775 IANA is requested to register the following values in the RDAP 776 Extensions Registry: 778 * Extension identifier: rdap_openidc_remote_level_0 779 * Registry operator: Any 780 * Published specification: This document. 781 * Contact: IESG 782 * Intended usage: This extension describes a federated 783 authentication method for RDAP using OAuth 2.0, OpenID Connect, 784 and a remote Authorization Server. 786 * Extension identifier: rdap_openidc_local_level_0 787 * Registry operator: Any 788 * Published specification: This document. 789 * Contact: IESG 790 * Intended usage: This extension describes a federated 791 authentication method for RDAP using OAuth 2.0, OpenID Connect, 792 and a local Authorization Server. 794 6.2. JSON Web Token Claims Registry 796 IANA is requested to register the following values in the JSON Web 797 Token Claims Registry: 799 * Claim Name: "purpose" 800 * Claim Description: This claim describes the stated purpose for 801 submitting a request to access a protected RDAP resource. 802 * Change Controller: IESG 803 * Specification Document(s): Section 3.1.4.1 of this document. 805 * Claim Name: "dnt" 806 * Claim Description: This claim contains a JSON boolean literal that 807 describes an End-User's "do not track" preference for identity 808 tracking, logging, or recording when accessing a protected RDAP 809 resource. 810 * Change Controller: IESG 811 * Specification Document(s): Section 3.1.4.2 of this document. 813 6.3. RDAP Query Purpose Registry 815 IANA is requested to create a new protocol registry to manage RDAP 816 query purpose values. This registry should appear under its own 817 heading on IANA's protocol listings, using the same title as the name 818 of the registry. The information to be registered and the procedures 819 to be followed in populating the registry are described in 820 Section 3.1.4.1. 822 Name of registry: Registration Data Access Protocol (RDAP) Query 823 Purpose Values 825 Section at http://www.iana.org/protocols: 827 Registry Title: Registration Data Access Protocol (RDAP) Query 828 Purpose Values 830 Registry Name: Registration Data Access Protocol (RDAP) Query Purpose 831 Values 833 Registration Procedure: Specification Required 835 Reference: This draft 837 Required information: See Section 3.1.4.1. 839 Review process: "Specification Required" as described in RFC 5226 840 [RFC5226]. 842 Size, format, and syntax of registry entries: See Section 3.1.4.1. 844 Initial assignments and reservations: 846 -----BEGIN FORM----- Value: domainNameControl Description: Tasks 847 within the scope of this purpose include creating and managing and 848 monitoring a registrant's own domain name, including creating the 849 domain name, updating information about the domain name, transferring 850 the domain name, renewing the domain name, deleting the domain name, 851 maintaining a domain name portfolio, and detecting fraudulent use of 852 the Registrant's own contact information. -----END FORM----- 854 -----BEGIN FORM----- Value: personalDataProtection Description: Tasks 855 within the scope of this purpose include identifying the accredited 856 privacy/proxy provider associated with a domain name and reporting 857 abuse, requesting reveal, or otherwise contacting the provider. 858 -----END FORM----- 860 -----BEGIN FORM----- Value: technicalIssueResolution Description: 861 Tasks within the scope of this purpose include (but are not limited 862 to) working to resolve technical issues, including email delivery 863 issues, DNS resolution failures, and web site functional issues. 864 -----END FORM----- 866 -----BEGIN FORM----- Value: domainNameCertification Description: 867 Tasks within the scope of this purpose include a Certification 868 Authority (CA) issuing an X.509 certificate to a subject identified 869 by a domain name. -----END FORM----- 870 -----BEGIN FORM----- Value: individualInternetUse Description: Tasks 871 within the scope of this purpose include identifying the organization 872 using a domain name to instill consumer trust, or contacting that 873 organization to raise a customer complaint to them or file a 874 complaint about them. -----END FORM----- 876 -----BEGIN FORM----- Value: businessDomainNamePurchaseOrSale 877 Description: Tasks within the scope of this purpose include making 878 purchase queries about a domain name, acquiring a domain name from a 879 registrant, and enabling due diligence research. -----END FORM----- 881 -----BEGIN FORM----- Value: academicPublicInterestDNSRResearch 882 Description: Tasks within the scope of this purpose include academic 883 public interest research studies about domain names published in the 884 registration data service, including public information about the 885 registrant and designated contacts, the domain name's history and 886 status, and domain names registered by a given registrant (reverse 887 query). -----END FORM----- 889 -----BEGIN FORM----- Value: legalActions Description: Tasks within 890 the scope of this purpose include investigating possible fraudulent 891 use of a registrant's name or address by other domain names, 892 investigating possible trademark infringement, contacting a 893 registrant/licensee's legal representative prior to taking legal 894 action and then taking a legal action if the concern is not 895 satisfactorily addressed. -----END FORM----- 897 -----BEGIN FORM----- Value: regulatoryAndContractEnforcement 898 Description: Tasks within the scope of this purpose include tax 899 authority investigation of businesses with online presence, Uniform 900 Dispute Resolution Policy (UDRP) investigation, contractual 901 compliance investigation, and registration data escrow audits. 902 -----END FORM----- 904 -----BEGIN FORM----- Value: 905 criminalInvestigationAndDNSAbuseMitigation Description: Tasks within 906 the scope of this purpose include reporting abuse to someone who can 907 investigate and address that abuse, or contacting entities associated 908 with a domain name during an offline criminal investigation. 909 -----END FORM----- 911 -----BEGIN FORM----- Value: dnsTransparency Description: Tasks within 912 the scope of this purpose involve querying the registration data made 913 public by registrants to satisfy a wide variety of use cases around 914 informing the general public. -----END FORM----- 916 7. Implementation Status 918 NOTE: Please remove this section and the reference to RFC 7942 prior 919 to publication as an RFC. 921 This section records the status of known implementations of the 922 protocol defined by this specification at the time of posting of this 923 Internet-Draft, and is based on a proposal described in RFC 7942 924 [RFC7942]. The description of implementations in this section is 925 intended to assist the IETF in its decision processes in progressing 926 drafts to RFCs. Please note that the listing of any individual 927 implementation here does not imply endorsement by the IETF. 928 Furthermore, no effort has been spent to verify the information 929 presented here that was supplied by IETF contributors. This is not 930 intended as, and must not be construed to be, a catalog of available 931 implementations or their features. Readers are advised to note that 932 other implementations may exist. 934 According to RFC 7942, "this will allow reviewers and working groups 935 to assign due consideration to documents that have the benefit of 936 running code, which may serve as evidence of valuable experimentation 937 and feedback that have made the implemented protocols more mature. 938 It is up to the individual working groups to use this information as 939 they see fit". 941 Version -09 of this specification introduced changes that are 942 incompatible with earlier implementations. Implementations that are 943 consistent with this specification will be added as they are 944 identified. 946 8. Security Considerations 948 Security considerations for RDAP can be found in RFC 7481 [RFC7481]. 949 Security considerations for OpenID Connect Core [OIDCC] and OAuth 2.0 950 [RFC6749] can be found in their reference specifications. OpenID 951 Connect defines optional mechanisms for robust signing and encryption 952 that can be used to provide data integrity and data confidentiality 953 services as needed. Security services for ID Tokens and Access 954 Tokens (with references to the JWT specification) are described in 955 the OpenID Connect Core protocol. 957 8.1. Authentication and Access Control 959 Having completed the client identification, authorization, and 960 validation process, an RDAP server can make access control decisions 961 based on a comparison of client-provided information and local 962 policy. For example, a client who provides an email address (and 963 nothing more) might be entitled to receive a subset of the 964 information that would be available to a client who provides an email 965 address, a full name, and a stated purpose. Development of these 966 access control policies is beyond the scope of this document. 968 9. Acknowledgements 970 The author would like to acknowledge the following individuals for 971 their contributions to the development of this document: Tom 972 Harrison, Russ Housley, Rhys Smith, Jaromir Talir, and Alessandro 973 Vesely. In addition, the Verisign Registry Services Lab development 974 team of Joseph Harvey, Andrew Kaizer, Sai Mogali, Anurag Saxena, 975 Swapneel Sheth, Nitin Singh, and Zhao Zhao provided critical "proof 976 of concept" implementation experience that helped demonstrate the 977 validity of the concepts described in this document. 979 Mario Loffredo provided significant feedback based on implementation 980 experience that led to welcome improvements in several sections of 981 this document. His contributions are greatly appreciated. 983 10. References 985 10.1. Normative References 987 [OIDC] OpenID Foundation, "OpenID Connect", 988 . 990 [OIDCC] OpenID Foundation, "OpenID Connect Core incorporating 991 errata set 1", November 2014, 992 . 994 [OIDCD] OpenID Foundation, "OpenID Connect Discovery 1.0 995 incorporating errata set 1", November 2014, 996 . 999 [OIDCR] OpenID Foundation, "OpenID Connect Dynamic Client 1000 Registration 1.0 incorporating errata set 1", November 1001 2014, . 1004 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1005 Requirement Levels", BCP 14, RFC 2119, 1006 DOI 10.17487/RFC2119, March 1997, 1007 . 1009 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1010 Resource Identifier (URI): Generic Syntax", STD 66, 1011 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1012 . 1014 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1015 IANA Considerations Section in RFCs", RFC 5226, 1016 DOI 10.17487/RFC5226, May 2008, 1017 . 1019 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1020 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1021 . 1023 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1024 Framework: Bearer Token Usage", RFC 6750, 1025 DOI 10.17487/RFC6750, October 2012, 1026 . 1028 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 1029 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 1030 August 2013, . 1032 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1033 Protocol (HTTP/1.1): Message Syntax and Routing", 1034 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1035 . 1037 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1038 Protocol (HTTP/1.1): Authentication", RFC 7235, 1039 DOI 10.17487/RFC7235, June 2014, 1040 . 1042 [RFC7480] Newton, A., Ellacott, B., and N. Kong, "HTTP Usage in the 1043 Registration Data Access Protocol (RDAP)", STD 95, 1044 RFC 7480, DOI 10.17487/RFC7480, March 2015, 1045 . 1047 [RFC7481] Hollenbeck, S. and N. Kong, "Security Services for the 1048 Registration Data Access Protocol (RDAP)", STD 95, 1049 RFC 7481, DOI 10.17487/RFC7481, March 2015, 1050 . 1052 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1053 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 1054 2015, . 1056 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1057 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1058 . 1060 [RFC7617] Reschke, J., "The 'Basic' HTTP Authentication Scheme", 1061 RFC 7617, DOI 10.17487/RFC7617, September 2015, 1062 . 1064 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1065 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1066 May 2017, . 1068 [RFC8628] Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, 1069 "OAuth 2.0 Device Authorization Grant", RFC 8628, 1070 DOI 10.17487/RFC8628, August 2019, 1071 . 1073 [RFC8693] Jones, M., Nadalin, A., Campbell, B., Ed., Bradley, J., 1074 and C. Mortimore, "OAuth 2.0 Token Exchange", RFC 8693, 1075 DOI 10.17487/RFC8693, January 2020, 1076 . 1078 [RFC9082] Hollenbeck, S. and A. Newton, "Registration Data Access 1079 Protocol (RDAP) Query Format", STD 95, RFC 9082, 1080 DOI 10.17487/RFC9082, June 2021, 1081 . 1083 [RFC9083] Hollenbeck, S. and A. Newton, "JSON Responses for the 1084 Registration Data Access Protocol (RDAP)", STD 95, 1085 RFC 9083, DOI 10.17487/RFC9083, June 2021, 1086 . 1088 10.2. Informative References 1090 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 1091 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 1092 . 1094 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 1095 Code: The Implementation Status Section", BCP 205, 1096 RFC 7942, DOI 10.17487/RFC7942, July 2016, 1097 . 1099 Appendix A. Change Log 1101 00: Initial working group version ported from draft-hollenbeck- 1102 regext-rdap-openid-10. 1103 01: Modified ID Token delivery approach to note proper use of an 1104 HTTP bearer authorization header. 1105 02: Modified token delivery approach (Access Token is the bearer 1106 token) to note proper use of an HTTP bearer authorization header, 1107 fixing the change made in -01. 1108 03: Updated OAuth 2.0 Device Authorization Grant description and 1109 reference due to publication of RFC 8628. 1110 04: Updated OAuth 2.0 token exchange description and reference due 1111 to publication of RFC 8693. Corrected the RDAP conformance 1112 identifier to be registered with IANA. 1113 05: Keepalive refresh. 1114 06: Keepalive refresh. 1115 07: Added "login_hint" description to Section 3.1.3.2. Added some 1116 text to Section 3.1.4.2 to note that "do not track" requires 1117 compliance with local regulations. 1118 08: Rework of token management processing in Sections 4 and 5. 1119 09: Updated RDAP specification references. Added text to describe 1120 both local and remote Authorization Server processing. Removed 1121 text that described passing of ID Tokens as query parameters. 1123 Author's Address 1125 Scott Hollenbeck 1126 Verisign Labs 1127 12061 Bluemont Way 1128 Reston, VA 20190 1129 United States of America 1131 Email: shollenbeck@verisign.com 1132 URI: http://www.verisignlabs.com/