From 5de2d9a88cc50aa89263223699dde437506bcc31 Mon Sep 17 00:00:00 2001 From: Michael Jones Date: Thu, 5 Sep 2024 12:14:39 -0700 Subject: [PATCH] Move text about possible use of metadata to issue #22 --- openid-federation-wallet-1_0.md | 372 ++------------------------------ 1 file changed, 12 insertions(+), 360 deletions(-) diff --git a/openid-federation-wallet-1_0.md b/openid-federation-wallet-1_0.md index aaaa687..56a89b1 100644 --- a/openid-federation-wallet-1_0.md +++ b/openid-federation-wallet-1_0.md @@ -1,5 +1,5 @@ %%% -title = "OpenID Federation Wallet Architectures 1.0 - draft 01" +title = "OpenID Federation Wallet Architectures 1.0 - draft 02" abbrev = "openid-federation-wallet" ipr = "none" workgroup = "OpenID Connect A/B" @@ -78,6 +78,12 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 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. +.# Warning + +This document is not an OpenID Foundation International Standard. +It is distributed for review and comment. +It is subject to change without notice and may not be referred to as an International Standard. + # Scope This specification is a profile of [@!OpenID.Federation] for wallet ecosystems. @@ -641,365 +647,6 @@ We would like to thank the following individuals for their comments, ideas, and -# 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](https://pages.nist.gov/800-63-3/sp800-63b.html#sec4). 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": [ - "informazioni@example.it", - "protocollo@pec.example.it" - ], - "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": [ - "informazioni@example.it", - "protocollo@pec.example.it" - ], - "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": [ - "informazioni@example.it" - ], - "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](https://datatracker.ietf.org/doc/draft-ietf-oauth-resource-metadata/). - -This section provides some common configurations for ... - -``` -non-normative example 1 -``` - -``` -non-normative example 2 -``` - # Notices Copyright (c) 2024 The OpenID Foundation. @@ -1012,6 +659,11 @@ The technology described in this specification was made available from contribut [[ To be removed from the final specification ]] + -02 + + * 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.