idnits 2.17.1 draft-hollenbeck-regext-rdap-openid-07.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 (April 17, 2018) is 2199 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 1113 -- Looks like a reference, but probably isn't: '2' on line 1115 -- Looks like a reference, but probably isn't: '3' on line 1118 -- Looks like a reference, but probably isn't: '4' on line 1120 == Outdated reference: A later version (-15) exists of draft-ietf-oauth-device-flow-08 -- 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 (~~), 2 warnings (==), 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 April 17, 2018 5 Expires: October 19, 2018 7 Federated Authentication for the Registration Data Access Protocol 8 (RDAP) using OpenID Connect 9 draft-hollenbeck-regext-rdap-openid-07 11 Abstract 13 The Registration Data Access Protocol (RDAP) provides "RESTful" web 14 services to retrieve registration metadata from domain name and 15 regional internet registries. RDAP allows a server to make access 16 control decisions based on client identity, and as such it includes 17 support for client identification features provided by the Hypertext 18 Transfer Protocol (HTTP). Identification methods that require 19 clients to obtain and manage credentials from every RDAP server 20 operator present management challenges for both clients and servers, 21 whereas a federated authentication system would make it easier to 22 operate and use RDAP without the need to maintain server-specific 23 client credentials. This document describes a federated 24 authentication system for RDAP based on OpenID Connect. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at https://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on October 19, 2018. 43 Copyright Notice 45 Copyright (c) 2018 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 (https://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 Claims for RDAP . . . . . . . . . . . . . 8 76 3.1.4.1. Stated Purpose . . . . . . . . . . . . . . . . . 8 77 3.1.4.2. Do Not Track . . . . . . . . . . . . . . . . . . 9 78 4. Protocol Parameters . . . . . . . . . . . . . . . . . . . . . 9 79 4.1. Client Authentication Request and Response . . . . . . . 10 80 4.2. Token Request and Response . . . . . . . . . . . . . . . 10 81 4.3. Token Refresh and Revocation . . . . . . . . . . . . . . 11 82 4.4. Parameter Processing . . . . . . . . . . . . . . . . . . 14 83 4.5. RDAP Conformance . . . . . . . . . . . . . . . . . . . . 15 84 5. Clients with Limited User Interfaces . . . . . . . . . . . . 15 85 5.1. OAuth 2.0 Device Flow . . . . . . . . . . . . . . . . . . 15 86 5.2. Manual Token Management . . . . . . . . . . . . . . . . . 16 87 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 88 6.1. RDAP Extensions Registry . . . . . . . . . . . . . . . . 17 89 6.2. JSON Web Token Claims Registry . . . . . . . . . . . . . 17 90 6.3. RDAP Query Purpose Registry . . . . . . . . . . . . . . . 17 91 7. Implementation Status . . . . . . . . . . . . . . . . . . . . 20 92 7.1. Verisign Labs . . . . . . . . . . . . . . . . . . . . . . 20 93 8. Security Considerations . . . . . . . . . . . . . . . . . . . 21 94 8.1. Authentication and Access Control . . . . . . . . . . . . 21 95 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 22 96 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 22 97 10.1. Normative References . . . . . . . . . . . . . . . . . . 22 98 10.2. Informative References . . . . . . . . . . . . . . . . . 24 99 10.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 24 100 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 24 101 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 25 103 1. Introduction 105 The Registration Data Access Protocol (RDAP) provides "RESTful" web 106 services to retrieve registration metadata from domain name and 107 regional internet registries. RDAP allows a server to make access 108 control decisions based on client identity, and as such it includes 109 support for client identification features provided by the Hypertext 110 Transfer Protocol (HTTP) [RFC7230]. 112 RDAP is specified in multiple documents, including "HTTP Usage in the 113 Registration Data Access Protocol (RDAP)" [RFC7480], "Security 114 Services for the Registration Data Access Protocol (RDAP)" [RFC7481], 115 "Registration Data Access Protocol Query Format" [RFC7482], and "JSON 116 Responses for the Registration Data Access Protocol (RDAP)" 117 [RFC7483]. RFC 7481 describes client identification and 118 authentication services that can be used with RDAP, but it does not 119 specify how any of these services can (or should) be used with RDAP. 121 1.1. Problem Statement 123 The traditional "user name and password" authentication method does 124 not scale well in the RDAP ecosystem. Assuming that all domain name 125 and address registries will eventually provide RDAP service, it is 126 impractical and inefficient for users to secure login credentials 127 from the hundreds of different server operators. Authentication 128 methods based on user names and passwords do not provide information 129 that describes the user in sufficient detail (while protecting the 130 personal privacy of the user) for server operators to make fine- 131 grained access control decisions based on the user's identity. The 132 authentication system used for RDAP needs to address all of these 133 needs. 135 1.2. Proposal 137 A basic level of RDAP service can be provided to users who possess an 138 identifier issued by a recognized provider who is able to 139 authenticate and validate the user. The identifiers issued by social 140 media services, for example, can be used. Users who require higher 141 levels of service (and who are willing to share more information 142 about them self to gain access to that service) can secure 143 identifiers from specialized providers who are or will be able to 144 provide more detailed information about the user. Server operators 145 can then make access control decisions based on the identification 146 information provided by the user. 148 A federated authentication system would make it easier to operate and 149 use RDAP by re-using existing identifiers to provide a basic level of 150 access. It can also provide the ability to collect additional user 151 identification information, and that information can be shared with 152 the consent of the user. This document describes a federated 153 authentication system for RDAP based on OpenID Connect [OIDC] that 154 meets all of these needs. 156 2. Conventions Used in This Document 158 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 159 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 160 "OPTIONAL" in this document are to be interpreted as described in BCP 161 14 [RFC2119] [RFC8174] when, and only when, they appear in all 162 capitals, as shown here. 164 3. Federated Authentication for RDAP 166 RDAP itself does not include native security services. Instead, RDAP 167 relies on features that are available in other protocol layers to 168 provide needed security services including access control, 169 authentication, authorization, availability, data confidentiality, 170 data integrity, and identification. A description of each of these 171 security services can be found in "Internet Security Glossary, 172 Version 2" [RFC4949]. This document focuses on a federated 173 authentication system for RDAP that provides services for 174 authentication, authorization, and identification, allowing a server 175 operator to make access control decisions. Section 3 of RFC 7481 176 [RFC7481] describes general considerations for RDAP access control, 177 authentication, and authorization. 179 The traditional client-server authentication model requires clients 180 to maintain distinct credentials for every RDAP server. This 181 situation can become unwieldy as the number of RDAP servers 182 increases. Federated authentication mechanisms allow clients to use 183 one credential to access multiple RDAP servers and reduce client 184 credential management complexity. 186 3.1. RDAP and OpenID Connect 188 OpenID Connect 1.0 [OIDCC] is a decentralized, single sign-on (SSO) 189 federated authentication system that allows users to access multiple 190 web resources with one identifier instead of having to create 191 multiple server-specific identifiers. Users acquire identifiers from 192 OpenID Providers, or OPs. Relying Parties, or RPs, are applications 193 (such as RDAP) that outsource their user authentication function to 194 an OP. OpenID Connect is built on top of the authorization framework 195 provided by the OAuth 2.0 [RFC6749] protocol. 197 The OAuth authorization framework describes a method for users to 198 access protected web resources without having to hand out their 199 credentials. Instead, clients are issued Access Tokens by 200 authorization servers with the permission of the resource owners. 201 Using OpenID Connect and OAuth, multiple RDAP servers can form a 202 federation and clients can access any server in the federation by 203 providing one credential registered with any OP in that federation. 204 The OAuth authorization framework is designed for use with HTTP and 205 thus can be used with RDAP. 207 3.1.1. Terminology 209 This document uses the terms "client" and "server" defined by RDAP 210 [RFC7480]. An RDAP client performs the role of an OpenID Connect 211 Core [OIDCC] Entity or End-User. An RDAP server performs the role of 212 an OpenID Connect Core Relying Party (RP). Additional terms from 213 Section 1.2 of the OpenID Connect Core specification are incorporated 214 by reference. 216 3.1.2. Overview 218 At a high level, RDAP authentication of a browser-based client using 219 OpenID Connect requires completion of the following steps: 221 1. An RDAP client (acting as an OpenID End-User) sends an HTTP (or 222 HTTPS) query containing OAuth 2.0 request parameters to an RDAP 223 server. 224 2. The RDAP server (acting as an OpenID Relying Party (RP)) prepares 225 an Authentication Request containing the desired request 226 parameters. 227 3. The RDAP server sends the RDAP client and Authentication Request 228 to an Authorization Server operated by an OpenID Provider (OP) 229 using an HTTP redirect. 230 4. The Authorization Server authenticates the RDAP Client. 231 5. The Authorization Server obtains RDAP Client consent/ 232 authorization. 233 6. The Authorization Server sends the RDAP Client back to the RDAP 234 server with an Authorization Code using an HTTP redirect. 235 7. The RDAP server requests a response using the Authorization Code 236 at the Token Endpoint. 237 8. The RDAP server receives a response that contains an ID Token and 238 Access Token in the response body. 240 9. The RDAP server validates the ID Token and retrieves the RDAP 241 client's Subject Identifier. 243 The RDAP server can then make identification, authorization, and 244 access control decisions based on local policies, the ID Token 245 received from the OP, and the received Claims. Note that OpenID 246 Connect describes different process flows for other types of clients, 247 such as script-based or command line clients. 249 3.1.3. RDAP Authentication and Authorization Steps 251 End-Users MUST possess an identifier (an OpenID) issued by an OP to 252 use OpenID Connect with RDAP. The OpenID Foundation maintains a list 253 of OPs on its web site [1]. Additional OPs are almost certainly 254 needed to fully realize the potential for federated authentication 255 with RDAP because RDAP has authorization and access control 256 requirements that go beyond the end-user authentication requirements 257 of a typical web site. 259 OpenID Connect requires RPs to register with OPs to use OpenID 260 Connect services for an End-User. That process is described by the 261 "OpenID Connect Dynamic Client Registration" protocol [OIDCR]. 263 3.1.3.1. Provider Discovery 265 An RDAP server/RP needs to receive an identifier from an End-User 266 that can be used to discover the End-User's OP. That process is 267 required and is documented in the "OpenID Connect Discovery" protocol 268 [OIDCD]. 270 3.1.3.2. Authentication Request 272 Once the OP is known, an RP MUST form an Authentication Request and 273 send it to the OP as described in Section 3 of the OpenID Connect 274 Core protocol [OIDCC]. The authentication path followed 275 (authorization, implicit, or hybrid) will depend on the 276 Authentication Request response_type set by the RP. The remainder of 277 the processing steps described here assume that the Authorization 278 Code Flow is being used by setting "response_type=code" in the 279 Authentication Request. 281 The benefits of using the Authorization Code Flow for authenticating 282 a human user are described in Section 3.1 of the OpenID Connect Core 283 protocol. The Implicit Flow is more commonly used by clients 284 implemented in a web browser using a scripting language; it is 285 described in Section 3.2 of the OpenID Connect Core protocol. The 286 Hybrid Flow (described in Section 3.3 of the OpenID Connect Core 287 protocol) combines elements of the Authorization and Implicit Flows 288 by returning some tokens from the Authorization Endpoint and others 289 from the Token Endpoint. 291 An Authentication Request can contain several parameters. REQUIRED 292 parameters are specified in Section 3.1.2.1 of the OpenID Connect 293 Core protocol [OIDCC]. Other parameters MAY be included. 295 The OP receives the Authentication Request and attempts to validate 296 it as described in Section 3.1.2.2 of the OpenID Connect Core 297 protocol [OIDCC]. If the request is valid, the OP attempts to 298 authenticate the End-User as described in Section 3.1.2.3 of the 299 OpenID Connect Core protocol [OIDCC]. The OP returns an error 300 response if the request is not valid or if any error is encountered. 302 3.1.3.3. End-User Authorization 304 After the End-User is authenticated, the OP MUST obtain authorization 305 information from the End-User before releasing information to the 306 RDAP Server/RP. This process is described in Section 3.1.2.4 of the 307 OpenID Connect Core protocol [OIDCC]. 309 3.1.3.4. Authorization Response and Validation 311 After the End-User is authenticated, the OP will send a response to 312 the RP that describes the result of the authorization process in the 313 form of an Authorization Grant. The RP MUST validate the response. 314 This process is described in Sections 3.1.2.5 - 3.1.2.7 of the OpenID 315 Connect Core protocol [OIDCC]. 317 3.1.3.5. Token Processing 319 The RP sends a Token Request using the Authorization Grant to a Token 320 Endpoint to obtain a Token Response containing an Access Token, ID 321 Token, and an OPTIONAL Refresh Token. The RP MUST validate the Token 322 Response. This process is described in Section 3.1.3 of the OpenID 323 Connect Core protocol [OIDCC]. 325 3.1.3.6. Delivery of User Information 327 The set of Claims can be retrieved by sending a request to a UserInfo 328 Endpoint using the Access Token. The Claims MAY be returned in the 329 ID Token. The process of retrieving Claims from a UserInfo Endpoint 330 is described in Section 5.3 of the OpenID Connect Core protocol 331 [OIDCC]. 333 OpenID Connect specified a set of standard Claims in Section 5.1. 334 Additional Claims for RDAP are described in Section 3.1.4. 336 3.1.4. Specialized Claims for RDAP 338 OpenID Connect claims are pieces of information used to make 339 assertions about an entity. Section 5 of the OpenID Connect Core 340 protocol [OIDCC] describes a set of standard claims that can be used 341 to identify a person. Section 5.1.2 notes that additional claims MAY 342 be used, and it describes a method to create them. 344 3.1.4.1. Stated Purpose 346 There are communities of RDAP users and operators who wish to make 347 and validate claims about a user's "need to know" when it comes to 348 requesting access to a resource. For example, a law enforcement 349 agent or a trademark attorney may wish to be able to assert that they 350 have a legal right to access a protected resource, and a server 351 operator will need to be able to receive and validate that claim. 352 These needs can be met by defining and using an additional "purpose" 353 claim. 355 The "purpose" claim identifies the purpose for which access to a 356 protected resource is being requested. Use of the "purpose" claim is 357 OPTIONAL; processing of this claim is subject to server acceptance of 358 the purpose and successful authentication of the End-User. 359 Unrecognized purpose values MUST be ignored and the associated query 360 MUST be processed as if the unrecognized purpose value was not 361 present at all. 363 The "purpose" value is a case-sensitive string containing a 364 StringOrURI value as specified in Section 2 of the JSON Web Token 365 (JWT) specification ([RFC7519]). An example: 367 {"purpose" : "domainNameControl"} 369 Purpose values are themselves registered with IANA. Each entry in 370 the registry contains the following fields: 372 Value: the purpose string value being registered. Value strings can 373 contain upper case characters from "A" to "Z", lower case ASCII 374 characters from "a" to "z", and the underscore ("_") character. 375 Value strings contain at least one character and no more than 64 376 characters. 378 Description: a one- or two-sentence description of the meaning of the 379 purpose value, how it might be used, and/or how it should be 380 interpreted by clients and servers. 382 This registry is operated under the "Specification Required" policy 383 defined in RFC 5226 ([RFC5226]). The set of initial values used to 384 populate the registry as described in Section 6.3 are taken from the 385 final report [2] produced by the Expert Working Group on gTLD 386 Directory Services chartered by the Internet Corporation for Assigned 387 Names and Numbers (ICANN). 389 3.1.4.2. Do Not Track 391 There are also communities of RDAP users and operators who wish to 392 make and validate claims about a user's wish to not have their 393 queries logged, tracked, or recorded. For example, a law enforcement 394 agent may wish to be able to assert that their queries are part of a 395 criminal investigation and should not be tracked due to a risk of 396 query exposure compromising the investigation, and a server operator 397 will need to be able to receive and validate that claim. These needs 398 can be met by defining and using an additional "do not track" claim. 400 The "do not track" ("dnt") claim can be used to identify an End-User 401 that is authorized to perform queries without the End-User's 402 association with those queries being logged, tracked, or recorded by 403 the server. Client use of the "dnt" claim is OPTIONAL. Server 404 operators MUST NOT log, track, or record any association of the query 405 and the End-User's identity if the End-User is successfully 406 identified and authorized, the "dnt" claim is present, and the value 407 of the claim is "true". 409 The "dnt" value is a case-sensitive string containing a JSON boolean 410 value. An example: 412 {"dnt" : "true"} 414 No special query tracking processing is required if this claim is not 415 present or if the value of the claim is "false". Use of this claim 416 MUST be limited to End-Users who are granted "do not track" 417 priviliges in accordance with service policies and regulations. 418 Specification of these policies and regulations is beyond the scope 419 of this document. 421 4. Protocol Parameters 423 This specification adds the following protocol parameters to RDAP: 425 1. A query parameter to request authentication for a specific end- 426 user identity. 427 2. A path segment to request an ID Token and an Access Token for a 428 specific end-user identity. 429 3. A query parameter to deliver an ID Token and an Access Token for 430 use with an RDAP query. 432 4.1. Client Authentication Request and Response 434 Client authentication is requested by adding a query component to an 435 RDAP request URI using the syntax described in Section 3.4 of RFC 436 3986 [RFC3986]. The query used to request client authentication is 437 represented as a "key=value" pair using a key value of "id" and a 438 value component that contains the client identifier issued by an OP. 439 An example: 441 https://example.com/rdap/domain/example.com?id=user.idp.example 443 The response to an authenticated query MUST use the response 444 structures specified in RFC 7483 [RFC7483]. Information that the 445 end-user is not authorized to receive MUST be omitted from the 446 response. 448 4.2. Token Request and Response 450 Clients MAY send a request to an RDAP server to authenticate an end- 451 user and return an ID Token and an Access Token from an OP that can 452 be then be passed to the RP/RDAP server to authenticate and process 453 subsequent queries. Identity provider authentication is requested 454 using a "tokens" path segment and a query parameter with key value of 455 "id" and a value component that contains the client identifier issued 456 by an OP. An example: 458 https://example.com/rdap/tokens?id=user.idp.example 460 In addition to any core RDAP response elements, the response to this 461 query MUST contain four name-value pairs, in any order, representing 462 the returned ID Token and Access Token. The ID Token is represented 463 using a key value of "id_token". The Access Token is represented 464 using a key value of "access_token". The access token type is 465 represented using a key value of "token_type" and a value of "bearer" 466 as described in Sections 4.2.2 and 7.1 of RFC 6749 [RFC6749]. The 467 lifetime of the access token is represented using a key value of 468 "expires_in" and a numerical value that describes the lifetime in 469 seconds of the access token as described in Section 4.2.2 of RFC 6749 470 [RFC6749]. The token values returned in the RDAP server response 471 MUST be Base64url encoded as described in RFCs 7515 [RFC7515] and 472 7519 [RFC7519]. 474 An example (the encoded tokens have been abbreviated for clarity): 476 { 477 "access_token" : "eyJ0...NiJ9", 478 "id_token" : "eyJ0...EjXk", 479 "token_type" : "bearer", 480 "expires_in" : "3600" 481 } 483 Figure 1 485 An RDAP server that processes this type of query MUST determine if 486 the identifier is associated with an OP that is recognized and 487 supported by the server. Servers MUST reject queries that include an 488 identifier associated with an unsupported OP with an HTTP 501 (Not 489 Implemented) response. An RDAP server that receives a query 490 containing an identifier associated with a recognized OP MUST perform 491 the steps required to authenticate the user with the OP using a 492 browser or browser-like client and return encoded tokens to the 493 client. Note that tokens are typically valid for a limited period of 494 time and new tokens will be required when an existing token's 495 validity period has expired. 497 The tokens can then be passed to the server for use with an RDAP 498 query using a query parameter with key values of "id_token" and 499 "access_token" and values that represent the encoded tokens. An 500 example (the encoded tokens have been abbreviated and the URI split 501 across multiple lines for clarity): 503 https://example.com/rdap/domain/example.com 504 ?id_token=eyJ0...EjXk 505 &access_token=eyJ0...NiJ9 507 The response to an authenticated query MUST use the response 508 structures specified in RFC 7483 [RFC7483]. Information that the 509 end-user is not authorized to receive MUST be omitted from the 510 response. 512 4.3. Token Refresh and Revocation 514 An access token can be refreshed as described in Section 12 of the 515 OpenID Connect Core protocol [OIDCC] and Section 6 of OAuth 2.0 516 [RFC6749]. Clients can take advantage of this functionality if it is 517 supported by the OP and accepted by the RDAP server. 519 A refresh token is requested using a "tokens" path segment and two 520 query parameters. The first query parameter includes a key value of 521 "id" and a value component that contains the client identifier issued 522 by an OP. The second query parameter includes a key value of 523 "refresh" and a value component of "true". A value component of 524 "false" MUST be processed to return a result that is consistent with 525 not including a "refresh" parameter at all as described in 526 Section 4.2. An example using "refresh=true": 528 https://example.com/rdap/tokens?id=user.idp.example 529 &refresh=true 531 The response to this query MUST contain all of the response elements 532 described in Section 4.2. In addition, the response MUST contain a 533 name-value pair that represents a refresh token. The name-value pair 534 includes a key value of "refresh_token" and a Base64url-encoded value 535 that represents the refresh token. 537 Example refresh token request response (the encoded tokens have been 538 abbreviated for clarity): 540 { 541 "access_token" : "eyJ0...NiJ9", 542 "id_token" : "eyJ0...EjXk", 543 "token_type" : "bearer", 544 "expires_in" : "3600", 545 "refresh_token" : "eyJ0...c8da" 546 } 548 Figure 2 550 Once acquired, a refresh token can be used to refresh an access 551 token. An access token is refreshed using a "tokens" path segment 552 and two query parameters. The first query parameter includes a key 553 value of "id" and a value component that contains the client 554 identifier issued by an OP. The second query parameter includes a 555 key value of "refresh_token" and a Base64url-encoded value that 556 represents the refresh token. An example: 558 https://example.com/rdap/tokens?id=user.idp.example 559 &refresh_token=eyJ0...f3jE 561 In addition to any core RDAP response elements, the response to this 562 query MUST contain four name-value pairs, in any order, representing 563 a returned Refresh Token and Access Token. The Refresh Token is 564 represented using a key value of "refresh_token". The Access Token 565 is represented using a key value of "access_token". The access token 566 type is represented using a key value of "token_type" and a value of 567 "bearer" as described in Sections 4.2.2 and 7.1 of RFC 6749 568 [RFC6749]. The lifetime of the access token is represented using a 569 key value of "expires_in" and a numerical value that describes the 570 lifetime in seconds of the access token as described in Section 4.2.2 571 of RFC 6749 [RFC6749]. The token values returned in the RDAP server 572 response MUST be Base64url encoded as described in RFCs 7515 573 [RFC7515] and 7519 [RFC7519]. 575 Example access token refresh response (the encoded tokens have been 576 abbreviated for clarity): 578 { 579 "access_token" : "0dac...13b0", 580 "refresh_token" : "f735...d30c", 581 "token_type" : "bearer", 582 "expires_in" : "3600" 583 } 585 Figure 3 587 Access and refresh tokens can be revoked as described in RFC 7009 588 [RFC7009] by sending a request to an RDAP server that contains a 589 "tokens/revoke" path segment and two query parameters. The first 590 query parameter includes a key value of "id" and a value component 591 that contains the client identifier issued by an OP. The second 592 query parameter includes a key value of "token" and a Base64url- 593 encoded value that represents either the current refresh token or the 594 associated access token. An example: 596 https://example.com/rdap/tokens/revoke?id=user.idp.example 597 &token=f735...d30c 599 Note that this command will revoke both access and refresh tokens at 600 the same time. In addition to any core RDAP response elements, the 601 response to this query MUST contain a description of the result of 602 processing the revocation request within the RDAP "notices" data 603 structure. 605 Example token revocation success: 607 "notices" : 608 [ 609 { 610 "title" : "Token Revocation Result", 611 "description" : "Token revocation succeeded.", 612 } 613 ], 614 "lang" : "en-US" 616 Figure 4 618 Example token revocation failure: 620 "notices" : 621 [ 622 { 623 "title" : "Token Revocation Result", 624 "description" : "Token revocation failed.", 625 } 626 ], 627 "errorCode" : 400, 628 "lang" : "en-US" 630 Figure 5 632 4.4. Parameter Processing 634 Unrecognized query parameters MUST be ignored. An RDAP request that 635 does not include an "id" query component MUST be processed as an 636 unauthenticated query. An RDAP server that processes an 637 authenticated query MUST determine if the identifier is associated 638 with an OP that is recognized and supported by the server. Servers 639 MUST reject queries that include an identifier associated with an 640 unsupported OP with an HTTP 501 (Not Implemented) response. An RDAP 641 server that receives a query containing an identifier associated with 642 a recognized OP MUST perform the steps required to authenticate the 643 user with the OP, process the query, and return an RDAP response that 644 is appropriate for the end user's level of authorization and access. 646 An RDAP server that receives a query containing tokens associated 647 with a recognized OP and authenticated end user MUST process the 648 query and return an RDAP response that is appropriate for the end 649 user's level of authorization and access. Errors based on processing 650 either the ID Token or the Access Token MUST be signaled with an 651 appropriate HTTP status code as described in Section 3.1 of RFC 6750 652 [RFC6750]. 654 On receiving a query containing tokens, the RDAP server MUST validate 655 the ID Token. It can do this independently of the OP, because the ID 656 Token is a JWT that contains all the data necessary for validation. 657 The Access Token, however, is an opaque value, and can only be 658 validated by sending a request using it to the UserInfo Endpoint and 659 confirming that a successful response is received. This is different 660 from the OpenID Connect Authorization Code and Implicit flows, where 661 the Access Token can be validated against the at_hash claim from the 662 ID Token. With a query containing tokens, the Access Token might not 663 validate against the at_hash claim because the Access Token may have 664 been refreshed since the ID Token was issued. 666 An RDAP server that processes requests without needing the UserInfo 667 claims does not need to retrieve the claims merely in order to 668 validate the Access Token. Similarly, an RDAP server that has cached 669 the UserInfo claims for an end user, in accordance with the HTTP 670 headers of a previous UserInfo Endpoint response, does not need to 671 retrieve those claims again in order to revalidate the Access Token. 673 4.5. RDAP Conformance 675 RDAP responses that contain values described in this document MUST 676 indicate conformance with this specification by including an 677 rdapConformance ([RFC7483]) value of "rdap_openidc_level_0". The 678 information needed to register this value in the RDAP Extensions 679 Registry is described in Section 6.1. 681 Example rdapConformance structure with extension specified: 683 "rdapConformance" : 684 [ 685 "rdap_level_0", 686 "rdap_openidc_level_0" 687 ] 689 Figure 6 691 5. Clients with Limited User Interfaces 693 The flow described in Section 3.1.3 requires a client to interact 694 with a server using a web browser. This will not work well in 695 situations where the client is automated or an end-user is using a 696 command line user interface such as curl [3] or wget [4]. There are 697 multiple ways to address this limitation using a web browser on a 698 second device. Two are described here. 700 5.1. OAuth 2.0 Device Flow 702 The "OAuth 2.0 Device Flow for Browserless and Input Constrained 703 Devices" [I-D.ietf-oauth-device-flow] provides one method to request 704 user authorization from devices that have an Internet connection, but 705 lack a suitable browser for a more traditional OAuth flow. This 706 method requires a client to use a second device (such as a smart 707 telephone) that has access to a web browser for entry of a code 708 sequence that is presented on the constrained device. 710 5.2. Manual Token Management 712 A second method of requesting user authorization from a constrained 713 device is possible by producing and managing tokens manually as 714 follows: 716 1. Authenticate with the OP as described in Section 4.2 using a 717 browser or browser-like client. 718 2. Store the returned ID Token and Access Token locally. 719 3. Send a request to the content provider/RP along with the ID Token 720 and Access Token received from the OP. 722 The Access Token MAY be passed to the RP in an HTTP "Authorization" 723 header [RFC7235] or as a query parameter. The Access Token MUST be 724 specified using the "Bearer" authentication scheme [RFC6750] if it is 725 passed in an "Authorization" header. The ID Token MUST be passed to 726 the RP as a query parameter. 728 Here are two examples using the curl and wget utilities. Start by 729 authenticating with the OP: 731 https://example.com/rdap/tokens?id=user.idp.example 733 Save the token information and pass it to the RP along with the URI 734 representing the RDAP query. Using curl (encoded tokens have been 735 abbreviated for clarity: 737 curl -H "Authorization: Bearer eyJ0...NiJ9"\ 738 -k https://example.com/rdap/domain/example.com\ 739 ?id_token=eyJ0...EjXk 741 curl -k https://example.com/rdap/domain/example.com\ 742 ?id_token=eyJ0...EjXk&access_token=eyJ0...NiJ9 744 Using wget: 746 wget --header="Authorization: Bearer eyJ0...NiJ9"\ 747 https://example.com/rdap/domain/example.com\ 748 ?id_token=eyJ0...EjXk 750 wget https://example.com/rdap/domain/example.com\ 751 ?id_token=eyJ0...EjXk&access_token=eyJ0...NiJ9 753 Refresh tokens can be useful to automated or command line clients who 754 wish to continue a session without explicitly re-authenticating an 755 end user. See Section 4.3 for more information. 757 6. IANA Considerations 759 6.1. RDAP Extensions Registry 761 IANA is requested to register the following value in the RDAP 762 Extensions Registry: 764 Extension identifier: rdap_openidc 765 Registry operator: Any 766 Published specification: This document. 767 Contact: IESG 768 Intended usage: This extension includes response information 769 required for federated authentication using OpenID Connect. 771 6.2. JSON Web Token Claims Registry 773 IANA is requested to register the following values in the JSON Web 774 Token Claims Registry: 776 Claim Name: "purpose" 777 Claim Description: This claim describes the stated purpose for 778 submitting a request to access a protected RDAP resource. 779 Change Controller: IESG 780 Specification Document(s): Section 3.1.4.1 of this document. 782 Claim Name: "dnt" 783 Claim Description: This claim contains a boolean value that 784 describes an End-User's "do not track" preference for identity 785 tracking, logging, or recording when accessing a protected RDAP 786 resource. 787 Change Controller: IESG 788 Specification Document(s): Section 3.1.4.2 of this document. 790 6.3. RDAP Query Purpose Registry 792 IANA is requested to create a new protocol registry to manage RDAP 793 query purpose values. This registry should appear under its own 794 heading on IANA's protocol listings, using the same title as the name 795 of the registry. The information to be registered and the procedures 796 to be followed in populating the registry are described in 797 Section 3.1.4.1. 799 Name of registry: Registration Data Access Protocol (RDAP) Query 800 Purpose Values 802 Section at http://www.iana.org/protocols: 804 Registry Title: Registration Data Access Protocol (RDAP) Query 805 Purpose Values 807 Registry Name: Registration Data Access Protocol (RDAP) Query Purpose 808 Values 810 Registration Procedure: Specification Required 812 Reference: This draft 814 Required information: See Section 3.1.4.1. 816 Review process: "Specification Required" as described in RFC 5226 817 [RFC5226]. 819 Size, format, and syntax of registry entries: See Section 3.1.4.1. 821 Initial assignments and reservations: 823 -----BEGIN FORM----- 824 Value: domainNameControl 825 Description: Tasks within the scope of this purpose include creating 826 and managing and monitoring a registrant's own domain name, including 827 creating the domain name, updating information about the domain name, 828 transferring the domain name, renewing the domain name, deleting the 829 domain name, maintaining a domain name portfolio, and detecting 830 fraudulent use of the Registrant's own contact information. 831 -----END FORM----- 833 -----BEGIN FORM----- 834 Value: personalDataProtection 835 Description: Tasks within the scope of this purpose include 836 identifying the accredited privacy/proxy provider associated with a 837 domain name and reporting abuse, requesting reveal, or otherwise 838 contacting the provider. 839 -----END FORM----- 841 -----BEGIN FORM----- 842 Value: technicalIssueResolution 843 Description: Tasks within the scope of this purpose include (but are 844 not limited to) working to resolve technical issues, including email 845 delivery issues, DNS resolution failures, and web site functional 846 issues. 847 -----END FORM----- 849 -----BEGIN FORM----- 850 Value: domainNameCertification 851 Description: Tasks within the scope of this purpose include a 852 Certification Authority (CA) issuing an X.509 certificate to a 853 subject identified by a domain name. 854 -----END FORM----- 856 -----BEGIN FORM----- 857 Value: individualInternetUse 858 Description: Tasks within the scope of this purpose include 859 identifying the organization using a domain name to instill consumer 860 trust, or contacting that organization to raise a customer complaint 861 to them or file a complaint about them. 862 -----END FORM----- 864 -----BEGIN FORM----- 865 Value: businessDomainNamePurchaseOrSale 866 Description: Tasks within the scope of this purpose include making 867 purchase queries about a domain name, acquiring a domain name from a 868 registrant, and enabling due diligence research. 869 -----END FORM----- 871 -----BEGIN FORM----- 872 Value: academicPublicInterestDNSRResearch 873 Description: Tasks within the scope of this purpose include academic 874 public interest research studies about domain names published in the 875 registration data service, including public information about the 876 registrant and designated contacts, the domain name's history and 877 status, and domain names registered by a given registrant (reverse 878 query). 879 -----END FORM----- 881 -----BEGIN FORM----- 882 Value: legalActions 883 Description: Tasks within the scope of this purpose include 884 investigating possible fraudulent use of a registrant's name or 885 address by other domain names, investigating possible trademark 886 infringement, contacting a registrant/licensee's legal representative 887 prior to taking legal action and then taking a legal action if the 888 concern is not satisfactorily addressed. 889 -----END FORM----- 891 -----BEGIN FORM----- 892 Value: regulatoryAndContractEnforcement 893 Description: Tasks within the scope of this purpose include tax 894 authority investigation of businesses with online presence, Uniform 895 Dispute Resolution Policy (UDRP) investigation, contractual 896 compliance investigation, and registration data escrow audits. 897 -----END FORM----- 898 -----BEGIN FORM----- 899 Value: criminalInvestigationAndDNSAbuseMitigation 900 Description: Tasks within the scope of this purpose include reporting 901 abuse to someone who can investigate and address that abuse, or 902 contacting entities associated with a domain name during an offline 903 criminal investigation. 904 -----END FORM----- 906 -----BEGIN FORM----- 907 Value: dnsTransparency 908 Description: Tasks within the scope of this purpose involve querying 909 the registration data made public by registrants to satisfy a wide 910 variety of use cases around informing the general public. 911 -----END FORM----- 913 7. Implementation Status 915 NOTE: Please remove this section and the reference to RFC 7942 prior 916 to publication as an RFC. 918 This section records the status of known implementations of the 919 protocol defined by this specification at the time of posting of this 920 Internet-Draft, and is based on a proposal described in RFC 7942 921 [RFC7942]. The description of implementations in this section is 922 intended to assist the IETF in its decision processes in progressing 923 drafts to RFCs. Please note that the listing of any individual 924 implementation here does not imply endorsement by the IETF. 925 Furthermore, no effort has been spent to verify the information 926 presented here that was supplied by IETF contributors. This is not 927 intended as, and must not be construed to be, a catalog of available 928 implementations or their features. Readers are advised to note that 929 other implementations may exist. 931 According to RFC 7942, "this will allow reviewers and working groups 932 to assign due consideration to documents that have the benefit of 933 running code, which may serve as evidence of valuable experimentation 934 and feedback that have made the implemented protocols more mature. 935 It is up to the individual working groups to use this information as 936 they see fit". 938 7.1. Verisign Labs 940 Responsible Organization: Verisign Labs 941 Location: https://rdap.verisignlabs.com/ 942 Description: This implementation includes support for domain 943 registry RDAP queries using live data from the .cc and .tv country 944 code top-level domains and the .career generic top-level domain. 946 Three access levels are provided based on the authenticated 947 identity of the client: 949 1. Unauthenticated: Limited information is returned in response 950 to queries from unauthenticated clients. 951 2. Basic: Clients who authenticate using a publicly available 952 identity provider like Google Gmail or Microsoft Hotmail will 953 receive all of the information available to an unauthenticated 954 client plus additional registration metadata, but no 955 personally identifiable information associated with entities. 956 3. Advanced: Clients who authenticate using a more restrictive 957 identity provider will receive all of the information 958 available to a Basic client plus whatever information the 959 server operator deems appropriate for a fully authorized 960 client. Currently supported identity providers include those 961 developed by Verisign Labs 962 (https://testprovider.rdap.verisignlabs.com/) and CZ.NIC 963 (https://www.mojeid.cz/). 964 Level of Maturity: This is a "proof of concept" research 965 implementation. 966 Coverage: This implementation includes all of the features 967 described in this specification. 968 Contact Information: Scott Hollenbeck, shollenbeck@verisign.com 970 8. Security Considerations 972 Security considerations for RDAP can be found in RFC 7481 [RFC7481]. 973 Security considerations for OpenID Connect Core [OIDCC] and OAuth 2.0 974 [RFC6749] can be found in their reference specifications. OpenID 975 Connect defines optional mechanisms for robust signing and encryption 976 that can be used to provide data integrity and data confidentiality 977 services as needed. Security services for ID Tokens and Access 978 Tokens (with references to the JWT specification) are described in 979 the OpenID Connect Core protocol. 981 8.1. Authentication and Access Control 983 Having completed the client identification, authorization, and 984 validation process, an RDAP server can make access control decisions 985 based on a comparison of client-provided information and local 986 policy. For example, a client who provides an email address (and 987 nothing more) might be entitled to receive a subset of the 988 information that would be available to a client who provides an email 989 address, a full name, and a stated purpose. Development of these 990 access control policies is beyond the scope of this document. 992 9. Acknowledgements 994 The author would like to acknowledge the following individuals for 995 their contributions to the development of this document: Tom 996 Harrison, Russ Housley, Rhys Smith, Jaromir Talir, and Alessandro 997 Vesely. In addition, the Verisign Registry Services Lab development 998 team of Andrew Kaizer, Sai Mogali, Anurag Saxena, Swapneel Sheth, 999 Nitin Singh, and Zhao Zhao provided critical "proof of concept" 1000 implementation experience that helped demonstrate the validity of the 1001 concepts described in this document. 1003 10. References 1005 10.1. Normative References 1007 [I-D.ietf-oauth-device-flow] 1008 Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, 1009 "OAuth 2.0 Device Flow for Browserless and Input 1010 Constrained Devices", draft-ietf-oauth-device-flow-08 1011 (work in progress), March 2018. 1013 [OIDC] OpenID Foundation, "OpenID Connect", 1014 . 1016 [OIDCC] OpenID Foundation, "OpenID Connect Core incorporating 1017 errata set 1", November 2014, 1018 . 1020 [OIDCD] OpenID Foundation, "OpenID Connect Discovery 1.0 1021 incorporating errata set 1", November 2014, 1022 . 1025 [OIDCR] OpenID Foundation, "OpenID Connect Dynamic Client 1026 Registration 1.0 incorporating errata set 1", November 1027 2014, . 1030 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1031 Requirement Levels", BCP 14, RFC 2119, 1032 DOI 10.17487/RFC2119, March 1997, 1033 . 1035 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1036 Resource Identifier (URI): Generic Syntax", STD 66, 1037 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1038 . 1040 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1041 IANA Considerations Section in RFCs", RFC 5226, 1042 DOI 10.17487/RFC5226, May 2008, 1043 . 1045 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1046 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1047 . 1049 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1050 Framework: Bearer Token Usage", RFC 6750, 1051 DOI 10.17487/RFC6750, October 2012, 1052 . 1054 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 1055 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 1056 August 2013, . 1058 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1059 Protocol (HTTP/1.1): Message Syntax and Routing", 1060 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1061 . 1063 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1064 Protocol (HTTP/1.1): Authentication", RFC 7235, 1065 DOI 10.17487/RFC7235, June 2014, 1066 . 1068 [RFC7480] Newton, A., Ellacott, B., and N. Kong, "HTTP Usage in the 1069 Registration Data Access Protocol (RDAP)", RFC 7480, 1070 DOI 10.17487/RFC7480, March 2015, 1071 . 1073 [RFC7481] Hollenbeck, S. and N. Kong, "Security Services for the 1074 Registration Data Access Protocol (RDAP)", RFC 7481, 1075 DOI 10.17487/RFC7481, March 2015, 1076 . 1078 [RFC7482] Newton, A. and S. Hollenbeck, "Registration Data Access 1079 Protocol (RDAP) Query Format", RFC 7482, 1080 DOI 10.17487/RFC7482, March 2015, 1081 . 1083 [RFC7483] Newton, A. and S. Hollenbeck, "JSON Responses for the 1084 Registration Data Access Protocol (RDAP)", RFC 7483, 1085 DOI 10.17487/RFC7483, March 2015, 1086 . 1088 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1089 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 1090 2015, . 1092 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1093 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1094 . 1096 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1097 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1098 May 2017, . 1100 10.2. Informative References 1102 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 1103 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 1104 . 1106 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 1107 Code: The Implementation Status Section", BCP 205, 1108 RFC 7942, DOI 10.17487/RFC7942, July 2016, 1109 . 1111 10.3. URIs 1113 [1] http://openid.net/get-an-openid/ 1115 [2] https://www.icann.org/en/system/files/files/final-report- 1116 06jun14-en.pdf 1118 [3] http://curl.haxx.se/ 1120 [4] https://www.gnu.org/software/wget/ 1122 Appendix A. Change Log 1124 00: Initial version. 1125 01: Updated flow description (Section 3.1.2) and description of the 1126 registration process (Section 3.1.3). Thanks to Jaromir Talir. 1127 02: Updated flow description. 1128 03: Added description of query parameters and non-browser clients. 1129 Updated security considerations to note issues associated with 1130 access control. 1131 04: Updated references for JSON Web Token, OpenID Connect Core, and 1132 OpenID Connect Discovery. Added acknowledgement to the Verisign 1133 Labs developers. Changed intended status to Standards Track. 1134 Added text to describe protocol parameters and processing. Other 1135 minor edits. 1137 05: Added examples for curl and wget. Added a reference to RFC 1138 7235. 1139 00: Changed WG reference in file name from weirds to regext. 1140 Described support for refresh tokens. Editorial updates. 1141 Corrected several examples. Added registry of purpose values. 1142 01: Added Implementation Status section (Section 7). 1143 02: Updated section Section 4.4 to clarify ID Token validation 1144 requirements. 1145 03: Keepalive refresh. 1146 04: Added rdap_conformance. 1147 05: Added "do not track" claim. 1148 06: Added text describing the OAuth device flow and modified other 1149 text associated with UI-limited devices. Updated BCP 14 text. 1150 07: Removed outdated BCP 14 text. 1152 Author's Address 1154 Scott Hollenbeck 1155 Verisign Labs 1156 12061 Bluemont Way 1157 Reston, VA 20190 1158 USA 1160 Email: shollenbeck@verisign.com 1161 URI: http://www.verisignlabs.com/