How to configure discovery metadata

Context

This document provides essential information for configuring Credential Issuer Metadata, Authorisation Server Metadata and Organisational and Holder Wallets Metadata. The purpose of this page is to guide Wallet Providers through the configuration process of various metadata types necessary for the proper functioning of digital wallets within the ecosystem.

This configuration is applicable to different types of wallets, including Organisational Wallets and Holder Wallets. Each type has specific metadata requirements that must be met to ensure compliance and functionality.

Introduction

Discovery metadata refers to the information that helps different entities (like credential issuers, holders, and verifiers) discover and interact with each other in a standardized way. Proper configuration of discovery metadata is crucial for ensuring interoperability, security, and seamless operation of digital wallets. It enables Wallet Providers to correctly issue, authorize, and manage credentials.

This sequence diagram illustrates the steps involved in retrieving discovery metadata for both Organisational and Holder Wallets.

Organisational Wallets

Organisational Wallets are digital wallets managed by organizations to issue and manage credentials. These wallets are affected by the configuration of:

Credential Issuer Metadata
Authorisation Server Metadata
Service Wallet Metadata

The Server-based Client's Entity Identifiers must always be in the format of an HTTPS URL. The metadata can be retrieved by concatenating the Entity Identifier client_id with /.well-known/x-y-z. Ensure any terminating / is removed before concatenation.

Credential Issuer Metadata

location

Configuration location: /.well-known/openid-credential-issuer

This location refers to a specific and standard URL path in OpenID connect where the metadata is published.

Visit OpenID for Verifiable Credential Issuance specifications for further details on Credential Issuer Metadata

Field	Requirement	Notes
`authorization_server`	OPTIONAL	Identifier of the OAuth 2.0 Authorisation Server (as defined in `RFC 8414`) the Credential Issuer relies on for authorisation. If this element is omitted, the entity providing the Credential Issuer is also acting as the AS, i.e. the Credential Issuer's identifier is used as the OAuth 2.0 Issuer value to obtain the Authorisation Server metadata as per `RFC 8414`.
`credential_issuer`	REQUIRED	The Credential Issuer's identifier.
`credential_endpoint`	REQUIRED	URL of the Credential Issuer's Credential Endpoint. This URL MUST use the https scheme and MAY contain port, path and query parameter components.
`deferred_credential_endpoint`	REQUIRED	URL of the Credential Issuer's Deferred Credential Endpoint. This URL MUST use the https scheme and MAY contain port, path and query parameter components.
`display`	OPTIONAL	A JSON array containing a list of JSON objects, each of them representing display properties of a Credential Issuer for a certain language.
`display[]` `.name`	OPTIONAL	String value of a display name for the Credential Issuer.
`display[]` `.locale`	OPTIONAL	String value that identifies the language of this object represented as a language tag taken from values defined in BCP47 `RFC 5646`. There MUST be only one object with the same language identifier.
`credentials_supported`	REQUIRED	A JSON array containing a list of JSON objects, each of them representing metadata about a separate credential type that the Credential Issuer can issue.
`credentials_supported[]` `.format`	REQUIRED	A JSON string identifying the format of this credential, e.g. `jwt_vc`.
`credentials_supported[]` `.types`	REQUIRED	A JSON array designating the types a certain credential type supports according to `VC_DATA`, Section 4.3.
`credentials_supported[]` `.trust_framework`	OPTIONAL	A JSON object defining the Trust Framework details.
`credentials_supported[]` `.trust_framework` `.name`	REQUIRED	A JSON string defining the Trust Framework name the credential will be issued under.
`credentials_supported[]` `.trust_framework` `.type`	REQUIRED	A JSON string designating the behaviour and properties bound to the type. Types may include extra properties.
`credentials_supported[]` `.trust_framework` `.uri`	OPTIONAL	A JSON string belonging to `type` with value of `Accreditation`, pointing towards the Verifiable Accreditation, which will be the basis for the issuance of the Verifiable Credential.
`credentials_supported[]` `.display`	OPTIONAL	A JSON array of objects, where each object contains display properties of a certain claim in the Credential for a certain language.
`credentials_supported[]` `.display[]` `.name`	OPTIONAL	A JSON string value of a display name for the claim
`credentials_supported[]` `.display[]` `.locale`	OPTIONAL	String value that identifies the language of this object represented as a language tag taken from values defined in BCP47 `RFC 5646`. There MUST be only one object with the same language identifier.

Example Credential Issuer Metadata

{
  "authorization_server": "https://api-conformance.ebsi.eu/conformance/v3/auth-mock",
  "credential_issuer": "https://api-conformance.ebsi.eu/conformance/v3/issuer-mock",
  "credential_endpoint": "https://api-conformance.ebsi.eu/conformance/v3/issuer-mock/credential",
  "deferred_credential_endpoint": "https://api-conformance.ebsi.eu/conformance/v3/issuer-mock/deferred_credential",
  "credentials_supported": [
    {
      "format": "jwt_vc",
      "types": [
        "VerifiableCredential",
        "VerifiableAttestation",
        "VerifiableAuthorisationToOnboard"
      ],
      "trust_framework": {
        "name": "ebsi",
        "type": "Accreditation",
        "uri": "TIR link towards accreditation"
      },
      "display": [
        {
          "name": "Verifiable Authorisation to onboard",
          "locale": "en-GB"
        }
      ]
    },
    {
      "format": "jwt_vc",
      "types": [
        "VerifiableCredential",
        "VerifiableAttestation",
        "VerifiableAccreditation",
        "VerifiableAccreditationToAttest"
      ],
      "trust_framework": {
        "name": "ebsi",
        "type": "Accreditation",
        "accreditation_uri": "TIR link towards accreditation"
      },
      "display": [
        {
          "name": "Verifiable Accreditation to attest",
          "locale": "en-GB"
        }
      ]
    }
  ]
}

Authorisation Server Metadata

location

Configuration location: /.well-known/openid-configuration

Visit OpenID for Verifiable Presentation specifications for further details on openID configuration enpoint.

Field	Requirement	Notes
`issuer`	OPTIONAL	Authorisation Server's issuer identifier URL
`authorization_endpoint`	OPTIONAL	URL of the Authorisation Server's authorisation endpoint
`token_endpoint`	OPTIONAL	URL of the Authorisation Server's token endpoint
`userinfo_endpoint`	OPTIONAL	URL of the Authorisation Server's UserInfo endpoint
`presentation_definition_endpoint`	OPTIONAL	URL of the Authorisation Server's Presentation Definitions endpoint
`jwks_uri`	OPTIONAL	URL of the Authorisation Server's JWK Set document
`scopes_supported`	OPTIONAL	A JSON array containing a list of the OAuth 2.0 "scope" values that this Authorisation Server supports
`response_types_supported`	OPTIONAL	A JSON array containing a list of the OAuth 2.0 "response_type" values that this Authorisation Server supports
`response_modes_supported`	OPTIONAL	A JSON array containing a list of the OAuth 2.0 "response_mode" values that this Authorisation Server supports
`grant_types_supported`	OPTIONAL	A JSON array containing a list of the OAuth 2.0 "grant type" values that this Authorisation Server supports
`subject_types_supported`	OPTIONAL	A JSON array containing a list of the Subject Identifier types that this OP supports
`id_token_signing_alg_values_supported`	OPTIONAL	A JSON array containing a list of the JWS "alg" values supported by the OP for the ID Token
`request_object_signing_alg_values_supported`	OPTIONAL	A JSON array containing a list of the JWS "alg" values supported by the OP for Request Objects
`request_parameter_supported`	OPTIONAL	A Boolean value specifying whether the OP supports use of the "request" parameter
`request_uri_parameter_supported`	OPTIONAL	A Boolean value specifying whether the OP supports use of the "request_uri" parameter
`token_endpoint_auth_methods_supported`	OPTIONAL	A JSON array containing a list of client authentication methods supported by this token endpoint
`vp_formats_supported`	REQUIRED	A JSON Object containing a list of key value pairs, where the key is a string identifying a Credential format supported by the Wallet
`vp_formats_supported` `.jwt_vp`	OPTIONAL	A JSON Object, defining support for Verifiable Presentations in JWT format
`vp_formats_supported` `.jwt_vp` `.alg_values_supported`	OPTIONAL	A JSON Array of case sensitive strings that identify the cryptographic suites that are supported
`vp_formats_supported` `.jwt_vc`	OPTIONAL	A JSON Object, defining support for Verifiable Credentials in JWT format
`vp_formats_supported` `.jwt_vc` `.alg_values_supported`	OPTIONAL	A JSON Array of case sensitive strings that identify the cryptographic suites that are supported
`subject_syntax_types_supported`	OPTIONAL	A JSON Array of supported DID methods and their possible sub types
`subject_trust_frameworks_supported`	OPTIONAL	A JSON Array of supported Trust Frameworks
`id_token_types_supported`	OPTIONAL	A JSON array of strings containing the list of ID Token types supported by the OP

Example Authorisation Server Metadata

{
  "issuer": "https://api-conformance.ebsi.eu/conformance/v3/auth-mock",
  "authorization_endpoint": "https://api-conformance.ebsi.eu/conformance/v3/auth-mock/authorize",
  "token_endpoint": "https://api-conformance.ebsi.eu/conformance/v3/auth-mock/token",
  "jwks_uri": "https://api-conformance.ebsi.eu/conformance/v3/auth-mock/jwks",
  "scopes_supported": ["openid"],
  "response_types_supported": ["code", "vp_token", "id_token"],
  "response_modes_supported": ["query"],
  "grant_types_supported": ["authorization_code"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["ES256"],
  "request_object_signing_alg_values_supported": ["ES256"],
  "request_parameter_supported": true,
  "request_uri_parameter_supported": true,
  "token_endpoint_auth_methods_supported": ["private_key_jwt"],
  "vp_formats_supported": {
    "jwt_vp": {
      "alg_values_supported": ["ES256"]
    },
    "jwt_vc": {
      "alg_values_supported": ["ES256"]
    }
  },
  "subject_syntax_types_supported": ["did:key", "did:ebsi"],
  "subject_trust_frameworks_supported": ["ebsi"],
  "id_token_types_supported": [
    "subject_signed_id_token",
    "attester_signed_id_token"
  ]
}

Service Wallet Metadata

Service Wallet is a decoupled construct, having a composite relationship with an Issuer or a Verifier, with purpose of requesting, signing and managing Verifiable Credentials. These share the same client_id as the main functionality (verification or issuance), but expose own configuration through client_metadata in Authorisation Request.

The configuration contains all fields from Holder Wallet Metadata, and the following extension.

Field	Requirement	Notes
`jwks_uri`	REQUIRED	URL of the Authorisation Server's JWK Set document. Must start with `client_id`.

Example Service Wallet Metadata

{
  "authorization_endpoint": "openid:",
  "jwks_uri": "https://my-issuer.rocks/jwks"
}

Holder Wallet Metadata

Holder Wallets are used by individuals to store and present their credentials. Proper configuration of Holder Wallet Metadata ensures that these wallets can securely interact with Credential Issuers and Authorisation Servers.

Holder Wallets are non-reachable, and they can use the client_metadata field in the initial Authorisation Request to deliver the configuration, the default configuration will be used if not explicitly provided. All provided fields in client_metadata will fully replace the default properties.

Field	Requirement	Notes	Default Property
`authorization_endpoint`	OPTIONAL	URL of the Authorisation Server’s authorisation endpoint	`"openid:"`
`scopes_supported`	OPTIONAL	A JSON array containing a list of the OAuth 2.0 “scope” values that this Authorisation Server supports	`["openid"]`
`response_types_supported`	OPTIONAL	A JSON array containing a list of the OAuth 2.0 “response_type” values that this Authorisation Server supports	`["vp_token", "id_token"]`
`subject_types_supported`	OPTIONAL	A JSON array containing a list of the Subject Identifier types that this OP supports	`["public"]`
`id_token_signing_alg_values_supported`	OPTIONAL	A JSON array containing a list of the JWS “alg” values supported by the OP for the ID Token	`["ES256"]`
`request_object_signing_alg_values_supported`	OPTIONAL	A JSON array containing a list of the JWS “alg” values supported by the OP for Request Objects	`["ES256"]`
`vp_formats_supported`	REQUIRED	A JSON Object containing a list of key value pairs, where the key is a string identifying a Credential format supported by the Wallet	`"jwt_vp": { "alg_values_supported": ["ES256"] }` `"jwt_vc": { "alg_values_supported": ["ES256"] }`
`vp_formats_supported` `.jwt_vp`	OPTIONAL	A JSON Object, defining support for Verifiable Presentations in JWT format	`{ "alg_values_supported": ["ES256"] }`
`vp_formats_supported` `.jwt_vp` `.alg_values_supported`	OPTIONAL	A JSON Array of case sensitive strings that identify the cryptographic suites that are supported	`["ES256"]`
`vp_formats_supported` `.jwt_vc`	OPTIONAL	A JSON Object, defining support for Verifiable Credentials in JWT format	`{ "alg_values_supported": ["ES256"] }`
`vp_formats_supported` `.jwt_vc` `.alg_values_supported`	OPTIONAL	A JSON Array of case sensitive strings that identify the cryptographic suites that are supported	`["ES256"]`
`subject_syntax_types_supported`	OPTIONAL	A JSON Array of supported DID methods and their possible sub types.	`["urn:ietf:params:oauth:jwk-thumbprint", "did:key :jwk_jcs-pub"]`
`id_token_types_supported`	OPTIONAL	A JSON array of strings containing the list of ID Token types supported by the OP	`["subject_signed_id_token"]`

Default Properties Example for Holder Wallet Metadata

{
  "authorization_endpoint": "openid:",
  "response_types_supported": ["vp_token", "id_token"],
  "vp_formats_supported": {
    "jwt_vp": {
      "alg_values_supported": ["ES256"]
    },
    "jwt_vc": {
      "alg_values_supported": ["ES256"]
    }
  },
  "scopes_supported": ["openid"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["ES256"],
  "request_object_signing_alg_values_supported": ["ES256"],
  "subject_syntax_types_supported": [
    "urn:ietf:params:oauth:jwk-thumbprint",
    "did:key:jwk_jcs-pub"
  ],
  "id_token_types_supported": ["subject_signed_id_token"]
}

Context​

Introduction​

Organisational Wallets​

Credential Issuer Metadata​

Authorisation Server Metadata​

Service Wallet Metadata​

Holder Wallet Metadata​