Skip to content

Commit 15cdda3

Browse files
mickraumickrau
authored
Merge branch 'main' into 719-revisiting-building-iae-on-top-of-first-party-apps-draft
2 parents cc107d1 + 4ef9f26 commit 15cdda3

1 file changed

Lines changed: 87 additions & 9 deletions

File tree

‎1.1/openid-4-verifiable-credential-issuance-1_1.md‎

Lines changed: 87 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1218,9 +1218,9 @@ A Client makes a Credential Request to the Credential Endpoint by sending the fo
12181218
* `credential_configuration_id`: REQUIRED if a `credential_identifiers` parameter was not returned from the Token Response as part of the `authorization_details` parameter. It MUST NOT be used otherwise. String that uniquely identifies one of the keys in the name/value pairs stored in the `credential_configurations_supported` Credential Issuer metadata. The corresponding object in the `credential_configurations_supported` map MUST contain one of the value(s) used in the `scope` parameter in the Authorization Request. When this parameter is used, the `credential_identifier` MUST NOT be present.
12191219
* `proofs`: OPTIONAL. Object providing one or more proof of possessions of the cryptographic key material to which the issued Credential instances will be bound to. The `proofs` parameter contains exactly one parameter named as the proof type in (#proof-types), the value set for this parameter is a non-empty array containing parameters as defined by the corresponding proof type.
12201220
* `credential_response_encryption`: OPTIONAL. Object containing information for encrypting the Credential Response. If this request element is not present, the corresponding credential response returned is not encrypted.
1221-
* `jwk`: REQUIRED. Object containing a single public key as a JWK used for encrypting the Credential Response.
1222-
* `enc`: REQUIRED. JWE [@!RFC7516] `enc` algorithm [@!RFC7518] for encrypting Credential Responses.
1223-
* `zip`: OPTIONAL. JWE [@!RFC7516] `zip` algorithm [@!RFC7518] for compressing Credential Responses prior to encryption. If absent then compression MUST not be used.
1221+
* `jwk`: REQUIRED. Object containing a single public key as a JWK used for encrypting the Credential Response.
1222+
* `enc`: REQUIRED. JWE [@!RFC7516] `enc` algorithm [@!RFC7518] for encrypting Credential Responses.
1223+
* `zip`: OPTIONAL. JWE [@!RFC7516] `zip` algorithm [@!RFC7518] for compressing Credential Responses prior to encryption. If absent then compression MUST not be used.
12241224

12251225
See (#identifying_credential) for the summary of the options how requested Credential(s) are identified throughout the Issuance flow.
12261226

@@ -1340,10 +1340,11 @@ If the Credential Response is not encrypted, the media type of the response MUST
13401340
The following parameters are used in the JSON-encoded Credential Response body:
13411341

13421342
* `credentials`: OPTIONAL. Contains an array of one or more issued Credentials. It MUST NOT be used if the `transaction_id` parameter is present. The elements of the array MUST be objects. The number of elements in the `credentials` array matches the number of keys that the Wallet has provided via the `proofs` parameter of the Credential Request, unless the Issuer decides to issue fewer Credentials. Each key provided by the Wallet is used to bind to, at most, one Credential. This specification defines the following parameters to be used inside this object:
1343-
* `credential`: REQUIRED. Contains one issued Credential. The encoding of the Credential depends on the Credential Format and MAY be a string or an object. Credential Formats expressed as binary data MUST be base64url-encoded and returned as a string. More details are defined in the Credential Format Profiles in (#format-profiles).
1343+
* `credential`: REQUIRED. Contains one issued Credential. The encoding of the Credential depends on the Credential Format and MAY be a string or an object. Credential Formats expressed as binary data MUST be base64url-encoded and returned as a string. More details are defined in the Credential Format Profiles in (#format-profiles).
13441344
* `transaction_id`: OPTIONAL. String identifying a Deferred Issuance transaction. This parameter is contained in the response if the Credential Issuer cannot immediately issue the Credential. The value is subsequently used to obtain the respective Credential with the Deferred Credential Endpoint (see (#deferred-credential-issuance)). It MUST not be used if the `credentials` parameter is present. It MUST be invalidated after the Credential for which it was meant has been obtained by the Wallet.
13451345
* `interval`: REQUIRED if `transaction_id` is present. Contains a positive number that represents the minimum amount of time in seconds that the Wallet SHOULD wait after receiving the response before sending a new request to the Deferred Credential Endpoint. It MUST NOT be used if the `credentials` parameter is present.
13461346
* `notification_id`: OPTIONAL. String identifying one or more Credentials issued in one Credential Response. It MUST be included in the Notification Request as defined in (#notification). It MUST not be used if the `credentials` parameter is not present.
1347+
* `credential_metadata`: OPTIONAL. Object that contains additional metadata specific to the issued Credential(s). The definitions and contained parameters for this Object are identical to the `credential_metadata` parameter as defined in Credential Issuer Metadata (see (#credential-issuer-metadata)) See (#display-metadata-considerations) for implementation considerations on credential metadata.
13471348

13481349
Additional Credential Response parameters MAY be defined and used. The Wallet MUST ignore any unrecognized parameters.
13491350

@@ -1485,7 +1486,7 @@ A Deferred Credential Response may either contain the requested Credentials or f
14851486
* If the Credential Issuer is able to issue the requested Credentials, the Deferred Credential Response MUST use the `credentials` parameter as defined in (#credential-response) and MUST respond with the HTTP status code 200 (see Section 15.3.3 of [@!RFC9110]).
14861487
* If the Credential Issuer still requires more time, the Deferred Credential Response MUST use the `interval` and `transaction_id` parameters as defined in (#credential-response) and it MUST respond with the HTTP status code 202 (see Section 15.3.3 of [@!RFC9110]). The value of `transaction_id` MUST be same as the value of `transaction_id` in the Deferred Credential Request.
14871488

1488-
The Deferred Credential Response MAY use the `notification_id` parameter as defined in (#credential-response).
1489+
The Deferred Credential Response MAY use the `notification_id` and `credential_metadata` parameters as defined in (#credential-response).
14891490

14901491
Additional Deferred Credential Response parameters MAY be defined and used.
14911492
The Wallet MUST ignore any unrecognized parameters.
@@ -1779,17 +1780,17 @@ This specification defines the following Credential Issuer Metadata parameters:
17791780
* `key_attestations_required`: OPTIONAL. Object that describes the requirement for key attestations as described in (#keyattestation), which the Credential Issuer expects the Wallet to send within the proof(s) of the Credential Request. If the Credential Issuer does not require a key attestation, this parameter MUST NOT be present in the metadata. If both `key_storage` and `user_authentication` parameters are absent, the `key_attestations_required` parameter may be empty, indicating a key attestation is needed without additional constraints.
17801781
* `key_storage`: OPTIONAL. A non-empty array defining values specified in (#keyattestation-apr) accepted by the Credential Issuer.
17811782
* `user_authentication`: OPTIONAL. A non-empty array defining values specified in (#keyattestation-apr) accepted by the Credential Issuer.
1782-
* `credential_metadata`: OPTIONAL. Object containing information relevant to the usage and display of issued Credentials. Credential Format-specific mechanisms can overwrite the information in this object to convey Credential metadata. Format-specific mechanisms, such as SD-JWT VC display metadata are always preferred by the Wallet over the information in this object, which serves as the default fallback. Below is a non-exhaustive list of parameters that MAY be included:
1783+
* `credential_metadata`: OPTIONAL. Object containing information relevant to the usage and display of issued Credentials. Credential Format-specific mechanisms can overwrite the information in this object to convey Credential metadata and is preferred by the Wallet over the information in this object, which serves as the default fallback. Additionally, the Credential Response MUST be preferred by the Wallet over any other information, effectively overwriting the information in this object and any Credential Format-specific mechanisms. See (#display-metadata-considerations) for implementation considerations on credential metadata. Below is a default, non-exhaustive, extensible list of parameters that MAY be included:
17831784
* `display`: OPTIONAL. A non-empty array of objects, where each object contains the display properties of the supported Credential for a certain language. Below is a non-exhaustive list of parameters that MAY be included.
17841785
* `name`: REQUIRED. String value of a display name for the Credential.
17851786
* `locale`: OPTIONAL. String value that identifies the language of this object represented as a language tag taken from values defined in BCP47 [@!RFC5646]. Multiple `display` objects MAY be included for separate languages. There MUST be only one object for each language identifier.
17861787
* `logo`: OPTIONAL. Object with information about the logo of the Credential. The following non-exhaustive set of parameters MAY be included:
1787-
* `uri`: REQUIRED. String value that contains a URI where the Wallet can obtain the logo of the Credential from the Credential Issuer. The Wallet needs to determine the scheme, since the URI value could use the `https:` scheme, the `data:` scheme, etc.
1788-
* `alt_text`: OPTIONAL. String value of the alternative text for the logo image.
1788+
* `uri`: REQUIRED. String value that contains a URI where the Wallet can obtain the logo of the Credential from the Credential Issuer. The Wallet needs to determine the scheme, since the URI value could use the `https:` scheme, the `data:` scheme, etc.
1789+
* `alt_text`: OPTIONAL. String value of the alternative text for the logo image.
17891790
* `description`: OPTIONAL. String value of a description of the Credential.
17901791
* `background_color`: OPTIONAL. String value of a background color of the Credential represented as numerical color values defined in CSS Color Module Level 3 [@!CSS-Color].
17911792
* `background_image`: OPTIONAL. Object with information about the background image of the Credential. At least the following parameter MUST be included:
1792-
* `uri`: REQUIRED. String value that contains a URI where the Wallet can obtain the background image of the Credential from the Credential Issuer. The Wallet needs to determine the scheme, since the URI value could use the `https:` scheme, the `data:` scheme, etc.
1793+
* `uri`: REQUIRED. String value that contains a URI where the Wallet can obtain the background image of the Credential from the Credential Issuer. The Wallet needs to determine the scheme, since the URI value could use the `https:` scheme, the `data:` scheme, etc.
17931794
* `text_color`: OPTIONAL. String value of a text color of the Credential represented as numerical color values defined in CSS Color Module Level 3 [@!CSS-Color].
17941795
* `claims`: OPTIONAL. A non-empty array of claims description objects as defined in (#claims-description-issuer-metadata).
17951796

@@ -1987,6 +1988,82 @@ It is up to the Credential Issuer whether to update both the signature and the c
19871988

19881989
The Credential Issuer determines the number of the Credentials issued in the Credential Response, regardless of number of proofs/keys contained in the `proofs` parameter in the Credential Request.
19891990

1991+
## Credential Metadata {#display-metadata-considerations}
1992+
1993+
Credential metadata is provided by the Credential Issuer, but can be conveyed using different mechanisms. Defined mechanisms to provide display metadata are:
1994+
1995+
* Credential Issuer metadata MAY contain credential metadata as defined in (#credential-issuer-parameters)
1996+
* Credential Formats MAY define their own mechanisms for metadata
1997+
* Credential Response MAY also contain metadata as defined in (#credential-response)
1998+
1999+
Credential metadata provided via the Credential Issuer metadata SHOULD be interpreted as the most generic form of metadata and as a general fallback solution. If defined and present, Credential Format specific metadata overwrites the values from the Credential Issuer metadata. If present, metadata in the Credential Response overwrites existing values.
2000+
2001+
(#credential-issuer-parameters) defines a set of default Credential metadata parameters, but additional ones can be defined and added by profiles or extensions. Other standardization organizations or ecosystems defining extensions to the Credential metadata parameters SHOULD do so by defining a collision-resistant parameter that contains an Object with all parameters they are defining.
2002+
2003+
Below is a non-normative example of how credential metadata from the Credential Issuer metadata and the Credential Response would be merged:
2004+
2005+
Credential metadata contained in Credential Issuer metadata:
2006+
2007+
```json
2008+
{
2009+
"display": [
2010+
{
2011+
"name": "BankCredential",
2012+
"logo": {
2013+
"uri": "https://bank.example.net/public/logo.png",
2014+
"alt_text": "a square logo of a bank"
2015+
},
2016+
"locale": "en-US",
2017+
"background_color": "#12107c",
2018+
"text_color": "#FFFFFF"
2019+
}
2020+
]
2021+
}
2022+
```
2023+
2024+
Credential metadata contained in the Credential Response:
2025+
2026+
```json
2027+
{
2028+
"display": [
2029+
{
2030+
"logo": {
2031+
"uri": "data:image/png;base64,F00==",
2032+
},
2033+
"com.example.domain": {
2034+
"some_text": "something_really_important",
2035+
"more_text": "also_really_important"
2036+
}
2037+
}
2038+
]
2039+
}
2040+
```
2041+
2042+
Resulting (combined) metadata:
2043+
2044+
```json
2045+
{
2046+
"display": [
2047+
{
2048+
"name": "BankCredential",
2049+
"logo": {
2050+
"uri": "data:image/png;base64,F00==",
2051+
"alt_text": "a square logo of a bank"
2052+
},
2053+
"locale": "en-US",
2054+
"background_color": "#12107c",
2055+
"text_color": "#FFFFFF",
2056+
"com.example.domain": {
2057+
"some_text": "something_really_important",
2058+
"more_text": "also_really_important"
2059+
}
2060+
}
2061+
]
2062+
}
2063+
```
2064+
2065+
Note that `com.example.domain` in the above example shows how an extension would be defined and used.
2066+
19902067
## Pre-Final Specifications
19912068

19922069
Implementers should be aware that this specification uses several specifications that are not yet final specifications. Those specifications are:
@@ -3642,3 +3719,4 @@ The technology described in this specification was made available from contribut
36423719
* add URNs for IAE type identifiers
36433720
* add iana registration for an openid foundation urn
36443721
* use OAuth 2.0 for First-Party Applications as basis for Interactive Authorization
3722+
* add optional metadata to the credential response

0 commit comments

Comments
 (0)