OpenID Federation for Wallet Architectures 1.0 - draft 06

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. OpenID Federation is a building block for applying 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. This specification 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. It covers only the technical and procedural aspects of a Trust Framework. To allow for a scalable approach, as many aspects of a Trust Framework as possible should be presented in a machine-discoverable and machine-readable way.¶

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 [OpenID.Core], "JSON Web Token (JWT)" defined by JSON Web Token (JWT) [RFC7519], "Client" as defined by [RFC6749], "Verifiable Presentation" and "Verifier Attestation JWT" defined in [OpenID4VP], "Holder", "Credential Issuer", "Digital Credential", "Credential Issuer Identifier", "Wallet Attestation", and "Key Attestation" 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:¶

Digital Credential:

A Credential as defined in [OpenID4VCI]. This specification uses Digital Credential for that term to distinguish it from other uses of "credential", such as in [OpenID.Core] and [RFC6749].¶

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 Digital 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 a Holder and receive from that Holder a Digital Credential, sometimes in a proximity flow, and then verify the received Digital Credential. A Credential Verifier Instance is not a Federation Entity since it has no queryable Entity Identifier. It can be attested by a Credential Verifier Provider.¶

Credential Verifier Provider:

An Organizational Entity that develops, publishes, or manages Credential Verifier Instance software and that issues Verifier Attestation JWTs about those instances.¶

Trust Model:

The relationships and mechanisms through which trust is established and maintained between Entities, including how they interact, the basis on which they can trust each other, and the roles they play.¶

Trust Framework:

A structure of policies, standards, and guidelines that governs the implementation of a Trust Model, including legal, technical, and procedural rules.¶

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. Trust among those Entities is established through the Trust Anchor acting as a trusted third party. Participants MAY configure multiple Trust Anchors.¶

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, attributes, or both, through the presentation of Digital 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 Digital 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 Four-Party Model. Horizontal arrows represent protocol interactions: issuance of Digital Credentials between the Credential Issuer and the Holder, and presentation between the Holder and the Credential Verifier. Vertical arrows mean that the party uses the Trust Anchor to evaluate trust in other parties. They are not client/server relations and they are not the flow of credential data. A vertical arrow does not mean that the party is a Federation Entity under the Trust Anchor. The Holder is not a Federation Entity; it uses the Trust Anchor to evaluate Credential Issuers and Credential Verifiers.¶

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: Authentic Sources and Wallet Providers in the Four-Party Model. Horizontal arrows have the same meaning as in Figure 1 (issuance and presentation). The additional downward arrows from Authentic Source to Credential Issuer and from Wallet Provider to Holder represent data used for issuance and Wallet Attestation, respectively. Vertical arrows to the Trust Anchor have the same meaning as in Figure 1: the party uses the Trust Anchor to evaluate trust in other parties. The Wallet Provider is a Federation Entity evaluated under the Trust Anchor, for example by Credential Issuers; that evaluation is not drawn as an arrow from the Wallet Provider.¶

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 Digital 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. The Credential Issuer, the Credential Verifier, and the Wallet Provider are Federation Entities evaluated under the Trust Anchor. The Holder is not a Federation Entity. Other parties evaluate the Holder through the Wallet Provider and its Wallet Attestation, and the Holder uses the Trust Anchor to evaluate the other parties.¶

5. Wallet Instances

This section describes deployment forms of Wallet Instances and how trust is established with the Holder.¶

The Wallet Instance types below are informative and non-exhaustive. This specification does not define type-specific federation processing. Credential Issuers, Credential Verifiers, and other Entities evaluate trust with the Holder using the Wallet Provider and Wallet Attestation, regardless of Wallet Instance type.¶

Wallet Instances may be used by a natural person or by an Organizational Entity. These two cases may have different usage and functional requirements; those differences do not change the federation mechanisms defined in this specification.¶

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

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

{
  "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": {
      "jwks": {
        "keys": [
          {
            "kty": "EC",
            "crv": "P-256",
            "use": "sig",
            "kid": "verifier-key-1",
            "x": "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
            "y": "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM"
          }
        ]
      },
      "request_uris": [
        "https://credential-verifier.example.it/request"
      ],
      "response_uris": [
        "https://credential-verifier.example.it/response"
      ],
      "redirect_uris": [
        "https://credential-verifier.example.it/cb"
      ],
      "dcql_queries": [
        {
          "credentials": [
            {
              "id": "pid",
              "format": "dc+sd-jwt",
              "meta": {
                "vct_values": [
                  "https://credentials.example.com/pid"
                ]
              },
              "claims": [
                {"path": ["given_name"]},
                {"path": ["family_name"]},
                {"path": ["birth_date"]}
              ]
            }
          ]
        }
      ]
    }
  },
  "jwks": {
    "keys": [
      {
        "kty": "RSA",
        "use": "sig",
        "kid": "1",
        "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEPCRfceaC7mkxr8v...",
        "e": "AQAB"
      }
    ]
  }
}

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

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

These use cases are independent: a Trust Framework MAY require support for any subset of them. Normative requirements in a use case apply only when that use case is used for OpenID Federation trust establishment.¶

+-------------------------------------+
| Trust Chain                         |
| +-------------------------------+   |
| | Trust Anchor                  |   |
| | (Entity Configuration)        |   |
| +-------------------------------+   |
|                          |          |
|                          v          |
| +-------------------------------+   |
| | Credential Verifier Provider  |   |    +-------------------------------+
| | (Entity Configuration)        |------->|   Verifier Attestation JWT    |
| +-------------------------------+   |    | (Not part of the Trust Chain) |
+-------------------------------------+    +-------------------------------+

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

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

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

        +-------------------+                      +-----------------+ +-------------------------+
        |Credential Verifier|                      |Credential Issuer| |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            |  |                     |
+------+         |                                       |  |                     |
|                |----+                                  |  |                     |
|                |    | Derive final metadata and keys   |  |                     |
|                |<---+                                  |  |                     |
|                |                                       |  |                     |
|                |----+                                  |  |                     |
|                |    | Verify Digital Credential        |  |                     |
|                |    | and evaluate issuance policies   |  |                     |
|                |<---+                                  |  |                     |
+----------------+---------------------------------------+  |                     |
|                |                                       |  |                     |
|                |----+                                  |  |                     |
|                |    | Abort Process with Error         |  |                     |
|                |<---+                                  |  |                     |
+----------------+---------------------------------------+  |                     |
        +--------+----------+                      +--------+--------+ +--------+----------------+
        |Credential Verifier|                      |Credential Issuer| |Intermediate/Trust Anchor|
        +-------------------+                      +-----------------+ +-------------------------+

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

• Wallet Providers in signed Wallet Attestations (Appendix E of [OpenID4VCI]). The Wallet Instance obtains one or more Wallet Attestations from its Wallet Provider; each Wallet Attestation SHOULD include a trust_chain JOSE header parameter related to a Trust Anchor the Wallet Provider trusts, as defined in Section 4.3 of [OpenID.Federation];¶
• Wallet Providers or key storage components in signed Key Attestations (Appendix D of [OpenID4VCI]). A Key Attestation MAY include a trust_chain JOSE header parameter as specified in Appendix D.1 and Appendix F.1 of [OpenID4VCI];¶
• Credential Verifier Providers in signed Verifier Attestation JWTs ([OpenID4VP]). The Credential Verifier Instance obtains a Verifier Attestation JWT from its Credential Verifier Provider; that JWT SHOULD include a trust_chain JOSE header parameter related to a Trust Anchor the Credential Verifier Provider trusts;¶
• Credential Verifiers in signed request objects. The Wallet Instance obtains a presentation request that includes a Trust Chain using a Trust Anchor that the Credential Verifier has in common with the Wallet Provider, according to the information obtained in the wallet_metadata parameter provided by the Wallet using the Request URI POST;¶
• Credential Issuers in signed Digital Credentials. A Credential Verifier (or Wallet Instance) obtaining such a Credential MAY use the included Trust Chain to establish trust in the Credential Issuer without real-time Federation Entity Discovery, as described in Credential Verifiers Establishing Trust in Credential Issuers.¶

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. Security Considerations

The security considerations in [OpenID.Federation], [OpenID4VP], and [OpenID4VCI] apply to this specification.¶

Without per-instance attestation, a Credential Verifier either routes every request through its backend for signature, which does not work offline, or deploys the same organizational key on every terminal, so that one compromise affects the whole organization. Verifier Attestation JWTs bind a distinct key to each instance instead. A Verifier Attestation JWT MUST NOT expand the Credential Verifier's entitlements. The Wallet accepts an attestation only when sub authorizes iss, either because they are the same Entity or because iss is listed in the final credential_verifier_providers metadata of sub. A compromised Credential Verifier Provider can at worst narrow the entitlements of the Credential Verifiers that authorized it. It cannot name an arbitrary sub. Authorization authority remains with the federation.¶

Section 3.1 of [OpenID.Federation] states that Federation Entity Keys SHOULD NOT be used in other protocols. Credential Verifier Providers SHOULD use keys distinct from their Federation Entity Keys to sign Verifier Attestation JWTs, and publish those keys only in the jwks parameter of openid_credential_verifier_provider metadata.¶

11. IANA Considerations

12. Acknowledgements

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, Eduardo Perottoni, Samuel Rinnetmäki, Giada Sciarretta, and Niels van Dijk.¶

Appendix A. Notices

Copyright (c) 2026 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, Final Specification, or Final Specification Incorporating Errata Corrections solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts, Final Specifications, and Final Specification Incorporating Errata Corrections 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 (found at openid.net) requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. OpenID 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 ]]¶

-06¶

• Defined Credential Verifier Provider (openid_credential_verifier_provider) and profiled OpenID4VP Verifier Attestation JWTs so Credential Verifier Instances (POS terminals, mobile readers) are attested like Wallet Instances (federation-wallet issue #60). iss is the Provider Entity Identifier resolved through the Trust Chain; sub is the Credential Verifier; cnf is the instance key. Attestation MAY narrow the Credential Verifier's entitlements and MUST NOT expand them.¶
• Attestation signing keys come only from openid_credential_verifier_provider jwks. Limited this use case to OpenID4VP, including the Digital Credentials API; ISO/IEC 18013-5 reader authentication is out of scope. A Verifier Attestation JWT MAY carry a Token Status List status claim so one Credential Verifier Instance can be revoked; the same claim applies to Wallet Attestations. sub authorizes iss by equality or by listing it in credential_verifier_providers. The Wallet checks a request against both the attestation constraints and the final verifier metadata.¶
• Added note on prefixing Client ID values used with OpenID4VP.¶
• Filled Example 1 openid_credential_verifier metadata with protocol keys, registered endpoints, and an authorized DCQL query (federation-wallet issue #65).¶
• Clarified that Wallet Instance types are informative and that federation processing does not vary by type (federation-wallet issue #64). Trust with the Holder is established through the Wallet Provider and Wallet Attestation for all instance types.¶
• Removed unused Terminology subsection on Direct Trust, Web of Trust, and Trusted Third-Party (federation-wallet issue #62). Defined Trust Model and Trust Framework as terms used in the specification, restated that trust is established through Trust Anchors (participants MAY configure more than one) in the Four-Party Model, and aligned the Credential Verifier metadata rationale with that language.¶
• Profiled Trust Marks for wallet ecosystems instead of restating OpenID Federation (federation-wallet issue #66): issuance entitlement, verifier authorization, Wallet Provider assurance, and verifier attributes presented to the End-User.¶
• Clarified Four-Party Model figure captions so horizontal arrows are protocol interactions and vertical arrows are trust evaluation (federation-wallet issue #63). The section and diagrams are retained. Added Digital Credential, Credential, and Credential Issuer Identifier to Terminology. Restored Wallet Attestation and Key Attestation citations from OpenID4VCI after a merge had moved Wallet Attestation back to OpenID4VP.¶
• Added Federation Trust Discovery use case "Credential Verifiers Establishing Trust in Credential Issuers" to resolve federation-wallet issue #48: map https issuer identifiers carried in presented Credentials to Federation Entity Identifiers, perform Federation Entity Discovery (or validate an offline trust_chain), and verify Credentials with keys from the validated Trust Chain. Specified that key binding is verified against openid_credential_issuer jwks, and that issuer identity is established by matching the identifier of the issuer obtained from the Digital Credential to the Federation Entity Identifier and validating a Trust Chain to a configured Trust Anchor. Clarified that W3C VC issuer / issuer.id is not used as the Federation Entity Identifier when it differs from the OpenID4VCI Credential Issuer Identifier. DIDs and ISO mDOC X.509 bindings remain out of scope for this version; extensions MAY define DID Leaf Entities. Clarified that Trust Discovery use cases are independently adoptable by Trust Frameworks.¶

-05¶

• Clarified Credential Issuers Establishing Trust in the Wallet Provider and Credential Issuers Establishing Trust in the Wallet to resolve federation-wallet issue #29, with normative references to OpenID4VCI Wallet Attestation (Appendix E), Key Attestation (Appendix D), proof types (Appendix F), Credential Request (Section 8.2), Credential Issuer metadata (Section 12.2.4), and Trust between Wallet and Issuer (Section 13.3), plus OAuth 2.0 Attestation-Based Client Authentication.¶
• Distinguished Wallet Attestation (client authentication at PAR / Token endpoints) from Key Attestation (Credential Request proofs).¶
• Profiled use of the OpenID Federation trust_chain JOSE header on Wallet Attestations and Key Attestations for offline trust evaluation.¶
• Corrected Terminology so Wallet Attestation and Key Attestation are cited from OpenID4VCI rather than OpenID4VP.¶
• Added subsection "OpenID Credential Issuer Metadata Parameters" under OpenID Credential Issuer Entity Type, profiling openid_credential_issuer metadata when used in Wallet federations.¶
• Documented credential_issuer, authorization_servers, and the OpenID4VCI parameters (credential_endpoint, nonce_endpoint, display, credential_configurations_supported, etc.) as carried in Federation metadata/metadata_policy.¶
• Added jwks: scope for signature of responses, tokens, and issued credentials; requirement that public keys used to verify signed Credential Issuer metadata (e.g. at .well-known/openid-credential-issuer per OpenID4VCI 12.2.3) be provided in openid_credential_issuer jwks when trust frameworks require it.¶
• Extended OpenID Credential Verifier entity type with additional metadata parameters: jwks, request_uris, response_uris, redirect_uris, and dcql_queries, with definitions and rationale aligned to the Trusted Third-Party trust model.¶
• Specified that when a Credential Verifier participates in a federation, Wallets MUST use jwks from federation metadata and MUST ignore jwks from client_metadata in the Authorization Request.¶
• Added section on using openid_credential_verifier metadata and metadata_policy in Subordinate Statements for policy enforcement by superior entities (endpoints, keys, dcql_queries).¶
• Clarified dcql_queries override rules: metadata in a Subordinate Statement overrides request/client_metadata; metadata_policy applies to verifier metadata or, if absent, to client_metadata; profiles MAY use Trust Marks to convey dcql_queries-related policies.¶
• Defined dcql_queries as a non-empty array of DCQL query objects (as in OpenID4VP) so verifiers can publish multiple authorized queries for different situations.¶
• Added IANA Considerations registering the dcql_queries parameter.¶
• Added Security Considerations.¶

-04¶

• Changed name to OpenID Federation for Wallet Architectures 1.0.¶
• Updated references.¶
• Removed unused references.¶

-03¶

• Added section about Credential Issuers establishing trust with Wallet Solution¶
• Added sequence diagrams using ascii-arts¶
• Renamed Third-Party Trust Model to Trusted Third-Party Model¶
• Added legends to the figures¶
• Added section about Wallet Checking the Non-Revocation of its Wallet Provider¶
• Added implementation Considerations for Offline Flows¶
• Improved clarification about using metadata in Subordiante Statements¶

-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