Disclaimer

This document provides a practical overview of key processes related to metadata and Trust Mark validation in the OpenID Federation. It is not exhaustive and does not cover all aspects of the OpenID Federation 1.0 specification. For complete details, including advanced use cases and comprehensive workflows, refer to the OpenID Federation 1.0 specification.

Implementers are advised to consult the official specification to ensure full compliance and alignment with federation standards.

...

Table of Contents

Introduction

The OpenID Federation forms the backbone of the DC4EU Pilot Wallet ecosystem, enabling secure, scalable

Table of Contents

Introduction

The OpenID Federation forms the backbone of the DC4EU Wallet ecosystem, enabling secure, scalable, and interoperable interactions between diverse entities such as credential issuers, verifiers, and wallet providers. As part of the EU Digital Identity Wallet (EUDIW) initiative, the federation aims to facilitate seamless credential management across national and sectoral boundaries, adhering to the revised eIDAS regulation and the Architectural Reference Framework (ARF).

Purpose Purpose of the Federation

Trust Framework: Establish and maintain a scalable trust model based on cryptographic proofs and hierarchical relationships.
Interoperability: Enable cross-border, multi-stakeholder interaction while ensuring technical, semantic, and organizational compatibility.
Ecosystem Integration: Support the issuance, storage, and verification of credentials such as EHIC and PDA1 within the EUDIW ecosystem.

...

Definition: A set of public keys in JSON format, typically published at /.well-known/jwks.json.
Purpose: Used for verifying the signatures of JWTs.

...

Definition: A feature of credentials that allows holders to share only specific claims or data fields with verifiers.
Purpose: Enhances privacy and minimizes data exposure.

...

Federation Overview

The OpenID Federation in the DC4EU Wallet ecosystem operates as a dynamic trust framework, enabling seamless and scalable interactions between issuers, wallets, and verifiers. By leveraging cryptographic proofs and hierarchical relationships, the federation ensures secure credential issuance, management, and verification.

...

Federation Architecture

...

and Core Entities

The federation follows a hierarchical structure, with the Trust Anchor (TA) serving as the root of trust. Below the TA, subordinate entities like Subordinate entities, including Trust Mark Issuers, Credential Issuers, and Wallet Providers, and Verifiers, establish their roles through dynamic metadata exchanges and trust chains.

Key

...

Entities and Their Roles:

Trust Anchor (TA):
Root entity responsible for
- Acts as the root of trust, defining federation policies and signing metadata.
- Ensures the authenticity and integrity of the federation’s trust framework.
Trust Mark Issuer (TMI):
- Issues
cryptographic
- Trust Marks to
attest to an entity’s compliance with federation policies
- certify entities’ compliance with trust and interoperability requirements.
- Plays a critical role in policy enforcement within the federation.
Credential Issuers:
- Generate and issue verifiable credentials (e.g., EHIC, PDA1).
- Interface with authentic sources to retrieve user attributes.
Wallet Providers:
- Enable Wallet Instance registration and interaction with the federation.
- Act as the primary interface for wallets
to discover and interact with
- , which are external to the federation.
Verifiers:
Validate the authenticity and integrity of credentials for relying parties.

Core Entities and Their Roles

Trust Anchor (TA):
- Signs metadata for subordinate entities.
- Acts as the authoritative root for trust relationships.
Trust Mark Issuer (TMI):
- Issues Trust Marks as cryptographic JWTs.
- Ensures compliance with federation policies.
Credential Issuers:
- Issue verifiable credentials to wallets.
- Interface with authentic sources to retrieve user attributes.
Wallet Providers and Holders:
- An entity within the federation that enables Wallet Instance registration for wallets.
- Holders (wallets) store and manage credentials securely.
Verifiers:
- Validate credentials presented by holders.
- Ensure compliance with schemas and trust models.

Trust Workflow

The trust workflow involves metadata discovery, validation, and trust establishment:

Metadata Exchange:
- Entities publish their Entity Configuration Document at /.well-known/openid-federation.
- Contents of the Entity Configuration Document include, but are not limited to:
  - Entity ID: Unique identifier for the entity.
  - Entity Role(s): Specifies the role of the entity (e.g., Credential Issuer, Trust Anchor).
  - Authority Hints: Lists trusted superior entities, such as the Trust Anchor.
  - JWKS URL: Location of the JSON Web Key Set for signature validation.
  - Trust Marks: Optional; may list issued or received Trust Marks.
Validation:
- Metadata published by subordinate entities is validated by other federation participants using the Trust Anchor's public keys.
- Trust Marks issued by the TMI are used to attest to an entity's conformance with a well-scoped set of trust and interoperability requirements as determined by an accreditation authority.
Dynamic Trust Relationships:
- Unlike static configurations, trust is established dynamically through metadata exchange, enabling scalability and flexibility.

Standards and Protocols

OpenID Connect: Forms the foundation for authentication and API security.
OpenID Federation: Extends OpenID Connect with dynamic metadata exchange and hierarchical trust.
OpenID4VCI: Enables credential issuance using OAuth2 flows.
OpenID4VP: Facilitates credential presentation for selective disclosure.

Trust Establishment and Validation

In the OpenID Federation, trust is established and validated dynamically through cryptographic proofs, hierarchical relationships, and metadata exchange. This ensures secure interactions among entities while supporting scalability and flexibility across the DC4EU Wallet ecosystem.

Role of the Trust Anchor

The Trust Anchor (TA) is the root of trust for the federation. It serves as the foundational authority, enabling trust relationships by:

Defining Policies: Establishing the rules and compliance criteria for entities within the federation.
Signing Subordinate Statements: Issuing signed statements about subordinates, which include attributes such as keys and roles, to establish a chain of trust that allows relying parties to validate subordinate entities.
Anchoring Trust: Acting as the central point of trust verification for the federation hierarchy.

Trust Mark Issuance

The Trust Mark Issuer (TMI) plays a critical role in attesting to an entity’s conformance with a well-scoped set of trust and interoperability requirements as determined by an accreditation authority.

Process

Request Submission: An entity (e.g., a Credential Issuer) submits a request for a Trust Mark to the TMI.
Evaluation: The TMI evaluates whether the entity meets the predefined trust and interoperability requirements.
Issuance: If compliant, the TMI issues a Trust Mark, which is a signed JWT (JSON Web Token) containing, but not limited to:
- iss: The issuer of the Trust Mark (the TMI).
- sub: The entity receiving the Trust Mark.
- id: The Trust Mark identifier, represents the specific policy or requirement being attested to.
- iat: Issued at timestamp indicating when the Trust Mark was created.
- exp: Expiration timestamp defining the Trust Mark’s validity period.

Trust Marks in the Federation

- Validate credentials presented by holders.
- Ensure that credentials adhere to defined schemas and trust models.

...

Trust Workflow

The trust workflow involves metadata discovery, validation, and trust establishment:

Metadata Exchange:
- Entities publish their Entity Configuration Document at /.well-known/openid-federation.
- Contents of the Entity Configuration Document include, but are not limited to:
  - Entity ID: Unique identifier for the entity.
  - Entity Role(s): Specifies the role of the entity (e.g., Credential Issuer, Trust Anchor).
  - Authority Hints: Lists trusted superior entities, such as the Trust Anchor.
  - JWKS URL: Location of the JSON Web Key Set for signature validation.
  - Trust Marks: Optional; may list issued or received Trust Marks.
Validation:
- Metadata published by subordinate entities is validated by other federation participants using the Trust Anchor's public keys.
- Trust Marks issued by the TMI are used to attest to an entity's conformance with a well-scoped set of trust and interoperability requirements as determined by an accreditation authority.
Dynamic Trust Relationships:
- Unlike static configurations, trust is established dynamically through metadata exchange, enabling scalability and flexibility.

...

Standards and Protocols

OpenID Connect: Forms the foundation for authentication and API security.
OpenID Federation: Extends OpenID Connect with dynamic metadata exchange and hierarchical trust.
OpenID4VCI: Enables credential issuance using OAuth2 flows.
OpenID4VP: Facilitates credential presentation for selective disclosure.

Trust Establishment and Validation

In the OpenID Federation, trust is established and validated dynamically through cryptographic proofs, hierarchical relationships, and metadata exchange. This ensures secure interactions among entities while supporting scalability and flexibility across the DC4EU Wallet ecosystem.

...

Role of the Trust Anchor

The Trust Anchor (TA) is the root of trust for the federation. It serves as the foundational authority, enabling trust relationships by:

Defining Policies: Establishing the rules and compliance criteria for entities within the federation.
Signing Subordinate Statements: Issuing signed statements about subordinates, which include attributes such as keys and roles, to establish a chain of trust that allows relying parties to validate subordinate entities.
Anchoring Trust: Acting as the central point of trust verification for the federation hierarchy.

...

Trust Mark Issuance

The Trust Mark Issuer (TMI) plays a critical role in attesting to an entity’s conformance with a well-scoped set of trust and interoperability requirements as determined by an accreditation authority.

Process

Request Submission: An entity (e.g., a Credential Issuer) submits a request for a Trust Mark to the TMI.
Evaluation: The TMI evaluates whether the entity meets the predefined trust and interoperability requirements.
Issuance: If compliant, the TMI issues a Trust Mark, which is a signed JWT (JSON Web Token) containing, but not limited to:
- iss: The issuer of the Trust Mark (the TMI).
- sub: The entity receiving the Trust Mark.
- id: The Trust Mark identifier, represents the specific policy or requirement being attested to.
- iat: Issued at timestamp indicating when the Trust Mark was created.
- exp: Expiration timestamp defining the Trust Mark’s validity period.

Trust Marks in the Federation

EHIC Credential Trust Mark:
- ID: http://dc4eu.example.com/EHICCredential/se
- Purpose: Attests to the entity’s compliance with EHIC credential issuance standards.
PDA1 EHIC Credential Trust Mark:
- ID: http://dc4eu.example.com/EHICCredentialPDA1Credential/se
- Purpose: Attests to the entity’s compliance with EHIC credential issuance standards.
PDA1 Credential Trust Mark:
- ID: http://dc4eu.example.com/PDA1Credential/se
- Purpose: Certifies the entity’s adherence Certifies the entity’s adherence to PDA1 requirements.

...

Entity Validation

...

Role: The Trust Anchor (TA) serves as the root of trust, signing and validating metadata for subordinate entities.
Endpoint: https://openidfed-test-1.sunet.se:7001

Public Keys:

Code Block

language	js

{
   "https://openidfed-test-1.sunet.se:7001": {
      "keys": [
            {
               "kty": "RSA",
               "use": "sig",
               "kid": "UFpoajluZU42dTNUUXo5RnhBVEJnRk9JY2NtU1JKdlVYUk1RUFRyVkFFRQ",
               "n": "p9S2whcSjmBdxerp80tIJreUUmZiGNGXIocJlNjx9pgD5_WD2l6mBNuEZMpP-QUB_TSV3VesNiqmOdydGp1wkfQ-NmVdoso29FjEdgrckLIwirAVmVQ6bGQQnXJrR56mRz0QqENi11vVpbDj6hsprxK1EZBQL-sQ2kem289B_BCNT-NvwVHrYJlaQA32z7cs1a7W8wt9eLxA10PeiYMgDVU_69wKBw4YrjjozOHKMRGchUQEjQhfSZfk49bip_5TNz4dmBmSCIbdE2yilFrfRSNrh7q2myuyDE3k2QZbSOXXGGT1LtHO74WIY58v-M3A7_zxp0f2Eo9ZD3N4h-InIw",
               "e": "AQAB"
            },
            {
               "kty": "EC",
               "use": "sig",
               "kid": "Nm82cTJKMDkydXhxOUMtTm0teFpMWlZiR0ZVa2U3YVVtbkJTV3hBd3FqOA",
               "crv": "P-256",
               "x": "69XlQkKYfWJDXAv_Vbrqyfz9gfAhu1qQ4mtLde18-Cg",
               "y": "ntBwdhy4_cS2PRBS-xdKkNwcO1yQP8TdoOHbHN9Yjv8"
            }
      ]
   }
}

...

Trust Mark Issuer

Role: The Trust Mark Issuer (TMI) certifies entities’ compliance with federation policies by issuing cryptographic Trust Marks.
Endpoint: https://openidfed-test-1.sunet.se:6001
Notes: The TMI’s public keys for verifying Trust Marks are Metadata for the TMI is accessible at: https://openidfed-test-1.sunet.se:6001/.well-known/jwks.json openid-federation

...

Wallet Provider

Role: Acts as the intermediary for wallets to interact with the federation, supporting Wallet Instance registration.
Endpoint: https://openidfed-test-1.sunet.se:5001
Notes: Metadata for the Wallet Provider is accessible at: https://openidfed-test-1.sunet.se:5001/.well-known/openid-federation

...

Credential Issuer

Role: Issues credentials (e.g., EHIC, PDA1) to wallets upon successful interaction.
Endpoint: https://satosa-test-1.sunet.se/
Notes: Supports credential issuance based on OpenID4VCI protocols.

...

Usage Notes

Metadata Retrieval

...

Retrieve the Entity Configuration Document from a federation node’s /.well-known/openid-federation endpoint:

Code Block

language	bash

curl https://openidfed-test-1.sunet.se:7001/.well-known/openid-federation

...

The metadata is encoded as a JSON Web Token (JWT), which must be validated and decoded securely

...

Decoding Metadata

...

:

...

Fetch the public keys from the Trust Anchor’s /.well-known/jwks.json endpoint:

Code Block

language	bash

curl https://openidfed-test-1.sunet.se:7001/.well-known/jwks.js

...

Decoding Metadata After Validation:

...

Decode it using tools such as base64:

Code Block

language	bash

echo '<Base64URL-encoded payload>' | tr '_-' '/+' | base64 -d

Decode the JWT to inspect the payload:

Extract the payload (the second segment of the JWT).
Decode it using tools such as base64 and use tools like jq to explore the JSON payload:
Code Block
language bash
echo '<Base64URL-encoded payload>' | tr '_-' '/+' | base64 - | jq

Validating Metadata Signatures:

To validate the signature of metadata, the public keys of the entity can be represented in one of three ways in the metadata. Each representation has specific handling requirements.

jwks (JSON Web Key Set by Value):
- The keys are embedded directly in the metadata. They are inherently validated as part of the metadata’s cryptographic signature. No additional fetch operation is required.
jwks_uri and signed_jwks_uri:

- jwks_uri: A URI pointing to the JSON Web Key Set hosted by the entity.
- signed_jwks_uri: A URI pointing to a signed JWT containing the key set.
- In both cases, the keys must be fetched from the URI

Fetching and Validating Trust Marks:

...

- :
  Code Block
  language bash
  curl

...

Inspecting Decoded JSON:

After validation, use tools like jq to explore the JSON payload:

...

language	bash

...

- <jwks-uri>
- For signed_jwks_uri, the fetched JWT must also be validated before the keys can be used.

Signature Validation:
Use a library or tool such as CryptoJWT to validate the signature. CryptoJWT is a Python library specifically designed for OpenID-related standards, including JSON Web Token (JWT) handling and signature verification.

...

Security Notes:

Always validate JWT signatures using trusted public keys before using the data. Ensure the key’s kid (Key ID) in the JWT header matches a key in the jwks.json document.

Page tree

Versions Compared

Old Version 5

New Version Current

Key

Introduction

Introduction

Purpose Purpose of the Federation

Federation Overview

Federation Architecture

and Core Entities

Key

Entities and Their Roles:

Core Entities and Their Roles

Trust Workflow

Standards and Protocols

Trust Establishment and Validation

Role of the Trust Anchor

Trust Mark Issuance

Process

Trust Marks in the Federation

Trust Workflow

Standards and Protocols

Trust Establishment and Validation

Role of the Trust Anchor

Trust Mark Issuance

Process

Trust Marks in the Federation

Entity Validation

Trust Mark Issuer

Wallet Provider

Credential Issuer

Usage Notes

Metadata Retrieval

Decoding Metadata

:

Validating Metadata Signatures:

Security Notes:

Page tree

Page History

Versions Compared

Old Version 5

New Version Current

Key

Introduction

Introduction

Purpose Purpose of the Federation

Federation Overview

Federation Architecture

and Core Entities

Key

Entities and Their Roles:

Core Entities and Their Roles

Trust Workflow

Standards and Protocols

Trust Establishment and Validation

Role of the Trust Anchor

Trust Mark Issuance

Process

Trust Marks in the Federation

Trust Workflow

Standards and Protocols

Trust Establishment and Validation

Role of the Trust Anchor

Trust Mark Issuance

Process

Trust Marks in the Federation

Entity Validation

Trust Mark Issuer

Wallet Provider

Credential Issuer

Usage Notes

Metadata Retrieval

Decoding Metadata

:

Validating Metadata Signatures:

Security Notes: