RFC 9560

Federated Authentication for the Registration Data Access Protocol (RDAP) Using OpenID Connect

📅 published April 2024, from ietf

Federated Authentication for the Registration Data Access Protocol (RDAP) Using OpenID Connect ✨

Okay bestie, RFC 9560 is all about federated login for RDAP 🔐💖 Here are the title-block facts you need first:

  • Series: Internet Engineering Task Force (IETF) 🌸
  • Author: S. Hollenbeck, Verisign Labs 🎀
  • Category: Standards Track 👑
  • Date: April 2024 📅
  • ISSN: 2070-1721 🧚
  • Obsoletes / Updates: Neither is listed in this header, so there's nothing to report there 🙈

Abstract 🦋

RDAP gives you Representational State Transfer (RESTful) web services for grabbing registration metadata from domain name and regional internet registries. It lets a server make access control decisions based on who the client is, so it supports the client identification features that the Hypertext Transfer Protocol (HTTP) provides. The catch is that if every client has to collect and manage its own credentials from every RDAP server operator, it gets messy for both sides 😭 A federated authentication system would make RDAP easier to run and easier to use, because you wouldn't need server-specific client credentials. This document describes a federated authentication system for RDAP based on OpenID Connect. 💅

Status of This Memo

This is an Internet Standards Track document. ✨

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841. 📚

Info about the current status of this document, any errata, and how to send feedback is at https://www.rfc-editor.org/info/rfc9560. 🔗

Copyright (c) 2024 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, because they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions, and they are provided without warranty as described in the Revised BSD License. ⚖️

Table of Contents 🗺️

1.  Introduction
  1.1.  Problem Statement
  1.2.  Approach
2.  Conventions Used in This Document
3.  Federated Authentication for RDAP
  3.1.  RDAP and OpenID Connect
    3.1.1.  Terminology
    3.1.2.  Client Considerations
    3.1.3.  Overview
    3.1.4.  RDAP Authentication and Authorization Steps
      3.1.4.1.  Provider Discovery
      3.1.4.2.  Authentication Request
      3.1.4.3.  End User Authorization
      3.1.4.4.  Authorization Response and Validation
      3.1.4.5.  Token Processing
      3.1.4.6.  Delivery of User Information
    3.1.5.  Specialized Claims and Authorization Scope for RDAP
      3.1.5.1.  Stated Purposes
      3.1.5.2.  Do Not Track
4.  Common Protocol Features
  4.1.  OpenID Connect Configuration
  4.2.  RDAP Query Parameters
    4.2.1.  RDAP Query Purpose
    4.2.2.  RDAP Do Not Track
    4.2.3.  Parameter Processing
5.  Protocol Features for Session-Oriented Clients
  5.1.  Data Structures
    5.1.1.  Session
    5.1.2.  Device Info
  5.2.  Client Login
    5.2.1.  End-User Identifier
    5.2.2.  OP Issuer Identifier
    5.2.3.  Login Response
    5.2.4.  Clients with Limited User Interfaces
      5.2.4.1.  UI-Constrained Client Login
      5.2.4.2.  UI-Constrained Client Login Polling
  5.3.  Session Status
  5.4.  Session Refresh
  5.5.  Client Logout
  5.6.  Request Sequencing
6.  Protocol Features for Token-Oriented Clients
  6.1.  Client Login
  6.2.  Client Queries
  6.3.  Access Token Validation
  6.4.  Token Exchange
7.  RDAP Query Processing
8.  RDAP Conformance
9.  IANA Considerations
  9.1.  RDAP Extensions Registry
  9.2.  JSON Web Token Claims Registry
  9.3.  RDAP Query Purpose Registry
10. Security Considerations
  10.1.  Authentication and Access Control
11. References
  11.1.  Normative References
  11.2.  Informative References
Acknowledgments
Author's Address

1. Introduction 🎀

RDAP gives you RESTful web services for pulling registration metadata from domain name and regional internet registries. It lets a server make access control decisions based on client identity, which is why it supports the client identification features of HTTP [RFC9110]. 💅

RDAP is specified in several documents, including "HTTP Usage in the Registration Data Access Protocol (RDAP)" [RFC7480], "Security Services for the Registration Data Access Protocol (RDAP)" [RFC7481], "Registration Data Access Protocol (RDAP) Query Format" [RFC9082], and "JSON Responses for the Registration Data Access Protocol (RDAP)" [RFC9083]. [RFC7481] describes client identification and authentication services that can be used with RDAP, but it doesn't say how any of those services can (or should) be used with RDAP. 🤔

1.1. Problem Statement 😩

The conventional "username and password" method doesn't scale well in the RDAP ecosystem. Assuming every domain name and address registry eventually provides RDAP service, it's impractical and inefficient for users to get login credentials from hundreds of different server operators. Username and password methods also don't give server operators enough detail about the user (while still protecting the user's personal privacy) to make fine-grained access control decisions based on identity. The authentication system used for RDAP needs to cover all of these needs. ✨

1.2. Approach 🧩

A basic level of RDAP service can be offered to users who have an identifier issued by a recognized provider that can authenticate and validate them. For example, identifiers issued by social media services can be used. Users who need a higher level of service (and who are willing to share more information about themselves to get it) can get identifiers from specialized providers who are or will be able to supply more detailed information about them. Server operators can then make access control decisions based on the identification information the user provides. 👑

A federated authentication system, where an RDAP server hands off identification and authentication to a trusted identity provider, would make RDAP easier to run and use, because it reuses existing identifiers to provide a basic level of access. It can also collect additional identification information, and that information can be shared with the RDAP server operator with the user's consent to help the operator make access control decisions. This kind of system lets an RDAP server make access control decisions based on the nature of a query and on the identity, authentication, and authorization information it receives from the identity provider. This document describes a federated authentication system for RDAP based on OpenID Connect [OIDC] that meets these needs. 🌸

2. Conventions Used in This Document 📖

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 🫶

All of the HTTP requests described in this document that are sent from an RDAP client to an RDAP server use the HTTP GET method as specified in [RFC9110]. 🍓

Long lines in examples are wrapped using "The Single Backslash Strategy" described in [RFC8792]. 🌈

3. Federated Authentication for RDAP 🔐

RDAP doesn't have built-in security services on its own. Instead, it relies on features from other protocol layers to provide the security services it needs: access control, authentication, authorization, availability, data confidentiality, data integrity, and identification. You can find a description of each of these in "Internet Security Glossary, Version 2" [RFC4949]. This document focuses on a federated authentication system for RDAP that provides authentication, authorization, and identification services so a server operator can make access control decisions. Section 3 of [RFC7481] describes general considerations for RDAP access control, authentication, and authorization. 🧚

The conventional client-server authentication model requires clients to keep separate credentials for every RDAP server. That gets unwieldy as the number of RDAP servers grows. Federated authentication mechanisms let clients use one credential to access multiple RDAP servers, which reduces the complexity of managing client credentials. 💖

3.1. RDAP and OpenID Connect 🦋

OpenID Connect 1.0 [OIDCC] is a decentralized, Single Sign-On (SSO) federated authentication system. It lets users access multiple web resources with one identifier, instead of creating a separate server-specific identifier for each one. Users get their identifiers from OpenID Providers (OPs). Relying Parties (RPs) are applications (such as RDAP) that outsource their user authentication function to an OP. OpenID Connect is built on top of the authorization framework provided by the OAuth 2.0 protocol [RFC6749]. 🌟

The OAuth authorization framework describes a way for users to access protected web resources without handing out their credentials. Instead, clients are issued access tokens by OPs, with the permission of the resource owners. With OpenID Connect and OAuth, multiple RDAP servers can form a federation, and clients can access any server in that federation by presenting one credential registered with any OP in the federation. The OAuth authorization framework is designed for use with HTTP, so it can be used with RDAP. 👑

3.1.1. Terminology ✨

okay bestie, let's get the vocab down first 📚 this document uses the following terms, and some of them are borrowed from other specs 🫶

Terms defined by [RFC7480]:

  • client
  • server

Terms defined by [RFC6749]:

  • access token
  • authorization code
  • authorization endpoint
  • authorization grant
  • client authentication
  • client identifier
  • protected resource
  • refresh token
  • resource owner
  • resource server
  • token endpoint

Terms defined by [RFC7519]:

  • claim name
  • claim value
  • JSON Web Token (JWT)

Terms defined by [OIDCC]:

  • ID Token
  • UserInfo Endpoint

Term defined by [RFC9068]:

  • JWT access token

Extra terms from Section 1.2 of the OpenID Connect Core specification are incorporated by reference, so they come along for the ride too 💜

This document uses the words "remote" and "default" to describe how an RDAP server relates to the OPs it talks to 🌸 a "remote" OP is one that the RDAP client identifies by giving either an Issuer Identifier or an end-user identifier in a login request. Whether an Issuer Identifier or end-user identifier can be given in the login request to pick an OP can be figured out by retrieving the RDAP server's OIDC configuration details (see Section 4.1). A "default" OP is the one the RDAP server uses when the RDAP client doesn't give an Issuer Identifier or an end-user identifier in the login request. Simple, but important 🧚

This document uses the term "session" to describe a set of interactions between an RDAP client and an RDAP server during a given period of time ⏳ for session-oriented clients (see Section 3.1.2), the RDAP session is a typical HTTP session. It starts with a farv1_session/login request and ends with either a farv1_session/logout request (see Section 5 for a description of both path segments) or a timeout. For token-oriented clients (see Sections 3.1.2 and 6), the RDAP session lines up with the lifespan of an authorization obtained from an OP and the matching access token, including any refreshed access tokens 🔥

3.1.2. Client Considerations

okay so there are two flavors of client here, and they're both giving different energy 🎀

Clients that hand off OIDC authentication to an RDAP server as part of session-oriented interactions, and that can accept and process HTTP cookies [RFC6265] to keep the session going, are called "session-oriented" clients 🍓 this kind of RDAP client is playing the role of a user agent [RFC9110]. The RDAP server plays the role of an OpenID Connect Core Relying Party (RP). A web browser used to send queries straight to an RDAP server is a classic example of a session-oriented client 🌈 specs for this type of client live in Section 5.

Clients that do OIDC authentication themselves, acting as an RP when talking to an OP and sending access tokens [RFC6749] to an RDAP server to authorize RDAP queries, are called "token-oriented" clients 💅 the RDAP server acts as a resource server [RFC6749] here, checking the tokens it gets from the client, and it also does RP stuff to pull info from the OP when it needs to make access control decisions 👑 a web browser running JavaScript that came from a web service, and that sends queries to an RDAP server directly or through its back-end web service, is an example of a token-oriented client ✨ specs for this type of client live in Section 6.

Clients MAY operate as either session-oriented or token-oriented clients, but they MUST do so consistently by not mixing token-oriented and session-oriented requests while interacting with an OP 🙈 this is a big deal, so don't skip it bestie 😭

Servers SHOULD support both types of client to maximize interoperability, but they MAY choose to support only one type of client if local policy or operating conditions call for it 🦋 a server that doesn't support a particular client type will not support the protocol features (the data structures, path segments, parameters, and interactions) specified for that client type 💀 server signaling of supported client types is described in Section 4.1 🫶

3.1.3. Overview ✨

okay so, big picture time 🦋 RDAP authentication for a session-oriented client using OpenID Connect goes through these steps:

  1. An RDAP client sends an RDAP "help" query to an RDAP server to figure out the types and capabilities of the OPs that the RDAP server uses. This info comes back in the rdapConformance section of the response. A value of farv1 means the server supports the extension described in this specification. If one or more remote OPs are supported, the RDAP client SHOULD evaluate the additional information described in Section 4.1 to discover the capabilities of the RDAP server and optionally get the set of supported OPs, unless that information came from a trusted out-of-band source and has already been processed.
  2. An RDAP client sends an RDAP "login" request to an RDAP server as described in Section 5.2.
  3. The RDAP server prepares an Authentication Request with the desired request parameters. 📝
  4. The RDAP server sends an Authentication Request to an OP authorization endpoint and redirects the RDAP client to the OP using an HTTP redirect. ↪️
  5. The OP authenticates the end user. 🔐
  6. The OP obtains end-user consent and authorization. 🙋‍♀️
  7. The OP sends the RDAP client back to the RDAP server with an authorization code using an HTTP redirect.
  8. The RDAP server requests tokens using the authorization code at the OP's 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 tokens as described in [OIDCC] and retrieves the claims tied to the end user's identity from the OP's UserInfo Endpoint. 💅

Here's the sequence diagram, because pictures are everything 🎀

   End          OpenID         RDAP                 RDAP
   User        Provider       Client               Server
     |             |             |                    |
     |             |             |-----Help Query---->|
     |             |             |                    |
     |             |             |<---Help Response---|
     |             |             |                    |
     |-------Login Request------>|                    |
     |             |             |                    |
     |             |             |---Login Request--->|
     |             |             |                    |
     |             |<-----Authentication Request------|
     |             |             |                    |
     | Credential--|             |                    |
     |<--Request   |             |                    |
     |             |             |                    |
     |--Credential |             |                    |
     |   Response->|             |                    |
     |             |             |                    |
     |             |-----Authentication Response----->|
     |             |             |                    |
     |             |<----------Token Request----------|
     |             |             |                    |
     |             |-----------Token Response-------->|
     |             |             |                    |
     |             |<----------Claim Request----------|
     |             |             |                    |
     |             |-----------Claim Response-------->|
     |             |             |                    |
     |             |             |<--Login Response---|
     |             |             |                    |
     |<------Login Response------|                    |
     |             |             |                    |
     |----------RDAP Query------>|                    |
     |             |             |                    |
     |             |             |-----RDAP Query---->|
     |             |             |                    |
     |             |             |<---RDAP Response---|
     |             |             |                    |
     |<------RDAP Response-------|                    |

                                  Figure 1

The RDAP server can then make identification, authorization, and access control decisions based on end-user identity info and local policies 👑. Note that OpenID Connect describes different process flows for other types of clients, such as script-based or command-line clients. 🧚

RDAP authentication of a token-oriented client using OpenID Connect goes through these steps, and it's a little different, bestie 🌈:

  1. An RDAP client sends an RDAP "help" query to an RDAP server to figure out the type and capabilities of the OPs that the RDAP server uses. This info comes back in the rdapConformance section of the response. A value of farv1 means the server supports the extension described in this specification. If one or more remote OPs are supported, the RDAP client SHOULD evaluate the additional information described in Section 4.1 to discover the capabilities of the RDAP server and optionally get the set of supported OPs. Support for token-oriented clients requires a default OP. 🍓
  2. The RDAP client determines the end user's OP and confirms that it's supported by the RDAP server.
  3. The RDAP client sends an Authentication Request to the OP's authorization endpoint.
  4. The OP authenticates the end user. 🔐
  5. The OP obtains end-user consent or authorization.
  6. The OP returns an authorization code to the RDAP client.
  7. The RDAP client requests tokens using the authorization code at the OP's token endpoint.
  8. The RDAP client receives a response that contains an ID Token and an access token in the response body.
  9. The RDAP client monitors the token validity period and either refreshes the token or requests new tokens as necessary. ⏰
  10. The RDAP client sends queries that require user identification, authentication, and authorization to an RDAP server. These include an access token in an HTTP authorization header using the bearer authentication scheme described in [RFC6750]. 🔑
  11. The RDAP server validates the access token and retrieves the claims tied to the end user's identity from the OP's UserInfo Endpoint.
  12. The RDAP server determines the end user's authorization level and processes the query according to server policies. ✨

And the token-oriented diagram, fr fr 💜:

   End          OpenID         RDAP                 RDAP
   User        Provider       Client               Server
     |             |             |                    |
     |             |             |-----Help Query---->|
     |             |             |                    |
     |             |             |<----Help Response--|
     |             |             |                    |
     |-------Login Request------>|                    |
     |             |             |                    |
     |             |<-Authentication                  |
     |             |   Request---|                    |
     |             |             |                    |
     |<-Credential |             |                    |
     |   Request---|             |                    |
     |             |             |                    |
     |--Credential |             |                    |
     |   Response->|             |                    |
     |             |             |                    |
     |             |--Authentication                  |
     |             | Response--->|                    |
     |             |             |                    |
     |             |<-Token      |                    |
     |             |  Request----|                    |
     |             |             |                    |
     |             |--Token      |                    |
     |             |  Response-->|                    |
     |             |             |                    |
     |<------Login Response------|                    |
     |             |             |                    |
     |-----RDAP Query----------->|                    |
     |             |             |                    |
     |             |             |----RDAP Query----->|
     |             |             |                    |
     |             |<------------Claim                |
     |             |            Request---------------|
     |             |             |                    |
     |             |-------------Claim                |
     |             |            Response------------->|
     |             |             |                    |
     |             |             |<---RDAP Response---|
     |             |             |                    |
     |<----RDAP Response---------|                    |

                                  Figure 2

3.1.4. RDAP Authentication and Authorization Steps 🦋

End users MAY present an identifier (an OpenID) issued by an OP to use OpenID Connect with RDAP. If the RDAP server supports a default OP or if provider discovery is not supported, the end-user identifier MAY be omitted. An OP SHOULD include support for the claims described in Section 3.1.5 to provide the extra info needed for RDAP end-user authorization. Without these claims, clients and servers MAY make authorization and access control decisions as appropriate, based on any other info returned from the OP. 🫶

OpenID Connect requires RPs to register with OPs before they can use OpenID Connect services for an end user. Registration is often done with out-of-band methods, but it's also possible to use the automated method described by the OpenID Connect Dynamic Client Registration protocol [OIDCR]. The parties involved can use any method that's mutually acceptable. 🤝

3.1.4.1. Provider Discovery 🔍

An RDAP server acting as an RP needs to be able to map an end user's identifier to an OP. This can be done using the OPTIONAL OpenID Connect Discovery protocol [OIDCD], but that protocol isn't widely implemented, sadly 😭. Out-of-band methods are also possible and can be more dependable. For example, an RP can support a limited number of OPs and keep internal associations of those identifiers with the OPs that issued them. 🗂️

Alternatively, if mapping an end user's identifier isn't possible, or isn't supported by the RDAP server, the RDAP server SHOULD support explicit specification of a remote OP by the RDAP client, in the form of a query parameter as described in Section 5.2.2. The exception is when the remote OP has already been identified using an out-of-band mechanism. An RDAP server MUST provide info about its capabilities and supported OPs in the "help" query response, in the farv1_openidcConfiguration data structure described in Section 4.1. An RDAP server acting as an RP MUST support at least one of these methods of OP discovery. 💖

3.1.4.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 [OIDCC]. ✨ Which path it takes (authorization, implicit, or hybrid) depends on the response_type the RP sets in that request. For the rest of these steps, we're assuming the authorization code flow, so the request has response_type=code in it. 💖

The authorization code flow is the one you want for authenticating a human user, and Section 3.1 of [OIDCC] explains why. 🎀 The Implicit Flow is more common with clients running in a web browser using a scripting language, and it's covered in Section 3.2 of [OIDCC]. Just so you know, at the time of writing, the Implicit Flow is considered insecure, and people are working to deprecate it. 💀 The Hybrid Flow (Section 3.3 of [OIDCC]) is the mix: it blends the authorization code and Implicit Flows by returning some tokens from the authorization endpoint and the rest from the token endpoint. 🦋

An Authentication Request can carry several parameters. The REQUIRED ones are listed in Section 3.1.2.1 of [OIDCC]. Beyond those, it is RECOMMENDED that the RP include the optional login_hint parameter, with its value set to the farv1_id query parameter from the end user's RDAP login request, if one was provided. 🌸 Passing login_hint lets a client pre-fill the login form, which makes logging in way smoother for users. Other parameters MAY be included too. ✨

When the OP gets the Authentication Request, it tries to validate it as described in Section 3.1.2.2 of [OIDCC]. If the request checks out, the OP tries to authenticate the end user as described in Section 3.1.2.3 of [OIDCC]. If the request isn't valid, or if any error shows up along the way, the OP sends back an error response. 🙈

3.1.4.3. End User Authorization

After the end user is authenticated, the OP MUST obtain consent from the end user to release authorization information to the RDAP server acting as an RP. 🔐 This process is described in Section 3.1.2.4 of [OIDCC]. Consent is non-negotiable, bestie. 💅

3.1.4.4. Authorization Response and Validation

Once the OP has an authorization result, it sends a response to the RP that carries that result using an authorization code. 🦋 The RP MUST validate the response. This process is described in Sections 3.1.2.5 - 3.1.2.7 of [OIDCC]. Validation is a must, periodt. 👑

3.1.4.5. Token Processing

The RP sends a token request to a token endpoint, using the authorization grant, and gets back a token response. That response holds an access token, an ID Token, and an OPTIONAL refresh token. 🧚 The RP MUST validate the token response. This process is described in Section 3.1.3.5 [OIDCC]. ✨

3.1.4.6. Delivery of User Information

The set of claims can be fetched by sending a request to a UserInfo Endpoint with the access token. 💜 The claims also come back in the ID Token. The process for retrieving claims from a UserInfo Endpoint is described in Section 5.3 of [OIDCC].

OpenID Connect defines a set of standard claims in Section 5.1 of [OIDCC]. The extra claims made for RDAP are described in Section 3.1.5. 🌈

3.1.5. Specialized Claims and Authorization Scope for RDAP

OpenID Connect claims are pieces of information used to make assertions about an entity. 🧠 Section 5 of [OIDCC] describes a set of standard claims. Section 5.1.2 of [OIDCC] notes that additional claims MAY be used, and it describes how to create them. The claims that are specific to RDAP are tied to an OAuth scope request parameter value (see Section 3.3 of [RFC6749]) of "rdap". 🎀

3.1.5.1. Stated Purposes

Communities of RDAP users and operators may want to make and validate claims about a user's "need to know" when they request access to a protected resource. 🕵️‍♀️ For example, a law enforcement agent or a trademark attorney might want to assert that they have a legal right to access a protected resource, and a server operator might need to receive and validate that claim. We can handle all of this by defining and using an additional "rdap_allowed_purposes" claim. 💖

The "rdap_allowed_purposes" claim identifies the purposes for which an end user can request access to a protected resource. Using this claim is OPTIONAL. Processing it depends on the server accepting the purposes, the trust level the server assigns to the claim, and the end user being successfully authenticated. Unrecognized purpose values MUST be ignored, and the associated query MUST be processed as if the unrecognized purpose value was not present at all. 🙃 See Section 9.3 for a description of the IANA considerations associated with this claim. 🍓

The "rdap_allowed_purposes" claim is an array of case-sensitive StringOrURI values, as specified in Section 2 of [RFC7519]. Here's an example:

"rdap_allowed_purposes": ["domainNameControl","dnsTransparency"]

Identity providers assign purpose values to an end user's credential. Identity providers MUST ensure that appropriate purpose values are only assigned to end user identities that are authorized to use them. 🔒 No handing out purposes to just anybody, iykyk. 😤

3.1.5.2. Do Not Track

Communities of RDAP users and operators may want to make and validate claims about a user's wish to not have their queries logged, tracked, or recorded. 🫣 For example, a law enforcement agent may want to assert that their queries are part of a criminal investigation and shouldn't be tracked, because query exposure could compromise the investigation. A server operator might need to receive and validate that claim. These needs can be met by defining and using an additional "do not track" claim. 🦋

The "do not track" (rdap_dnt_allowed) claim can be used to identify an end user who is authorized to make queries without the end user's association with those queries being logged, tracked, or recorded by the server. Using the rdap_dnt_allowed claim is OPTIONAL on the client side. Server operators MUST NOT log, track, or record any association between the query and the end user's identity if all of these are true: the end user is successfully identified and authorized, the rdap_dnt_allowed claim is present, the value of the claim is "true", and accepting the claim complies with local regulations on logging and tracking. 🚫📝 That's a big deal, so read it twice. 👀

The rdap_dnt_allowed value is a JSON boolean literal. Here's an example:

rdap_dnt_allowed: true

No special query tracking processing is required if the claim isn't present, or if its value is "false". 💤 Use of this claim MUST be limited to end users who are granted "do not track" privileges in accordance with service policies and regulations. Specifying those policies and regulations is beyond the scope of this document. 📜

4. Common Protocol Features ✨

As described in Section 3.1.4.1, an RDAP server MUST provide information about its capabilities and supported OPs in a "help" query response. 🌷 This specification describes a new "farv1_openidcConfiguration" data structure. It describes the OpenID Connect configuration and the related extension features the RDAP server supports. This data structure is returned to all client types. 💜

4.1. OpenID Connect Configuration

The "farv1_openidcConfiguration" data structure is an object with the following members:

  • "sessionClientSupported": (REQUIRED) a boolean value that describes RDAP server support for session-oriented clients (see Section 3.1.2). 🍪
  • "tokenClientSupported": (REQUIRED) a boolean value that describes RDAP server support for token-oriented clients (see Section 3.1.2). 🎟️
  • "dntSupported": (REQUIRED) a boolean value that describes RDAP server support for the "farv1_dnt" query parameter (see Section 4.2.2). 🙈
  • "providerDiscoverySupported": (OPTIONAL) a boolean value that describes RDAP server support for discovery of providers of end-user identifiers. The default value is "true". 🔍
  • "issuerIdentifierSupported": (OPTIONAL) a boolean value that describes RDAP server support for explicit client specification of an Issuer Identifier. The default value is "true". 🪪
  • "implicitTokenRefreshSupported": (OPTIONAL) a boolean value that describes RDAP server support for implicit token refresh. The default value is "false". 🔄
  • "openidcProviders": (OPTIONAL) a list of objects with the following members that describes the set of OPs supported by the RDAP server. This data is RECOMMENDED if the value of issuerIdentifierSupported is "true": 🏢
    • "iss": (REQUIRED) a URI value that represents the Issuer Identifier of the OP as per the OpenID Connect Core specification [OIDCC]. 🌐
    • "name": (REQUIRED) a string value representing the human-friendly name of the OP. 🏷️
    • "default": (OPTIONAL) a boolean value that describes RDAP server support for an OPTIONAL default OP. That default OP is used when a client omits the "farv1_id" and "farv1_iss" query parameters from a "farv1_session/login" request. Only one member of this set can be identified as the default OP, by setting its value to true. The default value is "false". 👑
    • "additionalAuthorizationQueryParams": (OPTIONAL) an object where each member represents an OAuth authorization request parameter name-value pair supported by the OP. The name represents an OAuth query parameter, and the value is that query parameter's value. A token-oriented RDAP client SHOULD add these query parameters and their corresponding values to the Authentication Request URL when requesting authorization by a specified OP through a proxy OP. 🧩

An RDAP server MUST set either the "sessionClientSupported" or the "tokenClientSupported" value to "true". Both values MAY be set to "true" if the RDAP server supports both types of clients. 🤝

The "providerDiscoverySupported" value directly affects how the "farv1_id" query parameter is used, which is described in Sections 3.1.4.2 and 5.2.1. The value of "providerDiscoverySupported" MUST be "true" for an RDAP server to properly accept and process "farv1_id" query parameters. 🎯 Similarly, the "issuerIdentifierSupported" value directly affects the use of the "farv1_iss" query parameter, described in Section 5.2.2. The value of "issuerIdentifierSupported" MUST be "true" for an RDAP server to properly accept and process "farv1_iss" query parameters. 🧐

Here's an example of a "farv1_openidcConfiguration" data structure:

"farv1_openidcConfiguration": {
  "sessionClientSupported": true,
  "tokenClientSupported": true,
  "dntSupported": false,
  "providerDiscoverySupported": true,
  "issuerIdentifierSupported": true,
  "openidcProviders":
    [
      {
        "iss": "https://idp.example.com",
        "name": "Example IDP"
      },
      {
        "iss": "https://accounts.example.net",
        "name": "Login with EXAMPLE",
        "additionalAuthorizationQueryParams": {
          "kc_idp_hint": "examplePublicIDP"
        }
      },
      {
        "iss": "https://auth.nic.example/auth/realms/rdap",
        "name": "Default OP for the Example RDAP server",
        "default": true
      }
    ]
}

                              Figure 3

4.2. RDAP Query Parameters ✨

okay so this spec gives RDAP two OPTIONAL query parameters for queries that want info behind protected resources 🔐. they're totally optional, but bestie, they're iconic:

  • farv1_qp: tells the server WHY you're asking 🎯
  • farv1_dnt: asks the server not to log or record info about the identity behind the query 🙈

One or both parameters MAY be added to an RDAP request URI, using the syntax in Section "application/x-www-form-urlencoded" of [HTMLURL] 💅

4.2.1. RDAP Query Purpose 🎯

this query is a key=value pair. the key is farv1_qp, and the value is a single query purpose string picked from the set of allowed purposes tied to the end user's identity (see Section 3.1.5.1) 💖. if it's there, the server SHOULD compare the value to the rdap_allowed_purposes claim values for that end user and make sure the purpose is in the allowed set.

the RDAP server MAY choose to ignore both the requested purpose and the rdap_allowed_purposes claim values if they clash with local server policy. the server MUST return an HTTP 403 (Forbidden) response if the requested purpose is not an allowed purpose 🚫.

if farv1_qp isn't there, the server MUST still process the query and make an access control decision using any other info it knows about the end user and what they're asking for ✨. for example, a server MAY treat the request like it came from an unidentified or unauthenticated user and return either an error or an appropriate subset of the available data 🌸

example domain query using farv1_qp:

https://example.com/rdap/domain/example.com?farv1_qp=legalActions

Figure 4

4.2.2. RDAP Do Not Track 🙈

this query is a key=value pair. the key is farv1_dnt, and the value is a single boolean value 🫶. true means the end user is asking that their query is not tracked or logged, following server policy. false means the end user is cool with their query being tracked or logged, again following server policy.

the server MUST return an HTTP 403 (Forbidden) response if it can't perform the action this parameter asks for 😭. example domain query using farv1_dnt:

https://example.com/rdap/domain/example.com?farv1_dnt=true

Figure 5

4.2.3. Parameter Processing 🧚

Unrecognized query parameters MUST be ignored 🫠. an RDAP server that processes an authenticated query MUST figure out whether the end-user identification info is tied to an OP that the server recognizes and supports 👀. RDAP servers MUST reject queries whose identification info isn't tied to a supported OP, by returning an HTTP 400 (Bad Request) response 🚩.

if a server gets a query with identification info tied to a recognized OP, it MUST do the steps needed to authenticate the user with that OP, process the query, and return an RDAP response that fits the end user's level of authorization and access 👑.

5. Protocol Features for Session-Oriented Clients 🦋

this spec adds these features to RDAP, the ones session-oriented clients usually need:

  1. Data structures that return info describing an established session, plus the info needed to set up a session for a UI-constrained device 📦.
  2. A query parameter to request authentication for a specific end-user identity 🔑.
  3. A query parameter to support authentication for a specific end-user identity on a device with a UI-constrained interface 📱.
  4. A query parameter to identify the purpose of the query 🎯.
  5. A query parameter to request that the server not log or otherwise record info about the identity associated with a query 🙈.
  6. Path segments to start, stop, refresh, and check the status of an authenticated session for a specific end-user identity 🔄.

5.1. Data Structures 💜

this spec describes two new data structures that send info back to a session-oriented client:

  • farv1_session: a data structure with info describing an established session 🎀.
  • farv1_deviceInfo: a data structure with info describing an active attempt to set up a session on a UI-constrained device 🧸.

5.1.1. Session 🎀

the farv1_session data structure is an object with these members:

  • userID: an OPTIONAL string value for the end-user identifier tied to the session.
  • iss: an OPTIONAL URI value for the issuer of the end-user identifier tied to the session.
  • userClaims: an OPTIONAL object with the set of claims tied to the end user's identity, based on the user info the OP gave (see Section 3.1.4.6) and that the RDAP server processed during authentication and authorization. what's possible here is decided by OP policy and RDAP server policy 🌈.
  • sessionInfo: an OPTIONAL object with two members:
    • tokenExpiration: an integer value for the number of seconds left in the access token's lifetime ⏳.
    • tokenRefresh: a boolean value that says whether the OP supports refresh tokens. as described in [RFC6749], support for refresh tokens is OPTIONAL.

note that every member of the farv1_session data structure is OPTIONAL 🫶. see Section 5.2.3 for when to return the minimum set of members.

here's an example farv1_session data structure:

  "farv1_session": {
    "userID": "user.idp.example",
    "iss": "https://idp.example.com",
    "userClaims": {
      "sub": "103892603076825016132",
      "name": "User Person",
      "given_name": "User",
      "family_name": "Person",
      "picture": "https://lh3.example.com/a-/AOh14=s96-c",
      "email": "user@example.com",
      "email_verified": true,
      "locale": "en",
      "rdap_allowed_purposes": [
        "domainNameControl",
        "personalDataProtection"
      ],
      "rdap_dnt_allowed": false
    },
    "sessionInfo": {
      "tokenExpiration": 3599,
      "tokenRefresh": true
    }
  }

Figure 6

5.1.2. Device Info 🧸

the flow in Section 3.1.4 needs the end user to interact with a server through a user interface that can process HTTP 🌐. this won't work well if the client is automated, or if the end user is on a command-line UI like curl (https://curl.se/) or wget (https://www.gnu.org/software/wget/) 💀. this can be handled with a web browser on a second device 📲.

the info the end user needs to type into that browser lives in the farv1_deviceInfo data structure. it's an object with the members described in Section 3.2 of [RFC8628] 🧚.

here's an example farv1_deviceInfo data structure:

  "farv1_deviceInfo": {
    "device_code": "AH-1ng2ezu",
    "user_code": "NJJQ-GJFC",
    "verification_uri": "https://www.example.com/device",
    "verification_uri_complete":
       "https://www.example.com/device?user_code=NJJQ-GJFC",
    "expires_in": 1800,
    "interval": 5
  }

Figure 7

5.2. Client Login 🔑

client authentication is requested by sending a farv1_session/login request to an RDAP server 💌. if the RDAP server supports only remote OPs, the farv1_session/login request MUST include at least one end-user identifier or OP Issuer Identifier 🫵.

the server sets an HTTP cookie, as described in [RFC6265], when it gets and successfully processes the farv1_session/login request 🍪. the client MUST include the session cookie from the server in any RDAP request within that session's scope. that includes farv1_session/refresh, farv1_session/status, and farv1_session/logout 🔄.

a farv1_session/login followed by another farv1_session/login that doesn't include an HTTP cookie MUST start a new session on the server, and that session MUST come with a new cookie 🆕. a server that gets a farv1_session/login followed by another farv1_session/login that DOES include an HTTP cookie MUST return an HTTP 409 (Conflict) response 🙅‍♀️.

to help lower the risk of resource starvation, a server MAY reject a farv1_session/login request and refuse to start a new session by returning an HTTP 409 (Conflict) response. this applies if a server-side maximum number of concurrent sessions per user exists and the client goes over that limit 🚧. also, an active session MAY be removed by the server because of timeout expiration, or because a maximum session lifetime has been exceeded ⏰. clients SHOULD proactively keep an eye on the tokenExpiration value for an active session, and refresh the session as needed for a positive user experience ✨.

5.2.1. End-User Identifier 🪪

the end-user identifier comes in one of two ways 🛎️. first, by adding a query component to an RDAP request URI, using the syntax in Section "application/x-www-form-urlencoded" of [HTMLURL]. second, by including an HTTP authorization request header for the Basic authentication scheme, as described in [RFC7617]. clients can use either method to deliver the end-user identifier to a server that supports remote OPs and provider discovery 💁‍♀️. servers that support remote OPs and provider discovery MUST accept both methods 🫶.

if the RDAP server supports a default OP, or if provider discovery isn't supported, the end-user identifier MAY be omitted 🙌.

the query parameter for the end-user identifier is an OPTIONAL key=value pair. the key is farv1_id, and the value is the client identifier issued by an OP 🎀. here's an example using the client identifier user.idp.example:

========== NOTE: '\' line wrapping per RFC 8792 ===========
https://example.com/rdap/farv1_session/\
login?farv1_id=user.idp.example

Figure 8

the authorization header for the Basic authentication scheme holds a base64-encoded version of the client identifier issued by an OP. no password is provided 🤫. here's an example for the client identifier user.idp.example:

https://example.com/rdap/farv1_session/login
Authorization: Basic dXNlci5pZHAuZXhhbXBsZQ==

Figure 9

and here's an example for use with a default OP 👑:

https://example.com/rdap/farv1_session/login

Figure 10

5.2.2. OP Issuer Identifier 🦋

Okay so the OP's Issuer Identifier gets delivered by tacking a query component onto an RDAP request URI, using the syntax from the section "application/x-www-form-urlencoded" of [HTMLURL] ✨. If the RDAP server supports a default OP, the Issuer Identifier MAY be omitted 🫶.

The query parameter is an OPTIONAL "key=value" pair 💜. The key is "farv1_iss" and the value is the Issuer Identifier associated with an OP. An RDAP server MAY accept Issuer Identifiers that aren't in the "farv1_openidcConfiguration" data structure, and it MAY also decide to accept specific Issuer Identifiers only from specific clients 👑. Here's an example for Issuer Identifier "https://idp.example.com":

========== NOTE: '\' line wrapping per RFC 8792 ===========
https://example.com/rdap/farv1_session/\
login?farv1_iss=https://idp.example.com

Figure 11

5.2.3. Login Response 🎀

The response to this request MUST be a valid RDAP response per [RFC9083] 📋. It MUST NOT include any members that relate to a specific RDAP object type (for example, "events" or "status") 🙅‍♀️. The response MAY include an indication of whether the operation succeeded or failed in the "notices" data structure. If it's successful, the response MUST include a "farv1_session" data structure that has a "sessionInfo" object and an OPTIONAL "userClaims" object ✨. If it's unsuccessful, the response MUST include a "farv1_session" data structure that leaves out the "userClaims" and "sessionInfo" objects 💀.

Here's an example of a successful "farv1_session/login" response:

    {
      "rdapConformance": [
        "farv1"
      ],
      "lang": "en-US",
      "notices": [
        {
          "title": "Login Result",
          "description": [
            "Login succeeded"
          ]
        }
      ],
      "farv1_session": {
        "userID": "user.idp.example",
        "iss": "https://idp.example.com",
        "userClaims": {
          "sub": "103892603076825016132",
          "name": "User Person",
          "given_name": "User",
          "family_name": "Person",
          "picture": "https://lh3.example.com/a-/AOh14=s96-c",
          "email": "user@example.com",
          "email_verified": true,
          "locale": "en",
          "rdap_allowed_purposes": [
            "domainNameControl",
            "personalDataProtection"
          ],
          "rdap_dnt_allowed": false
        },
        "sessionInfo": {
          "tokenExpiration": 3599,
          "tokenRefresh": true
        }
      }
    }

Figure 12

And here's an example of a failed "farv1_session/login" response:

    {
      "rdapConformance": [
        "farv1"
      ],
      "lang": "en-US",
      "notices": [
        {
          "title": "Login Result",
          "description": [
            "Login failed"
          ]
        }
      ],
      "farv1_session": {
        "userID": "user.idp.example",
        "iss": "https://idp.example.com"
      }
    }

Figure 13

5.2.4. Clients with Limited User Interfaces 📱

"OAuth 2.0 Device Authorization Grant" [RFC8628] gives you an OPTIONAL method to ask for user authorization from devices that have an Internet connection but don't have a proper browser for a more conventional OAuth flow 🥺. It works by having an end user grab a second device, like a smartphone with a web browser, and type in a code sequence that shows up on the UI-constrained device 📲.

5.2.4.1. UI-Constrained Client Login 🔐

Client authentication is requested by sending a "farv1_session/device" request to an RDAP server. If the RDAP server supports only remote OPs, the "farv1_session/device" request MUST include either an end-user identifier as described in Section 5.2.1 or an OP Issuer Identifier as described in Section 5.2.2 🌸.

Here's an example using wget for client identifier "user.idp.example":

   ========== NOTE: '\' line wrapping per RFC 8792 ===========
      wget -qO- "https://example.com/rdap/farv1_session/device\
      ?farv1_id=user.idp.example"

Figure 14

The authorization header for the Basic authentication scheme holds a base64-encoded version of the client identifier that an OP issued. No password is provided 🤫.

And here's an example using curl with an authorization header:

   ========== NOTE: '\' line wrapping per RFC 8792 ===========
      curl -H "Authorization: Basic dXNlci5pZHAuZXhhbXBsZQ=="\
      "https://example.com/rdap/farv1_session/device"

Figure 15

The response to this request MUST be a valid RDAP response per [RFC9083] 📋. It MUST NOT include any members that relate to a specific RDAP object type (for example, "events" or "status") 🙅‍♀️. The response MAY include an indication of whether the operation succeeded or failed in the "notices" data structure and, if it's successful, a "farv1_deviceInfo" data structure 🧚.

Here's an example of a "farv1_session/device" response:

  {
    "rdapConformance": [
      "farv1"
    ],
    "lang": "en-US",
    "notices": [
      {
        "title": "Device Login Result",
        "description": [
          "Login succeeded"
        ]
      }
    ],
    "farv1_deviceInfo": {
      "device_code": "AH-1ng2ezu",
      "user_code": "NJJQ-GJFC",
      "verification_uri": "https://www.example.com/device",
      "verification_uri_complete":
              "https://www.example.com/device?user_code=NJJQ-GJFC",
      "expires_in": 1800,
          "interval": 5
    }
  }

Figure 16

5.2.4.2. UI-Constrained Client Login Polling ⏳

After the "farv1_session/device" request is processed successfully, the client MUST send a "farv1_session/devicepoll" request to the RDAP server to keep the login going 💫. This request kicks off the polling function described in [RFC8628] on the RDAP server. The RDAP server polls the OP as described in Section 3.4 of [RFC8628], so it can wait for the end user to type in the information from the "farv1_session/device" request on their second device 🍓. Once the end user finishes, or if the process fails or times out, the OP responds to the polling requests with a success or failure indication 🎉. If the RDAP server supports only remote OPs, the "farv1_session/devicepoll" request MUST include either an end-user identifier as described in Section 5.2.1 or an OP Issuer Identifier as described in Section 5.2.2 🔥.

The "farv1_session/devicepoll" request MUST also include a "farv1_dc" query parameter. This query parameter is an OPTIONAL "key=value" pair, using the key "farv1_dc" and a value that holds the device_code returned in the response to the "farv1_session/device" request 🔑.

Here's an example using wget:

   ========== NOTE: '\' line wrapping per RFC 8792 ===========
      wget -qO- --keep-session-cookies --save-cookies cookie.txt\
      "https://example.com/rdap/farv1_session/devicepoll\
      ?farv1_id=user.idp.example&farv1_dc=AH-1ng2ezu"

Figure 17

And an example using curl:

   ========== NOTE: '\' line wrapping per RFC 8792 ===========
      curl -c cookie.txt "https://example.com/rdap/farv1_session/\
      devicepoll?farv1_id=user.idp.example&farv1_dc=AH-1ng2ezu"

Figure 18

The response to this request MUST use the response structures described in Section 5.2 💖. Once the device polling process has finished successfully, RDAP query processing can carry on as normal on the UI-constrained device 🌈.

5.3. Session Status 🌷

Clients MAY send a query to an RDAP server to check the status of an existing login session, using a "farv1_session/status" path segment 👀. Here's an example "farv1_session/status" request:

https://example.com/rdap/farv1_session/status

Figure 19

The response to this request MUST be a valid RDAP response per [RFC9083] 📋. It MUST NOT include any members that relate to a specific RDAP object type (for example, "events" or "status") 🙅‍♀️. The response MAY include an indication of whether the operation succeeded or failed in the "notices" data structure. If the operation succeeds and an active session exists, the response MUST include a "farv1_session" data structure that has a "sessionInfo" object and an OPTIONAL "userClaims" object 🫧. If the operation fails or there's no active session, the response MUST NOT include a "farv1_session" object 🚫.

Here's an example of a "farv1_session/status" response for an active session:

  {
    "rdapConformance": [
      "farv1"
    ],
    "lang": "en-US",
    "notices": [
      {
        "title": "Session Status Result",
        "description": [
          "Session status succeeded"
        ]
      }
    ],
    "farv1_session": {
      "userID": "user.idp.example",
      "iss": "https://idp.example.com",
      "userClaims": {
        "sub": "103892603076825016132",
        "name": "User Person",
        "given_name": "User",
        "family_name": "Person",
        "picture": "https://lh3.example.com/a-/AOh14=s96-c",
        "email": "user@example.com",
        "email_verified": true,
        "locale": "en",
        "rdap_allowed_purposes": [
          "domainNameControl",
          "personalDataProtection"
        ],
        "rdap_dnt_allowed": false
      },
      "sessionInfo": {
        "tokenExpiration": 3490,
        "tokenRefresh": true
      }
    }
  }

Figure 20

If the operation succeeds and there's no active session, the response MAY note the lack of an active session in the "notices" data structure. The "farv1_session" data structure MUST be omitted 🙈.

Here's an example of a "farv1_session/status" response with no active session:

  {
    "rdapConformance": [
      "farv1"
    ],
    "lang": "en-US",
    "notices": [
      {
        "title": "Session Status Result",
        "description": [
          "Session status succeeded",
          "No active session"
        ]
      }
    ]
  }

Figure 21

5.4. Session Refresh 🔄

Okay so, clients MAY slide into an RDAP server's DMs to refresh or extend an existing login session by hitting the "farv1_session/refresh" path segment 💌. The RDAP server MAY try to refresh the access token tied to the current session while it extends that session for a stretch of time the server picks ⏳. As [RFC6749] explains, OP support for refresh tokens is OPTIONAL 🤷‍♀️. The RDAP server MUST figure out whether the OP supports token refresh, then either ask for a refresh of the access token or send back a response saying refresh isn't supported by the OP in the "notices" data structure 🙅‍♀️. Here's an example request:

https://example.com/rdap/farv1_session/refresh

Figure 22

The response to this request MUST be a valid RDAP response per [RFC9083] 📜. It MUST NOT include any members that relate to a specific RDAP object type (e.g., "events" or "status") 🚫. The response MAY also say whether the operation worked or failed in the "notices" data structure ✅. The response MUST include a "farv1_session" data structure with a "sessionInfo" object and an OPTIONAL "userClaims" object 💁. If it fails but an active session still exists, the response MUST include a "farv1_session" data structure with a "sessionInfo" object and an OPTIONAL "userClaims" object 🫠. If it fails and there's no active session, the response MUST omit the "farv1_session" data structure 💀.

Here's what a successful "farv1_session/refresh" response looks like:

  {
    "rdapConformance": [
      "farv1"
    ],
    "lang": "en-US",
    "notices": [
      {
        "title": "Session Refresh Result",
        "description": [
          "Session refresh succeeded",
          "Token refresh succeeded."
        ]
      }
    ],
    "farv1_session": {
      "userID": "user.idp.example",
      "iss": "https://idp.example.com",
      "userClaims": {
        "sub": "103892603076825016132",
        "name": "User Person",
        "given_name": "User",
        "family_name": "Person",
        "picture": "https://lh3.example.com/a-/AOh14=s96-c",
        "email": "user@example.com",
        "email_verified": true,
        "locale": "en",
        "rdap_allowed_purposes": [
          "domainNameControl",
          "personalDataProtection"
        ],
        "rdap_dnt_allowed": false
      },
      "sessionInfo": {
        "tokenExpiration": 3599,
        "tokenRefresh": true
      }
    }
  }

Figure 23

Alternatively, an RDAP server MAY attempt to refresh an access token when a query comes in, if the access token tied to an existing session has expired and the matching OP supports token refresh 🔁. The default RDAP server behavior is spelled out in the "implicitTokenRefreshSupported" value inside the "farv1_openidcConfiguration" data structure (see Section 4.1) 🗺️.

If "implicitTokenRefreshSupported" is "true", the client MAY either explicitly try to refresh the session with the "farv1_session/refresh" query, or leave it to the RDAP server to try refreshing the session as needed when an RDAP query arrives 🪄. In this case, a server MUST attempt to refresh the access token when a query comes in if the access token tied to an existing session has expired and the matching OP supports token refresh. Servers MUST return an HTTP 401 (Unauthorized) response to a query if an attempt to implicitly refresh an existing session fails 🚪.

If "implicitTokenRefreshSupported" is "false", the client MUST explicitly attempt to refresh the session with the "farv1_session/refresh" query to extend an existing session 📣. If a session can't be extended for any reason, the client MUST establish a new session to keep authenticated query processing going, by submitting a "farv1_session/login" query 🔑. If the OP doesn't support token refresh, the client MUST submit a new "farv1_session/login" request to set up a new session once an access token has expired ♻️.

Clients SHOULD NOT send a "farv1_session/refresh" request when there's no active login session, because the request clashes with the server's current state 😬. Servers MUST return an HTTP 409 (Conflict) response if a "farv1_session/refresh" request arrives without a session cookie 🙅‍♀️.

5.5. Client Logout 👋

Clients MAY send a request to an RDAP server to end an existing login session 🚪. Ending a session is requested with the "farv1_session/logout" path segment. Access and refresh tokens can be revoked during the "farv1_session/logout" process, as described in [RFC7009], if the OP supports it (token revocation endpoint support is OPTIONAL per [RFC8414]) 🧹. When it's supported, this feature SHOULD be used so the tokens don't get mistakenly tied to a future RDAP session 🔒. Or, an RDAP server MAY try logging out from the OP using the OpenID Connect RP-Initiated Logout protocol [OIDCL], if the OP supports that protocol 👯. Either way, to stop abuse before the cookie times out, an RDAP server SHOULD invalidate the HTTP cookie tied to the session as part of ending it 🍪.

Here's an example "farv1_session/logout" request:

https://example.com/rdap/farv1_session/logout

Figure 24

The response to this request MUST be a valid RDAP response per [RFC9083] 📜. It MUST NOT include any members that relate to a specific RDAP object type (e.g., "events" or "status") 🚫. The response MAY also say whether the operation worked or failed in the "notices" data structure ✅. The "notices" data structure MAY include whether any attempt to log out from the OP, or to revoke the tokens issued by the OP, succeeded or failed 🧾.

Here's what a "farv1_session/logout" response looks like:

  {
    "rdapConformance": [
      "farv1"
    ],
    "lang": "en-US",
    "notices": [
      {
        "title": "Logout Result",
        "description": [
          "Logout succeeded"
          "Provider logout failed: Not supported by provider.",
          "Token revocation successful."
        ]
      }
    ]
  }

Figure 25

If there's no "logout" request, an RDAP session MUST be terminated by the RDAP server after a period of time the server defines 🕰️. The server SHOULD also take appropriate steps to make sure the tokens tied to the terminated session can't be reused 🛡️. That SHOULD include revoking the tokens, or logging out from the OP, if the OP supports either operation 💪.

5.6. Request Sequencing 🧩

The requests in this document usually happen in a specific order:

  1. "farv1_session/login" (or the related "farv1_session/device" and "farv1_session/devicepoll" requests) to start a session,
  2. "farv1_session/status" and/or "farv1_session/refresh" to manage a session,
  3. and "farv1_session/logout" to end a session.

If a client sends a "farv1_session/status", "farv1_session/refresh", or "farv1_session/logout" request without a session cookie, the server MUST return an HTTP 409 (Conflict) error 🚫.

A client can end a session explicitly by sending a "farv1_session/logout" request to the RDAP server 👋. A session can also end implicitly, when the server's defined period of time runs out ⌛. The status of a session can be checked at any time by sending a "farv1_session/status" query to the RDAP server 👀.

An RDAP server MUST keep session state information for as long as a session is active 🧠. This is commonly done with HTTP cookies, as described in [RFC6265] 🍪. That way, end users can submit queries without having to identify and authenticate themselves again for every single query 🫶.

An RDAP server might get queries that include a session cookie where the matching session has expired or is otherwise unavailable (e.g., because the user explicitly logged out of that session). The server MUST return an HTTP 401 (Unauthorized) error in response to such queries 🙈.

6. Protocol Features for Token-Oriented Clients 🪙

This specification adds extra processing steps for token-oriented clients, as covered in this section and Section 3.1.3 💅. It doesn't define any additional data structures or RDAP-specific protocol parameters just for token-oriented clients ✨.

6.1. Client Login 🔐

Clients identify and authenticate end users by exchanging information with an OP that the RDAP server recognizes, as described in Sections 3.1.4.2, 3.1.4.3, and 3.1.4.4 🤝. A client SHOULD append the "additionalAuthorizationQueryParams" values retrieved from the "openidcProviders" array described in Section 4.1 to the authorization endpoint URL when it asks the OP for authorization 🧁. Once those steps finish successfully, the client can request tokens from the OP as described in Section 3.1.4.5 🎟️. The OP SHOULD include the RDAP server's client_id in the "aud" claim value of an issued ID Token 💜. The RDAP server MAY choose to ignore the value of the "aud" claim, or exchange the token as described in Section 6.4 🔄. With all of that done, the access token from the OP can be passed to an RDAP server in an HTTP "authorization" request header [RFC6750] for RDAP queries that need end-user identification, authentication, and authorization 🦋.

6.2. Client Queries 🔍

An RDAP server that receives a bearer token in an HTTP "authorization" request header as part of an RDAP object query MUST validate the token according to local policy and confirm that the token is a legitimate access token 🕵️‍♀️. Once it's validated, the access token MAY be used to retrieve the claims tied to the end user's identity, including "rdap" scope claims that aren't already in the access token, as described in Section 3.1.4.6 🌸. The RDAP server can then look at the end user's identity information to work out the end user's authorization level, and process the query according to server policies 📋. A client MUST include the "farv1_iss" query parameter and Issuer Identifier value with an RDAP query if the token was issued by a remote OP 🌈.

6.3. Access Token Validation 🧐

An RDAP server MUST validate a received access token before using that token for access control purposes 🛂. Validation MAY include token introspection [RFC7662] using the issuing OP, or analysis of the values in a JWT access token 🔬. Once an access token is validated, an RDAP server MAY use that token to request user claims from the issuing OP 🙋‍♀️.

Validating a token and requesting user claims every time an RDAP query comes in has real performance costs ⚡. An RDAP server MAY cache validated information and use that cached information to speed up later RDAP queries tied to the same access token, as long as the token hasn't expired 🏎️. The client SHOULD monitor the token's expiration time and refresh the token as needed ⏰.

6.4. Token Exchange 🔁

okay so tokens can have an aud (audience) claim that holds the OAuth 2.0 client_id of the RP as an audience value 🎀 but in some setups (like when a client is running a proxy service) an RP can get tokens whose aud doesn't include its own client_id 😭 those tokens might not be trusted by the RP, so it might just refuse them. the fix is for the RP to swap its access token with the OP for a set of trusted tokens that reset the aud claim ✨ the token exchange protocol is in [RFC8693] bestie, go check it out 💜

7. RDAP Query Processing 🔍

once an RDAP session is active, an RDAP server MUST figure out whether the end user is allowed to make any queries that come in while the session is running 🧐 this MAY mean rejecting queries outright, and it MAY mean leaving out or redacting info the end user isn't authorized to see 🙈 the specific processing rules are out of scope for this doc, so that part's on the server side 💅

8. RDAP Conformance 🎀

RDAP responses that contain values described in this document MUST show they're conforming to this spec by including an rdapConformance [RFC9083] value of "farv1" (federated authentication method for RDAP version 1) 🌈 the info needed to register this value in the "RDAP Extensions" registry is in Section 9.1, go look there 🫶

Example rdapConformance structure with extension specified:

  "rdapConformance" :
    [
      "rdap_level_0",
      "farv1"
    ]

Figure 26 ✨

9. IANA Considerations 📋

9.1. RDAP Extensions Registry 🧚

IANA has registered the following value in the "RDAP Extensions" registry 💖

Extension Identifier:  farv1
Registry Operator:  Any
Specification:  RFC 9560
Contact:  IETF <iesg@ietf.org>
Intended Usage:  This extension describes federated authentication
   method for RDAP version 1 using OAuth 2.0 and OpenID Connect.

9.2. JSON Web Token Claims Registry 🍓

IANA has registered the following values in the "JSON Web Token Claims" registry, two of them, and they're both super important 🔥

Claim Name:  rdap_allowed_purposes
Claim Description:  This claim describes the set of RDAP query
   purposes that are available to an identity that is presented for
   access to a protected RDAP resource.
Change Controller:  IETF
Reference:  Section 3.1.5.1 of RFC 9560.

Claim Name:  rdap_dnt_allowed
Claim Description:  This claim contains a JSON boolean literal that
   describes a "do not track" request for server-side tracking,
   logging, or recording of an identity that is presented for access
   to a protected RDAP resource.
Change Controller:  IETF
Reference:  Section 3.1.5.2 of RFC 9560.

9.3. RDAP Query Purpose Registry 🦋

IANA has created a brand new protocol registry to manage RDAP query purpose values 🌸 the whole setup is below, verbatim, so nothing gets lost in translation 💅

Section at https://www.iana.org/protocols:  Registration Data Access
   Protocol (RDAP)
Registry Name:  Registration Data Access Protocol (RDAP) Query
   Purpose Values
Registration Procedure(s):  This registry is operated under the
   "Specification Required" policy defined in [RFC8126].  The
   designated expert must ensure that requests to add values to this
   registry meet the syntax, value, and description requirements
   described in this section.
Required Information:  Registration requests are described in a
   specification that's consistent with the "Specification Required"
   policy defined in [RFC8126].  The specification must include one
   or more purpose values as described below.

Individual purpose values get registered with IANA, and each entry in the registry has these fields 📝

Value:  The purpose string value being registered.  Value strings can
   contain uppercase ASCII characters from "A" to "Z", lowercase
   ASCII characters from "a" to "z", and the underscore ("_")
   character.  Value strings contain at least one character and no
   more than 64 characters.
Description:  One or two sentences in English describing the meaning
   of the purpose value, how it might be used, and/or how it should
   be interpreted by clients and servers.
Reference:  RFC 9560

The set of initial values used to fill the registry is derived from the final report from the Expert Working Group on gTLD Directory Services, which was chartered by the Internet Corporation for Assigned Names and Numbers (ICANN) [gTLD] 🌍 here are all the starter values, in order ✨

Value:  domainNameControl
Description:  Tasks within the scope of this purpose include, for a
   registrant's own domain name, creating the domain name, updating
   information about the domain name, transferring the domain name,
   renewing the domain name, deleting the domain name, maintaining a
   domain name portfolio, and detecting fraudulent use of the
   registrant's own contact information.
Reference:  RFC 9560

Value:  personalDataProtection
Description:  Tasks within the scope of this purpose include
   identifying the accredited privacy or proxy provider associated
   with a domain name, reporting abuse, requesting reveal, or
   otherwise contacting the provider.
Reference:  RFC 9560

Value:  technicalIssueResolution
Description:  Tasks within the scope of this purpose include (but are
   not limited to) working to resolve technical issues, including
   email delivery issues, DNS resolution failures, and website
   functionality issues.
Reference:  RFC 9560

Value:  domainNameCertification
Description:  Tasks within the scope of this purpose include a
   Certification Authority (CA) issuing an X.509 certificate to a
   subject identified by a domain name.
Reference:  RFC 9560

Value:  individualInternetUse
Description:  Tasks within the scope of this purpose include
   identifying the organization using a domain name to instill
   consumer trust or contacting that organization to raise a customer
   complaint to them or file a complaint about them.
Reference:  RFC 9560

Value:  businessDomainNamePurchaseOrSale
Description:  Tasks within the scope of this purpose include making
   purchase queries about a domain name, acquiring a domain name from
   a registrant, and enabling due diligence research.
Reference:  RFC 9560

Value:  academicPublicInterestDNSResearch
Description:  Tasks within the scope of this purpose include academic
   public interest research studies about domain names published in
   the registration data service, including public information about
   the registrant and designated contacts, the domain name's history
   and status, and domain names registered by a given registrant
   (reverse query).
Reference:  RFC 9560

Value:  legalActions
Description:  Tasks within the scope of this purpose include
   investigating possible fraudulent use of a registrant's name or
   address by other domain names, investigating possible trademark
   infringement, contacting a registrant's or licensee's legal
   representative prior to taking legal action, and then taking a
   legal action if the concern is not satisfactorily addressed.
Reference:  RFC 9560

Value:  regulatoryAndContractEnforcement
Description:  Tasks within the scope of this purpose include
   investigating the tax authority of businesses with online
   presences, investigating Uniform Domain-Name Dispute-Resolution
   Policy (UDRP), investigating contractual compliance, and
   registering data escrow audits.
Reference:  RFC 9560

Value:  criminalInvestigationAndDNSAbuseMitigation
Description:  Tasks within 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.
Reference:  RFC 9560

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 public.
Reference:  RFC 9560

10. Security Considerations 🚨

Security considerations for RDAP can be found in [RFC7481] 🔐 security considerations for OpenID Connect Core [OIDCC] and OAuth 2.0 [RFC6749] live in their reference specs, and the best current security practice for OAuth 2.0 is in [OAUTH-SECURITY] 💜 also, the practices described in [RFC9325] MUST be followed when the Transport Layer Security (TLS) protocol is used. no skipping that 😤

as described in Section 3.1.4.2, the OAuth 2.0 Implicit Flow [RFC6749] is considered insecure, and efforts are underway to deprecate it 💀 it MUST NOT be used. bestie, I'm serious, not even a little bit 🙅‍♀️

some of the responses in this spec send info from an RDAP server back to a client to help the client match responses to queries and manage sessions 🧠 some of that info, like the "userClaims" from Section 5.1.1, can be personally identifiable and sensitive if it reaches unauthorized people 😭 so an RDAP server operator has to build policies for information disclosure, making sure personally identifiable info only goes to clients that are authorized to handle it 🫶

the "do not track" claim depends on the good will of the RDAP server and its associated proxies 🙏 so using and processing this claim relies on out-of-band trust relationships that need to be set up before the claim is used in practice. if the RDAP server uses and accepts it, there's a risk of information loss that could seriously hurt audit capabilities 🥺 that's a lot, so be careful 💅

10.1. Authentication and Access Control 🗝️

once the client identification, authorization, and validation process is complete, an RDAP server can make access control decisions by comparing client-provided info (like the set of "userClaims" from Section 5.1.1) against local policy ✨ for example, a client who only provides an email address might get a subset of the info that a client providing an email address, a full name, and a stated purpose would get 👑 building those access control policies is beyond the scope of this document, so that's on you 🌈

11. References 📚

11.1. Normative References 📚

okay so these are the docs the spec needs you to read, no skipping bestie 🫶

11.2. Informative References 🌸

these ones are the extra reading, super helpful for context but not strictly required ✨

Acknowledgments 🫶

The author would like to shout out the following people for their contributions to the development of this document: Julien Bernard, Marc Blanchet, Tom Harrison, Russ Housley, Jasdip Singh, Rhys Smith, Jaromir Talir, Rick Wilhelm, 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. 👑

Pawel Kowalik and Mario Loffredo provided significant text contributions that led to welcome improvements in several sections of this document. Their contributions are greatly appreciated. 🌈

Author's Address 🦋

Scott Hollenbeck
Verisign Labs
12061 Bluemont Way
Reston, VA 20190
United States of America
Email: shollenbeck@verisign.com
URI:   https://www.verisignlabs.com/
📦 where this page comes from