Skip to content

Jake Federation Requirements Document

Jump to bottom
Michael Schwartz edited this page Oct 8, 2025 · 4 revisions

Requirements Document

Introduction

This specification describes the "Jake Federation", a trust framework to enable "WHOIS" requests by trusted entities. The Jake Federation is an OpenID Federation where participants--registries, registrars, and authorized requestor organizations--establish cryptographic relationships through a hierarchical trust model consisting of the Jake Federation Operator (root trust anchor) and Regional Trust Anchors (intermediate trust anchors), connected through signed entity statements and trust chains.

  1. Requestor Service ("Rqr"): Is a participant that makes requests for registrant data and agrees to manage the data according to the federation policies and procedures, including future obligations and restrictions.

  2. Data Holder ("DH"): Is a participant that protects registrant data, e.g. registrar or registry.

  3. Jake Federation Operator: The root trust anchor of the Jake Federation that serves as the ultimate source of trust for the entire federation ecosystem. The Jake Federation Operator operates at the top of the trust hierarchy and performs foundational functions:

    • Root Trust Establishment: Serves as the ultimate root of all trust chains in the Jake Federation
    • Regional Trust Anchor Authorization: Vets, authorizes, and publishes entity statements for Regional Trust Anchors
    • Federation-Wide Policy Definition: Establishes overarching policies and standards that apply across all regions
    • Root Token Status Management: Publishes OAuth Token Status Lists for federation-wide revocation management
    • Federation API Endpoints: Publishes OpenID Federation API endpoints for entity statement fetching, trust-mark status, and historical keys

  4. Regional Trust Anchor: Intermediate trust anchors authorized by the Jake Federation Operator that serve specific geographic regions or organizational domains. Regional Trust Anchors perform operational vetting and management functions:

    • Participant Vetting and Onboarding: Validate the identity and legitimacy of organizations seeking to join their region, including registries, registrars, and authorized requestor organizations
    • Entity Statement Publication and Management: Continuously publish and maintain signed JWT-based entity statements for their regional participants at well-known HTTPS endpoints. These entity statements contain each participant's current public keys, metadata, federation capabilities, and policy constraints
    • Regional Policy Enforcement: Define and enforce region-specific policies through metadata policies while adhering to federation-wide policies from the Jake Federation Operator
    • Trust Chain Facilitation: Enable trust chain resolution from their participants back to the Jake Federation Operator
    • Regional Token Status Management: Publish OAuth Token Status Lists for regional participant revocation management

Unlike traditional PKI Certificate Authorities, Trust Anchors in OpenID Federation enable dynamic trust establishment where entities can authenticate each other by resolving trust chains back to commonly trusted anchors, eliminating the need for pre-configured bilateral trust relationships or mutual TLS certificates.

The system replaces traditional WHOIS with a policy-driven, agreement-based approach where access to registration data is governed by formal agreements between vetted federation participants, ensuring appropriate data sharing while protecting privacy and complying with legal requirements.

Actors

Requestor Service ("Rqr"): A vetted organization that has legitimate need to request registrant data and has been approved by a Regional Trust Anchor. Examples include government agencies, intellectual property research firms, cybersecurity companies, law enforcement agencies, academic research institutions or public access requestor organizations.

Data Holder (DH): Organizations that hold registrant data. A DH could be either a registrars (who registers domains on behalf of registrants) or a registry (who manages top-level domains).

Registrant: A customer who registers a domain name.

Registrar: A company authorized to register domain names on behalf of registrants. Registrars maintain detailed registration information including registrant technical contact details and billing information.

Registry: An organization that manages a top-level domain (TLD) and maintains the authoritative database of domain names within that TLD. Note: a Registry may not store any registrant customer data.

System Administrator: Personnel responsible for managing and maintaining the information technology infrastructure.

Human Reviewer: Personnel at data holder organizations who manually review deferred registration data requests that require human judgment for approval or rejection.

Jake Federation Operator: The root trust anchor of the Jake Federation that serves as the ultimate source of trust for the entire federation ecosystem. The Jake Federation Operator operates at the top of the trust hierarchy and establishes federation-wide policies, authorizes Regional Trust Anchors, and maintains the root of all trust chains in the Jake Federation.

Regional Trust Anchor: Intermediate trust anchors authorized by the Jake Federation Operator that serve specific geographic regions or organizational domains. Regional Trust Anchors perform the operational functions of vetting participants (registries, registrars, and authorized requestor organizations), publishing and maintaining their entity statements, and enforcing both regional and federation-wide policies. Unlike traditional PKI Certificate Authorities, this hierarchical trust model enables participants to authenticate each other by resolving trust chains through Regional Trust Anchors back to the Jake Federation Operator, eliminating the need for pre-configured bilateral trust relationships or mutual TLS certificates.

jake-federation-user-stories

External Components

Federation Entity Endpoints: HTTPS endpoints where federation entities publish their current entity statements, enabling dynamic trust chain resolution and validation.

RDAP Server Discovery Service: An external service that accepts a domain name and returns the URL of the appropriate RDAP server that can provide information about that domain.

RDAP Server: The actual server that holds and serves registration data for specific domains, operated by registrars or registries.

Data Structures

Participant Agreement: A formal contract between groups of requestors and groups of data holders that defines access permissions, legal basis, maximum sensitivity levels, data elements that can be shared, and terms of use. Agreements reference federation entity identifiers rather than requiring separate Identity Provider configurations.

Transaction: A complete request-response cycle for registration data, including the initial request, any deferrals, and the final response (rejection or fulfillment).

Entity Statement: A signed JWT published and maintained by federation authorities (Jake Federation Operator or Regional Trust Anchors) at discoverable HTTPS endpoints that contains an entity's current metadata, public keys, and capabilities. Entity statements are living documents that are continuously updated and enable cryptographic verification of entity identity and authorization without requiring pre-configured trust relationships.

Trust Chain: A sequence of signed entity statements connecting a leaf entity (requestor or data holder) through a Regional Trust Anchor to the Jake Federation Operator, providing cryptographic proof of the entity's authorization to participate in the federation.

Entity Identifier: A globally unique HTTPS URL that identifies each federation entity and serves as the endpoint for fetching the entity's current entity statement.

Request Assertion: A signed JWT created by requestors using their federation private keys to authenticate individual registration data requests, eliminating the need for separate Identity Provider tokens.

Requirements

Requirement 1

User Story: As an authorized Requestor Service, I want to obtain registrant data using RDAP.

Acceptance Criteria

  1. WHEN an authorized requestor organization needs registration data THEN the system SHALL provide a cloud-based Rqr OAuth client for that organization to make RDAP requests
  2. WHEN the Rqr OAuth client needs to access a Data Holder's RDAP service THEN it SHALL perform Dynamic Client Registration (DCR) with the Data Holder's OAuth Provider (OP) to obtain client credentials
  3. WHEN performing DCR THEN the Rqr SHALL assert its entity identifier and sign the DCR request with the private key corresponding to the public key in its entity statement, enabling the Data Holder's OP to fetch the entity statement from the Regional Trust Anchor and cryptographically verify the requestor's identity
  4. WHEN the Data Holder's OP receives a DCR request THEN it SHALL validate the requestor's entity statement by resolving the trust chain through Regional Trust Anchors to the Jake Federation Operator
  5. WHEN entity statement validation succeeds THEN the OP SHALL issue OAuth client credentials for example a domain specific client_id to the Rqr
  6. WHEN the Rqr needs to make RDAP requests THEN it SHALL obtain an access token from the Data Holder's OP using private key JWT authentication (private_key_jwt client authentication method)
  7. WHEN requesting access tokens THEN the Rqr SHALL specify the appropriate RDAP scopes including: rdap:domain:read, rdap:nameserver:read, rdap:entity:read, rdap:autnum:read, rdap:network:read, and rdap:help:read as defined in RFC 9560
  8. WHEN the OP receives token requests THEN it SHALL evaluate authorization policies against the requestor's entity statement, trust chain, and federation agreements to determine if the requested RDAP scopes are authorized
  9. WHEN access token requests are authorized THEN the OP SHALL issue access tokens containing only the RDAP scopes that the requestor is authorized to access based on federation agreements and the evaluation of its other authorization policies
  10. WHEN access tokens are issued THEN they SHALL include claims identifying the requestor entity, and other security information defined by the Regional Trust Anchor.
  11. WHEN making RDAP API requests THEN the Rqr SHALL include the JWT access token in the Authorization header or POST body according to the policies specified by the Regional Trust Anchor
  12. WHEN processing RDAP requests THEN the Data Holder SHALL validate the access token signature, contents and status
  13. WHEN RDAP requests require additional authorization or human review THEN the Data Holder SHALL return an HTTP 401 response with a UMA permission ticket in the WWW-Authenticate header instead of the RDAP data
  14. WHEN receiving a UMA permission ticket response THEN the Rqr SHALL extract the authorization server URI and permission ticket to initiate the UMA authorization flow as specified in Requirement 5
  15. WHEN UMA authorization is complete and an RPT is obtained THEN the Rqr SHALL retry the RDAP request with the RPT in the Authorization header
  16. WHEN the Data Holder receives an RDAP request with a valid RPT THEN it SHALL provide the requested registrant data according to the authorization granted in the RPT
  17. WHEN DCR, token requests, RDAP requests, or UMA flows occur THEN the system SHALL log all authentication and authorization events including entity identifiers, trust chain validation results, requested scopes, granted permissions, UMA ticket usage, and data access patterns for audit and compliance purposes
  18. WHEN security violations are detected THEN the system SHALL use OpenID Shared Signals framework to transmit CAEP (Continuous Access Evaluation Protocol) security events or federation-defined security events to notify Regional Trust Anchors, federation participants, and security monitoring systems, enabling coordinated incident response and automated security policy enforcement across the federation
sequenceDiagram
    participant Rqr as Requestor Service (Rqr)
    participant RTA as Regional Trust Anchor
    participant OP as Data Holder OAuth Provider
    participant DH as Data Holder RDAP Server
    participant TSL as Token Status List

    Note over Rqr, DH: Dynamic Client Registration (DCR) Flow
    
    Rqr->>OP: 1. DCR Request (signed with private key)
    Note right of Rqr: Assert entity ID + signed request
    
    OP->>RTA: 2. Fetch Entity Statement
    Note right of OP: GET /.well-known/openid_federation
    
    RTA-->>OP: 3. Entity Statement (JWT)
    Note left of RTA: Contains public keys & metadata
    
    OP->>OP: 4. Validate Trust Chain
    Note right of OP: Verify signatures & trust to Jake Federation Operator
    
    OP->>OP: 5. Verify DCR Signature
    Note right of OP: Use public key from entity statement
    
    OP-->>Rqr: 6. Client Credentials (client_id)
    
    Note over Rqr, DH: Access Token Request Flow
    
    Rqr->>OP: 7. Token Request (private_key_jwt auth)
    Note right of Rqr: Request RDAP scopes
    
    OP->>OP: 8. Evaluate Authorization Policies
    Note right of OP: Check entity statement, agreements, scopes
    
    OP-->>Rqr: 9. Access Token (JWT)
    Note left of OP: Contains authorized RDAP scopes
    
    Note over Rqr, DH: RDAP Request Flow
    
    Rqr->>DH: 10. RDAP Request + Access Token
    Note right of Rqr: Authorization: Bearer <token>
    
    DH->>OP: 11. Token Validation
    Note right of DH: Verify signature & claims
    
    DH->>TSL: 12. Check Token Status
    Note right of DH: Verify not revoked
    
    TSL-->>DH: 13. Token Status OK
    
    DH->>DH: 14. Individual Record Authorization
    Note right of DH: Check record-specific policies
    
    alt Request Approved
        DH-->>Rqr: 15a. RDAP Response (JSON)
        Note left of DH: Filtered per agreements
    else Human Review Required (UMA Flow)
        DH->>DH: 15b. Register Permission Request
        Note right of DH: Create UMA permission ticket
        
        DH-->>Rqr: 15c. HTTP 401 + UMA Permission Ticket
        Note left of DH: WWW-Authenticate: UMA ticket="xyz"
        
        Rqr->>OP: 16. Request RPT with Permission Ticket
        Note right of Rqr: UMA grant type + ticket
        
        alt Claims Gathering Required
            OP-->>Rqr: 17a. need_info Error
            Note left of OP: Claims gathering endpoint
            
            Rqr->>OP: 17b. Claims Gathering Interaction
            Note right of Rqr: Collect additional claims
            
            OP-->>Rqr: 17c. Claim Tokens
            Note left of OP: Proof of claims collection
            
            Rqr->>OP: 17d. Retry RPT Request + Claims
            Note right of Rqr: Permission ticket + claim tokens
        end
        
        OP->>OP: 18. Authorization Assessment
        Note right of OP: Evaluate policies + human review
        
        alt Authorization Granted
            OP-->>Rqr: 19a. RPT (Requesting Party Token)
            Note left of OP: Authorized access token
            
            Rqr->>DH: 20a. Retry RDAP Request + RPT
            Note right of Rqr: Authorization: Bearer <RPT>
            
            DH->>OP: 20b. Validate RPT
            Note right of DH: Token introspection
            
            OP-->>DH: 20c. RPT Valid + Permissions
            Note left of OP: Authorized scopes & constraints
            
            DH-->>Rqr: 20d. RDAP Response (JSON)
            Note left of DH: Data per RPT authorization
        else Authorization Denied
            OP-->>Rqr: 19b. Authorization Denied
            Note left of OP: Access not granted
        end
    else Request Denied
        DH-->>Rqr: 15d. Denial Response
        Note left of DH: Reason + error details
    end
    
    Note over Rqr, TSL: Security Event Flow (if violations detected)
    
    alt Security Violation Detected
        DH->>RTA: 16. CAEP Security Event
        Note right of DH: OpenID Shared Signals
        
        RTA->>TSL: 17. Update Token Status List
        Note right of RTA: Revoke violating entity
    end
    
    Note over Rqr, DH: Audit Logging (throughout process)
    
    Rqr->>Rqr: Log DCR, token requests, RDAP requests
    OP->>OP: Log trust validation, policy decisions
    DH->>DH: Log access decisions, data provided
Loading

Requirement 2

User Story: As a System Administrator, I want to register an entity for a DH or Rqr with a Regional Trust Anchor after the organization legal representatives signed the Participant Agreement.

Acceptance Criteria

  1. WHEN an organization completes legal vetting and signs the Participant Agreement THEN the system SHALL enable entity registration with the appropriate Regional Trust Anchor
  2. WHEN registering an entity THEN the system SHALL collect the organization's public keys, metadata, and federation capabilities
  3. WHEN entity registration is complete THEN the Regional Trust Anchor SHALL publish a signed entity statement at the organization's entity identifier endpoint
  4. WHEN entity statements are published THEN they SHALL include the organization's role (DH or Rqr), authorized scopes, and applicable agreement references
  5. WHEN registration is successful THEN the entity SHALL be able to participate in federation trust chains and access federation services

Requirement 3

User Story: As a Data Holder, I want to validate requestor trust chains and respond to registration data requests appropriately, so that I can fulfill legitimate requests from verified federation participants while protecting sensitive information and complying with agreements.

Acceptance Criteria

  1. WHEN receiving RDAP requests THEN the Data Holder SHALL validate the requestor's access token and resolve trust chains through Regional Trust Anchors to the Jake Federation Operator
  2. WHEN trust chain validation succeeds THEN the Data Holder SHALL evaluate the request against federation agreements and record-specific policies
  3. WHEN requests are authorized THEN the Data Holder SHALL respond with appropriate registration data in JSON format according to agreement terms and requested scopes
  4. WHEN requests require human review THEN the Data Holder SHALL defer the request with transaction ID and estimated response time
  5. WHEN trust chain validation fails THEN the Data Holder SHALL reject the request with federation authentication error details
  6. WHEN rejecting requests THEN the system SHALL provide clear reasons while protecting confidential policy information

Requirement 4

User Story: As a Regional Trust Anchor, I want to facilitate and validate Agreements between vetted requestor groups and data holder groups in my region using OpenID Federation trust chains, so that access permissions and legal frameworks can be properly defined and enforced among cryptographically verified participants.

Acceptance Criteria

  1. WHEN creating agreements THEN the system SHALL verify that all parties have valid trust chains through Regional Trust Anchors to the Jake Federation Operator
  2. WHEN agreements are defined THEN the system SHALL include agreement identifier, purpose, legal basis, maximum sensitivity level, maximum data elements, and terms of use
  3. WHEN agreements are established THEN the system SHALL store them with entity identifiers for participating Requestor Services (Rqr) and Data Holders (DH)
  4. WHEN agreement violations occur THEN Regional Trust Anchors SHALL add the violating entity's JWTs to OAuth Token Status Lists, and federation participants SHALL check these status lists during JWT validation to reject revoked entity statements and request assertions

Requirement 5

User Story: As a Rqr, I want to handle authorization-required requests using UMA permission tickets and claims gathering, so that I can obtain access to protected registrant data that require human review and additional claims collection.

Acceptance Criteria

  1. WHEN RDAP requests require additional authorization THEN the Data Holder SHALL return an HTTP 401 response with a UMA permission ticket in the WWW-Authenticate header using the format: UMA realm="example", as_uri="https://as.example.com", ticket="016f84e8-f9b9-11e0-bd6f-0021cc6004de"
  2. WHEN receiving a UMA permission ticket THEN the Rqr SHALL extract the authorization server URI (as_uri) and permission ticket from the WWW-Authenticate header
  3. WHEN requesting an RPT (Requesting Party Token) THEN the Rqr SHALL use the UMA grant type with the permission ticket to request authorization from the UMA Authorization Server
  4. WHEN the UMA Authorization Server requires additional claims THEN it SHALL respond with a need_info error containing a claims gathering endpoint and required claim tokens
  5. WHEN claims gathering is required THEN the Rqr SHALL interact with the UMA Authorization Server's claims gathering endpoint to collect additional information such as purpose of use, legal basis, or requestor credentials
  6. WHEN claims gathering is complete THEN the Rqr SHALL retry the RPT request with the collected claim tokens and permission ticket
  7. WHEN authorization is granted THEN the UMA Authorization Server SHALL issue an RPT (Requesting Party Token) that the Rqr can use to access the protected RDAP resource
  8. WHEN retrying the RDAP request THEN the Rqr SHALL include the RPT in the Authorization header and the Data Holder SHALL validate the RPT before providing access to registrant data
  9. WHEN requests are deferred for human review THEN the system SHALL use UMA permission tickets to track the authorization state and allow the Rqr to poll for authorization decisions
  10. WHEN estimated review times are provided THEN the Rqr SHALL respect the timing guidance and avoid excessive polling of the UMA Authorization Server

Requirement 6

User Story: As a Regional Trust Anchor, I want to vet and register organizations into my OpenID Federation so that only trusted entities can participate in registration data sharing through cryptographically verifiable trust chains.

Acceptance Criteria

  1. WHEN organizations apply to join the federation THEN the system SHALL provide vetting processes to verify organizational credentials and legitimacy
  2. WHEN organizations are successfully vetted THEN the system SHALL publish and maintain signed entity statements at discoverable HTTPS endpoints that include their current public keys, metadata, and federation capabilities
  3. WHEN registered organizations need to authenticate THEN the system SHALL enable trust chain resolution from their entity identifiers to trust anchors
  4. WHEN entity statements are published THEN the system SHALL provide cryptographic trust establishment without requiring bilateral certificate management or X.509 PKI infrastructure
  5. WHEN trust relationships change THEN the system SHALL support entity statement updates and trust chain re-validation
  6. WHEN automatic registration is enabled THEN data holders SHALL accept new requestors based on valid trust chains without manual configuration

Requirement 7

User Story: As a federation participant, I want to establish and validate cryptographic trust with other federation entities using OpenID Federation trust chains, so that I can authenticate and authorize requests without pre-configured bilateral relationships.

Acceptance Criteria

  1. WHEN receiving requests from unknown entities THEN the system SHALL resolve trust chains from the entity identifier through Regional Trust Anchors to the Jake Federation Operator
  2. WHEN resolving trust chains THEN the system SHALL fetch entity statements from HTTPS entity identifiers and validate the complete chain of signatures
  3. WHEN validating entity statements THEN the system SHALL verify JWT signatures, expiration times, required claims (sub, iss, iat, exp), and check OAuth Token Status Lists to ensure JWTs have not been revoked
  4. WHEN generating request assertions THEN requestors SHALL create signed JWTs using the private key corresponding to their entity statement's public key
  5. WHEN signing request assertions THEN the system SHALL include required claims (iss, sub, aud, iat, exp, jti) and request-specific claims (domain, agreement_id)
  6. WHEN validating incoming requests THEN data holders SHALL extract the issuer claim, resolve the trust chain, and verify JWT signatures using the requestor's public key
  7. WHEN trust chain validation succeeds THEN the system SHALL cache entity statements respecting their expiration times and extract requestor identity for authorization decisions
  8. WHEN trust chain validation fails THEN the system SHALL reject the request and provide detailed error information
  9. WHEN entity statements expire THEN the system SHALL automatically refresh them from entity identifiers
  10. WHEN automatic registration is enabled THEN data holders SHALL dynamically accept new requestors based on valid trust chains without manual configuration

Requirement 8

User Story: As a system administrator, I want to maintain transaction logs and audit trails with federation context, so that all registration data requests and responses can be tracked for compliance and debugging purposes including trust chain information.

Acceptance Criteria

  1. WHEN requests are initiated THEN the system SHALL log request details including timestamp, requestor entity identifier, trust chain used, and domain name
  2. WHEN responses are received THEN the system SHALL log response details including status, data provided, completion time, and authentication method used
  3. WHEN transactions are deferred THEN the system SHALL log deferral details, polling activities, and trust validation results
  4. WHEN federation authentication is used THEN the system SHALL log trust chain resolution details, entity statement validation results, and any metadata policy applications
  5. WHEN audit requirements apply THEN the system SHALL provide comprehensive transaction history including federation trust context and reporting capabilities

Requirement 9

User Story: As a Data Holder, I want to individually authorize access to each registrant record based on federation policies and record-specific obligations, so that I can ensure appropriate data protection and compliance with registrant privacy requirements and Regional Trust Anchor agreements.

Acceptance Criteria

  1. WHEN processing RDAP requests for registrant records THEN the system SHALL evaluate authorization policies against each individual registrant record rather than applying blanket access permissions
  2. WHEN evaluating record access THEN the system SHALL consider the requestor's entity statement, federation agreements, requested scopes, and any record-specific access restrictions or sensitivity classifications
  3. WHEN registrant records contain additional obligations or restrictions THEN the system SHALL enforce these requirements according to the Regional Trust Anchor participant agreement and applicable data protection regulations
  4. WHEN record-specific obligations exist THEN the system SHALL apply appropriate data filtering, redaction, or access denial based on the specific obligations associated with that registrant record
  5. WHEN access is granted to registrant records THEN the system SHALL log the specific authorization decision, applied policies, and any record-specific restrictions that were enforced
  6. WHEN record-specific restrictions prevent full access THEN the system SHALL return appropriately filtered or redacted data while maintaining compliance with both federation agreements and registrant privacy requirements
  7. WHEN registrant records have different sensitivity levels THEN the system SHALL apply graduated access controls based on the requestor's authorized access level as defined in their federation agreements
  8. WHEN obligations require additional consent or notification THEN the system SHALL enforce these requirements before providing access to the registrant data
  9. WHEN record access is denied due to specific restrictions THEN the system SHALL provide clear indication of the denial reason while protecting the confidentiality of the underlying restrictions

Clone this wiki locally