--- 1/draft-ietf-regext-rdap-openid-07.txt 2021-11-08 05:13:16.751165270 -0800 +++ 2/draft-ietf-regext-rdap-openid-08.txt 2021-11-08 05:13:16.803166565 -0800 @@ -1,19 +1,19 @@ REGEXT Working Group S. Hollenbeck Internet-Draft Verisign Labs -Intended status: Standards Track 28 June 2021 -Expires: 30 December 2021 +Intended status: Standards Track 8 November 2021 +Expires: 12 May 2022 Federated Authentication for the Registration Data Access Protocol (RDAP) using OpenID Connect - draft-ietf-regext-rdap-openid-07 + draft-ietf-regext-rdap-openid-08 Abstract The Registration Data Access Protocol (RDAP) provides "RESTful" web services to retrieve registration metadata from domain name and regional internet registries. RDAP allows a server to make access control decisions based on client identity, and as such it includes support for client identification features provided by the Hypertext Transfer Protocol (HTTP). Identification methods that require clients to obtain and manage credentials from every RDAP server @@ -31,35 +31,35 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on 30 December 2021. + This Internet-Draft will expire on 12 May 2022. Copyright Notice Copyright (c) 2021 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components - extracted from this document must include Simplified BSD License text - as described in Section 4.e of the Trust Legal Provisions and are - provided without warranty as described in the Simplified BSD License. + extracted from this document must include Revised BSD License text as + described in Section 4.e of the Trust Legal Provisions and are + provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Problem Statement . . . . . . . . . . . . . . . . . . . . 3 1.2. Proposal . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Conventions Used in This Document . . . . . . . . . . . . . . 4 3. Federated Authentication for RDAP . . . . . . . . . . . . . . 4 3.1. RDAP and OpenID Connect . . . . . . . . . . . . . . . . . 5 3.1.1. Terminology . . . . . . . . . . . . . . . . . . . . . 5 @@ -69,36 +69,36 @@ 3.1.3.2. Authentication Request . . . . . . . . . . . . . 6 3.1.3.3. End-User Authorization . . . . . . . . . . . . . 7 3.1.3.4. Authorization Response and Validation . . . . . . 7 3.1.3.5. Token Processing . . . . . . . . . . . . . . . . 7 3.1.3.6. Delivery of User Information . . . . . . . . . . 8 3.1.4. Specialized Claims for RDAP . . . . . . . . . . . . . 8 3.1.4.1. Stated Purpose . . . . . . . . . . . . . . . . . 8 3.1.4.2. Do Not Track . . . . . . . . . . . . . . . . . . 9 4. Protocol Parameters . . . . . . . . . . . . . . . . . . . . . 10 4.1. Client Authentication Request and Response . . . . . . . 10 - 4.2. Token Request and Response . . . . . . . . . . . . . . . 10 + 4.2. Token Request and Response . . . . . . . . . . . . . . . 11 4.3. Token Refresh and Revocation . . . . . . . . . . . . . . 12 4.4. Token Exchange . . . . . . . . . . . . . . . . . . . . . 14 - 4.5. Parameter Processing . . . . . . . . . . . . . . . . . . 15 + 4.5. Parameter Processing . . . . . . . . . . . . . . . . . . 14 4.6. RDAP Conformance . . . . . . . . . . . . . . . . . . . . 15 - 5. Clients with Limited User Interfaces . . . . . . . . . . . . 16 + 5. Clients with Limited User Interfaces . . . . . . . . . . . . 15 5.1. OAuth 2.0 Device Authorization Grant . . . . . . . . . . 16 5.2. Manual Token Management . . . . . . . . . . . . . . . . . 16 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 6.1. RDAP Extensions Registry . . . . . . . . . . . . . . . . 17 6.2. JSON Web Token Claims Registry . . . . . . . . . . . . . 17 6.3. RDAP Query Purpose Registry . . . . . . . . . . . . . . . 18 7. Implementation Status . . . . . . . . . . . . . . . . . . . . 20 - 7.1. Verisign Labs . . . . . . . . . . . . . . . . . . . . . . 21 + 7.1. Verisign Labs . . . . . . . . . . . . . . . . . . . . . . 20 7.2. Viagenie . . . . . . . . . . . . . . . . . . . . . . . . 21 - 8. Security Considerations . . . . . . . . . . . . . . . . . . . 22 + 8. Security Considerations . . . . . . . . . . . . . . . . . . . 21 8.1. Authentication and Access Control . . . . . . . . . . . . 22 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 22 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 22 10.1. Normative References . . . . . . . . . . . . . . . . . . 22 10.2. Informative References . . . . . . . . . . . . . . . . . 24 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 25 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 25 1. Introduction @@ -410,83 +410,103 @@ the claim is "true", and accepting the claim complies with local regulations regarding logging and tracking. The "dnt" value is represented as a JSON boolean literal. An example: {"dnt" : true} No special query tracking processing is required if this claim is not present or if the value of the claim is "false". Use of this claim MUST be limited to End-Users who are granted "do not track" - priviliges in accordance with service policies and regulations. + privileges in accordance with service policies and regulations. Specification of these policies and regulations is beyond the scope of this document. 4. Protocol Parameters This specification adds the following protocol parameters to RDAP: 1. A query parameter to request authentication for a specific end- user identity. 2. A path segment to request an ID Token and an Access Token for a specific end-user identity. 3. A query parameter to deliver an ID Token and an Access Token for use with an RDAP query. 4.1. Client Authentication Request and Response - Client authentication is requested by adding a query component to an - RDAP request URI using the syntax described in Section 3.4 of RFC - 3986 [RFC3986]. The query used to request client authentication is - represented as a "key=value" pair using a key value of "id" and a - value component that contains the client identifier issued by an OP. - An example: + Client authentication is requested using one of two methods: either + by adding a query component to an RDAP request URI using the syntax + described in Section 3.4 of RFC 3986 [RFC3986], or by including an + HTTP authorization header for the Basic authentication scheme as + described in RFC 7617 [RFC7617]. Clients can use either method. + Servers MUST support both methods. + + The query used to request client authentication is represented as an + OPTIONAL "key=value" pair using a key value of "id" and a value + component that contains the client identifier issued by an OP. An + example for client identifier "user.idp.example": https://example.com/rdap/domain/example.com?id=user.idp.example + The authorization header for the Basic authentication scheme contains + a Base64-encoded representation of the client identifier issued by an + OP. No password is provided. An example for client identifier + "user.idp.example": + + https://example.com/rdap/domain/example.com Authorization: Basic + dXNlci5pZHAuZXhhbXBsZQ== + The response to an authenticated query MUST use the response structures specified in RFC 7483 [RFC7483]. Information that the end-user is not authorized to receive MUST be omitted from the response. 4.2. Token Request and Response Clients MAY send a request to an RDAP server to authenticate an end- - user and return an ID Token and an Access Token from an OP that can - be then be passed to the RP/RDAP server to authenticate and process - subsequent queries. Identity provider authentication is requested - using a "tokens" path segment and a query parameter with key value of - "id" and a value component that contains the client identifier issued - by an OP. An example: + user and return tokens (an ID Token, an Access Token, and a Refresh + Token) from an OP that can be then be passed to the RP/RDAP server to + authenticate and process subsequent queries. An access token can be + refreshed as described in Section 12 of the OpenID Connect Core + protocol [OIDCC] and Section 6 of RFC 6749 [RFC6749]. Clients can + take advantage of this functionality if it is supported by the OP and + accepted by the RDAP server. Identity provider authentication is + requested using a "tokens" path segment and a query parameter with a + key value of "id" and a value component that contains the client + identifier issued by an OP. An example: https://example.com/rdap/tokens?id=user.idp.example + In addition to any core RDAP response elements, the response to this - query MUST contain four name-value pairs, in any order, representing - the returned ID Token and Access Token. The ID Token is represented - using a key value of "id_token". The Access Token is represented - using a key value of "access_token". The access token type is - represented using a key value of "token_type" and a value of "bearer" - as described in Sections 4.2.2 and 7.1 of RFC 6749 [RFC6749]. The - lifetime of the access token is represented using a key value of - "expires_in" and a numerical value that describes the lifetime in - seconds of the access token as described in Section 4.2.2 of RFC 6749 - [RFC6749]. The token values returned in the RDAP server response - MUST be Base64url encoded as described in RFCs 7515 [RFC7515] and - 7519 [RFC7519]. + query MUST contain five name-value pairs, in any order, representing + the returned ID Token, Access Token, and Refresh Token. The ID Token + is represented using a key value of "id_token". The Access Token is + represented using a key value of "access_token". The access token + type is represented using a key value of "token_type" and a value of + "bearer" as described in Sections 4.2.2 and 7.1 of RFC 6749 + [RFC6749]. The lifetime of the access token is represented using a + key value of "expires_in" and a numerical value that describes the + lifetime in seconds of the access token as described in Section 4.2.2 + of RFC 6749 [RFC6749]. The Refresh Token is represented using a key + value of "refresh_token". The token values returned in the RDAP + server response MUST be Base64url-encoded as described in RFCs 7515 + [RFC7515] and 7519 [RFC7519]. An example (the encoded tokens have been abbreviated for clarity): { "access_token" : "eyJ0...NiJ9", "id_token" : "eyJ0...EjXk", "token_type" : "bearer", - "expires_in" : "3600" + "expires_in" : "3600", + "refresh_token" : "eyJ0...c8da" } Figure 1 An RDAP server that processes this type of query MUST determine if the identifier is associated with an OP that is recognized and supported by the server. Servers MUST reject queries that include an identifier associated with an unsupported OP with an HTTP 501 (Not Implemented) response. An RDAP server that receives a query containing an identifier associated with a recognized OP MUST perform @@ -499,142 +519,103 @@ The tokens can then be passed to the server for use with an RDAP query by passing the encoded ID Token as a query parameter with a key value of "id_token" and the encoded Access Token in an HTTP Bearer authorization header [RFC6750]. An example (the encoded tokens have been abbreviated and the URI split across multiple lines for clarity): https://example.com/rdap/domain/example.com?id_token=eyJ0...EjXk Authorization: Bearer eyJ0...NiJ9 + The response to an authenticated query MUST use the response structures specified in RFC 7483 [RFC7483]. Information that the end-user is not authorized to receive MUST be omitted from the response. 4.3. Token Refresh and Revocation - An access token can be refreshed as described in Section 12 of the - OpenID Connect Core protocol [OIDCC] and Section 6 of OAuth 2.0 - [RFC6749]. Clients can take advantage of this functionality if it is - supported by the OP and accepted by the RDAP server. - - A refresh token is requested using a "tokens" path segment and two - query parameters. The first query parameter includes a key value of - "id" and a value component that contains the client identifier issued - by an OP. The second query parameter includes a key value of - "refresh" and a value component of "true". A value component of - "false" MUST be processed to return a result that is consistent with - not including a "refresh" parameter at all as described in - Section 4.2. An example using "refresh=true": - - https://example.com/rdap/tokens?id=user.idp.example&refresh=true - - The response to this query MUST contain all of the response elements - described in Section 4.2. In addition, the response MUST contain a - name-value pair that represents a refresh token. The name-value pair + The refresh token returned in the token response can be used to + refresh an access token. An access token is refreshed using a + "tokens" path segment and a query parameter. The query parameter includes a key value of "refresh_token" and a Base64url-encoded value - that represents the refresh token. - - Example refresh token request response (the encoded tokens have been - abbreviated for clarity): - - { - "access_token" : "eyJ0...NiJ9", - "id_token" : "eyJ0...EjXk", - "token_type" : "bearer", - "expires_in" : "3600", - "refresh_token" : "eyJ0...c8da" - } - - Figure 2 - - Once acquired, a refresh token can be used to refresh an access - token. An access token is refreshed using a "tokens" path segment - and two query parameters. The first query parameter includes a key - value of "id" and a value component that contains the client - identifier issued by an OP. The second query parameter includes a - key value of "refresh_token" and a Base64url-encoded value that - represents the refresh token. An example: + that represents the refresh token. An example: - https://example.com/rdap/ - tokens?id=user.idp.example&refresh_token=eyJ0...f3jE + https://example.com/rdap/tokens?refresh_token=eyJ0...c8da In addition to any core RDAP response elements, the response to this query MUST contain four name-value pairs, in any order, representing a returned Refresh Token and Access Token. The Refresh Token is represented using a key value of "refresh_token". The Access Token is represented using a key value of "access_token". The access token type is represented using a key value of "token_type" and a value of "bearer" as described in Sections 4.2.2 and 7.1 of RFC 6749 [RFC6749]. The lifetime of the access token is represented using a key value of "expires_in" and a numerical value that describes the lifetime in seconds of the access token as described in Section 4.2.2 of RFC 6749 [RFC6749]. The token values returned in the RDAP server - response MUST be Base64url encoded as described in RFCs 7515 + response MUST be Base64url-encoded as described in RFCs 7515 [RFC7515] and 7519 [RFC7519]. Example access token refresh response (the encoded tokens have been abbreviated for clarity): { "access_token" : "0dac...13b0", "refresh_token" : "f735...d30c", "token_type" : "bearer", "expires_in" : "3600" } - Figure 3 + Figure 2 Access and refresh tokens can be revoked as described in RFC 7009 [RFC7009] by sending a request to an RDAP server that contains a - "tokens/revoke" path segment and two query parameters. The first - query parameter includes a key value of "id" and a value component - that contains the client identifier issued by an OP. The second - query parameter includes a key value of "token" and a Base64url- - encoded value that represents either the current refresh token or the + "tokens/revoke" path segment and a query parameter. The query + parameter includes a key value of "token" and a Base64url-encoded + value that represents either the current refresh token or the associated access token. An example: - https://example.com/rdap/tokens/ - revoke?id=user.idp.example&token=f735...d30c + https://example.com/rdap/tokens/revoke?token=f735...d30c + Note that this command will revoke both access and refresh tokens at the same time. In addition to any core RDAP response elements, the response to this query MUST contain a description of the result of processing the revocation request within the RDAP "notices" data structure. Example token revocation success: "notices" : [ { "title" : "Token Revocation Result", "description" : "Token revocation succeeded.", } ], "lang" : "en-US" - Figure 4 + Figure 3 Example token revocation failure: "notices" : [ { "title" : "Token Revocation Result", "description" : "Token revocation failed.", } ], "errorCode" : 400, "lang" : "en-US" - Figure 5 + Figure 4 4.4. Token Exchange ID tokens include an audience parameter that contains the OAuth 2.0 client_id of the RP as an audience value. In some operational scenarios (such as a client that is providing a proxy service), an RP can receive tokens with an audience value that does not include the RP's client_id. These tokens might not be trusted by the RP, and the RP might refuse to accept the tokens. This situation can be remedied by having the RP exchange these tokens with the OP for a set of @@ -691,21 +672,21 @@ Registry is described in Section 6.1. Example rdapConformance structure with extension specified: "rdapConformance" : [ "rdap_level_0", "rdap_openidc_level_0" ] - Figure 6 + Figure 5 5. Clients with Limited User Interfaces The flow described in Section 3.1.3 requires a client to interact with a server using a web browser. This will not work well in situations where the client is automated or an end-user is using a command line user interface such as curl (http://curl.haxx.se/) or wget (https://www.gnu.org/software/wget/). There are multiple ways to address this limitation using a web browser on a second device. Two are described here. @@ -721,21 +702,22 @@ constrained device. 5.2. Manual Token Management A second method of requesting user authorization from a constrained device is possible by producing and managing tokens manually as follows: 1. Authenticate with the OP as described in Section 4.2 using a browser or browser-like client. - 2. Store the returned ID Token and Access Token locally. + 2. Store the returned ID Token, Access Token, and Refresh Token + locally. 3. Send a request to the content provider/RP along with the ID Token and Access Token received from the OP. The Access Token MAY be passed to the RP in an HTTP "Authorization" header [RFC7235] or as a query parameter. The Access Token MUST be specified using the "Bearer" authentication scheme [RFC6750] if it is passed in an "Authorization" header. The ID Token MUST be passed to the RP as a query parameter. Here are two examples using the curl and wget utilities. Start by @@ -992,26 +974,30 @@ policy. For example, a client who provides an email address (and nothing more) might be entitled to receive a subset of the information that would be available to a client who provides an email address, a full name, and a stated purpose. Development of these access control policies is beyond the scope of this document. 9. Acknowledgements The author would like to acknowledge the following individuals for their contributions to the development of this document: Tom - Harrison, Russ Housley, Mario Loffredo, Rhys Smith, Jaromir Talir, - and Alessandro Vesely. In addition, the Verisign Registry Services - Lab development team of Joseph Harvey, Andrew Kaizer, Sai Mogali, - Anurag Saxena, Swapneel Sheth, Nitin Singh, and Zhao Zhao provided - critical "proof of concept" implementation experience that helped - demonstrate the validity of the concepts described in this document. + Harrison, Russ Housley, Rhys Smith, Jaromir Talir, and Alessandro + Vesely. In addition, the Verisign Registry Services Lab development + team of Joseph Harvey, Andrew Kaizer, Sai Mogali, Anurag Saxena, + Swapneel Sheth, Nitin Singh, and Zhao Zhao provided critical "proof + of concept" implementation experience that helped demonstrate the + validity of the concepts described in this document. + + Mario Loffredo provided significant feedback based on implementation + experience that led to welcome improvements in several sections of + this document. His contributions are greatly appreciated. 10. References 10.1. Normative References [OIDC] OpenID Foundation, "OpenID Connect", . [OIDCC] OpenID Foundation, "OpenID Connect Core incorporating errata set 1", November 2014, @@ -1086,20 +1072,24 @@ . [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2015, . [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, . + [RFC7617] Reschke, J., "The 'Basic' HTTP Authentication Scheme", + RFC 7617, DOI 10.17487/RFC7617, September 2015, + . + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8628] Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, "OAuth 2.0 Device Authorization Grant", RFC 8628, DOI 10.17487/RFC8628, August 2019, . [RFC8693] Jones, M., Nadalin, A., Campbell, B., Ed., Bradley, J., @@ -1130,20 +1120,21 @@ 03: Updated OAuth 2.0 Device Authorization Grant description and reference due to publication of RFC 8628. 04: Updated OAuth 2.0 token exchange description and reference due to publication of RFC 8693. Corrected the RDAP conformance identifier to be registered with IANA. 05: Keepalive refresh. 06: Keepalive refresh. 07: Added "login_hint" description to Section 3.1.3.2. Added some text to Section 3.1.4.2 to note that "do not track" requires compliance with local regulations. + 08: Rework of token management processing in Sections 4 and 5. Author's Address Scott Hollenbeck Verisign Labs 12061 Bluemont Way Reston, VA 20190 United States of America Email: shollenbeck@verisign.com