--- 1/draft-ietf-regext-rdap-openid-09.txt 2022-02-08 11:13:10.561039033 -0800 +++ 2/draft-ietf-regext-rdap-openid-10.txt 2022-02-08 11:13:10.617040429 -0800 @@ -1,19 +1,19 @@ REGEXT Working Group S. Hollenbeck Internet-Draft Verisign Labs -Intended status: Standards Track 18 January 2022 -Expires: 22 July 2022 +Intended status: Standards Track 8 February 2022 +Expires: 12 August 2022 Federated Authentication for the Registration Data Access Protocol (RDAP) using OpenID Connect - draft-ietf-regext-rdap-openid-09 + draft-ietf-regext-rdap-openid-10 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,21 +31,21 @@ 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 22 July 2022. + This Internet-Draft will expire on 12 August 2022. Copyright Notice Copyright (c) 2022 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 @@ -54,56 +54,59 @@ 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 . . . . . . . . . . . . . . . . . 4 + 3.1. RDAP and OpenID Connect . . . . . . . . . . . . . . . . . 5 3.1.1. Terminology . . . . . . . . . . . . . . . . . . . . . 5 3.1.2. Overview . . . . . . . . . . . . . . . . . . . . . . 5 3.1.3. RDAP Authentication and Authorization Steps . . . . . 6 3.1.3.1. Provider Discovery . . . . . . . . . . . . . . . 6 - 3.1.3.2. Authentication Request . . . . . . . . . . . . . 6 + 3.1.3.2. Authentication Request . . . . . . . . . . . . . 7 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.4. Authorization Response and Validation . . . . . . 8 + 3.1.3.5. Token Processing . . . . . . . . . . . . . . . . 8 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 . . . . . . . . . . . . . . . 11 - 4.3. Token Refresh and Revocation . . . . . . . . . . . . . . 13 - 4.4. Token Exchange . . . . . . . . . . . . . . . . . . . . . 15 - 4.5. Parameter Processing . . . . . . . . . . . . . . . . . . 15 - 4.6. RDAP Conformance . . . . . . . . . . . . . . . . . . . . 16 - 5. Clients with Limited User Interfaces . . . . . . . . . . . . 16 - 5.1. OAuth 2.0 Device Authorization Grant . . . . . . . . . . 16 - 5.2. Manual Token Management . . . . . . . . . . . . . . . . . 17 - 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 - 6.1. RDAP Extensions Registry . . . . . . . . . . . . . . . . 17 - 6.2. JSON Web Token Claims Registry . . . . . . . . . . . . . 18 - 6.3. RDAP Query Purpose Registry . . . . . . . . . . . . . . . 18 - 7. Implementation Status . . . . . . . . . . . . . . . . . . . . 21 - 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 + 4.1. Client Login . . . . . . . . . . . . . . . . . . . . . . 10 + 4.1.1. Clients with Limited User Interfaces . . . . . . . . 13 + 4.1.1.1. OAuth 2.0 Device Authorization Grant . . . . . . 13 + 4.1.1.2. UI-limited Client Login . . . . . . . . . . . . . 13 + 4.1.1.3. UI-limited Client Login Polling . . . . . . . . . 15 + 4.2. Session Status . . . . . . . . . . . . . . . . . . . . . 15 + 4.3. Client Logout . . . . . . . . . . . . . . . . . . . . . . 18 + 4.4. Token Exchange . . . . . . . . . . . . . . . . . . . . . 18 + 4.5. Parameter Processing . . . . . . . . . . . . . . . . . . 19 + 5. RDAP Query Processing . . . . . . . . . . . . . . . . . . . . 19 + 6. RDAP Conformance . . . . . . . . . . . . . . . . . . . . . . 19 + 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 + 7.1. RDAP Extensions Registry . . . . . . . . . . . . . . . . 20 + 7.2. JSON Web Token Claims Registry . . . . . . . . . . . . . 20 + 7.3. RDAP Query Purpose Registry . . . . . . . . . . . . . . . 21 + 8. Implementation Status . . . . . . . . . . . . . . . . . . . . 23 + 9. Security Considerations . . . . . . . . . . . . . . . . . . . 24 + 9.1. Authentication and Access Control . . . . . . . . . . . . 24 + + 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 24 + 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 + 11.1. Normative References . . . . . . . . . . . . . . . . . . 24 + 11.2. Informative References . . . . . . . . . . . . . . . . . 26 + Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 27 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 27 1. Introduction 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) [RFC7230]. @@ -206,77 +209,86 @@ This document uses the terms "client" and "server" defined by RDAP [RFC7480]. An RDAP client performs the role of an OpenID Connect Core [OIDCC] Entity or End-User. An RDAP server performs the role of an OpenID Connect Core Relying Party (RP). Additional terms from Section 1.2 of the OpenID Connect Core specification are incorporated by reference. 3.1.2. Overview - At a high level, RDAP authentication of a browser-based client using + At a high level, RDAP authentication of a browser-like client using OpenID Connect requires completion of the following steps: 1. An RDAP client sends an RDAP "help" query to an RDAP server to determine the type of OpenID Authorization Server that's used by the RDAP server. This information is returned in the rdapConformance section of the response. A value of "rdap_openidc_local_level_0" indicates that the server uses a local Authorization Server. A value of "rdap_openidc_remote_level_0" indicates that the server uses a remote Authorization Server. - 2. An RDAP client (acting as an OpenID End-User) sends a "tokens" - request (see Section 4.2) to an RDAP server. The request MUST - include an "id" parameter if the server uses only a remote - Authorization Server. The "id" parameter is OPTIONAL if the - server uses a local Authorization Server. + 2. An RDAP client (acting as an OpenID End-User) sends a "login" + request (see Section 4.1) to an RDAP server. The request MUST + include an "id" query parameter if the server uses only a remote + Authorization Server. The "id" query parameter is OPTIONAL if + the server uses a local Authorization Server. + 3. The RDAP server (acting as an OpenID Relying Party (RP)) prepares an Authentication Request containing the desired request parameters. 4. The RDAP server sends the RDAP client and Authentication Request to an Authorization Server operated by an OpenID Provider (OP) using an HTTP redirect. - 5. The Authorization Server authenticates the RDAP Client. - - 6. The Authorization Server obtains RDAP Client consent/ - authorization. + 5. The Authorization Server authenticates the End-User. + 6. The Authorization Server obtains End-User consent/authorization. 7. The Authorization Server sends the RDAP Client back to the RDAP server with an Authorization Code using an HTTP redirect. 8. The RDAP server requests a response using the Authorization Code at the Token Endpoint. 9. The RDAP server receives a response that contains an ID Token and Access Token in the response body. - 10. The RDAP server validates the ID Token and retrieves the RDAP - client's Subject Identifier. + 10. The RDAP server validates the ID Token and retrieves the claims + associated with the end-user's identity. The RDAP server can then make identification, authorization, and - access control decisions based on local policies, the ID Token - received from the OP, and the received Claims. Note that OpenID - Connect describes different process flows for other types of clients, - such as script-based or command line clients. + access control decisions based on end-user identity information and + local policies. Note that OpenID Connect describes different process + flows for other types of clients, such as script-based or command + line clients. 3.1.3. RDAP Authentication and Authorization Steps End-Users MUST possess an identifier (an OpenID) issued by an OP to use OpenID Connect with RDAP. An OP SHOULD include support for the claims described in Section 3.1.4 to provide additional information needed for RDAP End-User authorization. OpenID Connect requires RPs to register with OPs to use OpenID Connect services for an End-User. That process is described by the "OpenID Connect Dynamic Client Registration" protocol [OIDCR]. 3.1.3.1. Provider Discovery - An RDAP server/RP needs to receive an identifier from an End-User - that can be used to discover the End-User's OP. That process is - required and is documented in the "OpenID Connect Discovery" protocol - [OIDCD]. + An RDAP server/RP needs to be able to map an End-User's identifier to + an OP. This can be accomplished using the OPTIONAL "OpenID Connect + Discovery" protocol [OIDCD], but that protocol is not widely + implemented and can be unreliable. Out-of-band methods are also + possible and can be more dependable. For example, an RP can support + a limited number of OPs and maintain internal associations of those + identifiers with the OPs that issued them. An RP can also ask an + end-user to identify the OP that issued their identifier as part of + an RDAP query workflow. In this case, the RP will need to maintain + state for the association between the user's identifier and the OP in + order to process later queries that rely on passing the access token + and user identifier as authorization parameters. An RP MAY use any + provider discovery approach that is suitable for its operating + environment. 3.1.3.2. Authentication Request Once the OP is known, an RP MUST form an Authentication Request and send it to the OP as described in Section 3 of the OpenID Connect Core protocol [OIDCC]. The authentication path followed (authorization, implicit, or hybrid) will depend on the Authentication Request response_type set by the RP. The remainder of the processing steps described here assume that the Authorization Code Flow is being used by setting "response_type=code" in the @@ -289,24 +301,25 @@ described in Section 3.2 of the OpenID Connect Core protocol. The Hybrid Flow (described in Section 3.3 of the OpenID Connect Core protocol) combines elements of the Authorization and Implicit Flows by returning some tokens from the Authorization Endpoint and others from the Token Endpoint. An Authentication Request can contain several parameters. REQUIRED parameters are specified in Section 3.1.2.1 of the OpenID Connect Core protocol [OIDCC]. Apart from these parameters, it is RECOMMENDED that the RP include the optional "login_hint" parameter - in the request, with the value being that of the "id" from the query - component of the end user's RDAP request. Passing "login_hint" - allows a client to pre-fill login form information, so logging in can - be more convenient for users. Other parameters MAY be included. + in the request, with the value being that of the "id" query parameter + of the End-User's RDAP "login" request. Passing the "login_hint" + parameter allows a client to pre-fill login form information, so + logging in can be more convenient for users. Other parameters MAY be + included. The OP receives the Authentication Request and attempts to validate it as described in Section 3.1.2.2 of the OpenID Connect Core protocol [OIDCC]. If the request is valid, the OP attempts to authenticate the End-User as described in Section 3.1.2.3 of the OpenID Connect Core protocol [OIDCC]. The OP returns an error response if the request is not valid or if any error is encountered. 3.1.3.3. End-User Authorization @@ -383,21 +396,21 @@ characters from "a" to "z", and the underscore ("_") character. Value strings contain at least one character and no more than 64 characters. Description: a one- or two-sentence description of the meaning of the purpose value, how it might be used, and/or how it should be interpreted by clients and servers. This registry is operated under the "Specification Required" policy defined in RFC 5226 ([RFC5226]). The set of initial values used to - populate the registry as described in Section 6.3 are taken from the + populate the registry as described in Section 7.3 are taken from the final report (https://www.icann.org/en/system/files/files/final- report-06jun14-en.pdf) produced by the Expert Working Group on gTLD Directory Services chartered by the Internet Corporation for Assigned Names and Numbers (ICANN). 3.1.4.2. Do Not Track There are also communities of RDAP users and operators who wish to make and validate claims about a user's wish to not have their queries logged, tracked, or recorded. For example, a law enforcement @@ -427,397 +441,498 @@ 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 tokens for a specific end-user - identity. - 3. A query parameter to deliver an Access Token for use with an RDAP - query. - -4.1. Client Authentication Request and Response - - Client authentication is requested using one of three methods: + 2. Path segments to start, stop, and determine the status of an + authenticated session for a specific end-user identity. - 1. by adding a query component to an RDAP request URI using the - syntax described in Section 3.4 of RFC 3986 [RFC3986], - 2. by including an HTTP authorization header for the Basic - authentication scheme as described in RFC 7617 [RFC7617], or - 3. by including an HTTP authorization header with a Bearer token as - described in RFC 6750 [RFC6750]. +4.1. Client Login - Clients can use any of these methods. Servers MUST support all - methods. + Client authentication is requested by sending a "login" query to an + RDAP server. If the RDAP server supports only remote Authorization + Servers, the "login" query MUST include an End-User identifier that's + delivered using one of two methods: 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]. If + the RDAP server supports a local Authorization Servers, the End-User + identifier MAY be omitted. Clients can use either of these methods. + 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 + https://example.com/rdap/login?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 + https://example.com/rdap/login Authorization: Basic dXNlci5pZHAuZXhhbXBsZQ== - The HTTP Bearer authorization header contains a Base64url-encoded - representation of the Access Token issued by an OP. An example that - has been abbreviated for clarity: - - https://example.com/rdap/domain/example.com - Authorization: Bearer eyJ0...NiJ9 - - The response to an authenticated query MUST use the response - structures specified in RFC 9083 [RFC9083]. Information that the - end-user is not authorized to receive MUST be omitted from the - response. + An example for use with a local Authorization Server: -4.2. Token Request and Response + https://example.com/rdap/login - Clients MAY send a request to an RDAP server to authenticate an end- - 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 an OPTIONAL query - parameter (the query parameter isn't needed if the RDAP server is - using a local OP) with a key value of "id" and a value component that - contains the client identifier issued by an OP. An example for use - with a remote OP: + The response to this query MUST use the response structures specified + in RFC 9083 [RFC9083]. In addition, the response MUST include an + indication of the requested operation's success or failure, and, if + successful, the client identifier associated with the request, the + claims received from the Authorization Server, and the duration of + the authorized session. - https://example.com/rdap/tokens?id=user.idp.example + An example of a successful "login" response: - An example for use with a local OP: + { + "notices": { + "title": "Login Result", + "description": [ + "Login succeeded", + [ + "Client ID", + "user.idp.example" + ], + [ + "Claims", + { + "iss": "https://accounts.someprovider.com", + "azp": "729559086898-onapsvnhf2og.apps.someprovider.com", + "aud": "729559086898-onapsvnhf2og.apps.someprovider.com", + "sub": "103892603076825016132", + "email": "user@someprovider.com", + "email_verified": true, + "at_hash": "es5maY5y9jBAWCBMhLokAQ", + "nonce": "dcb29f97c836726ddc074f76fbc21bfd", + "name": "User Person", + "picture": "https://lh3.someprovider.com/a-/AOh14=s96-c", + "given_name": "User", + "family_name": "Person", + "locale": "en", + "iat": 1644239971, + "exp": 1644243571, + "purpose": "domainNameControl", + "dnt": false + } + ], + [ + "Expires in (seconds)", + 3599 + ] + ] + }, + "lang": "en-US" + } - https://example.com/rdap/tokens - In addition to any core RDAP response elements, the response to this - 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]. + Figure 1 - An example (the encoded tokens have been abbreviated for clarity): + An example of a failed "login" response: { - "access_token" : "eyJ0...NiJ9", - "id_token" : "eyJ0...EjXk", - "token_type" : "bearer", - "expires_in" : "3600", - "refresh_token" : "eyJ0...c8da" + "notices": { + "title": "Login Result", + "description": [ + "Login failed", + [ + "Client ID", + "user.idp.example" + ] + }, + "lang": "en-US" } - Figure 1 + Figure 2 - 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 - the steps required to authenticate the user with the OP using a - browser or browser-like client and return encoded tokens to the - client. Note that tokens are typically valid for a limited period of - time and new tokens will be required when an existing token's - validity period has expired. +4.1.1. Clients with Limited User Interfaces - The Access Token can then be passed to the server for use with an - RDAP query by including the encoded token in an HTTP Bearer - authorization header [RFC6750]. An example (the encoded token has - been abbreviated for clarity): + The flow described in Section 3.1.3 requires an end-user to interact + with a server using a user interface that can process HTTP. 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/). + This limitation can be addressed using a web browser on a second + device. - https://example.com/rdap/domain/example.com?id=user.idp.example +4.1.1.1. OAuth 2.0 Device Authorization Grant - Authorization: Bearer eyJ0...NiJ9 - The RDAP server can retrieve user information (such as claims - associated with the user) from the OP by querying the UserInfo - endpoint using the given Access Token. The user information can then - be used to determine if the uiser is authorized to receive the - requested information. The response to an authenticated query MUST - use the response structures specified in RFC 9083 [RFC9083]. - Information that the end-user is not authorized to receive MUST be - omitted from the response. + The "OAuth 2.0 Device Authorization Grant" [RFC8628] provides an + OPTIONAL method to request user authorization from devices that have + an Internet connection, but lack a suitable browser for a more + traditional OAuth flow. This method requires a client to use a + second device (such as a smart telephone) that has access to a web + browser for entry of a code sequence that is presented on the + constrained device. -4.3. Token Refresh and Revocation +4.1.1.2. UI-limited Client Login - 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. An example: + Client authentication is requested by sending a "login/device" query + to an RDAP server. If the RDAP server supports only remote + Authorization Servers, the "login/device" query MUST include an End- + User identifier that's delivered using one of two methods: 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]. If the RDAP server supports a local + Authorization Servers, the End-User identifier MAY be omitted. + Clients can use either of these methods. Servers MUST support both + methods. - https://example.com/rdap/tokens?refresh_token=eyJ0...c8da + 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 using wget for client identifier "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 - 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 - [RFC7515] and 7519 [RFC7519]. + wget -qO- --keep-session-cookies --save- + cookies\https://example.com/rdap/login/device?id=user.idp.example - Example Access Token refresh response (the encoded tokens have been - abbreviated for clarity): + 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 using curl and an + authorization header: + + curl -H "Authorization: Bearer dXNlci5pZHAuZXhhbXBsZQ=="\-c + cookies.txt https://example.com/rdap/domain/login/device + + The response to this query MUST use the response structures specified + in RFC 9083 [RFC9083]. In addition, the response MUST include an + indication of the requested operation's success or failure, and, if + successful, the name-value pairs described in Section 3.2 of RFC 8628 + [RFC8628]. + + An example of a device "login" response (the device_code has been + abbreviated): { - "access_token" : "0dac...13b0", - "refresh_token" : "f735...d30c", - "token_type" : "bearer", - "expires_in" : "3600" + "notices": { + "title": "Device Login Result", + "description": [ + "Login succeeded", + { + "device_code": "AH-1N...iy7yg", + "user_code": "CVYP-SYRC", + "expires_in": 1800, + "interval": 5, + "verification_url": "https:\/\/www.example.net\/device" + } + ] + }, + "lang": "en-US" } - Figure 2 + Figure 3 - 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 a query parameter. The query - parameter includes a key value of "token" and a Base64url-encoded - value that represents the current refresh token. An example: +4.1.1.3. UI-limited Client Login Polling - https://example.com/rdap/tokens/revoke?token=f735...d30c + After successful processing of the "login/device" query, the client + MUST send a "login/devicepoll" query to the RDAP server to continue + the login process. This query performs the polling function + described in RFC 8628 [RFC8628], allowing the RDAP server to wait for + the End-User to enter the information returned from the "login/ + device" query using the interface on their second device. After the + End-User has completed that process, or if the process fails or times + out, the OP will respond to the polling requests with an indication + of success or failure. Both should be noted using the response + structures described in Section 4.1. An example using wget: - 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. + wget -qO- --load-cookies cookies.txt\https://example.com/rdap/login/ + devicepoll - Example token revocation success: + An example using curl: - "notices" : + curl -b cookies.txt https://example.com/rdap/domain/login/devicepoll + + The response to this query MUST use the response structures described + in Section 4.1. RDAP query processing can continue normally on the + UI-limited device once the "login" process has been completed. + +4.2. Session Status + + Clients MAY send a request to an RDAP server to determine the status + of an existing login session using a "session" path segment. This + request MAY include an OPTIONAL "refresh" path segment to refresh the + access token associated with the current session and to extend the + session for a period of time determined by the OP. As described in + RFC 6749 [RFC6749], support for refresh tokens is OPTIONAL. An RDAP + server MUST determine if the OP supports token refresh and process + the refresh request by either requesting refresh of the access token + or by returning a response that indicates that token refresh is not + supported by the OP. An example "session" request: + + https://example.com/rdap/session + + An example "session" request with token refresh included: + + https://example.com/rdap/session/refresh + + In addition to any core RDAP response elements, the response MUST + include an indication of the requested operation's success or + failure, and, if successful, the client identifier associated with + the session, the claims received from the Authorization Server, and + the duration of the authorized session. + + An example without token refresh: + + { + "notices": { + "title": "Session Status Result", + "description": [ + "Session status succeeded", [ + "Client ID", + "user.idp.example" + ], + [ + "Token Refresh Status", + "Token refresh not requested." + ] + [ + "Expires in (seconds)", + 1873 + ] + [ + "Claims", { - "title" : "Token Revocation Result", - "description" : "Token revocation succeeded.", + "iss": "https://accounts.someprovider.com", + "azp": "729559086898-onapsvnhf2og.apps.someprovider.com", + "aud": "729559086898-onapsvnhf2og.apps.someprovider.com", + "sub": "103892603076825016132", + "email": "user@someprovider.com", + "email_verified": true, + "at_hash": "es5maY5y9jBAWCBMhLokAQ", + "nonce": "dcb29f97c836726ddc074f76fbc21bfd", + "name": "User Person", + "picture": "https://lh3.someprovider.com/a-/AOh14=s96-c", + "given_name": "User", + "family_name": "Person", + "locale": "en", + "iat": 1644239971, + "exp": 1644243571, + "purpose": "domainNameControl", + "dnt": false } ], + ] + }, "lang" : "en-US" + } - Figure 3 + Figure 4 - Example token revocation failure: + An example with token refresh: - "notices" : + { + "notices": { + "title": "Session Status Result", + "description": [ + "Session status succeeded", + [ + "Client ID", + "user.idp.example" + ], [ + "Token Refresh Status", + "Token refresh successful." + ] + [ + "Expires in (seconds)", + 3599 + ] + [ + "Claims", { - "title" : "Token Revocation Result", - "description" : "Token revocation failed.", + "iss": "https://accounts.someprovider.com", + "azp": "729559086898-onapsvnhf2og.apps.someprovider.com", + "aud": "729559086898-onapsvnhf2og.apps.someprovider.com", + "sub": "103892603076825016132", + "email": "user@someprovider.com", + "email_verified": true, + "at_hash": "es5maY5y9jBAWCBMhLokAQ", + "nonce": "dcb29f97c836726ddc074f76fbc21bfd", + "name": "User Person", + "picture": "https://lh3.someprovider.com/a-/AOh14=s96-c", + "given_name": "User", + "family_name": "Person", + "locale": "en", + "iat": 1644239971, + "exp": 1644243571, + "purpose": "domainNameControl", + "dnt": false } ], - "errorCode" : 400, + ] + }, "lang" : "en-US" + } - Figure 4 + Figure 5 + +4.3. Client Logout + + Clients MAY send a request to an RDAP server to terminate an existing + login session. Termination of a session is requested using a + "logout" path segment. An example: + + https://example.com/rdap/logout + + In addition to any core RDAP response elements, the response MUST + include an indication of the requested operation's success or + failure, and, if successful, the client identifier associated with + the session. + + Example "logout" response: + + { + "notices": { + "title": "Logout Result", + "description": [ + "Logout succeeded", + [ + "Client ID", + "user.idp.example" + ], + "Token revocation successful." + ] + }, + "lang": "en-US" + } + + Figure 6 + + Access and refresh tokens can be revoked during the "logout" process + as described in RFC 7009 [RFC7009] if supported by the OP (token + revocation endpoint support is OPTIONAL per RFC 8414 [RFC8414]). If + supported, this feature SHOULD be used to ensure that the tokens are + not mistakenly associated with a future RDAP session. In the absence + of a "logout" query, an RDAP session MUST be terminated by the RDAP + server after a server-defined period of time. 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 trusted tokens that reset the audience parameter. This token - exchange protocol is described in RFC 8693 [RFC8693]. + exchange protocol is described in RFC 8693 [RFC8693]. This issue is + not visible to the RDAP client and should be managed by the OpenID + implementation used by the RDAP server. 4.5. Parameter Processing Unrecognized query parameters MUST be ignored. An RDAP server that processes an authenticated query MUST determine if the end-user identification information is associated with an OP that is recognized and supported by the server. Servers MUST reject queries that include identification information that is not associated with a supported OP by returning an HTTP 501 (Not Implemented) response. An RDAP server that receives a query containing identification information associated with a recognized OP MUST perform the steps required to authenticate the user with the OP, process the query, and - return an RDAP response that is appropriate for the end user's level + return an RDAP response that is appropriate for the End-User's level of authorization and access. - An RDAP server that receives a query containing tokens associated - with a recognized OP and authenticated end user MUST process the - query and return an RDAP response that is appropriate for the end - user's level of authorization and access. Errors based on processing - either the ID Token or the Access Token MUST be signaled with an - appropriate HTTP status code as described in Section 3.1 of RFC 6750 - [RFC6750]. +5. RDAP Query Processing - On receiving a query containing tokens, the RDAP server MUST validate - the identity information received from a UserInfo endpoint. It can - do this independently of the OP, because the response is a JSON - object that contains all the data necessary for validation. The - Access Token can be validated by sending a request using it to the - UserInfo Endpoint and confirming that a successful response is - received. This is different from the OpenID Connect Authorization - Code and Implicit flows, where the Access Token can be validated - against the at_hash claim from the ID Token. With a query containing - tokens, the Access Token might not validate against the at_hash claim - because the Access Token may have been refreshed since the ID Token - was issued. + Once an RDAP "login" session is active, an RDAP server MUST determine + if the End-User is authorized to perform any queries that are + received during the duration of the session. This MAY include + rejecting queries outright, and it MAY include omitting or otherwise + redacting information that the End-User is not authorized to receive. + Specific processing requirements are beyond the scope of this + document. A client can end a session explicitly by sending a + "logout" query to the RDAP server. A session can also be ended + implicitly by the server after a server-defined period of time. The + status of a session can be determined at any time by sending a + "session" query to the RDAP server. - An RDAP server that processes requests without needing the UserInfo - claims does not need to retrieve the claims merely in order to - validate the Access Token. Similarly, an RDAP server that has cached - the UserInfo claims for an end user, in accordance with the HTTP - headers of a previous UserInfo Endpoint response, does not need to - retrieve those claims again in order to re-validate the Access Token. + An RDAP server MUST maintain session state information for the + duration of an active session. This is commonly done using HTTP + cookies as described in RFC 6265 [RFC6265]>. Doing so allows End- + User to submit queries without having to explicitly identify and + authenticate themselves for each and every query. -4.6. RDAP Conformance +6. RDAP Conformance RDAP responses that contain values described in this document MUST indicate conformance with this specification by including an rdapConformance ([RFC9083]) value of "rdap_openidc_remote_level_0" or "rdap_openidc_local_level_0". Both values MAY be present if a server supports both local and remote OpenID Authorization Servers. The information needed to register this value in the RDAP Extensions - Registry is described in Section 6.1. + Registry is described in Section 7.1. Example rdapConformance structure with extension specified: "rdapConformance" : [ "rdap_level_0", "rdap_openidc_remote_level_0" ] - Figure 5 - -5. Clients with Limited User Interfaces - - The flow described in Section 3.1.3 requires an end-user to interact - with a server using a user interface that can process HTTP. 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. - -5.1. OAuth 2.0 Device Authorization Grant - - The "OAuth 2.0 Device Authorization Grant" [RFC8628] provides one - method to request user authorization from devices that have an - Internet connection, but lack a suitable browser for a more - traditional OAuth flow. This method requires a client to use a - second device (such as a smart telephone) that has access to a web - browser for entry of a code sequence that is presented on the - 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, Access Token, and Refresh Token - locally. - 3. Send a request to the content provider/RP along with the client - ID and Access Token received from the OP. - - The Access Token MUST be passed to the RP in an HTTP "Authorization" - header [RFC7235]. The Access Token MUST be specified using the - "Bearer" authentication scheme [RFC6750]. - - Here are two examples using the curl and wget utilities. Start by - authenticating with the OP: - - https://example.com/rdap/tokens?id=user.idp.example - - Save the token information and pass it to the RP along with the URI - representing the RDAP query. Using curl (encoded tokens have been - abbreviated for clarity: - - curl -H "Authorization: Bearer eyJ0...NiJ9"\-k - https://example.com/rdap/domain/example.com\?id=user.idp.example - - Using wget: - - wget --header="Authorization: Bearer - eyJ0...NiJ9"\https://example.com/rdap/domain/ - example.com\id=user.idp.example - - Refresh tokens can be useful to automated or command line clients who - wish to continue a session without explicitly re-authenticating an - end user. See Section 4.3 for more information. + Figure 7 -6. IANA Considerations +7. IANA Considerations -6.1. RDAP Extensions Registry +7.1. RDAP Extensions Registry IANA is requested to register the following values in the RDAP Extensions Registry: * Extension identifier: rdap_openidc_remote_level_0 * Registry operator: Any * Published specification: This document. * Contact: IESG * Intended usage: This extension describes a federated authentication method for RDAP using OAuth 2.0, OpenID Connect, and a remote Authorization Server. * Extension identifier: rdap_openidc_local_level_0 * Registry operator: Any * Published specification: This document. * Contact: IESG * Intended usage: This extension describes a federated authentication method for RDAP using OAuth 2.0, OpenID Connect, and a local Authorization Server. -6.2. JSON Web Token Claims Registry +7.2. JSON Web Token Claims Registry IANA is requested to register the following values in the JSON Web Token Claims Registry: * Claim Name: "purpose" * Claim Description: This claim describes the stated purpose for submitting a request to access a protected RDAP resource. * Change Controller: IESG * Specification Document(s): Section 3.1.4.1 of this document. * Claim Name: "dnt" * Claim Description: This claim contains a JSON boolean literal that describes an End-User's "do not track" preference for identity tracking, logging, or recording when accessing a protected RDAP resource. * Change Controller: IESG * Specification Document(s): Section 3.1.4.2 of this document. -6.3. RDAP Query Purpose Registry +7.3. RDAP Query Purpose Registry IANA is requested to create a new protocol registry to manage RDAP query purpose values. This registry should appear under its own heading on IANA's protocol listings, using the same title as the name of the registry. The information to be registered and the procedures to be followed in populating the registry are described in Section 3.1.4.1. Name of registry: Registration Data Access Protocol (RDAP) Query Purpose Values @@ -906,21 +1020,21 @@ the scope of this purpose include reporting abuse to someone who can investigate and address that abuse, or contacting entities associated with a domain name during an offline criminal investigation. -----END FORM----- -----BEGIN FORM----- Value: dnsTransparency Description: Tasks within the scope of this purpose involve querying the registration data made public by registrants to satisfy a wide variety of use cases around informing the general public. -----END FORM----- -7. Implementation Status +8. Implementation Status NOTE: Please remove this section and the reference to RFC 7942 prior to publication as an RFC. This section records the status of known implementations of the protocol defined by this specification at the time of posting of this Internet-Draft, and is based on a proposal described in RFC 7942 [RFC7942]. The description of implementations in this section is intended to assist the IETF in its decision processes in progressing drafts to RFCs. Please note that the listing of any individual @@ -936,60 +1050,58 @@ running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature. It is up to the individual working groups to use this information as they see fit". Version -09 of this specification introduced changes that are incompatible with earlier implementations. Implementations that are consistent with this specification will be added as they are identified. -8. Security Considerations +9. Security Considerations Security considerations for RDAP can be found in RFC 7481 [RFC7481]. Security considerations for OpenID Connect Core [OIDCC] and OAuth 2.0 [RFC6749] can be found in their reference specifications. OpenID Connect defines optional mechanisms for robust signing and encryption that can be used to provide data integrity and data confidentiality - services as needed. Security services for ID Tokens and Access - Tokens (with references to the JWT specification) are described in - the OpenID Connect Core protocol. + services as needed. -8.1. Authentication and Access Control +9.1. Authentication and Access Control Having completed the client identification, authorization, and validation process, an RDAP server can make access control decisions based on a comparison of client-provided information and local 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 +10. Acknowledgments The author would like to acknowledge the following individuals for their contributions to the development of this document: Tom 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 +11. References -10.1. Normative References +11.1. Normative References [OIDC] OpenID Foundation, "OpenID Connect", . [OIDCC] OpenID Foundation, "OpenID Connect Core incorporating errata set 1", November 2014, . [OIDCD] OpenID Foundation, "OpenID Connect Discovery 1.0 incorporating errata set 1", November 2014, @@ -1009,57 +1121,47 @@ [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, . [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", RFC 5226, DOI 10.17487/RFC5226, May 2008, . + [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, + DOI 10.17487/RFC6265, April 2011, + . + [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, . - [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization - Framework: Bearer Token Usage", RFC 6750, - DOI 10.17487/RFC6750, October 2012, - . - [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, August 2013, . [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", RFC 7230, DOI 10.17487/RFC7230, June 2014, . - [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer - Protocol (HTTP/1.1): Authentication", RFC 7235, - DOI 10.17487/RFC7235, June 2014, - . - [RFC7480] Newton, A., Ellacott, B., and N. Kong, "HTTP Usage in the Registration Data Access Protocol (RDAP)", STD 95, RFC 7480, DOI 10.17487/RFC7480, March 2015, . [RFC7481] Hollenbeck, S. and N. Kong, "Security Services for the Registration Data Access Protocol (RDAP)", STD 95, RFC 7481, DOI 10.17487/RFC7481, March 2015, . - [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, @@ -1078,31 +1180,36 @@ [RFC9082] Hollenbeck, S. and A. Newton, "Registration Data Access Protocol (RDAP) Query Format", STD 95, RFC 9082, DOI 10.17487/RFC9082, June 2021, . [RFC9083] Hollenbeck, S. and A. Newton, "JSON Responses for the Registration Data Access Protocol (RDAP)", STD 95, RFC 9083, DOI 10.17487/RFC9083, June 2021, . -10.2. Informative References +11.2. Informative References [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, . [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running Code: The Implementation Status Section", BCP 205, RFC 7942, DOI 10.17487/RFC7942, July 2016, . + [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 + Authorization Server Metadata", RFC 8414, + DOI 10.17487/RFC8414, June 2018, + . + Appendix A. Change Log 00: Initial working group version ported from draft-hollenbeck- regext-rdap-openid-10. 01: Modified ID Token delivery approach to note proper use of an HTTP bearer authorization header. 02: Modified token delivery approach (Access Token is the bearer token) to note proper use of an HTTP bearer authorization header, fixing the change made in -01. 03: Updated OAuth 2.0 Device Authorization Grant description and @@ -1112,20 +1219,22 @@ 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. 09: Updated RDAP specification references. Added text to describe both local and remote Authorization Server processing. Removed text that described passing of ID Tokens as query parameters. + 10: Updated Section 3.1.3.1. Replaced token processing queries with + "login", "session", and "logout" queries. Author's Address Scott Hollenbeck Verisign Labs 12061 Bluemont Way Reston, VA 20190 United States of America Email: shollenbeck@verisign.com