Possible Use of Metadata Parameters by Wallet Ecosystems

[selfissued]

The following records text formerly in the specification about possible use of metadata parameters in Wallet ecosystems.

This partially addresses #21.

Possible Use of Metadata Parameters by Wallet Entities

This non-normative appendix speculates about metadata parameters that might be used
by the Entity Types defined by this specification.
Some of these are already defined by other specifications.
Some are yet to be defined, and may be defined in the future by other specifications.
Some are likely to change.
Please read this illustrative content with these caveats in mind.

Possible OpenID Wallet Provider Metadata Usage

Possible metadata parameters that could be used by
OpenID Wallet Providers with the openid_wallet_provider Entity Type Identifier
are listed in the table below.

The table and examples below use metadata parameters defined by
[@!OpenID.Federation], [@!RFC8414], and [@!OpenID4VP].

Metadata Parameter	Status	Description	Reference
jwks	REQUIRED	A JSON Web Key Set (JWKS) that represents the Wallet Provider's public keys	Section 5.2.1 of [@!OpenID.Federation] and JWK [@!RFC7517]
authorization_endpoint	REQUIRED	Endpoint for obtaining the authorization for the issuance of the Wallet Attestation	Section 2 of [@!RFC8414]
token_endpoint	REQUIRED	Endpoint for obtaining the Wallet Attestation	Section 2 of [@!RFC8414]
aal_values_supported	OPTIONAL	List of supported values for the Authenticator Assurance Level, as defined in NIST Special Publication 800-63B. These values specify the security level of the app. Values are trust framework specific	this specification
grant_types_supported	REQUIRED	Grant types supported by the token endpoint	Section 2 of [@!RFC8414]
token_endpoint_auth_methods_supported	REQUIRED	Supported authentication methods for the token endpoint	Section 2 of [@!RFC8414]
token_endpoint_auth_signing_alg_values_supported	REQUIRED	Supported signature algorithms for the token endpoint	Section 2 of [@!RFC8414]

Below is a non-normative example of openid_wallet_provider metadata:

{
  "authorization_endpoint": "https://wallet-provider.example/authorization",
  "token_endpoint": "https://wallet-provider.example/token",
  "jwks": {
      "keys": [
        {
          "crv": "P-256",
          "kty": "EC",
          "x": "qrJrj3Af_B57sbOIRrcBM7br7wOc8ynj7lHFPTeffUk",
          "y": "1H0cWDyGgvU8w-kPKU_xycOCUNT2o0bwslIQtnPU6iM",
          "kid": "5t5YYpBhN-EgIEEI5iUzr6r0MR02LnVQ0OmekmNKcjY"
        }
      ]
  },
  "aal_values_supported": [
      "https://trust-framework.example.org/LoA/basic",
      "https://trust-framework.example.org/LoA/medium",
      "https://trust-framework.example.org/LoA/high"
  ],
  "grant_types_supported": [
      "urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation"
  ],
  "token_endpoint_auth_signing_alg_values_supported": ["RS256", "ES256"],
  "token_endpoint_auth_methods_supported": [
      "private_key_jwt"
  ]
}

Possible OpenID Credential Issuer Metadata Usage

Possible metadata parameters that could be used by
OpenID Credential Issuers with the openid_credential_issuer Entity Type Identifier
are listed in the table below.

The table and examples below use metadata parameters defined by
[@!OpenID.Federation], [@!RFC8414]], [@!RFC9126], [@!OpenID.Discovery], and [@!OpenID4VCI].

The usage described below is intended to enable
the cryptographic material used for the Credential issuance operation be consistent
and verifiable using the Trust Chain.

Metadata Parameter	Status	Description	Reference
jwks	REQUIRED	JSON Web Key Set directly embeds the public keys used by the Credential Issuer for its signature operations, such as signing Digital Credentials	Section 5.2.1 of [@!OpenID.Federation] and JWK [@!RFC7517]

Below is a non-normative example of a payload of an Credential Issuer Entity Configuration:

{
    "iat": 1718207217,
    "exp": 1749743216,
    "iss": "https://eaa-provider.example.org",
    "sub": "https://eaa-provider.example.org",
    "authority_hints": [
        "https://trust-anchor.example.org"
    ],
    "jwks": {
        "keys": [
            {
                "kid": "FANFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs",
                "kty": "EC",
                "crv": "P-256",
                "x": "jE2RpcQbFQxKpMqehahgZv6smmXD0i/LTP2QRzMADk4",
                "y": "qkMx5iqt5PhPu5tfctS6HsP+FmLgrxfrzUV2GwMQuh8"
            }
        ]
    },
    "metadata": {
        "federation_entity": {
            "homepage_uri": "https://eaa-provider.example.org/",
            "organization_name": "Organization Name",
            "contacts": [
                "[email protected]",
                "[email protected]"
            ],
            "tos_uri": "https://eaa-provider.example.org/public/info_policy.html",
            "policy_uri": "https://eaa-provider.example.org/public/privacy_policy.html",
            "logo_uri": "https://eaa-provider.example.org/public/logo.svg"
        },
        "oauth_authorization_server": {
            "issuer": "https://eaa-provider.example.org",
            "pushed_authorization_request_endpoint": "https://eaa-provider.example.org/as/par",
            "authorization_endpoint": "https://eaa-provider.example.org/authorize",
            "token_endpoint": "https://eaa-provider.example.org/token",
            "client_registration_types_supported": [
                "automatic"
            ],
            "code_challenge_methods_supported": [
                "S256"
            ],
            "scopes_supported": [
                "EuropeanDisabilityCard",
                "EuropeanHealthInsuranceCard",
                "MDL"
            ],
            "response_modes_supported": [
                "form_post.jwt",
                "query"
            ],
            "authorization_signing_alg_values_supported": [
                "ES256",
                "ES384",
                "ES512"
            ],
            "grant_types_supported": [
                "authorization_code"
            ],
            "token_endpoint_auth_methods_supported": [
                "attest_jwt_client_auth"
            ],
            "token_endpoint_auth_signing_alg_values_supported": [
                "ES256",
                "ES384",
                "ES512"
            ],
            "request_object_signing_alg_values_supported": [
                "ES256",
                "ES384",
                "ES512"
            ],
            "jwks": {
                "keys": [
                    {
                        "kid": "f10aca0992694b3581f6f699bfc8a2c6cc687725",
                        "kty": "EC",
                        "crv": "P-256",
                        "x": "jE2RpcQbFQxKpMqehahgZv6smmXD0i/LTP2QRzMADk4",
                        "y": "qkMx5iqt5PhPu5tfctS6HsP+FmLgrxfrzUV2GwMQuh8"
                    }
                ]
            }
        },
        "openid_credential_issuer": {
            // ... parameters defined in OpenID4VCI ...
            "jwks": {
                "keys": [
                    {
                        "kid": "f10aca0992694b3581f6f699bfc8a2c6cc687725",
                        "kty": "EC",
                        "crv": "P-256",
                        "x": "jE2RpcQbFQxKpMqehahgZv6smmXD0i/LTP2QRzMADk4",
                        "y": "qkMx5iqt5PhPu5tfctS6HsP+FmLgrxfrzUV2GwMQuh8"
                    }
                ]
            }
        }
}

Possible OpenID Credential Verifier Metadata Usage

Possible metadata parameters that could be used by
OpenID Wallet Credential Verifiers with the openid_credential_verifier Entity Type Identifier
are listed in the table below.

The table and examples below use metadata parameters defined by
[@!OpenID.Federation], [@!RFC7591], [@!OpenID.Registration], [@!OAuth.JARM], and [@!OpenID4VP].

Metadata Parameter	Status	Description	Reference
client_id	REQUIRED	It MUST contain an HTTPS URL that uniquely identifies the Credential Verifier	Section 3.2.1 of [@!RFC7591] and Section 3.2 of [@!OpenID.Registration]
client_name	REQUIRED	Human-readable string name of the Credential Verifier used for representing the Credential Verifier to the User	Section 2 of [@!RFC7591]
request_uris	OPTIONAL	JSON Array of request_uri values that are pre-registered by the Credential Verifier. These URLs MUST use the https scheme.	Section 2 of [@!OpenID.Registration]
response_uris_supported	OPTIONAL	JSON Array of response_uri strings, as specified by [@!OpenID4VP], to which the Wallet Instance MAY send the Authorization Response using an HTTP POST request	this specification
authorization_signed_response_alg	OPTIONAL	String identifying the JWS algorithm that MUST be used for signing authorization responses. The algorithm none MUST NOT be used.	[@!RFC7515] and Section 3 of [@!OAuth.JARM]
vp_formats	OPTIONAL	JSON object defining the formats and proof types of Verifiable Presentations and Verifiable Credentials the Credential Verifier supports	Section 7.2.7 of [@!OpenID4VC-HAIP] and Section 9.1 of [@!OpenID4VP]
presentation_definitions_supported	OPTIONAL	JSON Array of supported presentation_definition objects	this specification, Section 5 of [@!DIF.PresentationExchange], and Section 7.2.8 of [@!OpenID4VC-HAIP]
jwks	REQUIRED	JSON Web Key Set document, passed by value, containing the protocol specific keys for the Credential Verifier	Section 5.2.1 of [@!OpenID.Federation] and JWK [@!RFC7517]

Below is a non-normative example of the payload of a Credential Verifier Entity Configuration:

{
    "iat": 1718207217,
    "exp": 1749743216,
    "iss": "https://verifier.example.org",
    "sub": "https://verifier.example.org",
    "authority_hints": [
        "https://trust-anchor.example.org"
    ],
    "jwks": {
        "keys": [
            {
                "kid": "FANFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs",
                "kty": "EC",
                "crv": "P-256",
                "x": "jE2RpcQbFQxKpMqehahgZv6smmXD0i/LTP2QRzMADk4",
                "y": "qkMx5iqt5PhPu5tfctS6HsP+FmLgrxfrzUV2GwMQuh8"
            }
        ]
    },
    "metadata": {
        "federation_entity": {
            "homepage_uri": "https://verifier.example.org",
            "organization_name": "Organization Name",
            "contacts": [
                "[email protected]",
                "[email protected]"
            ],
            "tos_uri": "https://verifier.example.org/public/info_policy.html",
            "policy_uri": "https://verifier.example.org/public/privacy_policy.html",
            "logo_uri": "https://verifier.example.org/public/logo.svg"
        },
        "openid_credential_verifier": {
            "application_type": "web",
            "client_id": "https://verifier.example.org",
            "client_name": "Organization Name",
            "contacts": [
                "[email protected]"
            ],
            "request_uris": [
                "https://verifier.example.org/request_uri"
            ],
            "response_uris_supported": [
                "https://verifier.example.org/response_uri"
            ],
            "authorization_signed_response_alg": "ES256",
            "vp_formats": {
                "vc+sd-jwt": {
                    "sd-jwt_alg_values": [
                        "ES256",
                        "ES384",
                        "ES512"
                    ]
                }
            },
            "presentation_definitions_supported": [
                {
                    "id": "d76c51b7-ea90-49bb-8368-6b3d194fc131",
                    "input_descriptors": [
                        {
                            "id": "PersonIdentificationData",
                            "name": "Person Identification Data",
                            "purpose": "User Authentication",
                            "format": {
                                "vc+sd-jwt": {
                                    "alg": [
                                        "ES256",
                                        "ES384",
                                        "ES512"
                                    ]
                                }
                            },
                            "constraints": {
                                "limit_disclosure": "required",
                                "fields": [
                                    {
                                        "filter": {
                                            "const": "PersonIdentificationData",
                                            "type": "string"
                                        },
                                        "path": [
                                            "$.vct"
                                        ]
                                    },
                                    {
                                        "filter": {
                                            "type": "object"
                                        },
                                        "path": [
                                            "$.cnf.jwk"
                                        ]
                                    },
                                    {
                                        "path": [
                                            "$.first_name"
                                        ]
                                    },
                                    {
                                        "path": [
                                            "$.family_name"
                                        ]
                                    }
                                ]
                            }

                        }
                    ]
                }
            ],
            "jwks": {
                "keys": [
                    {
                        "kid": "f10aca0992694b3581f6f699bfc8a2c6cc687725",
                        "kty": "EC",
                        "crv": "P-256",
                        "x": "jE2RpcQbFQxKpMqehahgZv6smmXD0i/LTP2QRzMADk4",
                        "y": "qkMx5iqt5PhPu5tfctS6HsP+FmLgrxfrzUV2GwMQuh8"
                    }
                ]
            }
        }
    }
}

Security Considerations about the Parameters request_uris and response_uris_supported

There are scenarios where the Credential Verifier's endpoints are attested by a trusted third party, such as a registration service owned by a federation Intermediate. This Intermediate attests to the Credential Verifier's metadata and ensures its integrity and authenticity by utilizing metadata and the metadata_policy in the Subordinate Statement about that Credential Verifier, as defined in the OpenID Federation specification.

In these cases, the Credential Verifier is restricted from altering its endpoint URIs due to the registration requirements, unless it utilizes URI fragments as permitted under the OpenID Connect Core 1.0 specification.

To enhance the security of implementations, it is generally recommended that Credential Verifiers randomize their endpoints. This strategy involves appending random fragments to the URIs, such as https://verifier.example.org/request-uri#random-value. Such randomization can help mitigate certain types of attacks by making it more difficult for attackers to predict or reuse fixed endpoint URLs, that could be victim of abuse, such as the one caused by the issuance of many signed responses that may facilitate resource consuptions attacks.

For this reason, the parameters metadata or metadata_policy SHOULD fix the supported URIs to prevent wallet hijacks to fraudolent endpoints and at the same time allow URI randomization using fragments.

Security Considerations about the End-User's Data Protection Using presentation_definitions_supported

The presentation_definitions_supported enhance the End-User data protection within wallet trust frameworks. By defining the specific presentation definitions that a Credential Verifier is authorized to use, this parameter limits the amount of personal data that can be requested. This constraint prevents the over-asking of personal data, aligning with the principles of data minimization and purpose limitation under privacy regulations.

The metadata and metadata_policy parameters can be used in the Federation Subordinate Statements, issued by the Trust Anchor and its Intermediates, to configure these limitations. They ensure that only the necessary data as defined by the federation's policy is requested and processed by the Credential Verifier. This approach protects End-User privacy and endures that all data collection practices are transparent and compliant with established policies.

Authentic Sources

An Authentic Source is a designated authority or system responsible for providing verified and reliable data. It is up to the implementers to decide if the Authentic Source should be implemented using the OAuth 2.0 framework, which offers security protocols and extensive support for diverse authentication scenarios. In these cases, the Authentice Sources represent an OAuth 2.0 Resource Server and therefore the metadata type used is oauth_protected_resource, as defined in OAuth 2.0 Protected Resource Metadata.

This section provides some common configurations for ...

non-normative example 1

non-normative example 2

[selfissued]

We discussed this on the 16-Jan-25 working group call. To make this actionable, we should create separate issues for each of the potential spec additions recorded in this rather large issue. Then this one can be closed.