idnits 2.17.1 draft-ietf-regext-rdap-openid-15.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 : ---------------------------------------------------------------------------- ** There are 2 instances of too long lines in the document, the longest one being 4 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (16 June 2022) is 673 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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. 'OIDCL' -- 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) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 7 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 16 June 2022 5 Expires: 18 December 2022 7 Federated Authentication for the Registration Data Access Protocol 8 (RDAP) using OpenID Connect 9 draft-ietf-regext-rdap-openid-15 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 18 December 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 . . . . . . . . . . . . . . . . . . . . . . . . 4 62 2. Conventions Used in This Document . . . . . . . . . . . . . . 4 63 3. Federated Authentication for RDAP . . . . . . . . . . . . . . 4 64 3.1. RDAP and OpenID Connect . . . . . . . . . . . . . . . . . 5 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 . . . . . . . . . . . . . . . 7 69 3.1.3.2. Authentication Request . . . . . . . . . . . . . 7 70 3.1.3.3. End-User Authorization . . . . . . . . . . . . . 8 71 3.1.3.4. Authorization Response and Validation . . . . . . 8 72 3.1.3.5. Token Processing . . . . . . . . . . . . . . . . 8 73 3.1.3.6. Delivery of User Information . . . . . . . . . . 8 74 3.1.4. Specialized Claims for RDAP . . . . . . . . . . . . . 9 75 3.1.4.1. Stated Purposes . . . . . . . . . . . . . . . . . 9 76 3.1.4.2. Do Not Track . . . . . . . . . . . . . . . . . . 10 77 4. Protocol Parameters . . . . . . . . . . . . . . . . . . . . . 11 78 4.1. Data Structures . . . . . . . . . . . . . . . . . . . . . 11 79 4.1.1. Session . . . . . . . . . . . . . . . . . . . . . . . 11 80 4.1.2. Device Info . . . . . . . . . . . . . . . . . . . . . 12 81 4.1.3. OpenID Connect Configuration . . . . . . . . . . . . 13 82 4.2. Client Login . . . . . . . . . . . . . . . . . . . . . . 14 83 4.2.1. End-User Identifier . . . . . . . . . . . . . . . . . 14 84 4.2.2. OP Issuer Identifier . . . . . . . . . . . . . . . . 15 85 4.2.3. Login Response . . . . . . . . . . . . . . . . . . . 15 86 4.2.4. Clients with Limited User Interfaces . . . . . . . . 17 87 4.2.4.1. UI-constrained Client Login . . . . . . . . . . . 17 88 4.2.4.2. UI-constrained Client Login Polling . . . . . . . 19 89 4.3. RDAP Query Parameters . . . . . . . . . . . . . . . . . . 19 90 4.3.1. RDAP Query Purpose . . . . . . . . . . . . . . . . . 20 91 4.3.2. RDAP Do Not Track . . . . . . . . . . . . . . . . . . 20 92 4.4. Session Status . . . . . . . . . . . . . . . . . . . . . 20 93 4.5. Session Refresh . . . . . . . . . . . . . . . . . . . . . 22 94 4.6. Client Logout . . . . . . . . . . . . . . . . . . . . . . 24 95 4.7. Parameter Processing . . . . . . . . . . . . . . . . . . 25 97 5. Token Exchange . . . . . . . . . . . . . . . . . . . . . . . 25 98 6. RDAP Query Processing . . . . . . . . . . . . . . . . . . . . 26 99 7. RDAP Conformance . . . . . . . . . . . . . . . . . . . . . . 26 100 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 101 8.1. RDAP Extensions Registry . . . . . . . . . . . . . . . . 27 102 8.2. JSON Web Token Claims Registry . . . . . . . . . . . . . 27 103 8.3. RDAP Query Purpose Registry . . . . . . . . . . . . . . . 27 104 9. Implementation Status . . . . . . . . . . . . . . . . . . . . 30 105 9.1. Editor Implementation . . . . . . . . . . . . . . . . . . 31 106 9.2. Verisign Labs . . . . . . . . . . . . . . . . . . . . . . 31 107 9.3. Viagenie . . . . . . . . . . . . . . . . . . . . . . . . 32 108 10. Security Considerations . . . . . . . . . . . . . . . . . . . 33 109 10.1. Authentication and Access Control . . . . . . . . . . . 33 110 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 33 111 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 33 112 12.1. Normative References . . . . . . . . . . . . . . . . . . 33 113 12.2. Informative References . . . . . . . . . . . . . . . . . 35 114 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 36 115 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 37 117 1. Introduction 119 The Registration Data Access Protocol (RDAP) provides "RESTful" web 120 services to retrieve registration metadata from domain name and 121 regional internet registries. RDAP allows a server to make access 122 control decisions based on client identity, and as such it includes 123 support for client identification features provided by the Hypertext 124 Transfer Protocol (HTTP) [RFC7230]. 126 RDAP is specified in multiple documents, including "HTTP Usage in the 127 Registration Data Access Protocol (RDAP)" [RFC7480], "Security 128 Services for the Registration Data Access Protocol (RDAP)" [RFC7481], 129 "Registration Data Access Protocol Query Format" [RFC9082], and "JSON 130 Responses for the Registration Data Access Protocol (RDAP)" 131 [RFC9083]. RFC 7481 describes client identification and 132 authentication services that can be used with RDAP, but it does not 133 specify how any of these services can (or should) be used with RDAP. 135 1.1. Problem Statement 137 The traditional "user name and password" authentication method does 138 not scale well in the RDAP ecosystem. Assuming that all domain name 139 and address registries will eventually provide RDAP service, it is 140 impractical and inefficient for users to secure login credentials 141 from the hundreds of different server operators. Authentication 142 methods based on user names and passwords do not provide information 143 that describes the user in sufficient detail (while protecting the 144 personal privacy of the user) for server operators to make fine- 145 grained access control decisions based on the user's identity. The 146 authentication system used for RDAP needs to address all of these 147 needs. 149 1.2. Proposal 151 A basic level of RDAP service can be provided to users who possess an 152 identifier issued by a recognized provider who is able to 153 authenticate and validate the user. The identifiers issued by social 154 media services, for example, can be used. Users who require higher 155 levels of service (and who are willing to share more information 156 about them self to gain access to that service) can secure 157 identifiers from specialized providers who are or will be able to 158 provide more detailed information about the user. Server operators 159 can then make access control decisions based on the identification 160 information provided by the user. 162 A federated authentication system in which an RDAP server outsources 163 identification and authentication services to a trusted OpenID 164 Provider would make it easier to operate and use RDAP by re-using 165 existing identifiers to provide a basic level of access. It can also 166 provide the ability to collect additional user identification 167 information, and that information can be shared with the consent of 168 the user. This type of system allows an RDAP server to make access 169 control decisions based on the nature of a query and the identity, 170 authentication, and authorization information that is received from 171 the OpenID Provider. This document describes a federated 172 authentication system for RDAP based on OpenID Connect [OIDC] that 173 meets all of these needs. 175 2. Conventions Used in This Document 177 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 178 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 179 "OPTIONAL" in this document are to be interpreted as described in BCP 180 14 [RFC2119] [RFC8174] when, and only when, they appear in all 181 capitals, as shown here. 183 3. Federated Authentication for RDAP 185 RDAP itself does not include native security services. Instead, RDAP 186 relies on features that are available in other protocol layers to 187 provide needed security services including access control, 188 authentication, authorization, availability, data confidentiality, 189 data integrity, and identification. A description of each of these 190 security services can be found in "Internet Security Glossary, 191 Version 2" [RFC4949]. This document focuses on a federated 192 authentication system for RDAP that provides services for 193 authentication, authorization, and identification, allowing a server 194 operator to make access control decisions. Section 3 of RFC 7481 195 [RFC7481] describes general considerations for RDAP access control, 196 authentication, and authorization. 198 The traditional client-server authentication model requires clients 199 to maintain distinct credentials for every RDAP server. This 200 situation can become unwieldy as the number of RDAP servers 201 increases. Federated authentication mechanisms allow clients to use 202 one credential to access multiple RDAP servers and reduce client 203 credential management complexity. 205 3.1. RDAP and OpenID Connect 207 OpenID Connect 1.0 [OIDCC] is a decentralized, single sign-on (SSO) 208 federated authentication system that allows users to access multiple 209 web resources with one identifier instead of having to create 210 multiple server-specific identifiers. Users acquire identifiers from 211 OpenID Providers, or OPs. Relying Parties, or RPs, are applications 212 (such as RDAP) that outsource their user authentication function to 213 an OP. OpenID Connect is built on top of the authorization framework 214 provided by the OAuth 2.0 [RFC6749] protocol. 216 The OAuth authorization framework describes a method for users to 217 access protected web resources without having to hand out their 218 credentials. Instead, clients are issued Access Tokens by 219 authorization servers with the permission of the resource owners. 220 Using OpenID Connect and OAuth, multiple RDAP servers can form a 221 federation and clients can access any server in the federation by 222 providing one credential registered with any OP in that federation. 223 The OAuth authorization framework is designed for use with HTTP and 224 thus can be used with RDAP. 226 3.1.1. Terminology 228 This document uses the terms "client" and "server" defined by RDAP 229 [RFC7480]. An RDAP client performs the role of an OpenID Connect 230 Core [OIDCC] Entity or End-User. An RDAP server performs the role of 231 an OpenID Connect Core Relying Party (RP). Additional terms from 232 Section 1.2 of the OpenID Connect Core specification are incorporated 233 by reference. 235 3.1.2. Overview 237 At a high level, RDAP authentication of a browser-like client using 238 OpenID Connect requires completion of the following steps: 240 1. An RDAP client sends an RDAP "help" query to an RDAP server to 241 determine the type and capabilities of the OpenID Authorization 242 Servers that are used by the RDAP server. This information is 243 returned in the rdapConformance section of the response. A 244 value of "roidc1" indicates support for the extension described 245 in this specification. If one or more remote Authorization 246 Servers are supported, the RDAP client SHOULD evaluate the 247 additional information described in Section 4.1.3 in order to 248 discover the capabilties of the RDAP server and optionally 249 obtain the set of supported OPs. 250 2. An RDAP client (acting as an OpenID End-User) sends an RDAP 251 "login" request to an RDAP server as described in Section 4.2. 252 3. The RDAP server (acting as an OpenID Relying Party (RP)) 253 prepares an Authentication Request containing the desired 254 request parameters. 255 4. The RDAP server sends the RDAP client and Authentication Request 256 to an Authorization Server operated by an OpenID Provider (OP) 257 using an HTTP redirect. 258 5. The Authorization Server authenticates the End-User. 259 6. The Authorization Server obtains End-User consent/authorization. 260 7. The Authorization Server sends the RDAP Client back to the RDAP 261 server with an Authorization Code using an HTTP redirect. 262 8. The RDAP server requests a response using the Authorization Code 263 at the Token Endpoint. 264 9. The RDAP server receives a response that contains an ID Token 265 and Access Token in the response body. 266 10. The RDAP server validates the ID Token and retrieves the claims 267 associated with the End-User's identity. 269 The RDAP server can then make identification, authorization, and 270 access control decisions based on End-User identity information and 271 local policies. Note that OpenID Connect describes different process 272 flows for other types of clients, such as script-based or command 273 line clients. 275 3.1.3. RDAP Authentication and Authorization Steps 277 End-Users MAY present an identifier (an OpenID) issued by an OP to 278 use OpenID Connect with RDAP. If the RDAP server supports a default 279 Authorization Server or End-User identifier discovery is not 280 supported, the End-User identifier MAY be omitted. An OP SHOULD 281 include support for the claims described in Section 3.1.4 to provide 282 additional information needed for RDAP End-User authorization. 283 OpenID Connect requires RPs to register with OPs to use OpenID 284 Connect services for an End-User. The registration process is often 285 completed using out-of-band methods, but it is also possible to use 286 the automated method described by the "OpenID Connect Dynamic Client 287 Registration" protocol [OIDCR]. The parties involved can use any 288 method that is mutually acceptable. 290 3.1.3.1. Provider Discovery 292 An RDAP server/RP needs to be able to map an End-User's identifier to 293 an OP. This can be accomplished using the OPTIONAL "OpenID Connect 294 Discovery" protocol [OIDCD], but that protocol is not widely 295 implemented. Out-of-band methods are also possible and can be more 296 dependable. For example, an RP can support a limited number of OPs 297 and maintain internal associations of those identifiers with the OPs 298 that issued them. 300 Alternatively, if mapping of an End-User's identifier is not 301 possible, or not supported by the RDAP server, the RDAP server SHOULD 302 support explicit specification of a remote OP by the RDAP client in 303 the form of a query parameter as described in Section 4.2.2. An RDAP 304 server MUST provide information about its capabilities and supported 305 OPs in the "help" query response in the "roidc1_openidcConfiguration" 306 data structure described in Section 4.1.3. 308 An RP can also ask an End-User to identify the OP that issued their 309 identifier as part of an RDAP query workflow. In this case, the RP 310 will need to maintain state for the association between the user's 311 identifier and the OP in order to process later queries that rely on 312 passing the access token and user identifier as authorization 313 parameters. An RDAP server MUST support at least one of these 314 methods of OP discovery. 316 3.1.3.2. Authentication Request 318 Once the OP is known, an RP MUST form an Authentication Request and 319 send it to the OP as described in Section 3 of the OpenID Connect 320 Core protocol [OIDCC]. The authentication path followed 321 (authorization, implicit, or hybrid) will depend on the 322 Authentication Request response_type set by the RP. The remainder of 323 the processing steps described here assume that the Authorization 324 Code Flow is being used by setting "response_type=code" in the 325 Authentication Request. 327 The benefits of using the Authorization Code Flow for authenticating 328 a human user are described in Section 3.1 of the OpenID Connect Core 329 protocol. The Implicit Flow is more commonly used by clients 330 implemented in a web browser using a scripting language; it is 331 described in Section 3.2 of the OpenID Connect Core protocol. The 332 Hybrid Flow (described in Section 3.3 of the OpenID Connect Core 333 protocol) combines elements of the Authorization and Implicit Flows 334 by returning some tokens from the Authorization Endpoint and others 335 from the Token Endpoint. 337 An Authentication Request can contain several parameters. REQUIRED 338 parameters are specified in Section 3.1.2.1 of the OpenID Connect 339 Core protocol [OIDCC]. Apart from these parameters, it is 340 RECOMMENDED that the RP include the optional "login_hint" parameter 341 in the request, with the value being that of the "roidc1_id" query 342 parameter of the End-User's RDAP "login" request, if provided. 343 Passing the "login_hint" parameter allows a client to pre-fill login 344 form information, so logging in can be more convenient for users. 345 Other parameters MAY be included. 347 The OP receives the Authentication Request and attempts to validate 348 it as described in Section 3.1.2.2 of the OpenID Connect Core 349 protocol [OIDCC]. If the request is valid, the OP attempts to 350 authenticate the End-User as described in Section 3.1.2.3 of the 351 OpenID Connect Core protocol [OIDCC]. The OP returns an error 352 response if the request is not valid or if any error is encountered. 354 3.1.3.3. End-User Authorization 356 After the End-User is authenticated, the OP MUST obtain authorization 357 information from the End-User before releasing information to the 358 RDAP Server/RP. This process is described in Section 3.1.2.4 of the 359 OpenID Connect Core protocol [OIDCC]. 361 3.1.3.4. Authorization Response and Validation 363 After the End-User is authenticated, the OP will send a response to 364 the RP that describes the result of the authorization process in the 365 form of an Authorization Grant. The RP MUST validate the response. 366 This process is described in Sections 3.1.2.5 - 3.1.2.7 of the OpenID 367 Connect Core protocol [OIDCC]. 369 3.1.3.5. Token Processing 371 The RP sends a Token Request using the Authorization Grant to a Token 372 Endpoint to obtain a Token Response containing an Access Token, ID 373 Token, and an OPTIONAL Refresh Token. The RP MUST validate the Token 374 Response. This process is described in Section 3.1.3 of the OpenID 375 Connect Core protocol [OIDCC]. 377 3.1.3.6. Delivery of User Information 379 The set of claims can be retrieved by sending a request to a UserInfo 380 Endpoint using the Access Token. The claims MAY be returned in the 381 ID Token. The process of retrieving claims from a UserInfo Endpoint 382 is described in Section 5.3 of the OpenID Connect Core protocol 383 [OIDCC]. 385 OpenID Connect specifies a set of standard claims in Section 5.1. 386 Additional claims for RDAP are described in Section 3.1.4. 388 3.1.4. Specialized Claims for RDAP 390 OpenID Connect claims are pieces of information used to make 391 assertions about an entity. Section 5 of the OpenID Connect Core 392 protocol [OIDCC] describes a set of standard claims that can be used 393 to identify a person. Section 5.1.2 notes that additional claims MAY 394 be used, and it describes a method to create them. The set of claims 395 that are specific to RDAP are associated with an OAuth scope request 396 parameter value (see Section 3.3 of RFC 6749 ([RFC6749])) of "rdap". 398 3.1.4.1. Stated Purposes 400 There are communities of RDAP users and operators who wish to make 401 and validate claims about a user's "need to know" when it comes to 402 requesting access to a resource. For example, a law enforcement 403 agent or a trademark attorney may wish to be able to assert that they 404 have a legal right to access a protected resource, and a server 405 operator will need to be able to receive and validate that claim. 406 These needs can be met by defining and using an additional 407 "rdap_allowed_purposes" claim. 409 The "rdap_allowed_purposes" claim identifies the purposes for which 410 access to a protected resource can be requested by an End-User. Use 411 of the "rdap_allowed_purposes" claim is OPTIONAL; processing of this 412 claim is subject to server acceptance of the purposes, the trust 413 level assigned to this claim by the server, and successful 414 authentication of the End-User. Unrecognized purpose values MUST be 415 ignored and the associated query MUST be processed as if the 416 unrecognized purpose value was not present at all. 418 The "rdap_allowed_purposes" claim is represented as an array of case- 419 sensitive StringOrURI values as specified in Section 2 of the JSON 420 Web Token (JWT) specification ([RFC7519]). An example: 422 "rdap_allowed_purposes": ["domainNameControl","dnsTransparency"] 424 Individual purpose values are registered with IANA. Each entry in 425 the registry contains the following fields: 427 Value: the purpose string value being registered. Value strings can 428 contain upper case characters from "A" to "Z", lower case ASCII 429 characters from "a" to "z", and the underscore ("_") character. 430 Value strings contain at least one character and no more than 64 431 characters. 433 Description: a one- or two-sentence description of the meaning of the 434 purpose value, how it might be used, and/or how it should be 435 interpreted by clients and servers. 437 This registry is operated under the "Specification Required" policy 438 defined in RFC 5226 ([RFC5226]). The set of initial values used to 439 populate the registry as described in Section 8.3 are taken from the 440 final report (https://www.icann.org/en/system/files/files/final- 441 report-06jun14-en.pdf) produced by the Expert Working Group on gTLD 442 Directory Services chartered by the Internet Corporation for Assigned 443 Names and Numbers (ICANN). 445 3.1.4.2. Do Not Track 447 There are also communities of RDAP users and operators who wish to 448 make and validate claims about a user's wish to not have their 449 queries logged, tracked, or recorded. For example, a law enforcement 450 agent may wish to be able to assert that their queries are part of a 451 criminal investigation and should not be tracked due to a risk of 452 query exposure compromising the investigation, and a server operator 453 will need to be able to receive and validate that claim. These needs 454 can be met by defining and using an additional "do not track" claim. 456 The "do not track" ("rdap_dnt_allowed") claim can be used to identify 457 an End-User that is authorized to perform queries without the End- 458 User's association with those queries being logged, tracked, or 459 recorded by the server. Client use of the "rdap_dnt_allowed" claim 460 is OPTIONAL. Server operators MUST NOT log, track, or record any 461 association of the query and the End-User's identity if the End-User 462 is successfully identified and authorized, the "rdap_dnt_allowed" 463 claim is present, the value of the claim is "true", and accepting the 464 claim complies with local regulations regarding logging and tracking. 466 The "rdap_dnt_allowed" value is represented as a JSON boolean 467 literal. An example: 469 rdap_dnt_allowed: true 471 No special query tracking processing is required if this claim is not 472 present or if the value of the claim is "false". Use of this claim 473 MUST be limited to End-Users who are granted "do not track" 474 privileges in accordance with service policies and regulations. 475 Specification of these policies and regulations is beyond the scope 476 of this document. 478 4. Protocol Parameters 480 This specification adds the following protocol parameters to RDAP: 482 1. Data structures to return information that describes an 483 established session, the information needed to establish a 484 session for a UI-constrained device, and the RDAP server's OpenID 485 Connect extension configuration. 486 2. A query parameter to request authentication for a specific End- 487 User identity. 488 3. A query parameter to identify the purpose of the query. 489 4. A query parameter to request that the server not log or otherwise 490 record information about the identity associated with a query. 491 5. Path segments to start, stop, refresh, and determine the status 492 of an authenticated session for a specific End-User identity. 494 4.1. Data Structures 496 This specification describes three new data structures that are used 497 to return information to a client: a "roidc1_session" data structure 498 that contains information that describes an established session, a 499 "roidc1_deviceInfo" data structure that contains information that 500 describes an active attempt to establish a session on a UI- 501 constrained device, and a "roidc1_openidcConfiguration" data 502 structure that describes the OpenID Connect configuration and related 503 extension features supported by the RDAP server. 505 4.1.1. Session 507 The "roidc1_session" data structure is an object that contains two 508 sub-objects: 510 1. A "userClaims" object that contains the set of claims associated 511 with the End-User's identity as used/requested by the RDAP server 512 to make access control decisions. The set of possible values is 513 determined by OP policy. 514 2. A "sessionInfo" object that contains two members: 515 a. "tokenExpiration": an integer value that represents the 516 number of seconds from the current time for which the Access 517 Token remains valid, and 518 b. "tokenRefresh": A boolean value that indicates if the OP 519 supports refresh tokens. As described in RFC 6749 [RFC6749], 520 support for refresh tokens is OPTIONAL. 522 An example of a "roidc1_session" data structure: 524 "roidc1_session": { 525 "userClaims": { 526 "sub": "103892603076825016132", 527 "name": "User Person", 528 "given_name": "User", 529 "family_name": "Person", 530 "picture": "https://lh3.example.com/a-/AOh14=s96-c", 531 "email": "user@example.com", 532 "email_verified": true, 533 "locale": "en", 534 "rdap_allowed_purposes": [ 535 "domainNameControl", 536 "personalDataProtection" 537 ], 538 "rdap_dnt_allowed": false 539 }, 540 "sessionInfo": { 541 "tokenExpiration": 3599, 542 "tokenRefresh": true 543 } 544 } 546 Figure 1 548 4.1.2. Device Info 550 The flow described in Section 3.1.3 requires an End-User to interact 551 with a server using a user interface that can process HTTP. This 552 will not work well in situations where the client is automated or an 553 End-User is using a command line user interface such as curl 554 (http://curl.haxx.se/) or wget (https://www.gnu.org/software/wget/). 555 This limitation can be addressed using a web browser on a second 556 device. The information that needs to be entered using the web 557 browser is contained in the "roidc1_deviceInfo" data structure. 559 The "roidc1_deviceInfo" data structure is an object that contains 560 three members: 562 1. "verification_url": the URL that the End-User needs to visit 563 using the web browser, 564 2. "user_code": the string value that the End-User needs to enter on 565 the form presented in the web browser, and 566 3. "expires_in": an integer value that represents the number of 567 seconds after which the opportunity to visit the URL and enter 568 the user_code will expire. 570 An example of a "roidc1_deviceInfo" data structure: 572 "roidc1_deviceInfo": { 573 "verification_url": "https://www.example.com/device", 574 "user_code": "NJJQ-GJFC", 575 "expires_in": "1800" 576 } 578 Figure 2 580 4.1.3. OpenID Connect Configuration 582 The "roidc1_openidcConfiguration" data structure is an object with 583 the following members: 585 1. "dntSupported": (MANDATORY) a boolean value that describes RDAP 586 server support for the "roidc1_dnt" query parameter (see 587 Section 4.3.2). 588 2. "endUserIdentifierDiscoverySupported": (OPTIONAL) a boolean value 589 that describes RDAP server support for discovery of End-User 590 identifiers. The default value is "true". 591 3. "issuerIdentifierSupported": (OPTIONAL) a boolean value that 592 describes RDAP server support for explicit client specification 593 of an Issuer Identifier. The default value is "true". 594 4. "implicitTokenRefreshSupported": (OPTIONAL) a boolean value that 595 describes RDAP server support for implicit token refresh. The 596 default value is "false". 597 5. "openidcProviders": (OPTIONAL) a list of objects with the 598 following members that describes the set of OPs that are 599 supported by the RDAP server. This data is RECOMMENDED if the 600 value of issuerIdentifierSupported is "true": 601 a. "iss": (MANDATORY) a string value equal to Issuer Identifier 602 of the OP as per OpenID Connect Core specification [OIDCC] 603 b. "name": (MANDATORY) a string value representing the human- 604 friendly name of the OP. 605 c. "default": (OPTIONAL) a boolean value that describes RDAP 606 server support for an OPTIONAL default OP that will be used 607 when a client omits the "roidc1_id" and "roidc1_iss" query 608 parameters from a "roidc1_session/login" request. Only one 609 member of this set can be identified as the default OP by 610 setting a value of "true". The default value is "false". 612 An example of a "roidc1_openidcConfiguration" data structure: 614 "roidc1_openidcConfiguration": { 615 "dntSupported": false, 616 "endUserIdentifierDiscoverySupported": true, 617 "issuerIdentifierSupported": true, 618 "openidcProviders": 619 [ 620 { 621 "iss": "https://idp.example.com", 622 "name": "Example IDP" 623 }, 624 { 625 "iss": "https://accounts.example.net", 626 "name": "Login with EXAMPLE" 627 }, 628 { 629 "iss": "https://auth.nic.example/auth/realms/rdap", 630 "name": "Default OP for the Example RDAP server", 631 "default": "true" 632 } 633 ] 634 } 636 Figure 3 638 4.2. Client Login 640 Client authentication is requested by sending a "roidc1_session/ 641 login" request to an RDAP server. If the RDAP server supports only 642 remote Authorization Servers, the "roidc1_session/login" request MUST 643 include at least one of an End-User Identifier or an OP Issuer 644 Identifier. 646 4.2.1. End-User Identifier 648 The End-User identifier is delivered using one of two methods: by 649 adding a query component to an RDAP request URI using the syntax 650 described in Section 3.4 of RFC 3986 [RFC3986], or by including an 651 HTTP authorization header for the Basic authentication scheme as 652 described in RFC 7617 [RFC7617]. Clients can use either of these 653 methods to deliver the End-User identifier to a server that supports 654 remote Authorization Servers and End-User identifier discovery. 655 Servers that support remote Authorization Servers and End-User 656 identifier discovery MUST accept both methods. If the RDAP server 657 supports a default Authorization Server or End-User identifier 658 discovery is not supported, the End-User identifier MAY be omitted. 660 The query used to request client authentication is represented as an 661 OPTIONAL "key=value" pair using a key value of "roidc1_id" and a 662 value component that contains the client identifier issued by an OP. 663 An example for client identifier "user.idp.example": 665 https://example.com/rdap/roidc1_session/ 666 login?roidc1_id=user.idp.example 668 The authorization header for the Basic authentication scheme contains 669 a Base64-encoded representation of the client identifier issued by an 670 OP. No password is provided. An example for client identifier 671 "user.idp.example": 673 https://example.com/rdap/roidc1_session/login 675 Authorization: Basic dXNlci5pZHAuZXhhbXBsZQ== 677 An example for use with a default Authorization Server: 679 https://example.com/rdap/roidc1_session/login 681 4.2.2. OP Issuer Identifier 683 The OP's Issuer Identifier is delivered by adding a query component 684 to an RDAP request URI using the syntax described in Section 3.4 of 685 RFC 3986 [RFC3986]. If the RDAP server supports a default 686 Authorization Server, the Issuer Identifier MAY be omitted. 688 The query used to request client authentication is represented as an 689 OPTIONAL "key=value" pair using a key value of "roidc1_iss" and a 690 value component that contains the Issuer Identifier associated with 691 an OP. An RDAP server MAY accept Issuer Identifiers not specified in 692 the "roidc1_openidcConfiguration" data structure and MAY also decide 693 to accept specific Issuer Identifiers only from specific clients. 695 An example for Issuer Identifier "https://idp.example.com": 697 https://example.com/rdap/roidc1_session/ 698 login?roidc1_iss=https%3A%2F%2Fidp.example.com 700 4.2.3. Login Response 702 The response to the login request MUST use the response structures 703 specified in RFC 9083 [RFC9083]. In addition, the response MUST 704 include an indication of the requested operation's success or failure 705 in the "notices" data structure (including the client identifier), 706 and, if successful, a "roidc1_session" data structure. 708 An example of a successful "roidc1_session/login" response: 710 { 711 "rdapConformance": [ 712 "roidc1" 713 ], 714 "lang": "en-US", 715 "notices": { 716 "title": "Login Result", 717 "description": [ 718 "Login succeeded", 719 "user.idp.example" 720 ], 721 }, 722 "roidc1_session": { 723 "userClaims": { 724 "sub": "103892603076825016132", 725 "name": "User Person", 726 "given_name": "User", 727 "family_name": "Person", 728 "picture": "https://lh3.example.com/a-/AOh14=s96-c", 729 "email": "user@example.com", 730 "email_verified": true, 731 "locale": "en", 732 "rdap_allowed_purposes": [ 733 "domainNameControl", 734 "personalDataProtection" 735 ], 736 "rdap_dnt_allowed": false 737 }, 738 "sessionInfo": { 739 "tokenExpiration": 3599, 740 "tokenRefresh": true 741 } 742 } 743 } 745 Figure 4 747 An example of a failed "roidc1_session/login" response: 749 { 750 "rdapConformance": [ 751 "roidc1" 752 ], 753 "lang": "en-US", 754 "notices": { 755 "title": "Login Result", 756 "description": [ 757 "Login failed", 758 "user.idp.example" 759 ] 760 } 761 } 763 Figure 5 765 4.2.4. Clients with Limited User Interfaces 767 The "OAuth 2.0 Device Authorization Grant" [RFC8628] provides an 768 OPTIONAL method to request user authorization from devices that have 769 an Internet connection, but lack a suitable browser for a more 770 traditional OAuth flow. This method requires an End-User to use a 771 second device (such as a smart telephone) that has access to a web 772 browser for entry of a code sequence that is presented on the UI- 773 constrained device. 775 4.2.4.1. UI-constrained Client Login 777 Client authentication is requested by sending a "roidc1_session/ 778 device" request to an RDAP server. If the RDAP server supports only 779 remote Authorization Servers, the "roidc1_session/device" request 780 MUST include an End-User identifier that's delivered using one of two 781 methods: by adding a query component to an RDAP request URI using the 782 syntax described in Section 3.4 of RFC 3986 [RFC3986], or by 783 including an HTTP authorization header for the Basic authentication 784 scheme as described in RFC 7617 [RFC7617]. If the RDAP server 785 supports a default Authorization Server, the End-User identifier MAY 786 be omitted. Clients can use either of these methods. Servers MUST 787 support both methods. 789 The query used to request client authentication is represented as an 790 OPTIONAL "key=value" pair using a key value of "roidc1_id" and a 791 value component that contains the client identifier issued by an OP. 793 An example using wget for client identifier "user.idp.example": 795 wget -qO- --keep-session-cookies --save-cookies\ 796 https://example.com/rdap/roidc1_session/device?roidc1_id=user.idp.example 797 Figure 6 799 The authorization header for the Basic authentication scheme contains 800 a Base64-encoded representation of the client identifier issued by an 801 OP. No password is provided. 803 An example using curl and an authorization header: 805 curl -H "Authorization: Bearer dXNlci5pZHAuZXhhbXBsZQ=="\ 806 -c cookies.txt https://example.com/rdap/roidc1_session/device 808 Figure 7 810 The response to this request MUST use the response structures 811 specified in RFC 9083 [RFC9083]. In addition, the response MUST 812 include an indication of the requested operation's success or failure 813 in the "notices" data structure (including the client identifier), 814 and, if successful, a "roidc1_deviceInfo" data structure. 816 An example of a "roidc1_session/device" response: 818 { 819 "rdapConformance": [ 820 "roidc1" 821 ], 822 "lang": "en-US", 823 "notices": { 824 "title": "Device Login Result", 825 "description": [ 826 "Login succeeded", 827 "user.idp.example" 828 ] 829 }, 830 "roidc1_deviceInfo": { 831 "verification_url": "https://www.example.com/device", 832 "user_code": "NJJQ-GJFC", 833 "expires_in": 1800 834 } 835 } 837 Figure 8 839 4.2.4.2. UI-constrained Client Login Polling 841 After successful processing of the "roidc1_session/device" request, 842 the client MUST send a "roidc1_session/devicepoll" request to the 843 RDAP server to continue the login process. This request performs the 844 polling function described in RFC 8628 [RFC8628], allowing the RDAP 845 server to wait for the End-User to enter the information returned 846 from the "roidc1_session/device" request using the interface on their 847 second device. After the End-User has completed that process, or if 848 the process fails or times out, the OP will respond to the polling 849 requests with an indication of success or failure. 851 An example using wget: 853 wget -qO- --load-cookies cookies.txt\ 854 https://example.com/rdap/roidc1_session/devicepoll 856 Figure 9 858 An example using curl: 860 curl -b cookies.txt https://example.com/rdap/roidc1_session/devicepoll 862 Figure 10 864 The response to this request MUST use the response structures 865 described in Section 4.2. RDAP query processing can continue 866 normally on the UI-constrained device once the "login" process has 867 been completed. 869 4.3. RDAP Query Parameters 871 This specification describes two OPTIONAL query parameters for use 872 with RDAP queries that request access to information associated with 873 protected resources: 875 1. "roidc1_qp": A query parameter to identify the purpose of the 876 query. 877 2. "roidc1_dnt": A query parameter to request that the server not 878 log or otherwise record information about the identity associated 879 with a query. 881 One or both of these parameters MAY be added to an RDAP request URI 882 using the syntax described in Section 3.4 of RFC 3986 [RFC3986]. 884 4.3.1. RDAP Query Purpose 886 This query is represented as a "key=value" pair using a key value of 887 "roidc1_qp" and a value component that contains a single query 888 purpose string from the set of allowed purposes associated with the 889 End-User's identity (see Section 3.1.4.1). If present, the server 890 SHOULD compare the value of the parameter to the 891 "rdap_allowed_purposes" claim values associated with the End-User's 892 identity and ensure that the requested purpose is present in the set 893 of allowed purposes. The RDAP server MAY choose to ignore both 894 requested purpose and the "rdap_allowed_purposes" claim values if 895 they are inconsistent with local server policy. The server MUST 896 return an HTTP 403 (Forbidden) response if the requested purpose is 897 not an allowed purpose. If this parameter is not present, the server 898 MUST proces the query and make an acces control decision based on any 899 other information known to the server about the End-User and the 900 information they are requesting. For example, a server MAY treat the 901 request as one performed by an unidentified or unauthenticated user 902 and return either an error or an appropriate subset of the available 903 data. An example domain query using the "roidc1_qp" query parameter: 905 https://example.com/rdap/domain/example.com?roidc1_qp=legalActions 907 4.3.2. RDAP Do Not Track 909 This query is represented as a "key=value" pair using a key value of 910 "roidc1_dnt" and a value component that contains a single boolean 911 value. A value of "true" indicates that the End-User is requesting 912 that their query not be tracked or logged in accordance with server 913 policy. A value of "false" indicates that the End-User is accepting 914 that their query can be tracked or logged in accordance with server 915 policy. The server MUST return an HTTP 501 (Not Implemented) 916 response if the server is unable to perform the action requested by 917 this query parameter. An example domain query using the "roidc1_dnt" 918 query parameter: 920 https://example.com/rdap/domain/example.com?roidc1_dnt=true 922 4.4. Session Status 924 Clients MAY send a query to an RDAP server to determine the status of 925 an existing login session using a "roidc1_session/status" path 926 segment. An example "roidc1_session/status" request: 928 https://example.com/rdap/roidc1_session/status 929 The response to this query MUST use the response structures specified 930 in RFC 9083 [RFC9083]. In addition, the response MUST include an 931 indication of the requested operation's success or failure in the 932 "notices" data structure (including the client identifier), and, if 933 successful, a "roidc1_session" data structure. 935 An example of a "roidc1_session/status" response: 937 { 938 "rdapConformance": [ 939 "roidc1" 940 ], 941 "lang": "en-US", 942 "notices": { 943 "title": "Session Status Result", 944 "description": [ 945 "Session status succeeded", 946 "user.idp.example" 947 ] 948 }, 949 "roidc1_session": { 950 "userClaims": { 951 "sub": "103892603076825016132", 952 "name": "User Person", 953 "given_name": "User", 954 "family_name": "Person", 955 "picture": "https://lh3.example.com/a-/AOh14=s96-c", 956 "email": "user@example.com", 957 "email_verified": true, 958 "locale": "en", 959 "rdap_allowed_purposes": [ 960 "domainNameControl", 961 "personalDataProtection" 962 ], 963 "rdap_dnt_allowed": false 964 }, 965 "sessionInfo": { 966 "tokenExpiration": 3490, 967 "tokenRefresh": true 968 } 969 } 970 } 972 Figure 11 974 4.5. Session Refresh 976 Clients MAY send a request to an RDAP server to refresh, or extend, 977 an existing login session using a "roidc1_session/refresh" path 978 segment. The RDAP server MAY attempt to refresh the access token 979 associated with the current session as part of extending the session 980 for a period of time determined by the RDAP server. As described in 981 RFC 6749 [RFC6749], OP support for refresh tokens is OPTIONAL. An 982 RDAP server MUST determine if the OP supports token refresh and 983 process the refresh request by either requesting refresh of the 984 access token or by returning a response that indicates that token 985 refresh is not supported by the OP in the "notices" data structure. 986 An example "roidc1_session/refresh" request: 988 https://example.com/rdap/roidc1_session/refresh 990 The response to this request MUST use the response structures 991 specified in RFC 9083 [RFC9083]. In addition, the response MUST 992 include an indication of the requested operation's success or failure 993 in the "notices" data structure (including the client identifier), 994 and, if successful, a "roidc1_session" data structure. 996 An example of a "roidc1_session/refresh" response: 998 { 999 "rdapConformance": [ 1000 "roidc1" 1001 ], 1002 "lang": "en-US", 1003 "notices": { 1004 "title": "Session Refresh Result", 1005 "description": [ 1006 "Session refresh succeeded", 1007 "user.idp.example", 1008 "Token refresh succeeded." 1009 ] 1010 }, 1011 "roidc1_session": { 1012 "userClaims": { 1013 "sub": "103892603076825016132", 1014 "name": "User Person", 1015 "given_name": "User", 1016 "family_name": "Person", 1017 "picture": "https://lh3.example.com/a-/AOh14=s96-c", 1018 "email": "user@example.com", 1019 "email_verified": true, 1020 "locale": "en", 1021 "rdap_allowed_purposes": [ 1022 "domainNameControl", 1023 "personalDataProtection" 1024 ], 1025 "rdap_dnt_allowed": false 1026 }, 1027 "sessionInfo": { 1028 "tokenExpiration": 3599, 1029 "tokenRefresh": true 1030 } 1031 } 1032 } 1034 Figure 12 1036 Alternatively, an RDAP server MAY implicitly attempt to refresh an 1037 access token upon receipt of a query if the access token associated 1038 with an existing session has expired and the corresponding OP 1039 supports token refresh. The default RDAP server behavior is 1040 described in the "implicitTokenRefreshSupported" value that's include 1041 in the "roidc1_openidcConfiguration" data structure (see 1042 Section 4.1.3). If the value of "implicitTokenRefreshSupported" is 1043 "true", the client MAY either explicitly attempt to refresh the 1044 session using the "roidc1_session/refresh" query, or it MAY depend on 1045 the RDAP server to implicitly attempt to refresh the session as 1046 necessary when an RDAP query is received by the server. If the value 1047 of "implicitTokenRefreshSupported" is "false", the client MUST 1048 explicitly attempt to refresh the session using the "roidc1_session/ 1049 refresh" query to extend an existing session. If a session cannot be 1050 extended for any reason, the client MUST establish a new session to 1051 continue authenticated query processing by submitting a 1052 "roidc1_session/login" query. If the OP does not support token 1053 refresh, the client MUST submit a new "roidc1_session/login" request 1054 to establish a new session once an access token has expired. 1056 4.6. Client Logout 1058 Clients MAY send a request to an RDAP server to terminate an existing 1059 login session. Termination of a session is requested using a 1060 "roidc1_session/logout" path segment. Access and refresh tokens can 1061 be revoked during the "roidc1_session/logout" process as described in 1062 RFC 7009 [RFC7009] if supported by the OP (token revocation endpoint 1063 support is OPTIONAL per RFC 8414 [RFC8414]). If supported, this 1064 feature SHOULD be used to ensure that the tokens are not mistakenly 1065 associated with a future RDAP session. Alternatively, an RDAP server 1066 MAY attempt to logout from the OP using the "OpenID Connect RP- 1067 Initiated Logout" protocol ([OIDCL]) if that protocol is supported by 1068 the OP. 1070 An example "roidc1_session/logout" request: 1072 https://example.com/rdap/roidc1_session/logout 1074 The response to this request MUST use the response structures 1075 specified in RFC 9083 [RFC9083]. In addition, the response MUST 1076 include an indication of the requested operation's success or failure 1077 in the "notices" data structure (including the client identifier). 1078 The "notices" data structure MUST also include an indication of the 1079 success or failure of any attempt to logout from the OP or to revoke 1080 the tokens issued by the OP. 1082 An example of a "roidc1_session/logout" response: 1084 { 1085 "rdapConformance": [ 1086 "roidc1" 1087 ], 1088 "lang": "en-US", 1089 "notices": { 1090 "title": "Logout Result", 1091 "description": [ 1092 "Logout succeeded", 1093 "user.idp.example", 1094 "Provider logout failed: Not supported by provider.", 1095 "Token revocation successful." 1096 ] 1097 } 1098 } 1100 Figure 13 1102 In the absence of a "logout" request, an RDAP session MUST be 1103 terminated by the RDAP server after a server-defined period of time. 1104 The server should also take appropriate steps to ensure that the 1105 tokens associated with the terminated session cannot be reused. This 1106 SHOULD include revoking the tokens or logging out from the OP if 1107 either operation is supported by the OP. 1109 4.7. Parameter Processing 1111 Unrecognized query parameters MUST be ignored. An RDAP server that 1112 processes an authenticated query MUST determine if the End-User 1113 identification information is associated with an OP that is 1114 recognized and supported by the server. Servers MUST reject queries 1115 that include identification information that is not associated with a 1116 supported OP by returning an HTTP 501 (Not Implemented) response. An 1117 RDAP server that receives a query containing identification 1118 information associated with a recognized OP MUST perform the steps 1119 required to authenticate the user with the OP, process the query, and 1120 return an RDAP response that is appropriate for the End-User's level 1121 of authorization and access. 1123 5. Token Exchange 1125 ID tokens include an audience parameter that contains the OAuth 2.0 1126 client_id of the RP as an audience value. In some operational 1127 scenarios (such as a client that is providing a proxy service), an RP 1128 can receive tokens with an audience value that does not include the 1129 RP's client_id. These tokens might not be trusted by the RP, and the 1130 RP might refuse to accept the tokens. This situation can be remedied 1131 by having the RP exchange these tokens with the OP for a set of 1132 trusted tokens that reset the audience parameter. This token 1133 exchange protocol is described in RFC 8693 [RFC8693]. This issue is 1134 not visible to the RDAP client and should be managed by the OpenID 1135 implementation used by the RDAP server. 1137 6. RDAP Query Processing 1139 Once an RDAP session is active, an RDAP server MUST determine if the 1140 End-User is authorized to perform any queries that are received 1141 during the duration of the session. This MAY include rejecting 1142 queries outright, and it MAY include omitting or otherwise redacting 1143 information that the End-User is not authorized to receive. Specific 1144 processing requirements are beyond the scope of this document. A 1145 client can end a session explicitly by sending a "roidc1_session/ 1146 logout" request to the RDAP server. A session can also be ended 1147 implicitly by the server after a server-defined period of time. The 1148 status of a session can be determined at any time by sending a 1149 "roidc1_session/status" query to the RDAP server. 1151 An RDAP server MUST maintain session state information for the 1152 duration of an active session. This is commonly done using HTTP 1153 cookies as described in RFC 6265 [RFC6265]. Doing so allows End-User 1154 to submit queries without having to explicitly identify and 1155 authenticate themselves for each and every query. 1157 7. RDAP Conformance 1159 RDAP responses that contain values described in this document MUST 1160 indicate conformance with this specification by including an 1161 rdapConformance ([RFC9083]) value of "roidc1" (RDAP OpenID Connect 1162 version 1). The information needed to register this value in the 1163 RDAP Extensions Registry is described in Section 8.1. 1165 Example rdapConformance structure with extension specified: 1167 "rdapConformance" : 1168 [ 1169 "rdap_level_0", 1170 "roidc1" 1171 ] 1173 Figure 14 1175 8. IANA Considerations 1176 8.1. RDAP Extensions Registry 1178 IANA is requested to register the following value in the RDAP 1179 Extensions Registry: 1181 Extension identifier: roidc1 1182 Registry operator: Any 1183 Published specification: This document. 1184 Contact: IESG 1185 Intended usage: This extension describes version 1 of a federated 1186 authentication method for RDAP using OAuth 2.0 and OpenID Connect. 1188 8.2. JSON Web Token Claims Registry 1190 IANA is requested to register the following values in the JSON Web 1191 Token Claims Registry: 1193 Claim Name: "rdap_allowed_purposes" 1194 Claim Description: This claim describes the set of RDAP query 1195 purposes that are available to an identity that is presented for 1196 access to a protected RDAP resource. 1197 Change Controller: IESG 1198 Specification Document(s): Section 3.1.4.1 of this document. 1200 Claim Name: "rdap_dnt_allowed" 1201 Claim Description: This claim contains a JSON boolean literal that 1202 describes a "do not track" request for server-side tracking, 1203 logging, or recording of an identity that is presented for access 1204 to a protected RDAP resource. 1205 Change Controller: IESG 1206 Specification Document(s): Section 3.1.4.2 of this document. 1208 8.3. RDAP Query Purpose Registry 1210 IANA is requested to create a new protocol registry to manage RDAP 1211 query purpose values. This registry should be named "Registration 1212 Data Access Protocol (RDAP) Query Purpose Values" and should appear 1213 under the "Registration Data Access Protocol (RDAP)" section of 1214 IANA's protocol registries. The information to be registered and the 1215 procedures to be followed in populating the registry are described in 1216 Section 3.1.4.1. 1218 Section at http://www.iana.org/protocols: Registration Data Access 1219 Protocol (RDAP) 1221 Name of registry: Registration Data Access Protocol (RDAP) Query 1222 Purpose Values 1223 Registration Procedure: Specification Required 1225 Reference: This document 1227 Required information: See Section 3.1.4.1. 1229 Review process: "Specification Required" as described in RFC 5226 1230 [RFC5226]. 1232 Size, format, and syntax of registry entries: See Section 3.1.4.1. 1234 Initial assignments and reservations: 1236 -----BEGIN FORM----- 1238 Value: domainNameControl 1240 Description: Tasks within the scope of this purpose include 1241 creating and managing and monitoring a registrant's own domain 1242 name, including creating the domain name, updating information 1243 about the domain name, transferring the domain name, renewing the 1244 domain name, deleting the domain name, maintaining a domain name 1245 portfolio, and detecting fraudulent use of the Registrant's own 1246 contact information. 1248 -----END FORM----- 1250 -----BEGIN FORM----- 1252 Value: personalDataProtection 1254 Description: Tasks within the scope of this purpose include 1255 identifying the accredited privacy/proxy provider associated with 1256 a domain name and reporting abuse, requesting reveal, or otherwise 1257 contacting the provider. 1259 -----END FORM----- 1261 -----BEGIN FORM----- 1263 Value: technicalIssueResolution 1265 Description: Tasks within the scope of this purpose include (but 1266 are not limited to) working to resolve technical issues, including 1267 email delivery issues, DNS resolution failures, and web site 1268 functional issues. 1270 -----END FORM----- 1271 -----BEGIN FORM----- 1273 Value: domainNameCertification 1275 Description: Tasks within the scope of this purpose include a 1276 Certification Authority (CA) issuing an X.509 certificate to a 1277 subject identified by a domain name. 1279 -----END FORM----- 1281 -----BEGIN FORM----- 1283 Value: individualInternetUse 1285 Description: Tasks within the scope of this purpose include 1286 identifying the organization using a domain name to instill 1287 consumer trust, or contacting that organization to raise a 1288 customer complaint to them or file a complaint about them. 1290 -----END FORM----- 1292 -----BEGIN FORM----- 1294 Value: businessDomainNamePurchaseOrSale 1296 Description: Tasks within the scope of this purpose include making 1297 purchase queries about a domain name, acquiring a domain name from 1298 a registrant, and enabling due diligence research. 1300 -----END FORM----- 1302 -----BEGIN FORM----- 1304 Value: academicPublicInterestDNSRResearch 1306 Description: Tasks within the scope of this purpose include 1307 academic public interest research studies about domain names 1308 published in the registration data service, including public 1309 information about the registrant and designated contacts, the 1310 domain name's history and status, and domain names registered by a 1311 given registrant (reverse query). 1313 -----END FORM----- 1315 -----BEGIN FORM----- 1317 Value: legalActions 1318 Description: Tasks within the scope of this purpose include 1319 investigating possible fraudulent use of a registrant's name or 1320 address by other domain names, investigating possible trademark 1321 infringement, contacting a registrant/licensee's legal 1322 representative prior to taking legal action and then taking a 1323 legal action if the concern is not satisfactorily addressed. 1325 -----END FORM----- 1327 -----BEGIN FORM----- 1329 Value: regulatoryAndContractEnforcement 1331 Description: Tasks within the scope of this purpose include tax 1332 authority investigation of businesses with online presence, 1333 Uniform Dispute Resolution Policy (UDRP) investigation, 1334 contractual compliance investigation, and registration data escrow 1335 audits. 1337 -----END FORM----- 1339 -----BEGIN FORM----- 1341 Value: criminalInvestigationAndDNSAbuseMitigation 1343 Description: Tasks within the scope of this purpose include 1344 reporting abuse to someone who can investigate and address that 1345 abuse, or contacting entities associated with a domain name during 1346 an offline criminal investigation. 1348 -----END FORM----- 1350 -----BEGIN FORM----- 1352 Value: dnsTransparency 1354 Description: Tasks within the scope of this purpose involve 1355 querying the registration data made public by registrants to 1356 satisfy a wide variety of use cases around informing the general 1357 public. 1359 -----END FORM----- 1361 9. Implementation Status 1363 NOTE: Please remove this section and the reference to RFC 7942 prior 1364 to publication as an RFC. 1366 This section records the status of known implementations of the 1367 protocol defined by this specification at the time of posting of this 1368 Internet-Draft, and is based on a proposal described in RFC 7942 1369 [RFC7942]. The description of implementations in this section is 1370 intended to assist the IETF in its decision processes in progressing 1371 drafts to RFCs. Please note that the listing of any individual 1372 implementation here does not imply endorsement by the IETF. 1373 Furthermore, no effort has been spent to verify the information 1374 presented here that was supplied by IETF contributors. This is not 1375 intended as, and must not be construed to be, a catalog of available 1376 implementations or their features. Readers are advised to note that 1377 other implementations may exist. 1379 According to RFC 7942, "this will allow reviewers and working groups 1380 to assign due consideration to documents that have the benefit of 1381 running code, which may serve as evidence of valuable experimentation 1382 and feedback that have made the implemented protocols more mature. 1383 It is up to the individual working groups to use this information as 1384 they see fit". 1386 Version -09 of this specification introduced changes that are 1387 incompatible with earlier implementations. Implementations that are 1388 consistent with this specification will be added as they are 1389 identified. 1391 9.1. Editor Implementation 1393 Location: https://procuratus.net/rdap/ 1394 Description: This implementation is a functionally-limited RDAP 1395 server that supports only the path segments described in this 1396 specification. It uses the "jumbojett/OpenID-Connect-PHP" library 1397 found on GitHub, which appears to no longer be under active 1398 development. The library was modified to add support for the 1399 device authorization grant. Session variable management is still 1400 a little buggy. Supported OPs include Google (Gmail) and Yahoo. 1401 Level of Maturity: This is a "proof of concept" research 1402 implementation. 1403 Coverage: This implementation includes all of the features 1404 described in this specification. 1405 Version compatibility: Version -11+ of this specification. 1406 Contact Information: Scott Hollenbeck, shollenbeck@verisign.com 1408 9.2. Verisign Labs 1410 Responsible Organization: Verisign Labs 1411 Location: https://rdap.verisignlabs.com/ 1412 Description: This implementation includes support for domain 1413 registry RDAP queries using live data from the .cc and .tv country 1414 code top-level domains and the .career generic top-level domain. 1415 Three access levels are provided based on the authenticated 1416 identity of the client: 1417 1. Unauthenticated: Limited information is returned in response 1418 to queries from unauthenticated clients. 1419 2. Basic: Clients who authenticate using a publicly available 1420 identity provider like Google Gmail or Microsoft Hotmail will 1421 receive all of the information available to an unauthenticated 1422 client plus additional registration metadata, but no 1423 personally identifiable information associated with entities. 1424 3. Advanced: Clients who authenticate using a more restrictive 1425 identity provider will receive all of the information 1426 available to a Basic client plus whatever information the 1427 server operator deems appropriate for a fully authorized 1428 client. Currently supported identity providers include those 1429 developed by Verisign Labs 1430 (https://testprovider.rdap.verisignlabs.com/) and CZ.NIC 1431 (https://www.mojeid.cz/). 1432 Level of Maturity: This is a "proof of concept" research 1433 implementation. 1434 Coverage: This implementation includes all of the features 1435 described in this specification. 1436 Version compatibility: Version -07 of this specification. 1437 Contact Information: Scott Hollenbeck, shollenbeck@verisign.com 1439 9.3. Viagenie 1441 Responsible Organization: Viagenie 1442 Location: https://auth.viagenie.ca 1443 Description: This implementation is an OpenID identity provider 1444 enabling users and registries to connect to the federation. It 1445 also includes a barebone RDAP client and RDAP server in order to 1446 test the authentication framework. Various level of purposes are 1447 available for testing. 1448 Level of Maturity: This is a "proof of concept" research 1449 implementation. 1450 Coverage: This implementation includes most features described in 1451 this specification as an identity provider. 1452 Version compatibility: Version -07 of this specification. 1453 Contact Information: Marc Blanchet, marc.blanchet@viagenie.ca 1455 10. Security Considerations 1457 Security considerations for RDAP can be found in RFC 7481 [RFC7481]. 1458 Security considerations for OpenID Connect Core [OIDCC] and OAuth 2.0 1459 [RFC6749] can be found in their reference specifications. OpenID 1460 Connect defines optional mechanisms for robust signing and encryption 1461 that can be used to provide data integrity and data confidentiality 1462 services as needed. 1464 10.1. Authentication and Access Control 1466 Having completed the client identification, authorization, and 1467 validation process, an RDAP server can make access control decisions 1468 based on a comparison of client-provided information and local 1469 policy. For example, a client who provides an email address (and 1470 nothing more) might be entitled to receive a subset of the 1471 information that would be available to a client who provides an email 1472 address, a full name, and a stated purpose. Development of these 1473 access control policies is beyond the scope of this document. 1475 11. Acknowledgments 1477 The author would like to acknowledge the following individuals for 1478 their contributions to the development of this document: Marc 1479 Blanchet, Tom Harrison, Russ Housley, Jasdip Singh, Rhys Smith, 1480 Jaromir Talir, Rick Wilhelm, and Alessandro Vesely. In addition, the 1481 Verisign Registry Services Lab development team of Joseph Harvey, 1482 Andrew Kaizer, Sai Mogali, Anurag Saxena, Swapneel Sheth, Nitin 1483 Singh, and Zhao Zhao provided critical "proof of concept" 1484 implementation experience that helped demonstrate the validity of the 1485 concepts described in this document. 1487 Pawel Kowalik and Mario Loffredo provided significant text 1488 contributions that led to welcome improvements in several sections of 1489 this document. Their contributions are greatly appreciated. 1491 12. References 1493 12.1. Normative References 1495 [OIDC] OpenID Foundation, "OpenID Connect", 1496 . 1498 [OIDCC] OpenID Foundation, "OpenID Connect Core incorporating 1499 errata set 1", November 2014, 1500 . 1502 [OIDCD] OpenID Foundation, "OpenID Connect Discovery 1.0 1503 incorporating errata set 1", November 2014, 1504 . 1507 [OIDCL] OpenID Foundation, "OpenID Connect RP-Initiated Logout 1.0 1508 - draft 01", August 2020, . 1511 [OIDCR] OpenID Foundation, "OpenID Connect Dynamic Client 1512 Registration 1.0 incorporating errata set 1", November 1513 2014, . 1516 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1517 Requirement Levels", BCP 14, RFC 2119, 1518 DOI 10.17487/RFC2119, March 1997, 1519 . 1521 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1522 Resource Identifier (URI): Generic Syntax", STD 66, 1523 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1524 . 1526 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1527 IANA Considerations Section in RFCs", RFC 5226, 1528 DOI 10.17487/RFC5226, May 2008, 1529 . 1531 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 1532 DOI 10.17487/RFC6265, April 2011, 1533 . 1535 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1536 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1537 . 1539 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 1540 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 1541 August 2013, . 1543 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1544 Protocol (HTTP/1.1): Message Syntax and Routing", 1545 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1546 . 1548 [RFC7480] Newton, A., Ellacott, B., and N. Kong, "HTTP Usage in the 1549 Registration Data Access Protocol (RDAP)", STD 95, 1550 RFC 7480, DOI 10.17487/RFC7480, March 2015, 1551 . 1553 [RFC7481] Hollenbeck, S. and N. Kong, "Security Services for the 1554 Registration Data Access Protocol (RDAP)", STD 95, 1555 RFC 7481, DOI 10.17487/RFC7481, March 2015, 1556 . 1558 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1559 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1560 . 1562 [RFC7617] Reschke, J., "The 'Basic' HTTP Authentication Scheme", 1563 RFC 7617, DOI 10.17487/RFC7617, September 2015, 1564 . 1566 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1567 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1568 May 2017, . 1570 [RFC8628] Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, 1571 "OAuth 2.0 Device Authorization Grant", RFC 8628, 1572 DOI 10.17487/RFC8628, August 2019, 1573 . 1575 [RFC8693] Jones, M., Nadalin, A., Campbell, B., Ed., Bradley, J., 1576 and C. Mortimore, "OAuth 2.0 Token Exchange", RFC 8693, 1577 DOI 10.17487/RFC8693, January 2020, 1578 . 1580 [RFC9082] Hollenbeck, S. and A. Newton, "Registration Data Access 1581 Protocol (RDAP) Query Format", STD 95, RFC 9082, 1582 DOI 10.17487/RFC9082, June 2021, 1583 . 1585 [RFC9083] Hollenbeck, S. and A. Newton, "JSON Responses for the 1586 Registration Data Access Protocol (RDAP)", STD 95, 1587 RFC 9083, DOI 10.17487/RFC9083, June 2021, 1588 . 1590 12.2. Informative References 1592 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 1593 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 1594 . 1596 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 1597 Code: The Implementation Status Section", BCP 205, 1598 RFC 7942, DOI 10.17487/RFC7942, July 2016, 1599 . 1601 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 1602 Authorization Server Metadata", RFC 8414, 1603 DOI 10.17487/RFC8414, June 2018, 1604 . 1606 Appendix A. Change Log 1608 00: Initial working group version ported from draft-hollenbeck- 1609 regext-rdap-openid-10. 1610 01: Modified ID Token delivery approach to note proper use of an 1611 HTTP bearer authorization header. 1612 02: Modified token delivery approach (Access Token is the bearer 1613 token) to note proper use of an HTTP bearer authorization header, 1614 fixing the change made in -01. 1615 03: Updated OAuth 2.0 Device Authorization Grant description and 1616 reference due to publication of RFC 8628. 1617 04: Updated OAuth 2.0 token exchange description and reference due 1618 to publication of RFC 8693. Corrected the RDAP conformance 1619 identifier to be registered with IANA. 1620 05: Keepalive refresh. 1621 06: Keepalive refresh. 1622 07: Added "login_hint" description to Section 3.1.3.2. Added some 1623 text to Section 3.1.4.2 to note that "do not track" requires 1624 compliance with local regulations. 1625 08: Rework of token management processing in Sections 4 and 5. 1626 09: Updated RDAP specification references. Added text to describe 1627 both default and remote Authorization Server processing. Removed 1628 text that described passing of ID Tokens as query parameters. 1629 10: Updated Section 3.1.3.1. Replaced token processing queries with 1630 "login", "session", and "logout" queries. 1631 11: Replaced queries with "session/*" queries. Added description of 1632 "rdap" OAuth scope. Added implementation status information. 1633 12: Updated data structure descriptions. Updated Section 8. Minor 1634 formatting changes due to a move to xml2rfc-v3 markup. 1635 13: Added support for OP discovery via OP's Issuer Identifier. 1636 Modified the RDAP conformance text to use "roidc1", and added that 1637 value to extension path segments, data structures, and query 1638 parameters. Changed the "purpose" and "dnt" claims to 1639 "rdap_allowed_purposes" (making it an array) and 1640 "rdap_dnt_allowed". Added the "roidc1_qp" and "roidc1_dnt" query 1641 parameters. Changed the descriptions of "local" OPs to "default" 1642 OPs. 1643 14: Fixed a few instances of "id" that were changed to "roidc1_id" 1644 and "session" that were changed to "roidc1_session". Added 1645 "implicitTokenRefreshSupported". 1646 15: Fixed an instance of openidcConfiguration that was missing the 1647 "roidc1" prefix. Changed SHOULD to MUST to describe the need to 1648 return the roidc1_openidcConfiguration data structure in a "help" 1649 response. 1651 Author's Address 1653 Scott Hollenbeck 1654 Verisign Labs 1655 12061 Bluemont Way 1656 Reston, VA 20190 1657 United States of America 1658 Email: shollenbeck@verisign.com 1659 URI: http://www.verisignlabs.com/