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