OpenID Federation Wallet Architectures 1.0 - draft 02

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.¶

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.¶

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.¶

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.¶

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.¶

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, therefore to the End-User in control of the Wallet.¶

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.¶

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, such as a legal person. 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.¶

+----------------------------+
| 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) |
+----------------------------+    +-------------------------------+

6. 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.¶

7. 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.¶

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.¶

8. 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.¶

{
  "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": {
      "application_type": "web",
      "client_name": "Example Credential Verifier",
      "request_uris": [
          "https://verifier.example.org/request_uri"
      ],
      "response_uris_supported": [
          "https://verifier.example.org/response_uri"
      ],
      "presentation_definitions_supported": [
          {
              "id": "d76c51b7-ea90-49bb-8368-6b3d194fc131",
              "input_descriptors": [
                  {
                      "id": "PersonIdentificationData",
                      "name": "Person Identification Data",
                      "purpose": "User Authentication",
                      "format": {
                          "vc+sd-jwt": {
                              "alg": [
                                  "ES256",
                                  "ES384",
                                  "ES512"
                              ]
                          }
                      },
                      "constraints": {
                          "limit_disclosure": "required",
                          "fields": [
                              {
                                  "filter": {
                                      "const": "PersonIdentificationData",
                                      "type": "string"
                                  },
                                  "path": [
                                      "$.vct"
                                  ]
                              },
                              {
                                  "filter": {
                                      "type": "object"
                                  },
                                  "path": [
                                      "$.cnf.jwk"
                                  ]
                              },
                              {
                                  "path": [
                                      "$.first_name"
                                  ]
                              },
                              {
                                  "path": [
                                      "$.family_name"
                                  ]
                              }
                          ]
                      }

                  }
              ]
          }
      ],
    }
  },
  "jwks": {
    "keys": [
      {
        "kty": "RSA",
        "use": "sig",
        "kid": "1",
        "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEPCRfceaC7mkxr8v...",
        "e": "AQAB"
      }
    ]
  }
}

{
  "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"
}

9. 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).¶

sequenceDiagram
    participant Wallet
    participant TA as Trust Anchor
    participant IM as Intermediate
    participant CI as Credential Issuer

    Wallet->>TA: Fetch the list of all Intermediates and CIs
    loop for each Intermediate
        Wallet->>IM: Fetch listing of Subordinates/CIs
    end
    loop for each CI
        Wallet->>CI: Fetch CI's Entity Configuration
        Wallet->>IM: Fetch Subordinate Statement(s) for CI
        Wallet->>TA: Fetch Subordinate Statement for Intermediate(s)
        Wallet->>Wallet: Validate Trust Chain for CI
        Wallet->>Wallet: Include CI in Discovery Page<br/>with validated information and logo
    end

sequenceDiagram
    participant Wallet
    participant CI as Credential Issuer
    participant IE as Intermediate Entities
    participant TA as Trust Anchor

    Wallet->>CI: Fetch CI's Entity Configuration
    CI->>Wallet: Return Entity Configuration

    Wallet->>Wallet: Extract Authority Hints from CI's Configuration

    loop for each Authority Hint
        Wallet->>IE: Fetch Entity Configuration
        Wallet->>IE: Fetch Subordinate Statement
        Wallet->>Wallet: Validate the previous statement<br/>using the Federation Entity Keys<br/>provided in the Subordinate Statement
    end

    Wallet->>Wallet: Validate Trust Chain

    alt If Trust Chain is Valid and Unexpired
        Wallet->>Wallet: Proceed with Federation Process
    else
        Wallet->>Wallet: Abort Process with Error
    end

    Wallet->>Wallet: Applies Policies
    Wallet->>Wallet: Derive CI's final metadata
    Wallet->>Wallet: Get available Credentials allowed for issuance

sequenceDiagram
    participant WalletInstance as Wallet Instance
    participant CV as Credential Verifier
    participant IE as Intermediate
    participant TA as Trust Anchor

    WalletInstance->>CV: Fetch CV's Entity Configuration
    CV->>WalletInstance: Return Entity Configuration

    WalletInstance->>CV: Extract Authority Hints from CV's Configuration
    CV->>WalletInstance: Provide Authority Hints

    loop for each Authority Hint
        WalletInstance->>IE: Fetch Entity Configuration -> get federation_fetch_api URL
        IE->>WalletInstance: Fetch Subordinate Statement
        WalletInstance->>WalletInstance: Validate the previous statement<br/>using the Federation Entity Keys<br/>provided in the Subordinate Statement
    end

    WalletInstance->>WalletInstance: Validate Trust Chain

    alt If Trust Chain is valid and unexpired
        WalletInstance->>WalletInstance: Proceed with Federation Process
    else
        WalletInstance->>WalletInstance: Abort Process with Error
    end

    WalletInstance->>WalletInstance: Applies Policies
    WalletInstance->>WalletInstance: Derive CV's final metadata

10. Implementation Considerations for Offline Flows

TBD: usage of static trust chain having at least a Trust Anchor in common with the requestor¶

11. 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.¶

• Leif Johansson¶
• Stefan Liström¶
• Francesco Antonio Marino¶
• Giada Sciarretta¶
• Niels van Dijk¶

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 ]]¶

-02¶

• Added non-normative example about using policies with metadata and trust marks¶
• Added Credential Verifier and Credential Verifier Instance¶
• Added section about Credential Verifier Instance¶
• Illustrative rationale about Authentic Sources and Wallet Provider within the Four-Party Model sections¶
• Moved text on Possible Use of Metadata Parameters by Wallet Ecosystems to issue #22.¶
• Added warning about the specification not being final.¶

-01¶

• Created Scope section describing the purpose of the document and collaboration with other working groups.¶
• Moved metadata tables and examples to an informative appendix on possible usage.¶
• Fixed #10: Renamed openid_wallet_relying_party to openid_credential_verifier.¶

-00¶

• Initial version¶

Authors' Addresses