openid-federation-wallet October 2024
De Marco, et al. Standards Track [Page]
Workgroup:
OpenID Connect A/B
Published:
Authors:
G. De Marco
Dipartimento per la trasformazione digitale
R. Hedberg
Catalogix
M.B. Jones
Self-Issued Consulting
J. Bradley
Yubico

OpenID Federation Wallet Architectures 1.0 - draft 03

Abstract

This specification defines the OpenID Federation entity types for digital wallet architectures.

▲

Table of Contents

1. Introduction

As digital wallets become increasingly deployed for managing identity credentials, establishing an architecture for trusted communication is required to allow each participant in the ecosystem to evaluate other participants' compliance with mutual trust frameworks and accomplish secure and trusted transactions.

This specification defines how to use OpenID Federation 1.0 [OpenID.Federation] to enhance the security and interoperability of wallet ecosystems, facilitating trust establishment among the parties and enabling secure metadata exchange and policy application across large scale deployments. It outlines the general architecture of a federated trust infrastructure for wallet ecosystems, identifying participant roles and describing the use of those roles.

Additionally, this specification provides practical examples of how to apply policies for typical use cases within wallet ecosystems. Finally, it offers guidance on defining trust marks for use within wallet ecosystems.

1.1. Requirements Notation and Conventions

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.

1.2. Warning

This document is not an OpenID Foundation International Standard. It is distributed for review and comment. It is subject to change without notice and may not be referred to as an International Standard.

2. Scope

This specification is a profile of [OpenID.Federation] for wallet ecosystems. It defines entity types for entities participating in those ecosystems. It describes trust evaluation mechanisms for those entities. It uses applicable metadata parameters defined by other specifications for wallet entities.

Collaboration Note: When a metadata parameter is needed for an Entity Type defined by this specification that does not currently exist and that would be usable by wallet ecosystems both using and not using OpenID Federation, it is the editors' intent to work with the working groups creating general-purpose wallet specifications to define those new parameters there.

3. Terminology

This specification uses the terms "End-User" and "Entity" as defined by OpenID Connect Core [OpenID.Core], "JSON Web Token (JWT)" defined by JSON Web Token (JWT) [RFC7519], "CBOR Web Token (CWT)" defined by CBOR Web Token (CWT) [RFC8392], "Client" as defined by [RFC6749], "Verifiable Presentation" and "Wallet Attestation" defined in [OpenID4VP], "Holder" and "Credential Issuer" defined in [OpenID4VCI], and "Trust Mark", "Federation Entity", "Trust Anchor", "Intermediate", and "Subordinate Statement" defined in [OpenID.Federation].

This specification also defines the following terms:

Organizational Entity:
A Federation Entity represented by a legal entity, specifically referring to public or private organizations (excluding natural persons) recognized through a unique identifier. For the purposes of this specification, an Organizational Entity is also referred to as an Organization.
Personal Device:
Any electronic device that is primarily used by an individual. This includes smartphones, tablets, laptops, personal computers, smart watches, and other wearable technologies. Personal Devices are owned and managed by End-Users as individuals, rather than by Organizations, or by End-Users on behalf of an Organization.
Wallet Provider:
An Organizational Entity responsible for the development, publication, and management of a Wallet Solution.
Wallet Instance:
Instance of a Wallet Solution belonging to and controlled by a person, be this natural or legal. It enables the request, storage, presentation, and management of Digital Credentials. It can be installed (instantiated) in a Personal Device or in a Remote Service.
Wallet Solution:
The Wallet Solution is a product offered by a Wallet Provider to enable End-Users to securely manage and use their Digital Credentials. It is delivered by the Wallet Provider in the form of mobile app or cloud service or another form of software application. It may also utilize services and web services for the exchange of data between its Wallet Provider and the Wallet Instances.
Authentic Source:
A protected Resource Server, not necessarily an OAuth 2.0 Resource Server, utilized by the Credential Issuer to retrieve the data necessary for issuing a Credential related to a subject.
Credential Verifier:
Entity that requests and verifies Digital Credentials presented by a Holder.
Credential Verifier Instance:
A software application that allows an individual to request to an Holder and receive from that Holder a Digital Credential, sometimes in a proximity flow, and then verify the received Digital Credential.

3.1. Trust Models and Trust Frameworks

The terms "trust model" and "trust framework" are often used in the context of security, identity management, and federation systems.

The Trust Model defines the relationships and mechanisms through which trust is established and maintained between entities in a system. It outlines how entities interact, the basis on which they can trust each other, and the roles they play within the system. Trust Models can be simple or complex, depending on the number of parties involved and the nature of their interactions. Common examples include:

  • Direct Trust: Trust is established directly between two parties without intermediaries.
  • Trusted Third Party: Trust is facilitated by a trusted third party.
  • Web of Trust: Each participant makes individual decisions about whom to trust, using Direct Trust or potentially multiple Third-Parties.

Trusted Third-Party is the focus of this specification, although the Web of Trust model is not excluded if multiple trusted third parties (Trust Anchors) are supported by the participants.

A Trust Framework is a comprehensive structure that includes policies, standards, and guidelines that govern the implementation of a Trust Model. It provides detailed rules for how trust should be managed, including the legal, technical, and procedural aspects. To allow for a scalable approach, as many aspects of the framework as possible should be presented in a machine discoverable and machine-readable way.

In the scope of this specification, only the technical and procedural aspects are considered and fully covered.

OpenID Federation [OpenID.Federation] is a building block for assembling and using trust frameworks. It can help ensure that all participants in a system understand and adhere to the same principles and practices, making interactions predictable and secure.

4. The Four-Party Model

The Four-Party Model is a framework involving four key participants: the Holder, the Credential Issuer, the Credential Verifier, and an Entity trusted by the other Entities called the Trust Anchor. This is an extension of the three-party Issuer-Holder-Verifier Model described in [OpenID4VCI] and [OpenID4VP] that adds a fourth party: the Trust Anchor.

The four Entities interact with each other as described below:

  1. Holder: The Holder requests, stores, presents, and manages Digital Credentials and other forms of digital attestations. It discovers trustworthy Credential Issuers through the Trust Anchor and its Intermediates. Additionally, the Holder evaluates trust with Credential Verifiers recognized by the Trust Anchor and its Intermediates and checks for the non-revocation of the other Entities in use.
  2. Credential Issuer: This Entity issues Digital Credentials to the Holder, after having evaluated the trust in the Wallet Solution and the security of the Holder.
  3. Credential Verifier: This is any Entity that requires proof of the End-User's identity, through the presentation of Credentials, to provide services or carry out transactions. Credential Verifiers rely on the validity of the Digital Credentials presented via the End-User's Wallet. They MUST have the means to verify these Credentials against the Credential Issuer's cryptographic public keys or other verification methods to ensure they are authentic and have not been tampered with. The Credential Verifier uses the Trust Anchor and its Intermediates to establish the trust with the Credential Issuers, obtains their metadata and cryptographic material, and check the validity of the presented Digital Credentials. It also establishes trust with the Holder and the Wallet Solution used by it.
  4. Trust Anchor: This Entity and its Intermediates, issue Subordinate Statements and any required information about the status of the Federation and its participants (Organizational Entities), to demonstrate their non-revocations, distribute the policies and prevents the repudiation of the past transaction about any trust evaluation, if signed. Historical proofs allow for the evaluation of an Organizational Entity's status within a federation and their past signatures, which can be verified using a historical Trust Chain. 
+-------------------+    +---------------+    +---------------------+
| Credential Issuer |<-->|    Holder     |<-->| Credential Verifier |
|                   |    |               |    |                     |
+-------------------+    +---------------+    +---------------------+
         |                       |                     |
         |                       |                     |
         V                       V                     V
+--------------------------------------------------------------+
|                          Trust Anchor                        |
+--------------------------------------------------------------+

Figure 1: The relationships and interactions within a Wallet ecosystem using the Four-Party Model, where Authentic Sources and Wallet Providers figure such as extensions to be not considered in the core structure of the four parties.

In the Wallet Ecosystem, the primary interaction resolves around asset management. Unlike an Identity Provider in OpenID Connect or SAML2, which authenticates the End-User's identity for third parties, the Credential Issuer in the Wallet ecosystem focuses on managing the issuance of Digital Credentials to the Holder.

The transactions primarily involve the transfer or management of Digital Credentials rather than granting access to services based on identity verification.

Consequently, the End-User obtains and holds the Digital Credentials without disclosing their intended use to the Credential Issuers. At any subsequent time, the End-User can present these Digital Credentials to a Credential Verifier to authenticate themselves.

+------------------+     +-----------------+
| Authentic Source |     | Wallet Provider |
|                  |     |                 |
+------------------+     +-----------------+
         |                       |
         |                       |
         V                       V
+-------------------+    +---------------+    +---------------------+
| Credential Issuer |<-->|    Holder     |<-->| Credential Verifier |
|                   |    |               |    |                     |
+-------------------+    +---------------+    +---------------------+
         |                       |                     |
         |                       |                     |
         V                       V                     V
+-------------------------------------------------------------------+
|                          Trust Anchor                             |
+-------------------------------------------------------------------+

Figure 2: Representation acknowledging the roles of Authentic Sources and Wallet Providers in the ecosystem while maintaining the core structure of the Four-Party Model.

The Figure above illustrates at the center the Holder, who interacts directly with both the Credential Issuer and the Credential Verifier. The Credential Issuer provides Digital Credentials to the Holder, while the Credential Verifier relies on these Credentials to verify the Holder's claims. Above the Holder is the Wallet Provider, which facilitates the registration and the attestation of the security and integrity of the Holder. All entities, including the Credential Issuer, Credential Verifier, Wallet Provider and therefore Holders, and are underpinned by a Trust Anchor, which provides a foundational layer of trust and security for the entire system. This setup ensures that all interactions and transactions are anchored in a trusted framework.

5. Wallet Instance Types

There are many ways to technically implement Wallet Instances to manage Digital Credentials. There are typically two types of Wallet End-Users: one is a natural person and another is an Organizational Entity. These two types of End-Users may have different usage and functional requirements.

Below a non-exhaustive list of the different Wallet Instance types.

Mobile Wallet Native Application
Also known as Mobile Wallet only, is an application that runs natively on a Personal Device under the sole control of an End-User and provided through a platform vendor specific app-store, on behalf of the Wallet Solution. In some cases the End-User as natural person uses the Mobile Wallet representing a legal person.
Web Wallet Native Application

Also known as Cloud Wallet or Web Wallet only, is a Wallet that uses native web technologies for its components, such as UI components. Cloud Wallets are typically suited for Organizational Entities that requires automated Digital Credential operations (request, issuance, store, presentation, revocations) in unsupervised flows, therefore without any human control. Web Wallets are divided into two additional subtypes:

  • Custodial Web Wallet: Cloud Wallets that have dependency on a cloud infrastructure, not necessarily hosted by the Wallet Provider, are typically classified as Custodial Web Wallets; in this case, the cryptographic keys used and the Digital Credentials are stored in the cloud infrastructure.
  • Non-Custodial Web Wallet: A Web Wallet where the cryptographic keys are stored and managed on a media in possession by the End-User and the Digital Credentials can only be used by the End-User, e.g. using a FIDO enabled security hardware token, no matter whether the Credentials are stored locally in a Personal Device or in cloud storage.
Progressive Web Application Wallet (PWAW)
PWAW is a web application that looks like a native app. It can be installed on a Personal Device and not necessarily using the operative system specific app-store. The advantage with a PWAW is that it gives the End-User the same experience as a Mobile Native Wallet Application while also offering the benefits of a web application. PWAW can be Custodial or Non-Custodial.

5.1. Establishing Trust with the Holder

Since the Holder may not be an Organizational Entity and cannot be registered as an Organization through registration services, it is not represented within a Trust Chain and does not qualify as a Federation Entity. This context sets the stage for understanding the unique position of the Holder in relation to the Trust Chain and Federation Entities.

+----------------------------+
| Trust Chain                |
| +------------------------+ |
| | Trust Anchor           | |
| | (Entity Configuration) | |
| +------------------------+ |
|                     |      |
|                     v      |
| +------------------------+ |
| | Trust Anchor           | |
| | (Subordinate Statement | |
| |  about the             | |
| |  Wallet Provider)      | |
| +------------------------+ |
|                     |      |
|                     v      |
| +------------------------+ |
| | Wallet Provider        | |    +-------------------------------+
| | (Entity Configuration) |----->|      Wallet Attestation       |
| +------------------------+ |    | (Not part of the Trust Chain) |
+----------------------------+    +-------------------------------+

Figure 3: Federation Trust Chain and Wallet Attestation are separate things, where the Wallet Attestation is linked to its Issuer attested within the Trust Chain.

Outside the Trust Chain, it is the Wallet Attestation, where the Wallet Provider that issued it is attestable through the Trust Chain, while the Wallet, such as the End-User's Native Mobile Application installed on the Personal Device, is attested through the Wallet Attestation and under the responsibility of its issuer, the Wallet Provider.

6. Wallet Architecture Entity Types

This section defines the Entity Types used by Organizational Entities in their Entity Configurations according to their roles in the Wallet ecosystem.

Table 1
Entity Entity Type Identifiers References
Trust Anchor federation_entity [OpenID.Federation]
Intermediate federation_entity [OpenID.Federation]
Wallet Provider federation_entity, openid_wallet_provider this specification
Authorization Server federation_entity, oauth_authorization_server [OpenID4VCI], [RFC8414]
Credential Issuer federation_entity, openid_credential_issuer, oauth_authorization_server [OpenID4VCI], this specification
Credential Verifier federation_entity, openid_credential_verifier [OpenID.Federation], [OpenID4VP], this specification

Table 1: Map of the Federation Entity Types and corresponding metadata types for the Wallet architectures.

The Credential Issuer is an OAuth 2.0 Protected Resource Server and it MAY also implement, within the same Entity, an OAuth 2.0 Authorization Server. According to [OpenID4VCI], the Authorization Server can be external to the Entity that implements the Credential Endpoint, therefore the use of oauth_authorization_server is OPTIONAL.

6.1. OpenID Wallet Provider Entity Type

The OpenID Federation Entity Type Identifier for the Wallet Provider is openid_wallet_provider.

For information on metadata parameters specific to OpenID Wallets, refer to Section 8. Wallet Metadata (Authorization Server Metadata) of the OpenID for Verifiable Presentations [OpenID4VP] specification.

6.2. OpenID Credential Issuer Entity Type

The OpenID Federation Entity Type Identifier for the Credential Issuer is openid_credential_issuer.

For information on metadata parameters specific to OpenID Credential Issuers, refer to Section 10.2. Credential Issuer Metadata of the OpenID for Verifiable Credential Issuance [OpenID4VCI] specification.

6.3. OpenID Credential Verifier Entity Type

The OpenID Federation Entity Type Identifier for the Credential Verifier is openid_credential_verifier.

This specification introduces a distinct Entity Type Identifier for the OpenID Credential Verifier to clearly differentiate it from a traditional OpenID Connect Relying Party (openid_relying_party). This distinction highlights the unique characteristics and functionalities of the Wallet ecosystem and its Credential Verifier.

For information on metadata parameters specific to OpenID Credential Verifiers, refer to Section 9. Verifier Metadata (Client Metadata) of the OpenID for Verifiable Presentations [OpenID4VP] specification.

7. Federation Policies

Policies refer to a set of rules that govern the operations, security, and interactions within a federation.

Technical implementation of federation policies over participants metadata is managed with the use of metadata and metadata_policy parameters in Subordinate Statements. These parameters allow for the configuration enforcement of application-specific metadata changes for each subject (Leaf).

Qualitative aspects of federation entities, including administrative protocols, security measures, and behavioral profiling, are regulated by Trust Marks. These marks provide verifiable assertions of compliance with specific profiles beyond the scope of the application-specific metadata.

7.1. Using Metadata

Metadata refers to application-specific properties about a subject and for the purpose of the interoperability. This includes details such as service endpoints, cryptographic keys, and other supported configurations.

Metadata within a Subordinate Statement allows for modifications to the metadata published in a Leaf's Entity Configuration. These modifications allow a federation authority, such as a Trust Anchor, to apply policies coercively to its subordinates. This can include actions such as removing weak signature algorithms from their metadata, enforcing the use of specific endpoints configured at the time of the entity's registration within the ecosystem, or restricting the personal data that a Credential Verifier is allowed to request.

{
  "iss": "https://trust-anchor.example.com",
  "sub": "https://credential-verifier.example.it",
  "iat": 1616239022,
  "exp": 1616239322,
  "metadata": {
    "federation_entity": {
      "organization_name": "Example Credential Verifier",
    },
    "openid_credential_verifier": { ... as defined in the OpenID4VP specs ... }
  },
  "jwks": {
    "keys": [
      {
        "kty": "RSA",
        "use": "sig",
        "kid": "1",
        "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEPCRfceaC7mkxr8v...",
        "e": "AQAB"
      }
    ]
  }
}

Example 1: Example demonstrating how a Federation Authority can issue a Subordinate Statement about a Credential Verifier, specifying certain metadata parameters such as the endpoints to use and the allowed Digital Credentials to be requested.

7.2. Differences Between metadata and metadata_policy

The key difference between metadata and metadata_policy is that metadata directly affects only the Immediate Subordinate Entity, while metadata_policy impacts the configuration of all Subordinate Entities along a Trust Chain, as defined in Sections 3, 5 and 6.1 of [OpenID.Federation].

7.3. Using Metadata Policies

Differently from metadata, metadata_policy ensures that specific settings can be propagated to all the Entities Statements contained within a Trust Chain.

7.4. Using Trust Marks

Trust Marks are issued by authorized entities (Trust Mark Issuers) within the federation, typically after an entity has demonstrated compliance with certain standards, this might happen through auditing or certification processes.

Trust Marks are typically implemented as signed assertions that can be verified by other entities.

This verification process involves checking the digital signature against the public key of the Trust Mark Issuer to ensure the Trust Mark has not been forged, and its check to the Trust Mark Status endpoint to check it against any revocation.

Trust Marks SHOULD be defined within the trust framework. Trust Marks are asserted about a subject through a registration service or compliance evaluation mechanism and therefore included in subject's Entity Configurations. This allows other entities to quickly assess the compliance status of a subject by examining the Entity Configuration of a subject.

{
  "id":"https://diligent.federation.example.com/openid_credential_verifier/private/under-age",
  "iss": "https://trustissuer.pinarolo.example.it",
  "sub": "https://vavuso.example.com/rp",
  "iat": 1579621160,
  "policy_uri": "https://vavuso.example.com/policy",
  "tos_uri": "https://vavuso.example.com/tos"
}

Example 2: Trust Mark to be included in a Leaf Entity Configuration, which payload states Leaf's compliance in interacting with under-age End-User.

8. Federation Trust Discovery Use Cases

The process of trust establishment in federated environments is illustrated in this section through specific use cases involving Wallet Instances, Credential Issuers (CIs), and Credential Verifiers (CVs).

8.1. Establishing Trust with a Credential Verifier Instance

A Credential Verifier Instance is typically installed on a mobile device, personal computer, or embedded system. It enables an individual to perform Digital Credential verification tasks locally, often in proximity to the Holder, and without necessarily requiring a broadband connection. This instance engages in peer-to-peer exchanges with Holders, facilitating Credential verifications directly on the device. This approach represents a shift from traditional server-based verification to a more user-centric model within the Wallet ecosystem.

To establish trust between a Holder's Wallet Instance and a Credential Verifier Instance, a mechanism using a verifiable attestation, such as the Wallet Instance Attestations, SHOULD be employed. This process ensures that the Credential Verifier Instance is legitimate and trustworthy.

The mechanisms used to present the Wallet Instance Attestation to a Credential Verifier are out of scope for this specification, as they are related to Credential presentation flows. For implementation details on these presentation mechanisms, please refer to the OpenID for Verifiable Presentations (OpenID4VP) specification.

8.2. Wallet Checking the Non-Revocation of its Wallet Provider

Wallets SHOULD periodically check their Wallet Providers' compliance through the federation's trust infrastructure. This involves retrieving the Wallet Provider's Entity Configuration and verifying its Trust Chain up to a recognized Trust Anchor, ensuring that the Wallet Provider has not been revoked within the federation. Wallets SHOULD remain neutral in attesting to the reliability of their Wallet Providers for the End-User, thereby protecting the End-User against any malevolent behavior by the Wallet Provider.

The Wallet Provider’s Entity Configuration provides essential information, including its roles within the federation, policies it adheres to, and cryptographic keys for secure communication. The Wallet Instance SHOULD use the Federation API to periodically reestablish trust with its Wallet Provider.

The process to discover the trust with a Wallet Provider is equivalent to the one used for discovering the trust with a Credential Issuer, as described in the dedicated section below.

8.3. Wallet Discovering Credentials Issuers

Wallets begin by discovering the identity of Credential Issuers through the federation's trust infrastructure. This involves retrieving the Credential Issuer's Entity Configuration and verifying its Trust Chain up to a recognized Trust Anchor. The Credential Issuer’s Entity Configuration provides essential information, including its roles within the federation, policies it adheres to, and cryptographic keys for secure communication.

In the process represented in the sequence diagram below, the Wallet Instance uses the Federation API to discover and collect all the Credential Issuers enabled within the federation.

        +------+                        +------------+ +------------+ +-----------------+
        |Wallet|                        |Trust Anchor| |Intermediate| |Credential Issuer|
        +---+--+                        +------+-----+ +------+-----+ +--------+--------+
            |  Fetch the list of all           |              |                |
            |  Intermediates and CIs           |              |                |
            |--------------------------------->|              |                |
            |                                  |              |                |
+-----------+----------------------------------+--------------+------+         |
| LOOP  |for each Intermediate                 |              |      |         |
|-------+   |                                  |              |      |         |
|           | Fetch listing of                 |              |      |         |
|           | Subordinates/CIs                 |              |      |         |
|           |------------------------------------------------>|      |         |
+-----------+----------------------------------+--------------+------+         |
            |                                  |              |                |
+-----------+----------------------------------+--------------+----------------+--------+
| LOOP  |for each CI                           |              |                |        |
|-------+   |                                  |              |                |        |
|           | Fetch CI's Entity Configuration  |              |                |        |
|           |----------------------------------------------------------------->|        |
|           |                                  |              |                |        |
|           | Fetch Subordinate Statement(s)   |              |                |        |
|           | for CI                           |              |                |        |
|           |------------------------------------------------>|                |        |
|           |                                  |              |                |        |
|           | Fetch Subordinate Statement      |              |                |        |
|           | for Intermediate(s)              |              |                |        |
|           |--------------------------------->|              |                |        |
|           |----+                             |              |                |        |
|           |    | Validate Trust Chain        |              |                |        |
|           |    | for CI                      |              |                |        |
|           |<---+                             |              |                |        |
|           |                                  |              |                |        |
|           |----+                             |              |                |        |
|           |    | Include CI in               |              |                |        |
|           |    | Discovery Page              |              |                |        |
|           |    | with validated              |              |                |        |
|           |    | information and logo        |              |                |        |
|           |<---+                             |              |                |        |
+-----------+----------------------------------+--------------+----------------+--------+
        +---+--+                        +------+-----+ +------+-----+ +--------+--------+
        |Wallet|                        |Trust Anchor| |Intermediate| |Credential Issuer|
        +------+                        +------------+ +------------+ +-----------------+

Figure 4: Federation Credential Issuer listing, the Wallet Instance browse the entire federation collecting all the Credential Issuers.

The diagram above shows how a Wallet navigates the federation, collecting and validating the Trust Chain for each Credential Issuer (CI), and creating a discovery page including each Credential Issuer using the information, such as the Credential Types and logo obtained through their Trust Chain.

The diagram below illustrates how a Wallet establishes trust with a Credential Issuer by verifying its link (even if indirect) to a Trust Anchor and validating which Credentials it is authorized to issue. This may happen in a credential offer flow, for instance, where the Wallet is used by an End-User starting from the Credential Issuer website and without any discovery phases started before within the Wallet.

        +------+                                 +-----------------+ +-------------------------+
        |Wallet|                                 |Credential Issuer| |Intermediate/Trust Anchor|
        +---+--+                                 +--------+--------+ +------------+------------+
            |    Fetch CI's Entity Configuration          |                       |
            |-------------------------------------------->|                       |
            |                                             |                       |
            |----+                                        |                       |
            |    | Extract Authority Hints                |                       |
            |    | from CI's Configuration                |                       |
            |<---+                                        |                       |
            |                                             |                       |
            |                                             |                       |
+-------+---+---------------------------------------------+-----------------------+------------+
| LOOP  |for each Authority Hint                          |                       |            |
+-------+   |                                             |                       |            |
|           |                     Fetch Entity Configuration                      |            |
|           |-------------------------------------------------------------------->|            |
|           |                                             |                       |            |
|           |                    Fetch Subordinate Statement                      |            |
|           |-------------------------------------------------------------------->|            |
|           |                                             |                       |            |
|           |----+                                        |                       |            |
|           |    | Validate the previous statement        |                       |            |
|           |<---+ using the Federation Entity Keys       |                       |            |
|           |      provided in the Subordinate Statement  |                       |            |
|           |                                             |                       |            |
+-----------+---------------------------------------------+-----------------------+------------+
            |                                             |                       |
            |----+                                        |                       |
            |    | Validate Trust Chain                   |                       |
            |<---+                                        |                       |
            |                                             |                       |
            |                                             |                       |
+------+----+----------------------------------------+    |                       |
| ALT  |If Trust Chain is Valid and Unexpired        |    |                       |
+------+    |                                        |    |                       |
|           |----+                                   |    |                       |
|           |    | Proceed with Federation Process   |    |                       |
|           |<---+                                   |    |                       |
+-----------+----------------------------------------+    |                       |
|           |                                        |    |                       |
|           |----+                                   |    |                       |
|           |    | Abort Process with Error          |    |                       |
|           |<---+                                   |    |                       |
+-----------+----------------------------------------+    |                       |
            |                                             |                       |
            |----+                                        |                       |
            |    | Applies Policies                       |                       |
            |<---+                                        |                       |
            |                                             |                       |
            |----+                                        |                       |
            |    | Derive CI's final metadata             |                       |
            |<---+                                        |                       |
            |                                             |                       |
            |----+                                        |                       |
            |    | Get available Credentials              |                       |
            |    | allowed for issuance                   |                       |
            |<---+                                        |                       |
        +---+--+                                 +--------+--------+ +------------+------------+
        |Wallet|                                 |Credential Issuer| |Intermediate/Trust Anchor|
        +------+                                 +-----------------+ +-------------------------+

Figure 5: Federation Entity Discovery, the Wallet Instance evaluates the trust with a Credential Issuer.

8.4. Credential Issuers Establishing Trust in the Wallet Provider

The evaluation of trust by the Credential Issuer towards the Wallet Provider is conducted exactly as other federation entities. This process can be achieved through Federation Entity Discovery, where the Trust Chain is constructed starting from the Entity Configuration of the Wallet Provider. The Credential Issuer retrieves the Entity Configuration of the Wallet Provider and follows the authority_hints to build the Trust Chain in the usual manner.

Alternatively, trust can be established via a signed data object issued by Wallet Provider, which includes the trust_chain parameter, as defined in Section 4.3 of [OpenID.Federation]. This parameter contains a pre-constructed and verifiable Trust Chain, which MUST be validated using one of the the public keys of the Trust Anchor. This method allows for a streamlined trust evaluation process, as the Trust Chain is provided directly by the Wallet Provider and can be quickly validated.

8.5. Credential Issuers Establishing Trust in the Wallet

During the issuance phase, the Wallet Instance authenticates with the Credential Issuer using a Client authentication mechanism that includes a proof issued by its Wallet Provider.

This proof is a signed data object that confirms the match of a Wallet Instance to a Wallet Solution, as attested by the Wallet Provider. This proof contains all the information the Credential Issuer requires regarding the security and compliance of the Wallet Instance and the cryptographic proof of possession of this attestation provided by the Wallet Instance presenting it.

To establish trust with the Wallet Instance, the Credential Issuer MUST first establish trust with the Wallet Provider that is the issuer of the verifiable attestation, as described in the previous section.

The verifiable attestation issued by the Wallet Provider to the Wallet Instance MUST be cryptographically validated using the cryptographic material provided by the federation Trust Chain. The Credential Issuer evaluates the adequacy of these verifiable attestations using mechanisms and rules that might depend upon different regulations and frameworks that are out of the scope of this specification.

8.6. Wallet Establishing Trust in the Credential Verifier

The Federation Entity Discovery starts with the Wallet Instance fetching the Credential Verifier's Entity Configuration to identify authority hints, pointing to Federation Entities that can issue Subordinate Statements about the Credential Verifier. The Wallet Instance then follows these hints and collects the Subordinate Statements and validating each one. The process continues until the Wallet Instance reaches the Trust Anchor. Finally, the Wallet Instance compiles the validated Trust Chain. If the Trust Chain is valid, the Wallet Instance processes the Credential Verifier final metadata.

Note: While this section exemplifies the journey of discovery from the perspective of an OpenID Wallet Instance, it is important to understand that this approach can be applied to every kind of entity type within the federation.

        +------+                               +-------------------+ +-------------------------+
        |Wallet|                               |Credential Verifier| |Intermediate/Trust Anchor|
        +---┬--+                               +--------+----------+ +--------+----------------+
            |       Fetch Entity Configuration          |                     |
            |------------------------------------------>|                     |
            |                                           |                     |
            |----+                                      |                     |
            |    | Extract Authority Hints              |                     |
            |    | from Entity Configuration            |                     |
            |<---+                                      |                     |
            |                                           |                     |
            |                                           |                     |
+-------+---+-------------------------------------------+---------------------+----------+
| LOOP  |for each Authority Hint                        |                     |          |
+-------+   |                                           |                     |          |
|           |                   Fetch Entity Configuration                    |          |
|           |---------------------------------------------------------------->|          |
|           |                                           |                     |          |
|           |                    Fetch Subordinate Statement                  |          |
|           |---------------------------------------------------------------->|          |
|           |                                           |                     |          |
|           |----+                                      |                     |          |
|           |    | Validate the previous statement      |                     |          |
|           |<---+ using the Federation Entity Keys     |                     |          |
|           |      provided in the Subordinate Statement|                     |          |
|           |                                           |                     |          |
+-----------+-------------------------------------------+---------------------+----------+
            |                                           |                     |
            |----+                                      |                     |
            |    | Validate Trust Chain                 |                     |
            |<---+                                      |                     |
            |                                           |                     |
            |                                           |                     |
+------+----+----------------------------------------+  |                     |
| ALT  |If Trust Chain is Valid and Unexpired        |  |                     |
+------+    |                                        |  |                     |
|           |----+                                   |  |                     |
|           |    | Proceed with Federation Process   |  |                     |
|           |<---+                                   |  |                     |
+-----------+----------------------------------------+  |                     |
|           |                                        |  |                     |
|           |----+                                   |  |                     |
|           |    | Abort Process with Error          |  |                     |
|           |<---+                                   |  |                     |
+-----------+----------------------------------------+  |                     |
            |                                           |                     |
            |----+                                      |                     |
            |    | Applies Policies                     |                     |
            |<---+                                      |                     |
            |                                           |                     |
            |----+                                      |                     |
            |    | Derive final metadata                |                     |
            |<---+                                      |                     |
            |                                           |                     |
            |----+                                      |                     |
            |    | Get Credentials                      |                     |
            |    | allowed for presentation             |                     |
            |<---+                                      |                     |
        +---+--+                               +--------+--------+ +----------+--------------+
        |Wallet|                               |Credential Issuer| |Intermediate/Trust Anchor|
        +------+                               +-----------------+ +-------------------------+

Figure 6: Federation Entity Discovery, the Wallet Instance evaluates the trust with a Credential Verifier.

9. Implementation Considerations for Offline Flows

The static Trust Chain parameter within the JWT headers, as defined in Section 4.3 of [OpenID.Federation], is used as a hint to the Entity involved in a transaction with a common Trust Anchor. This facilitates trust evaluation without the need for real-time Federation Entity Discovery using Federation API endpoints.

The Entity that issues a signed data object, including the trust_chain parameter, might be:

The Entity that receives the data object including the JWT trust_chain, such as the Wallet Instance obtaining a signed request object, verifies the Trust Chain using the Trust Anchor's public keys and applies any metadata policies, without needing to have a working network connection for reaching the Federation API.

Using short-lived Trust Chains ensures compatibility with required revocation administrative protocols, such as those defined in a legal framework. For example, if a revocation must be propagated in less than 24 hours, the Trust Chain should not be valid for more than that period.

10. Acknowledgments

We would like to thank the following individuals for their comments, ideas, and contributions to this implementation profile and to the initial set of implementations.

11. Normative References

[OpenID.Core]
Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, "OpenID Connect Core 1.0 incorporating errata set 2", , <http://openid.net/specs/openid-connect-core-1_0.html>.
[OpenID.Federation]
Ed., R. H., Jones, M. B., Solberg, A., Bradley, J., Marco, G. D., and V. Dzhuvinov, "OpenID Federation 1.0", , <https://openid.net/specs/openid-federation-1_0.html>.
[OpenID4VCI]
Lodderstedt, T., Yasuda, K., and T. Looker, "OpenID for Verifiable Credential Issuance", , <https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html>.
[OpenID4VP]
Terbu, O., Lodderstedt, T., Yasuda, K., and T. Looker, "OpenID for Verifiable Presentations", , <https://openid.net/specs/openid-4-verifiable-presentations-1_0.html>.
[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC6749]
Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, , <https://www.rfc-editor.org/info/rfc6749>.
[RFC7519]
Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, , <https://www.rfc-editor.org/info/rfc7519>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/info/rfc8174>.
[RFC8392]
Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, , <https://www.rfc-editor.org/info/rfc8392>.
[RFC8414]
Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, , <https://www.rfc-editor.org/info/rfc8414>.

Appendix A. Notices

Copyright (c) 2024 The OpenID Foundation.

The OpenID Foundation (OIDF) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft or Final Specification solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts and Final Specifications based on such documents, provided that attribution be made to the OIDF as the source of the material, but that such attribution does not indicate an endorsement by the OIDF.

The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this specification make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The OpenID Intellectual Property Rights policy requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. The OpenID Foundation invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that MAY cover technology that MAY be required to practice this specification.

Appendix B. Document History

[[ To be removed from the final specification ]]

-03

-02

-01

-00

Authors' Addresses

Giuseppe De Marco
Dipartimento per la trasformazione digitale
Roland Hedberg
Catalogix
Michael B. Jones
Self-Issued Consulting
John Bradley
Yubico