idnits 2.17.1 draft-hollenbeck-regext-rdap-openid-04.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 (August 14, 2017) is 2446 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) -- Looks like a reference, but probably isn't: '1' on line 1044 -- Looks like a reference, but probably isn't: '2' on line 1046 -- Looks like a reference, but probably isn't: '3' on line 1049 -- Looks like a reference, but probably isn't: '4' on line 1051 -- 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) ** Obsolete normative reference: RFC 7482 (Obsoleted by RFC 9082) ** Obsolete normative reference: RFC 7483 (Obsoleted by RFC 9083) Summary: 5 errors (**), 0 flaws (~~), 1 warning (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force S. Hollenbeck 3 Internet-Draft Verisign Labs 4 Intended status: Standards Track August 14, 2017 5 Expires: February 15, 2018 7 Federated Authentication for the Registration Data Access Protocol 8 (RDAP) using OpenID Connect 9 draft-hollenbeck-regext-rdap-openid-04 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 http://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 February 15, 2018. 43 Copyright Notice 45 Copyright (c) 2017 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 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.1. Problem Statement . . . . . . . . . . . . . . . . . . . . 3 62 1.2. Proposal . . . . . . . . . . . . . . . . . . . . . . . . 3 63 2. Conventions Used in This Document . . . . . . . . . . . . . . 4 64 3. Federated Authentication for RDAP . . . . . . . . . . . . . . 4 65 3.1. RDAP and OpenID Connect . . . . . . . . . . . . . . . . . 4 66 3.1.1. Terminology . . . . . . . . . . . . . . . . . . . . . 5 67 3.1.2. Overview . . . . . . . . . . . . . . . . . . . . . . 5 68 3.1.3. RDAP Authentication and Authorization Steps . . . . . 6 69 3.1.3.1. Provider Discovery . . . . . . . . . . . . . . . 6 70 3.1.3.2. Authentication Request . . . . . . . . . . . . . 6 71 3.1.3.3. End-User Authorization . . . . . . . . . . . . . 7 72 3.1.3.4. Authorization Response and Validation . . . . . . 7 73 3.1.3.5. Token Processing . . . . . . . . . . . . . . . . 7 74 3.1.3.6. Delivery of User Information . . . . . . . . . . 7 75 3.1.4. Specialized Parameters for RDAP . . . . . . . . . . . 7 76 3.1.4.1. Claims . . . . . . . . . . . . . . . . . . . . . 7 77 4. Protocol Parameters . . . . . . . . . . . . . . . . . . . . . 9 78 4.1. Client Authentication Request and Response . . . . . . . 9 79 4.2. Token Request and Response . . . . . . . . . . . . . . . 9 80 4.3. Token Refresh and Revocation . . . . . . . . . . . . . . 10 81 4.4. Parameter Processing . . . . . . . . . . . . . . . . . . 13 82 4.5. RDAP Conformance . . . . . . . . . . . . . . . . . . . . 14 83 5. Non-Browser Clients . . . . . . . . . . . . . . . . . . . . . 14 84 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 85 6.1. RDAP Extensions Registry . . . . . . . . . . . . . . . . 15 86 6.2. JSON Web Token Claims Registry . . . . . . . . . . . . . 16 87 6.3. RDAP Query Purpose Registry . . . . . . . . . . . . . . . 16 88 7. Implementation Status . . . . . . . . . . . . . . . . . . . . 18 89 7.1. Verisign Labs . . . . . . . . . . . . . . . . . . . . . . 19 90 8. Security Considerations . . . . . . . . . . . . . . . . . . . 20 91 8.1. Authentication and Access Control . . . . . . . . . . . . 20 92 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 20 93 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 94 10.1. Normative References . . . . . . . . . . . . . . . . . . 20 95 10.2. Informative References . . . . . . . . . . . . . . . . . 22 96 10.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 22 97 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 23 98 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 23 100 1. Introduction 102 The Registration Data Access Protocol (RDAP) provides "RESTful" web 103 services to retrieve registration metadata from domain name and 104 regional internet registries. RDAP allows a server to make access 105 control decisions based on client identity, and as such it includes 106 support for client identification features provided by the Hypertext 107 Transfer Protocol (HTTP) [RFC7230]. 109 RDAP is specified in multiple documents, including "HTTP Usage in the 110 Registration Data Access Protocol (RDAP)" [RFC7480], "Security 111 Services for the Registration Data Access Protocol (RDAP)" [RFC7481], 112 "Registration Data Access Protocol Query Format" [RFC7482], and "JSON 113 Responses for the Registration Data Access Protocol (RDAP)" 114 [RFC7483]. RFC 7481 describes client identification and 115 authentication services that can be used with RDAP, but it does not 116 specify how any of these services can (or should) be used with RDAP. 118 1.1. Problem Statement 120 The traditional "user name and password" authentication method does 121 not scale well in the RDAP ecosystem. Assuming that all domain name 122 and address registries will eventually provide RDAP service, it is 123 impractical and inefficient for users to secure login credentials 124 from the hundreds of different server operators. Authentication 125 methods based on user names and passwords do not provide information 126 that describes the user in sufficient detail (while protecting the 127 personal privacy of the user) for server operators to make fine- 128 grained access control decisions based on the user's identity. The 129 authentication system used for RDAP needs to address all of these 130 needs. 132 1.2. Proposal 134 A basic level of RDAP service can be provided to users who possess an 135 identifier issued by a recognized provider who is able to 136 authenticate and validate the user. The identifiers issued by social 137 media services, for example, can be used. Users who require higher 138 levels of service (and who are willing to share more information 139 about them self to gain access to that service) can secure 140 identifiers from specialized providers who are or will be able to 141 provide more detailed information about the user. Server operators 142 can then make access control decisions based on the identification 143 information provided by the user. 145 A federated authentication system would make it easier to operate and 146 use RDAP by re-using existing identifiers to provide a basic level of 147 access. It can also provide the ability to collect additional user 148 identification information, and that information can be shared with 149 the consent of the user. This document describes a federated 150 authentication system for RDAP based on OpenID Connect [OIDC] that 151 meets all of these needs. 153 2. Conventions Used in This Document 155 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 156 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 157 document are to be interpreted as described in RFC 2119 [RFC2119]. 159 3. Federated Authentication for RDAP 161 RDAP itself does not include native security services. Instead, RDAP 162 relies on features that are available in other protocol layers to 163 provide needed security services including access control, 164 authentication, authorization, availability, data confidentiality, 165 data integrity, and identification. A description of each of these 166 security services can be found in "Internet Security Glossary, 167 Version 2" [RFC4949]. This document focuses on a federated 168 authentication system for RDAP that provides services for 169 authentication, authorization, and identification, allowing a server 170 operator to make access control decisions. Section 3 of RFC 7481 171 [RFC7481] describes general considerations for RDAP access control, 172 authentication, and authorization. 174 The traditional client-server authentication model requires clients 175 to maintain distinct credentials for every RDAP server. This 176 situation can become unwieldy as the number of RDAP servers 177 increases. Federated authentication mechanisms allow clients to use 178 one credential to access multiple RDAP servers and reduce client 179 credential management complexity. 181 3.1. RDAP and OpenID Connect 183 OpenID Connect 1.0 [OIDCC] is a decentralized, single sign-on (SSO) 184 federated authentication system that allows users to access multiple 185 web resources with one identifier instead of having to create 186 multiple server-specific identifiers. Users acquire identifiers from 187 OpenID Providers, or OPs. Relying Parties, or RPs, are applications 188 (such as RDAP) that outsource their user authentication function to 189 an OP. OpenID Connect is built on top of the authorization framework 190 provided by the OAuth 2.0 [RFC6749] protocol. 192 The OAuth authorization framework describes a method for users to 193 access protected web resources without having to hand out their 194 credentials. Instead, clients are issued Access Tokens by 195 authorization servers with the permission of the resource owners. 196 Using OpenID Connect and OAuth, multiple RDAP servers can form a 197 federation and clients can access any server in the federation by 198 providing one credential registered with any OP in that federation. 199 The OAuth authorization framework is designed for use with HTTP and 200 thus can be used with RDAP. 202 3.1.1. Terminology 204 This document uses the terms "client" and "server" defined by RDAP 205 [RFC7480]. An RDAP client performs the role of an OpenID Connect 206 Core [OIDCC] Entity or End-User. An RDAP server performs the role of 207 an OpenID Connect Core Relying Party (RP). Additional terms from 208 Section 1.2 of the OpenID Connect Core specification are incorporated 209 by reference. 211 3.1.2. Overview 213 At a high level, RDAP authentication of a browser-based client using 214 OpenID Connect requires completion of the following steps: 216 1. An RDAP client (acting as an OpenID End-User) sends an HTTP (or 217 HTTPS) query containing OAuth 2.0 request parameters to an RDAP 218 server. 219 2. The RDAP server (acting as an OpenID Relying Party (RP)) prepares 220 an Authentication Request containing the desired request 221 parameters. 222 3. The RDAP server sends the RDAP client and Authentication Request 223 to an Authorization Server operated by an OpenID Provider (OP) 224 using an HTTP redirect. 225 4. The Authorization Server authenticates the RDAP Client. 226 5. The Authorization Server obtains RDAP Client consent/ 227 authorization. 228 6. The Authorization Server sends the RDAP Client back to the RDAP 229 server with an Authorization Code using an HTTP redirect. 230 7. The RDAP server requests a response using the Authorization Code 231 at the Token Endpoint. 232 8. The RDAP server receives a response that contains an ID Token and 233 Access Token in the response body. 234 9. The RDAP server validates the ID Token and retrieves the RDAP 235 client's Subject Identifier. 237 The RDAP server can then make identification, authorization, and 238 access control decisions based on local policies, the ID Token 239 received from the OP, and the received Claims. Note that OpenID 240 Connect describes different process flows for other types of clients, 241 such as script-based or command line clients. 243 3.1.3. RDAP Authentication and Authorization Steps 245 End-Users MUST possess an identifier (an OpenID) issued by an OP to 246 use OpenID Connect with RDAP. The OpenID Foundation maintains a list 247 of OPs on its web site [1]. Additional OPs are almost certainly 248 needed to fully realize the potential for federated authentication 249 with RDAP because RDAP has authorization and access control 250 requirements that go beyond the end-user authentication requirements 251 of a typical web site. 253 OpenID Connect requires RPs to register with OPs to use OpenID 254 Connect services for an End-User. That process is described by the 255 "OpenID Connect Dynamic Client Registration" protocol [OIDCR]. 257 3.1.3.1. Provider Discovery 259 An RDAP server/RP needs to receive an identifier from an End-User 260 that can be used to discover the End-User's OP. That process is 261 required and is documented in the "OpenID Connect Discovery" protocol 262 [OIDCD]. 264 3.1.3.2. Authentication Request 266 Once the OP is known, an RP MUST form an Authentication Request and 267 send it to the OP as described in Section 3 of the OpenID Connect 268 Core protocol [OIDCC]. The authentication path followed 269 (authorization, implicit, or hybrid) will depend on the 270 Authentication Request response_type set by the RP. The remainder of 271 the processing steps described here assume that the Authorization 272 Code Flow is being used by setting "response_type=code" in the 273 Authentication Request. 275 The benefits of using the Authorization Code Flow for authenticating 276 a human user are described in Section 3.1 of the OpenID Connect Core 277 protocol. The Implicit Flow is more commonly used by clients 278 implemented in a web browser using a scripting language; it is 279 described in Section 3.2 of the OpenID Connect Core protocol. The 280 Hybrid Flow (described in Section 3.3 of the OpenID Connect Core 281 protocol) combines elements of the Authorization and Implicit Flows 282 by returning some tokens from the Authorization Endpoint and others 283 from the Token Endpoint. 285 An Authentication Request can contain several parameters. REQUIRED 286 parameters are specified in Section 3.1.2.1 of the OpenID Connect 287 Core protocol [OIDCC]. Other parameters MAY be included. 289 The OP receives the Authentication Request and attempts to validate 290 it as described in Section 3.1.2.2 of the OpenID Connect Core 291 protocol [OIDCC]. If the request is valid, the OP attempts to 292 authenticate the End-User as described in Section 3.1.2.3 of the 293 OpenID Connect Core protocol [OIDCC]. The OP returns an error 294 response if the request is not valid or if any error is encountered. 296 3.1.3.3. End-User Authorization 298 After the End-User is authenticated, the OP MUST obtain authorization 299 information from the End-User before releasing information to the 300 RDAP Server/RP. This process is described in Section 3.1.2.4 of the 301 OpenID Connect Core protocol [OIDCC]. 303 3.1.3.4. Authorization Response and Validation 305 After the End-User is authenticated, the OP will send a response to 306 the RP that describes the result of the authorization process in the 307 form of an Authorization Grant. The RP MUST validate the response. 308 This process is described in Sections 3.1.2.5 - 3.1.2.7 of the OpenID 309 Connect Core protocol [OIDCC]. 311 3.1.3.5. Token Processing 313 The RP sends a Token Request using the Authorization Grant to a Token 314 Endpoint to obtain a Token Response containing an Access Token, ID 315 Token, and an OPTIONAL Refresh Token. The RP MUST validate the Token 316 Response. This process is described in Section 3.1.3 of the OpenID 317 Connect Core protocol [OIDCC]. 319 3.1.3.6. Delivery of User Information 321 The set of Claims can be retrieved by sending a request to a UserInfo 322 Endpoint using the Access Token. The Claims MAY be returned in the 323 ID Token. The process of retrieving Claims from a UserInfo Endpoint 324 is described in Section 5.3 of the OpenID Connect Core protocol 325 [OIDCC]. 327 OpenID Connect specified a set of standard Claims in Section 5.1. 328 Additional Claims for RDAP are described in Section 3.1.4.1. 330 3.1.4. Specialized Parameters for RDAP 332 3.1.4.1. Claims 334 OpenID Connect claims are pieces of information used to make 335 assertions about an entity. Section 5 of the OpenID Connect Core 336 protocol [OIDCC] describes a set of standard claims that can be used 337 to identify a person. Section 5.1.2 notes that additional claims MAY 338 be used, and it describes a method to create them. 340 3.1.4.1.1. Stated Purpose 342 There are communities of RDAP users and operators who wish to make 343 and validate claims about a user's "need to know" when it comes to 344 requesting access to a resource. For example, a law enforcement 345 agent or a trademark attorney may wish to be able to assert that they 346 have a legal right to access a protected resource, and a server 347 operator will need to be able to receive and validate that claim. 348 These needs can be met by defining and using an additional "purpose" 349 claim. 351 The "purpose" claim identifies the purpose for which access to a 352 protected resource is being requested. Use of the "purpose" claim is 353 OPTIONAL; processing of this claim is subject to server acceptance of 354 the purpose and successful authentication of the End-User. 355 Unrecognized purpose values MUST be ignored and the associated query 356 MUST be processed as if the unrecognized purpose value was not 357 present at all. 359 The "purpose" value is a case-sensitive string containing a 360 StringOrURI value as specified in Section 2 of the JSON Web Token 361 (JWT) specification ([RFC7519]). An example: 363 {"purpose" : "domainNameControl"} 365 Purpose values are themselves registered with IANA. Each entry in 366 the registry contains the following fields: 368 Value: the purpose string value being registered. Value strings can 369 contain upper case characters from "A" to "Z", lower case ASCII 370 characters from "a" to "z", and the underscore ("_") character. 371 Value strings contain at least one character and no more than 64 372 characters. 374 Description: a one- or two-sentence description of the meaning of the 375 purpose value, how it might be used, and/or how it should be 376 interpreted by clients and servers. 378 This registry is operated under the "Specification Required" policy 379 defined in RFC 5226 ([RFC5226]). The set of initial values used to 380 populate the registry as described in Section 6.3 are taken from the 381 final report [2] produced by the Expert Working Group on gTLD 382 Directory Services chartered by the Internet Corporation for Assigned 383 Names and Numbers (ICANN). 385 4. Protocol Parameters 387 This specification adds the following protocol parameters to RDAP: 389 1. A query parameter to request authentication for a specific end- 390 user identity. 391 2. A path segment to request an ID Token and an Access Token for a 392 specific end-user identity. 393 3. A query parameter to deliver an ID Token and an Access Token for 394 use with an RDAP query. 396 4.1. Client Authentication Request and Response 398 Client authentication is requested by adding a query component to an 399 RDAP request URI using the syntax described in Section 3.4 of RFC 400 3986 [RFC3986]. The query used to request client authentication is 401 represented as a "key=value" pair using a key value of "id" and a 402 value component that contains the client identifier issued by an OP. 403 An example: 405 https://example.com/rdap/domain/example.com?id=user.idp.example 407 The response to an authenticated query MUST use the response 408 structures specified in RFC 7483 [RFC7483]. Information that the 409 end-user is not authorized to receive MUST be omitted from the 410 response. 412 4.2. Token Request and Response 414 Clients MAY send a request to an RDAP server to authenticate an end- 415 user and return an ID Token and an Access Token from an OP that can 416 be then be passed to the RP/RDAP server to authenticate and process 417 subsequent queries. Identity provider authentication is requested 418 using a "tokens" path segment and a query parameter with key value of 419 "id" and a value component that contains the client identifier issued 420 by an OP. An example: 422 https://example.com/rdap/tokens?id=user.idp.example 424 In addition to any core RDAP response elements, the response to this 425 query MUST contain four name-value pairs, in any order, representing 426 the returned ID Token and Access Token. The ID Token is represented 427 using a key value of "id_token". The Access Token is represented 428 using a key value of "access_token". The access token type is 429 represented using a key value of "token_type" and a value of "bearer" 430 as described in Sections 4.2.2 and 7.1 of RFC 6749 [RFC6749]. The 431 lifetime of the access token is represented using a key value of 432 "expires_in" and a numerical value that describes the lifetime in 433 seconds of the access token as described in Section 4.2.2 of RFC 6749 434 [RFC6749]. The token values returned in the RDAP server response 435 MUST be Base64url encoded as described in RFCs 7515 [RFC7515] and 436 7519 [RFC7519]. 438 An example (the encoded tokens have been abbreviated for clarity): 440 { 441 "access_token" : "eyJ0...NiJ9", 442 "id_token" : "eyJ0...EjXk", 443 "token_type" : "bearer", 444 "expires_in" : "3600" 445 } 447 Figure 1 449 An RDAP server that processes this type of query MUST determine if 450 the identifier is associated with an OP that is recognized and 451 supported by the server. Servers MUST reject queries that include an 452 identifier associated with an unsupported OP with an HTTP 501 (Not 453 Implemented) response. An RDAP server that receives a query 454 containing an identifier associated with a recognized OP MUST perform 455 the steps required to authenticate the user with the OP using a 456 browser or browser-like client and return encoded tokens to the 457 client. Note that tokens are typically valid for a limited period of 458 time and new tokens will be required when an existing token's 459 validity period has expired. 461 The tokens can then be passed to the server for use with an RDAP 462 query using a query parameter with key values of "id_token" and 463 "access_token" and values that represent the encoded tokens. An 464 example (the encoded tokens have been abbreviated and the URI split 465 across multiple lines for clarity): 467 https://example.com/rdap/domain/example.com 468 ?id_token=eyJ0...EjXk 469 &access_token=eyJ0...NiJ9 471 The response to an authenticated query MUST use the response 472 structures specified in RFC 7483 [RFC7483]. Information that the 473 end-user is not authorized to receive MUST be omitted from the 474 response. 476 4.3. Token Refresh and Revocation 478 An access token can be refreshed as described in Section 12 of the 479 OpenID Connect Core protocol [OIDCC] and Section 6 of OAuth 2.0 481 [RFC6749]. Clients can take advantage of this functionality if it is 482 supported by the OP and accepted by the RDAP server. 484 A refresh token is requested using a "tokens" path segment and two 485 query parameters. The first query parameter includes a key value of 486 "id" and a value component that contains the client identifier issued 487 by an OP. The second query parameter includes a key value of 488 "refresh" and a value component of "true". A value component of 489 "false" MUST be processed to return a result that is consistent with 490 not including a "refresh" parameter at all as described in 491 Section 4.2. An example using "refresh=true": 493 https://example.com/rdap/tokens?id=user.idp.example 494 &refresh=true 496 The response to this query MUST contain all of the response elements 497 described in Section 4.2. In addition, the response MUST contain a 498 name-value pair that represents a refresh token. The name-value pair 499 includes a key value of "refresh_token" and a Base64url-encoded value 500 that represents the refresh token. 502 Example refresh token request response (the encoded tokens have been 503 abbreviated for clarity): 505 { 506 "access_token" : "eyJ0...NiJ9", 507 "id_token" : "eyJ0...EjXk", 508 "token_type" : "bearer", 509 "expires_in" : "3600", 510 "refresh_token" : "eyJ0...c8da" 511 } 513 Figure 2 515 Once acquired, a refresh token can be used to refresh an access 516 token. An access token is refreshed using a "tokens" path segment 517 and two query parameters. The first query parameter includes a key 518 value of "id" and a value component that contains the client 519 identifier issued by an OP. The second query parameter includes a 520 key value of "refresh_token" and a Base64url-encoded value that 521 represents the refresh token. An example: 523 https://example.com/rdap/tokens?id=user.idp.example 524 &refresh_token=eyJ0...f3jE 526 In addition to any core RDAP response elements, the response to this 527 query MUST contain four name-value pairs, in any order, representing 528 a returned Refresh Token and Access Token. The Refresh Token is 529 represented using a key value of "refresh_token". The Access Token 530 is represented using a key value of "access_token". The access token 531 type is represented using a key value of "token_type" and a value of 532 "bearer" as described in Sections 4.2.2 and 7.1 of RFC 6749 533 [RFC6749]. The lifetime of the access token is represented using a 534 key value of "expires_in" and a numerical value that describes the 535 lifetime in seconds of the access token as described in Section 4.2.2 536 of RFC 6749 [RFC6749]. The token values returned in the RDAP server 537 response MUST be Base64url encoded as described in RFCs 7515 538 [RFC7515] and 7519 [RFC7519]. 540 Example access token refresh response (the encoded tokens have been 541 abbreviated for clarity): 543 { 544 "access_token" : "0dac...13b0", 545 "refresh_token" : "f735...d30c", 546 "token_type" : "bearer", 547 "expires_in" : "3600" 548 } 550 Figure 3 552 Access and refresh tokens can be revoked as described in RFC 7009 553 [RFC7009] by sending a request to an RDAP server that contains a 554 "tokens/revoke" path segment and two query parameters. The first 555 query parameter includes a key value of "id" and a value component 556 that contains the client identifier issued by an OP. The second 557 query parameter includes a key value of "token" and a Base64url- 558 encoded value that represents either the current refresh token or the 559 associated access token. An example: 561 https://example.com/rdap/tokens/revoke?id=user.idp.example 562 &token=f735...d30c 564 Note that this command will revoke both access and refresh tokens at 565 the same time. In addition to any core RDAP response elements, the 566 response to this query MUST contain a description of the result of 567 processing the revocation request within the RDAP "notices" data 568 structure. 570 Example token revocation success: 572 "notices" : 573 [ 574 { 575 "title" : "Token Revocation Result", 576 "description" : "Token revocation succeeded.", 577 } 578 ], 579 "lang" : "en-US" 581 Figure 4 583 Example token revocation failure: 585 "notices" : 586 [ 587 { 588 "title" : "Token Revocation Result", 589 "description" : "Token revocation failed.", 590 } 591 ], 592 "errorCode" : 400, 593 "lang" : "en-US" 595 Figure 5 597 4.4. Parameter Processing 599 Unrecognized query parameters MUST be ignored. An RDAP request that 600 does not include an "id" query component MUST be processed as an 601 unauthenticated query. An RDAP server that processes an 602 authenticated query MUST determine if the identifier is associated 603 with an OP that is recognized and supported by the server. Servers 604 MUST reject queries that include an identifier associated with an 605 unsupported OP with an HTTP 501 (Not Implemented) response. An RDAP 606 server that receives a query containing an identifier associated with 607 a recognized OP MUST perform the steps required to authenticate the 608 user with the OP, process the query, and return an RDAP response that 609 is appropriate for the end user's level of authorization and access. 611 An RDAP server that receives a query containing tokens associated 612 with a recognized OP and authenticated end user MUST process the 613 query and return an RDAP response that is appropriate for the end 614 user's level of authorization and access. Errors based on processing 615 either the ID Token or the Access Token MUST be signaled with an 616 appropriate HTTP status code as described in Section 3.1 of RFC 6750 617 [RFC6750]. 619 On receiving a query containing tokens, the RDAP server MUST validate 620 the ID Token. It can do this independently of the OP, because the ID 621 Token is a JWT that contains all the data necessary for validation. 622 The Access Token, however, is an opaque value, and can only be 623 validated by sending a request using it to the UserInfo Endpoint and 624 confirming that a successful response is received. This is different 625 from the OpenID Connect Authorization Code and Implicit flows, where 626 the Access Token can be validated against the at_hash claim from the 627 ID Token. With a query containing tokens, the Access Token might not 628 validate against the at_hash claim because the Access Token may have 629 been refreshed since the ID Token was issued. 631 An RDAP server that processes requests without needing the UserInfo 632 claims does not need to retrieve the claims merely in order to 633 validate the Access Token. Similarly, an RDAP server that has cached 634 the UserInfo claims for an end user, in accordance with the HTTP 635 headers of a previous UserInfo Endpoint response, does not need to 636 retrieve those claims again in order to revalidate the Access Token. 638 4.5. RDAP Conformance 640 RDAP responses that contain values described in this document MUST 641 indicate conformance with this specification by including an 642 rdapConformance ([RFC7483]) value of "rdap_openidc_level_0". The 643 information needed to register this value in the RDAP Extensions 644 Registry is described in Section 6.1. 646 Example rdapConformance structure with extension specified: 648 "rdapConformance" : 649 [ 650 "rdap_level_0", 651 "rdap_openidc_level_0" 652 ] 654 Figure 6 656 5. Non-Browser Clients 658 The flow described in Section 3.1.3 requires a client to interact 659 with a server using a web browser. This will not work well in 660 situations where the client is automated or an end-user is using a 661 command line client such as curl [3] or wget [4]. This is a known 662 issue with OpenID Connect, and is typically addressed using a two- 663 step process: 665 1. Authenticate with the OP using a browser or browser-like client 666 and store the ID Token and Access Token locally. 668 2. Send a request to the content provider/RP along with the ID Token 669 and Access Token received from the OP. 671 The Access Token MAY be passed to the RP in an HTTP "Authorization" 672 header [RFC7235] or as a query parameter. The Access Token MUST be 673 specified using the "Bearer" authentication scheme [RFC6750] if it is 674 passed in an "Authorization" header. The ID Token MUST be passed to 675 the RP as a query parameter. 677 Here are two examples using the curl and wget utilities. Start by 678 authenticating with the OP: 680 https://example.com/rdap/tokens?id=user.idp.example 682 Save the token information and pass it to the RP along with the URI 683 representing the RDAP query. Using curl (encoded tokens have been 684 abbreviated for clarity: 686 curl -H "Authorization: Bearer eyJ0...NiJ9"\ 687 -k https://example.com/rdap/domain/example.com\ 688 ?id_token=eyJ0...EjXk 690 curl -k https://example.com/rdap/domain/example.com\ 691 ?id_token=eyJ0...EjXk&access_token=eyJ0...NiJ9 693 Using wget: 695 wget --header="Authorization: Bearer eyJ0...NiJ9"\ 696 https://example.com/rdap/domain/example.com\ 697 ?id_token=eyJ0...EjXk 699 wget https://example.com/rdap/domain/example.com\ 700 ?id_token=eyJ0...EjXk&access_token=eyJ0...NiJ9 702 Refresh tokens can be useful to automated or command line clients who 703 wish to continue a session without explicitly re-authenticating an 704 end user. See Section 4.3 for more information. 706 6. IANA Considerations 708 6.1. RDAP Extensions Registry 710 IANA is requested to register the following value in the RDAP 711 Extensions Registry: 713 Extension identifier: rdap_openidc 714 Registry operator: Any 715 Published specification: This document. 717 Contact: IESG 718 Intended usage: This extension includes response information 719 required for federated authentication using OpenID Connect. 721 6.2. JSON Web Token Claims Registry 723 IANA is requested to register the following value in the JSON Web 724 Token Claims Registry: 726 Claim Name: "purpose" 727 Claim Description: The stated purpose for submitting a request to 728 access a protected RDAP resource. 729 Change Controller: IESG 730 Specification Document(s): Section 3.1.4.1.1 of this document. 732 6.3. RDAP Query Purpose Registry 734 IANA is requested to create a new protocol registry to manage RDAP 735 query purpose values. This registry should appear under its own 736 heading on IANA's protocol listings, using the same title as the name 737 of the registry. The information to be registered and the procedures 738 to be followed in populating the registry are described in 739 Section 3.1.4.1.1. 741 Name of registry: Registration Data Access Protocol (RDAP) Query 742 Purpose Values 744 Section at http://www.iana.org/protocols: 746 Registry Title: Registration Data Access Protocol (RDAP) Query 747 Purpose Values 749 Registry Name: Registration Data Access Protocol (RDAP) Query Purpose 750 Values 752 Registration Procedure: Specification Required 754 Reference: This draft 756 Required information: See Section 3.1.4.1.1. 758 Review process: "Specification Required" as described in RFC 5226 759 [RFC5226]. 761 Size, format, and syntax of registry entries: See Section 3.1.4.1.1. 763 Initial assignments and reservations: 765 -----BEGIN FORM----- 766 Value: domainNameControl 767 Description: Tasks within the scope of this purpose include creating 768 and managing and monitoring a registrant's own domain name, including 769 creating the domain name, updating information about the domain name, 770 transferring the domain name, renewing the domain name, deleting the 771 domain name, maintaining a domain name portfolio, and detecting 772 fraudulent use of the Registrant's own contact information. 773 -----END FORM----- 775 -----BEGIN FORM----- 776 Value: personalDataProtection 777 Description: Tasks within the scope of this purpose include 778 identifying the accredited privacy/proxy provider associated with a 779 domain name and reporting abuse, requesting reveal, or otherwise 780 contacting the provider. 781 -----END FORM----- 783 -----BEGIN FORM----- 784 Value: technicalIssueResolution 785 Description: Tasks within the scope of this purpose include (but are 786 not limited to) working to resolve technical issues, including email 787 delivery issues, DNS resolution failures, and web site functional 788 issues. 789 -----END FORM----- 791 -----BEGIN FORM----- 792 Value: domainNameCertification 793 Description: Tasks within the scope of this purpose include a 794 Certification Authority (CA) issuing an X.509 certificate to a 795 subject identified by a domain name. 796 -----END FORM----- 798 -----BEGIN FORM----- 799 Value: individualInternetUse 800 Description: Tasks within the scope of this purpose include 801 identifying the organization using a domain name to instill consumer 802 trust, or contacting that organization to raise a customer complaint 803 to them or file a complaint about them. 804 -----END FORM----- 806 -----BEGIN FORM----- 807 Value: businessDomainNamePurchaseOrSale 808 Description: Tasks within the scope of this purpose include making 809 purchase queries about a domain name, acquiring a domain name from a 810 registrant, and enabling due diligence research. 811 -----END FORM----- 812 -----BEGIN FORM----- 813 Value: academicPublicInterestDNSRResearch 814 Description: Tasks within the scope of this purpose include academic 815 public interest research studies about domain names published in the 816 registration data service, including public information about the 817 registrant and designated contacts, the domain name's history and 818 status, and domain names registered by a given registrant (reverse 819 query). 820 -----END FORM----- 822 -----BEGIN FORM----- 823 Value: legalActions 824 Description: Tasks within the scope of this purpose include 825 investigating possible fraudulent use of a registrant's name or 826 address by other domain names, investigating possible trademark 827 infringement, contacting a registrant/licensee's legal representative 828 prior to taking legal action and then taking a legal action if the 829 concern is not satisfactorily addressed. 830 -----END FORM----- 832 -----BEGIN FORM----- 833 Value: regulatoryAndContractEnforcement 834 Description: Tasks within the scope of this purpose include tax 835 authority investigation of businesses with online presence, Uniform 836 Dispute Resolution Policy (UDRP) investigation, contractual 837 compliance investigation, and registration data escrow audits. 838 -----END FORM----- 840 -----BEGIN FORM----- 841 Value: criminalInvestigationAndDNSAbuseMitigation 842 Description: Tasks within the scope of this purpose include reporting 843 abuse to someone who can investigate and address that abuse, or 844 contacting entities associated with a domain name during an offline 845 criminal investigation. 846 -----END FORM----- 848 -----BEGIN FORM----- 849 Value: dnsTransparency 850 Description: Tasks within the scope of this purpose involve querying 851 the registration data made public by registrants to satisfy a wide 852 variety of use cases around informing the general public. 853 -----END FORM----- 855 7. Implementation Status 857 NOTE: Please remove this section and the reference to RFC 7942 prior 858 to publication as an RFC. 860 This section records the status of known implementations of the 861 protocol defined by this specification at the time of posting of this 862 Internet-Draft, and is based on a proposal described in RFC 7942 863 [RFC7942]. The description of implementations in this section is 864 intended to assist the IETF in its decision processes in progressing 865 drafts to RFCs. Please note that the listing of any individual 866 implementation here does not imply endorsement by the IETF. 867 Furthermore, no effort has been spent to verify the information 868 presented here that was supplied by IETF contributors. This is not 869 intended as, and must not be construed to be, a catalog of available 870 implementations or their features. Readers are advised to note that 871 other implementations may exist. 873 According to RFC 7942, "this will allow reviewers and working groups 874 to assign due consideration to documents that have the benefit of 875 running code, which may serve as evidence of valuable experimentation 876 and feedback that have made the implemented protocols more mature. 877 It is up to the individual working groups to use this information as 878 they see fit". 880 7.1. Verisign Labs 882 Responsible Organization: Verisign Labs 883 Location: https://rdap.verisignlabs.com/ 884 Description: This implementation includes support for domain 885 registry RDAP queries using live data from the .cc and .tv country 886 code top-level domains. Three access levels are provided based on 887 the authenticated identity of the client: 889 1. Unauthenticated: Limited information is returned in response 890 to queries from unauthenticated clients. 891 2. Basic: Clients who authenticate using a publicly available 892 identity provider like Google Gmail or Microsoft Hotmail will 893 receive all of the information available to an unauthenticated 894 client plus additional registration metadata, but no 895 personally identifiable information associated with entities. 896 3. Advanced: Clients who authenticate using a more restrictive 897 identity provider will receive all of the information 898 available to a Basic client plus whatever information the 899 server operator deems appropriate for a fully authorized 900 client. Currently supported identity providers include those 901 developed by Verisign Labs 902 (https://testprovider.rdap.verisignlabs.com/) and CZ.NIC 903 (https://www.mojeid.cz/). 904 Level of Maturity: This is a "proof of concept" research 905 implementation. 906 Coverage: This implementation includes all of the features 907 described in this specification. 909 Contact Information: Scott Hollenbeck, shollenbeck@verisign.com 911 8. Security Considerations 913 Security considerations for RDAP can be found in RFC 7481 [RFC7481]. 914 Security considerations for OpenID Connect Core [OIDCC] and OAuth 2.0 915 [RFC6749] can be found in their reference specifications. OpenID 916 Connect defines optional mechanisms for robust signing and encryption 917 that can be used to provide data integrity and data confidentiality 918 services as needed. Security services for ID Tokens and Access 919 Tokens (with references to the JWT specification) are described in 920 the OpenID Connect Core protocol. 922 8.1. Authentication and Access Control 924 Having completed the client identification, authorization, and 925 validation process, an RDAP server can make access control decisions 926 based on a comparison of client-provided information and local 927 policy. For example, a client who provides an email address (and 928 nothing more) might be entitled to receive a subset of the 929 information that would be available to a client who provides an email 930 address, a full name, and a stated purpose. Development of these 931 access control policies is beyond the scope of this document. 933 9. Acknowledgements 935 The author would like to acknowledge the following individuals for 936 their contributions to the development of this document: Tom 937 Harrison, Russ Housley, Rhys Smith, Jaromir Talir, and Alessandro 938 Vesely. In addition, the Verisign Registry Services Lab development 939 team of Andrew Kaizer, Sai Mogali, Anurag Saxena, Swapneel Sheth, 940 Nitin Singh, and Zhao Zhao provided critical "proof of concept" 941 implementation experience that helped demonstrate the validity of the 942 concepts described in this document. 944 10. References 946 10.1. Normative References 948 [OIDC] OpenID Foundation, "OpenID Connect", 949 . 951 [OIDCC] OpenID Foundation, "OpenID Connect Core incorporating 952 errata set 1", November 2014, 953 . 955 [OIDCD] OpenID Foundation, "OpenID Connect Discovery 1.0 956 incorporating errata set 1", November 2014, 957 . 960 [OIDCR] OpenID Foundation, "OpenID Connect Dynamic Client 961 Registration 1.0 incorporating errata set 1", November 962 2014, . 965 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 966 Requirement Levels", BCP 14, RFC 2119, 967 DOI 10.17487/RFC2119, March 1997, 968 . 970 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 971 Resource Identifier (URI): Generic Syntax", STD 66, 972 RFC 3986, DOI 10.17487/RFC3986, January 2005, 973 . 975 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 976 IANA Considerations Section in RFCs", RFC 5226, 977 DOI 10.17487/RFC5226, May 2008, 978 . 980 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 981 RFC 6749, DOI 10.17487/RFC6749, October 2012, 982 . 984 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 985 Framework: Bearer Token Usage", RFC 6750, 986 DOI 10.17487/RFC6750, October 2012, 987 . 989 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 990 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 991 August 2013, . 993 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 994 Protocol (HTTP/1.1): Message Syntax and Routing", 995 RFC 7230, DOI 10.17487/RFC7230, June 2014, 996 . 998 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 999 Protocol (HTTP/1.1): Authentication", RFC 7235, 1000 DOI 10.17487/RFC7235, June 2014, 1001 . 1003 [RFC7480] Newton, A., Ellacott, B., and N. Kong, "HTTP Usage in the 1004 Registration Data Access Protocol (RDAP)", RFC 7480, 1005 DOI 10.17487/RFC7480, March 2015, 1006 . 1008 [RFC7481] Hollenbeck, S. and N. Kong, "Security Services for the 1009 Registration Data Access Protocol (RDAP)", RFC 7481, 1010 DOI 10.17487/RFC7481, March 2015, 1011 . 1013 [RFC7482] Newton, A. and S. Hollenbeck, "Registration Data Access 1014 Protocol (RDAP) Query Format", RFC 7482, 1015 DOI 10.17487/RFC7482, March 2015, 1016 . 1018 [RFC7483] Newton, A. and S. Hollenbeck, "JSON Responses for the 1019 Registration Data Access Protocol (RDAP)", RFC 7483, 1020 DOI 10.17487/RFC7483, March 2015, 1021 . 1023 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1024 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 1025 2015, . 1027 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1028 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1029 . 1031 10.2. Informative References 1033 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 1034 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 1035 . 1037 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 1038 Code: The Implementation Status Section", BCP 205, 1039 RFC 7942, DOI 10.17487/RFC7942, July 2016, 1040 . 1042 10.3. URIs 1044 [1] http://openid.net/get-an-openid/ 1046 [2] https://www.icann.org/en/system/files/files/final-report- 1047 06jun14-en.pdf 1049 [3] http://curl.haxx.se/ 1051 [4] https://www.gnu.org/software/wget/ 1053 Appendix A. Change Log 1055 00: Initial version. 1056 01: Updated flow description (Section 3.1.2) and description of the 1057 registration process (Section 3.1.3). Thanks to Jaromir Talir. 1058 02: Updated flow description. 1059 03: Added description of query parameters and non-browser clients. 1060 Updated security considerations to note issues associated with 1061 access control. 1062 04: Updated references for JSON Web Token, OpenID Connect Core, and 1063 OpenID Connect Discovery. Added acknowledgement to the Verisign 1064 Labs developers. Changed intended status to Standards Track. 1065 Added text to describe protocol parameters and processing. Other 1066 minor edits. 1067 05: Added examples for curl and wget. Added a reference to RFC 1068 7235. 1069 00: Changed WG reference in file name from weirds to regext. 1070 Described support for refresh tokens. Editorial updates. 1071 Corrected several examples. Added registry of purpose values. 1072 01: Added Implementation Status section (Section 7). 1073 02: Updated section Section 4.4 to clarify ID Token validation 1074 requirements. 1075 03: Keepalive refresh. 1076 04: Added rdap_conformance. 1078 Author's Address 1080 Scott Hollenbeck 1081 Verisign Labs 1082 12061 Bluemont Way 1083 Reston, VA 20190 1084 USA 1086 Email: shollenbeck@verisign.com 1087 URI: http://www.verisignlabs.com/