DIIP and OpenID Federation

[samuelmr]

Let's use this discussion thread to define how the DIIP-compliant wallets and agents should use the OpenID Federation specification.

Links:

• OpenID Federation
• OpenID Federation Wallet Architectures

[samuelmr]

In openid/federation-wallet#51, I added a missing aspect to the Wallet Architectures spec, trying to define how trust is established between the verifier and the issuer.

[TimoGlastra]

I have added a comment to the issue related to this PR: openid/federation-wallet#48 (comment)

[samuelmr]

Some time ago, I proposed the did:oidf DID method. I still believe that method might be useful for ecosystems that want to use OpenID Federation as the trust establishment layer. To succeed, the method should see some implementations or at least interest from some vendors to implement it. Might be a chicken/egg problem...

[TimoGlastra]

Not sure we'd go that direction. I'd rather define a way to use Federation directly in places where DIDs are used.

[samuelmr]

What we currently lack:

• A way for a credential issuer to tell a wallet that the issuer belongs to a federation (a pointer to the issuer's OpenID Federation Entity Configuration). Using this information, the wallet could show the wallet user that the issuer can be trusted. Some wallet vendors have implemented this functionality, but it's not defined. A wallet can search for a .well-known/openid-federation file in the credential_issuer endpoint in the credential offer. This works, but no specification explicitly describes this flow.
• A way for a credential verifier to tell a wallet that the issuer belongs to a federation (a pointer to the verifier's OpenID Federation Entity Configuration). Using this information, the wallet could show the wallet user that the verifier can be trusted. Some wallet vendors have implemented this functionality, but it's not defined. A wallet can search for a .well-known/openid-federation file somewhere (in the service that sends the Authorization Request or in the Request Object location). This works, but no specification explicitly describes this flow.
• A way for a credential issuer to tell the verifier that the issuer belongs to a federation (a pointer to the issuer's OpenID Federation Entity Configuration). Using this information, the verifier could check that the issuer is a member in a federation.

Do we agree that these are the main functional requirements?

[TimoGlastra]

A wallet can search for a .well-known/openid-federation file in the credential_issuer endpoint in the credential offer. This works, but no specification explicitly describes this flow.

I think we should add this to the wallet architectures specification

A wallet can search for a .well-known/openid-federation file somewhere (in the service that sends the Authorization Request or in the Request Object location). This works, but no specification explicitly describes this flow.

This is defined in OID4VP with the openid_federation client id prefix right? That's how we have implemented it

A way for a credential issuer to tell the verifier that the issuer belongs to a federation

Agreed. I created a comment here: openid/federation-wallet#48 (comment)

[samuelmr]

If the issuer and verifier were identified by plain HTTPS URLs, it would be trivial to get their Entity Configuration files.

In the DIIP community, we want issuers and verifiers to be identified by DIDs. The did:web method prescribed by the DIIP profile has a 1-to-1 mapping to an HTTPS URL, but no specification clearly defines the discovery path from a did:web identifier to an OpenID Federation Entity Configuration.

The main author of the OpenID Federation Wallet Architectures wasn't keen on introducing additional discovery mechanisms in that spec.

[TimoGlastra]

I think in the call yesterday we agreed that we want to come up with a solution that is not bound to dids as a base, to make the solution more generic. This could be added to OpenID Federation Wallet Architectures, and we could define in DIIP how you could use DIDs to sign credentials.

However I'm still not 100% sure what the benefits are of using DIDs if we're using OpenID Federation. Especially if we're only using did:web.

I do think an optional way to link a DID to a federation makes sense (using the alternative names proposed in the wallet architectures).

Only reason for using DIDs I can see is that the DID could be part of multiple ecosystems/trust registries that are not OpenID Federation and provide better interoperability in that sense.

I would like however credentials issued as part of DIIP with Federation to be as much aligned with the Wallet Architectures to promote interoperability across implementations (so having an additional non-breaking link between DID and federation on top of the base, rather than using the DID as the federation discovery mechanism)

[samuelmr]

The second Implementor's Draft of OID4VP included the section 10.2. Support for Federations/Trust Schemes with an example:

{
   "termsOfUse":[
      {
         "type":"<uri that identifies this type of terms of use>",
         "federations":[
            "<list of federations/trust schemes the Credential Issuer asserts it is a member of>"
         ]
      }
   ]
}

This section is removed from the subsequent versions of the specification. It would be a nice way to refer to the federation from a credential, but it is somewhat tied to W3C VCDM credentials (1.1 or 2.0). The same structure could be used in SD-JWT VC credentials, but we would need a specification to define the behaviour. If the OpenID Federation Wallet Architectures maintainers are reluctant to include additional discovery mechanisms into that document, what would be the correct place to define the termsOfUse discovery?

[samuelmr]

With the help of Claude, I drafted a proposal for a specification that defines how DID Documents can be used to point to OpenID Federation Entity Statements. See https://claude.ai/public/artifacts/d619613b-4506-4140-b21b-b5e64fc3fc3b

Using the DID document to reference OpenID Federation means that we didn't need to change the credential format specifications, or the credential protocol specifications, or the OpenID Federation specifications in any way. This would be limited to DIDs.

If there is interest in advancing this, we still would need a body to host this specification. Would DIF be a good home?

[samuelmr]

The DIIP Meetup on October 30th discussed that the support for OpenID Federation could be added as an optional requirement to DIIP v5.

[samuelmr]

My proposal in today's call:

DIIP v5 requires that DIIP-compliant issuers must publish their OpenID Federation Entity Configurations, and DIIP-compliant verifiers must be able to resolve the trust chain (perhaps using an existing resolve endpoint of an OpenID Federation server.

There would be no requirements for wallets, but they could optionally use the issuer's Entity Configuration to support the holder's trust decisions.

DIIP v6 would then require verifiers to publish their Entity Configurations and wallets to support OpenID Federation to establish trust to both issuers and verifiers.

[surfnet-niels]

For the upcoming pilots we (SURF, Animo, Impierce & Sphereon) have agreed opon:

• Draft 3 of the OpenID Federation for Wallet architectures spec as the starting point
• Issuers MUST publish OpenID Federation Entity Configuration
• Verifiers MUST OpenID Federation Entity Configuration
• Verifiers MUST validate the issuers via the trust chain
• Wallet MAY validate issuer and verifier
• Wallet MAY present end user with information on Trust Anchor (Without at this point defining how detailed).
• Use of wallet attestation is out of scope.

[TimoGlastra]

Where "Verifiers MUST validate the issuers via the trust chain" is still the most underspecified item I think.

[samuelmr]

What is defined:

• OpenID Federation tells how to get the Entity Configuration based on the Entity Id
• OpenID Federation Wallet Architectures 8.3 defines a top-down process from the trust anchor to the credential issuer's Entity Configuration
• OID4VP 5.9.3 defines how the Request Object can refer to the verifier's Entity Configuration
• OpenID Federation Wallet Architectures 8.6 defines a process to resolve the trust chain starting from the verifier's Entity Configuration

What is missing:

• normative language defining where the credential issuer should put their Entity Configuration
• normative language defining what metadata should be in the issuer's Entity Configuration
• normative language defining what metadata should be in the issuer's superior's entity statement about the issuer
• normative language defining what metadata should be in the verifier's Entity Configuration
• normative language defining what metadata should be in the verifier's superior's entity statement about the verifier
• normative language defining how the verifier discovers the issuer's Entity Configuration

Initial thoughts about the issuer's configuration

• as an example, one credential issuer endpoint is at https://procivis.sandbox.findy.fi/ssi/openid4vci/final-1.0/df0fc41b-f631-4f3c-b4ba-6b9e13c75e54
• per OID4VCI, the .well-known path for the issuer metadata is https://procivis.sandbox.findy.fi/.well-known/openid-credential-issuer/ssi/openid4vci/final-1.0/df0fc41b-f631-4f3c-b4ba-6b9e13c75e54 (the .well-known location is directly after the host part of the URL)
• per OpenID Federation, if the credential issuer endpoint is the Entity ID of the issuer, the Entity Configuration should be put to https://procivis.sandbox.findy.fi/ssi/openid4vci/final-1.0/df0fc41b-f631-4f3c-b4ba-6b9e13c75e54/.well-known/openid-federation (the .well-known location is appended to the end of the path – a practice used also in earlier OID4VCI drafts but changed in the final version)
• the issuer's Entity Configuration metadata should include
  • the OID4VCI issuer metadata of the issuer (this could override the OID4VCI issuer metadata, which the wallet could ignore)
  • the authorization server metadata of the issuer (including information about the issuer's keys), enabling the verifier to establish trust in the issuer
  • the authority_hints property

Initial thoughts about the content of the subordinate statement about the issuer

• the Subordinate Statement should include
  • the OID4VCI issuer metadata of the issuer (at least the credential_configurations_supported property with credential types as keys and at least format specified in the value objects)
  • optionally. the authorization server metadata of the issuer (including information about the issuer's keys)

Initial thoughts about the verifier's configuration

• the Request Object already contains information about the verifier
• the verifier's Entity Configuration should include the authority_hints property

Initial thoughts about the content of the subordinate statement about the verifier

• the Subordinate Statement could (in some cases) include some information about the credential types (and attributes?) that the superior thinks this verifier should be authorized to ask

Initial thoughts about the discovery of the issuer's configuration by the verifier

• it would be easiest to embed the whole trust chain of the issuer to the credential
• otherwise, the credential should include a pointer to the issuer's Entity Configuration
• alternatively, the issuer could point to its Entity Configuration in its DID document (see comment 14402158 in this thread)

[surfnet-niels]

Initial thoughts about the issuer's configuration

• as an example, one credential issuer endpoint is at https://procivis.sandbox.findy.fi/ssi/openid4vci/final-1.0/df0fc41b-f631-4f3c-b4ba-6b9e13c75e54
• per OID4VCI, the .well-known path for the issuer metadata is https://procivis.sandbox.findy.fi/.well-known/openid-credential-issuer/ssi/openid4vci/final-1.0/df0fc41b-f631-4f3c-b4ba-6b9e13c75e54 (the .well-known location is directly after the host part of the URL)
• per OpenID Federation, if the credential issuer endpoint is the Entity ID of the issuer, the Entity Configuration should be put to https://procivis.sandbox.findy.fi/ssi/openid4vci/final-1.0/df0fc41b-f631-4f3c-b4ba-6b9e13c75e54/.well-known/openid-federation (the .well-known location is appended to the end of the path – a practice used also in earlier OID4VCI drafts but changed in the final version)
• the issuer's Entity Configuration metadata should include
  • the OID4VCI issuer metadata of the issuer (this could override the OID4VCI issuer metadata, which the wallet could ignore)
  • the authorization server metadata of the issuer (including information about the issuer's keys), enabling the verifier to establish trust in the issuer
  • the authority_hints property

• I think we should leave the OID4VCI metadata as is at whatever endpoint they prefer, and tell OIDFed wallet MUST ignore it (as it is essentially untrusted)

• It is possible to do an integral copy of the OID4VCI metadata as OIDF4WA 7.1 I think seems to suggest. I could not find direct conflicts that would come from that.

• Do we mandate the "iss" in OIDfed Entity Configuration = "credential_issuer" in OID4VCI metadata for issuer entities?

• Other metadata elements we should support (inc multi language support) are all listed in OIDfed 5.2.2. There is a risk of duplication and inconsistency between this set and the OID4VCI metadata. Do we specify if OIDFed overrules the "inner" OpenID4VC? How tightly do we want to bind the OIDFed Entity COnfig and the OpenID4VCI metadata "display" section?

• For consideration: OpenID Connect OpenID Provider has its own entity type in OIDfed metadata, but I note in OIDF4WA 7.1 we have a more generic "federation_entity", and "openid_credential_issuer" is used to point to specifically OpenID4VCI.
  I feel having an openid_credential_issuer entity type would be more consistent with the general OIDFed specification?
  So not:

  "iss": "https://trust-anchor.example.com",
  "sub": "https://credential-verifier.example.it",
  "iat": 1616239022,
  "exp": 1616239322,
  "metadata": {
    "federation_entity": {
      "organization_name": "Example Credential Verifier",
    },
    "openid_credential_verifier": { ... as defined in the OpenID4VP specs ... }```
    
But rather:
```{
  "iss": "https://credential-issuer.example.it",
  "sub": "https://credential-issuer.example.it",
  "iat": 1616239022,
  "exp": 1616239322,
  "metadata": {
    "openid_credential_issuer": {
       "organization_name": "Example Credential Issuer",
    },
    "openid4vci": { ... as defined in the OpenID4CI specs ... }`` 

[samuelmr]

• I think we should leave the OID4VCI metadata as is at whatever endpoint they prefer, and tell OIDFed wallet MUST ignore it (as it is essentially untrusted)

Agreed. And we don't care if the logic for .well-known locations differs.

• It is possible to do an integral copy of the OID4VCI metadata as OIDF4WA 7.1 I think seems to suggest. I could not find direct conflicts that would come from that.

So the Leaf's Entity Configuration should contain the whole metadata. If the Superior also copies all metadata to the Subordinate Statement, and there is a conflict between the Subordinate Statement and the Entity Configuration, is the trust chain considered invalid?

• Do we mandate the "iss" in OIDfed Entity Configuration = "credential_issuer" in OID4VCI metadata for issuer entities?

I would say yes. But maybe I'd not require the signing key for Entity Configuration to be the same as used to sign credentials.

Do we specify if OIDFed overrules the "inner" OpenID4VC?

If we already stated that the OID4VC metadata should be ignored, what does this question mean?

How tightly do we want to bind the OIDFed Entity COnfig and the OpenID4VCI metadata "display" section?

I suppose the display sections (for the credential and for all claims) must be specified in the Entity Configuration if the OID4VCI issuer metadata is ignored. There is also a possibility to specify metadata in the VCT definition. Should it also be overridden by the Entity Configuration?

I feel having an openid_credential_issuer entity type would be more consistent with the general OIDFed specification?

I would put the generic information (organization_name, etc.) into the federation_entity property.

  "iss": "https://credential-issuer.example.it",
  "sub": "https://credential-issuer.example.it",
  "iat": 1616239022,
  "exp": 1616239322,
  "metadata": {
    "federation_entity": {
       "organization_name": "Example Credential Issuer",
    },
    "openid_credential_issuer": { ... as defined in the OpenID4CI specs ... }

Where did you pick the openid4vci property in your last example?

[samuelmr]

I feel having an openid_credential_issuer entity type would be more consistent with the general OIDFed specification?

Having re-read the spec (especially the example in 5.1.2. OpenID Connect Relying Party I think I understand why it might be preferable to have openid_credential_issuer as the entity type identifier (rather than using the generic federation_entity) as you suggested:

"metadata": {
    "openid_credential_issuer": {
       "organization_name": "Example Credential Issuer",
    },
    "openid4vci": { ... as defined in the OpenID4CI specs ... }

Since the OID4VCI issuer metadata can already include things like the issuer's name and logo, do we need two properties at all? How about just:

{
  "iss": "https://credential-issuer.example.it",
  "sub": "https://credential-issuer.example.it",
  "iat": 1616239022,
  "exp": 1616239322,
  "metadata": {
    "openid_credential_issuer": {
      "issuer": "https://credential-issuer.example.it",
      "display": [
        {
          "name": "Example Issuer",
          "locale": "en-US",
          "logo": {
            "uri": "https://credential-issuer.example.it/logo.png",
            "alt_text": "Example Logo"
          }
        }
      ],
      "credential_issuer": "https://credential-issuer.example.it",
      "authorization_endpoint": "https://credential-issuer.example.it/authorize",
      "authorization_servers": [
        "https://credential-issuer.example.it/authorize"
      ],
      "credential_endpoint": "https://credential-issuer.example.it/credential",
      "credential_configurations_supported": {
        "sd_jwt_vc_example": "..."
      }
    }
  }
}

[surfnet-niels]

@samuelmr OIDF4WA chapter 7.1 provides an example of verifier Entity Configuration where, as I interpret it, the intent is to 1-on-1 copy the verifier OpenID4VP metadata into the "openid_credential_verifier" claim.
I like that approach as it:

• reduces duplication of claims and
• clearly separates the trust layer from the transport layer and
• isolates us somewhat of changes to the OpenID4VP/VCI specification wrt metadata

However, in e.g. OIDfed 5.1.2. The specification showcases OP Entity Configuration which duplicates parts of the OP metadata which could also be discovered if OIDC Discovery was being used. That is also what you are showing in your last example

{
  "iss": "https://credential-issuer.example.it",
  "sub": "https://credential-issuer.example.it",
  "iat": 1616239022,
  "exp": 1616239322,
  "metadata": {
    "openid_credential_issuer": {
      "issuer": "https://credential-issuer.example.it",
      "display": [
        {
          "name": "Example Issuer",
          "locale": "en-US",
          "logo": {
            "uri": "https://credential-issuer.example.it/logo.png",
            "alt_text": "Example Logo"
          }
        }
      ],
      "credential_issuer": "https://credential-issuer.example.it",
      "authorization_endpoint": "https://credential-issuer.example.it/authorize",
      "authorization_servers": [
        "https://credential-issuer.example.it/authorize"
      ],
      "credential_endpoint": "https://credential-issuer.example.it/credential",
      "credential_configurations_supported": {
        "sd_jwt_vc_example": "..."
      }
    }
  }
}

the benefit of this approach is we have more control over various part of the metadata, but at the same time we will have to duplicate several elements already found in the OpenID4VP/VCI

[surfnet-niels]

Initial thoughts about the content of the subordinate statement about the verifier

the Subordinate Statement could (in some cases) include some information about the credential types (and attributes?) that the superior thinks this verifier should be authorized to ask

The assumption here being that the wallet should enforce that? Or at least warn if there is a mismatch?

I agree this capability would be very powerful especially from legal perspective, yet at the same time I am wondering/worrying how complex that would become.

Generally speaking OIDfed has the Metadata Policy capability, which is I think intended as away to technically enforce superior policy on subordinate entities. I am no so sure however if it was ever envisioned as way to express a policy in such detail as would be needed here.

As an alternative could we in some way use DCQL here? This would allow the TA to very clearly specify as DCQL is rather rich in its capabilities. It would also be very easy to test for a wallet as it could just directly compare the incoming DCQL from the verifier with the info from the TA. We could probably express the TA credential requirements in a new claim or better perhaps in a novel "additional operator" as described in OIDFed 6.1.3.2

[TimoGlastra]

The EUDI trust model uses a DCQL definition to determine what a relying party can request. The wallet checks if the query is a subset of the query in the registry.

This is implemented in our wallet and could be reused for OpenID Federation as well

[TimoGlastra]

This is the ETSI definition that includes the DCQL query: https://www.etsi.org/deliver/etsi_ts/119400_119499/119475/01.01.01_60/ts_119475v010101p.pdf

[surfnet-niels]

Initial thoughts about the discovery of the issuer's configuration by the verifier

it would be easiest to embed the whole trust chain of the issuer to the credential

Would that work?

• The chain contains signed statements for which the key material must be renewable, but if it is baked into a credential it might need to live for a long time?

• Also: which trust chain? You build a chain against a TA, but there is no requirement that there is only 1 TA at play here. E.g. if the chain would be against a gov TA, but the same issuer is in an R&E federation. Would that make the VC invalid?

otherwise, the credential should include a pointer to the issuer's Entity Configuration

In vanilla OIDfed that is the issuer (iss). If we mandate iss == credential_issuer, is this then not resolved?

alternatively, the issuer could point to its Entity Configuration in its DID document (see comment https://github.com/FIDEScommunity/DIIP/discussions/71#discussioncomment-14402158 in this thread)

Would also work for me

[samuelmr]

Based on the discussion yesterday, would the following specification be sufficient to implement OpenID Federation in wallet use cases:

Introduction

This specification profiles OpenID Federation [OpenID.Federation] for use with digital credentials, specifically focusing on credential issuance via OpenID for Verifiable Credential Issuance [OID4VCI] and credential presentation via OpenID for Verifiable Presentations [OID4VP].

The profile simplifies federation usage by limiting scope to trust chain resolution and metadata discovery, while omitting more complex features such as federation policies and trust marks.

Scope

This profile applies to:

• Credential issuers publishing OID4VCI metadata
• Credential verifiers publishing verifier metadata
• Wallets resolving trust chains to establish trust in issuers and verifiers

This profile does NOT apply to and does NOT require conforming implementations to support:

• Chapter 6 (Federation Policy) of OpenID Federation
• Chapter 7 (Trust Marks) of OpenID Federation
• Chapter 12 (OpenID Connect Client Registration) of OpenID Federation

Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Terminology

This specification uses the terms defined in OpenID Federation [OpenID.Federation], OpenID for Verifiable Credential Issuance [OID4VCI], OpenID for Verifiable Presentations [OID4VP], and SD-JWT VC [I-D.ietf-oauth-sd-jwt-vc].

Entity Identifier: As defined in OpenID Federation, a URL that uniquely identifies a federation entity.

Entity Configuration: As defined in OpenID Federation, a signed JWT published at the Entity Identifier's /.well-known/openid-federation endpoint containing metadata and authority hints.

Trust Chain: As defined in OpenID Federation, a sequence of Entity Statements from a Leaf Entity through intermediate entities to a Trust Anchor.

Issuer: The role of the entity issuing credentials as defined in [VC-DATA-MODEL-2.0]

Credential Issuer: The technical service used to issue credentials as defined in [OID4VCI]

Verifier: The entity that requests, receives, and validates Presentations as defined in [OID4VCI]. Note that this specification does not distinguish the role and the technical service of the verifier the same way it does for Issuer and Credential Issuer. For the purposes of this specification Verifier may refer to either the role or the technical service. (Thus, the reference to the definition in [OID4VCI] and not the one in [OID4VP].)

Credential Issuance

Entity Identifier

The Credential Issuer MUST use the value of the credential_issuer in its OID4VCI issuer metadata as its Entity Identifier.

The Credential Issuer's Entity Configuration can be found by appending the string /.well-known/openid-federation to the Entity Identifier.

Metadata Publication

The Credential Issuer MUST place the OpenID4VCI issuer metadata into the Entity Configuration, in the openid_credential_issuer property.

If the openid_credential_issuer property is found in the Entity Configuration, the Wallet MUST use only it and ignore the issuer metadata published in the well-known location defined in OID4VCI.

The Credential Issuer MAY place additional metadata into the federation_entity Entity Type Identifier.

The metadata in the openid_credential_issuer property overrides the metadata in the federation_entity property. For example, if both openid_credential_issuer.display.name and federation_entity.organization_name exist, the Wallet SHOULD show the value of openid_credential_issuer.display.name as the name of the issuer.

Example: Credential Issuer Entity Configuration

{
  "iss": "https://credential-issuer.example",
  "sub": "https://credential-issuer.example",
  "iat": 1616239022,
  "exp": 1616239322,
  "metadata": {
    "federation_entity": {
      "organization_name": "Example Credential Issuer",
      "contacts": ["[email protected]"]
    },
    "openid_credential_issuer": {
      "issuer": "https://credential-issuer.example",
      "display": [
        {
          "name": "Example Issuer",
          "locale": "en-US",
          "logo": {
            "uri": "https://credential-issuer.example/logo.png",
            "alt_text": "Example Logo"
          }
        }
      ],
      "credential_issuer": "https://credential-issuer.example",
      "authorization_endpoint": "https://credential-issuer.example/authorize",
      "authorization_servers": ["https://credential-issuer.example/authorize"],
      "credential_endpoint": "https://credential-issuer.example/credential",
      "credential_configurations_supported": {
        "sd_jwt_vc_example": "..."
      }
    },
    "openid-configuration": {
      "jwks_uri": "https://credential-issuer.example/jwks"
    }
  },
  "jwks": [
    {
      "kty": "EC",
      "kid": "MJ2BW-rNshp9sjh3SvwnBIkEsYsU92xVtC3-Fv_lcKc",
      "alg": "ES256",
      "crv": "P-256",
      "x": "JTEE5QghmkA_-7_pZoKIluRzGNvQGtzmpNvb_nAswhE",
      "y": "A_iBfIseHsdfE7CmI3lIYtKMdfyXXOIpPX_o6O0h0wY",
      "use": "sig"
    }
  ],
  "authority_hints": [
    "https://trustregistry.example"
  ]
}

SD-JWT VC Credentials

When the Issuer issues credentials in the SD-JWT VC format [I-D.ietf-oauth-sd-jwt-vc], the Issuer MUST place its Entity Identifier in the fed claim of the credential.

Example: SD-JWT VC with Federation Claim

The following non-normative example shows a decoded payload of an SD-JWT VC credential with the fed claim:

{
  "iss": "https://credential-issuer.example",
  "fed": "https://credential-issuer.example",
  "iat": 1683000000,
  "exp": 1883000000,
  "vct": "https://credentials.example.com/identity_credential",
  "is_over_65": true,
  "address": {
    "street_address": "123 Main St",
    "locality": "Anytown",
    "region": "Anystate",
    "country": "US"
  }
}

W3C VCDM Credentials

When the Issuer issues credentials in the W3C Verifiable Credentials Data Model format [VC-DATA-MODEL-2.0], the Issuer MUST place a termsOfUse property into the credential. The type of this termsOfUse property MUST be the string OpenIDFederation and the policyId MUST be the Issuer's Entity Identifier.

Example: W3C VCDM Credential with termsOfUse

The following non-normative example illustrates the use of the termsOfUse property:

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2"
  ],
  "id": "urn:uuid:c65d364e-2560-4e08-be03-9c3d944d609d",
  "type": [
    "VerifiableCredential"
  ],
  "issuer": "did:web:credential-issuer.example",
  "validFrom": "2025-12-01T00:00:00Z",
  "validUntil": "2028-12-31T23:59:59Z",
  "credentialSubject": {
  },
  "termsOfUse": {
    "type": "OpenIDFederation",
    "trustFramework": "Example Federation",
    "policyId": "https://credential-issuer.example"
  }
}

Note on Credential Issuer vs. Issuer

The Issuer defined in the digital credential (the value of the iss claim in SD-JWT VC credentials or the value of the id of the issuer property in W3C VCDM credentials) is not necessarily the same entity as the Credential Issuer defined in the property credential_issuer in the OID4VCI metadata.

For example, the OpenID Federation Entity Identifier of the Issuer of the credential could be https://university-of-utopia.example.edu, and the OpenID Federation Entity Identifier of the Credential Issuer could be https://credentials.ministryofeducation.example.edu.

If the Issuer chooses to make this kind of distinction between the entity issuing the credential and the technical service used for issuance, it is RECOMMENDED that the Entity Configuration of the technical service has an authority_hints value pointing to the Issuer's Entity Identifier and the Issuer publishes a Subordinate Statement about the technical service.

Credential Presentation and Verification

Client Identifier Scheme

The Verifier MUST use the openid_federation: prefix as defined in [OID4VP] Section 5.9.3.

Metadata Publication

The Verifier MUST place verifier metadata into the Entity Configuration, in the openid_credential_verifier property.

Trust Establishment

To establish trust with the issuer (ensure that the issuer can be trusted), the Verifier MUST resolve the Trust Chain from the issuer's Entity Configuration until it finds a Federation Entity it trusts.

Example: Verifier Entity Configuration

{
  "iss": "https://credential-verifier.example",
  "sub": "https://credential-verifier.example",
  "iat": 1616239023,
  "exp": 1616239323,
  "metadata": {
    "federation_entity": {
      "organization_name": "Example Credential Verifier",
      "contacts": ["[email protected]"]
    },
    "openid_credential_verifier": {
      "jwks": {
        "keys": [
          {
            "kty": "EC",
            "crv": "P-256",
            "x": "f83OJ3D2xF4Z1s3QpLQe4qVb8K7q6y1v3z4Yb6k9J0",
            "y": "x_FEzRu9q3u4bWz5n9X2L4q1U8T7c6v5s2d1a0b3C4",
            "alg": "ES256",
            "use": "enc",
            "kid": "ec-key-1"
          }
        ]
      },
      "encrypted_response_enc_values_supported": [
        "A128GCM",
        "A192GCM",
        "A256GCM"
      ],
      "vp_formats_supported": {
        "dc+sd-jwt": {
          "sd-jwt_alg_values": ["ES256"],
          "kb-jwt_alg_values": ["ES256"]
        }
      }
    }
  },
  "jwks": [
    {
      "kty": "EC",
      "kid": "y4nC8uTvcM5uJxOIvUqFjXb2EA6xPGdnt8zvjW94m6U",
      "alg": "ES256",
      "crv": "P-256",
      "x": "K6dA9ayt4P8xBN6SFiCZYOI2qeaFda7VV5wnmHWcl7w",
      "y": "CdE30dUX0geK4NL8IMC9u-rRMOLC9WaScJIGK5rxtKI"
    }
  ],
  "authority_hints": [
    "https://trustregistry.example"
  ]
}

Subordinate Statements

Intermediaries and Trust Anchors MAY authorize their subordinates to issue or request certain credential types by placing metadata values like openid_credential_issuer.credential_configurations_supported or openid_credential_verifier.dcql_query in the Subordinate Statements.

The meaning of such statements SHOULD be specified in ecosystem rulebooks and is out of the scope of this specification.

[samuelmr]

Which parts of the Wallet Architecture draft would need to be added here?

[TimoGlastra]

I think it's missing where the keys used for credential signing are placed in the Federation. This issue defines the use of jwks in Issuer Metadata to do this: openid/federation-wallet#22

I'd lean towards making it a separate metadata entry to not link OID4VCI with the keys used for signing credentials, but otherwise putting a jwks entry somewhere makes sense.

I think for SD-JWT VC we should then also put the kid of the JWK in the header, so you can easily find the key for signing. Not sure if fed should be a header or payload claim? For W3C VC SD-JWT we can do the same, for DataIntegrity we somehow need to combine the kid with the federation entity id i think (like is done with a did:did:key:123#123)

[samuelmr]

I'd lean towards making it a separate metadata entry to not link OID4VCI with the keys used for signing credentials, but otherwise putting a jwks entry somewhere makes sense.

Agreed. The example issuer Entity Configuration contains this:

    "openid_configuration": {
      "jwks_uri": "https://credential-issuer.example/jwks"
    }

It may be better to include jwks rather than jwks_uri so that the actual content is a part of the signed JWT. Would the openid_configuration be the correct property?

I think for SD-JWT VC we should then also put the kid of the JWK in the header, so you can easily find the key for signing.

Do you mean the JWK that was used to sign the credential? I agree that this would simplify key discovery, but I wonder if it has anything to do with OpenID Federation.

Not sure if fed should be a header or payload claim?

I'm not sure either. :)

It could be a header claim since it's not part of the credential payload.
On the other hand, it shouldn't be a header claim since it doesn't really describe the credential JWT (like typ, cty, and alg).
Since iss is a payload claim, perhaps fed should be in the same place?

[surfnet-niels]

@samuelmr can we move the above proposal into an md doc? IT will make it much easier to comment and contribute to specific sections

[samuelmr]

I created a separate PR for the proposal: #79

[samuelmr]

@TimoGlastra's comments #15105343 and openid/federation-wallet#48 (comment) got me re-thinking about the discussion we had related to the Issuer as a legal entity and the Credential Issuer as a technical service.

I still think that it makes sense to keep that distinction so that an authority (a federation Intermediary or Trust Anchor) can make statements about the status of legal entities without the need to validate each technical service they are using.

On the other hand, if the Issuer and the Credential Issuer are separate entities, I suppose both would need to include the same key (the one used to sign the credential) in their Entity Configurations.

[surfnet-niels]

if the Issuer and the Credential Issuer are separate entities

Not sure what 'separate' means here. Technically separate should work, so https://university-of-utopia.example.edu issuer publishing they use the https://utopia-planitia.example.com service as their technical issuer.
But even if these are separate entities technically, I do not assume they will be separately publishing Entity Configurations, as University-of-utopia is still the issuer from the perspective of the trust framework.

If they are really separate both technically and organizationally, I suggest to use a IA for the org entity and have the technical entities be subordinates to that

[surfnet-niels]

The profile simplifies federation usage by limiting scope to trust chain resolution and metadata discovery, while omitting more complex features such as federation policies and trust marks.

I would add: "at this time"

[surfnet-niels]

This profile does NOT apply to and does NOT require conforming implementations to support:

NOT is not BCP 14 [RFC2119] [RFC8174], so I suggest to reword to:
"This profile does not apply to and does not require conforming implementations to support:"