diff --git a/openid-4-verifiable-credential-issuance-1_0.md b/openid-4-verifiable-credential-issuance-1_0.md index ba912c7c..7c1c3908 100644 --- a/openid-4-verifiable-credential-issuance-1_0.md +++ b/openid-4-verifiable-credential-issuance-1_0.md @@ -7,7 +7,7 @@ keyword = ["security", "openid", "ssi"] [seriesInfo] name = "Internet-Draft" -value = "openid-4-verifiable-credential-issuance-1_0-14" +value = "openid-4-verifiable-credential-issuance-1_0-15" status = "standard" [[author]] @@ -118,6 +118,7 @@ Deferred Credential Issuance: This specification defines an API for Credential issuance provided by a Credential Issuer. The API is comprised of the following endpoints: * A mandatory Credential Endpoint from which Credentials can be issued (see (#credential-endpoint)). From this endpoint, one Credential, or multiple Credentials with the same Credential Dataset can be issued in one request. +* An optional Nonce Endpoint from which a fresh `c_nonce` value can be obtained to be used in proof of possession of key material in a subsequent request to the Credential Endpoint (see (#nonce-endpoint)). * An optional Deferred Credential Endpoint to allow for the deferred delivery of Credentials (see (#deferred-credential-issuance)). * An optional mechanism for the Credential Issuer to make a Credential Offer to the Wallet to encourage the Wallet to start the issuance flow (see (#credential-offer-endpoint)). * An optional mechanism for the Credential Issuer to receive from the Wallet notification(s) of the status of the Credential(s) that have been issued. @@ -137,7 +138,6 @@ Existing OAuth 2.0 mechanisms are extended as following: * A new authorization details [@!RFC9396] type `openid_credential` is defined to convey the details about the Credentials (including Credential Dataset, Credential Formats, and Credential types) the Wallet wants to obtain (see (#authorization-details)). * Client metadata is used to convey the Wallet's metadata. The new Client metadata parameter `credential_offer_endpoint` is added to allow a Wallet (acting as OAuth 2.0 client) to publish its Credential Offer Endpoint (see (#client-metadata)). * Authorization Endpoint: The additional parameter `issuer_state` is added to convey state in the context of processing an issuer-initiated Credential Offer (see (#credential-authz-request)). Additional parameters `wallet_issuer` and `user_hint` are added to enable the Credential Issuer to request Verifiable Presentations from the calling Wallet during Authorization Request processing. -* Token Endpoint: Optional response parameters `c_nonce` and `c_nonce_expires_in` are added to the Token Endpoint, and Credential Endpoint to provide the Client with a nonce to be used for proof of possession of key material in a subsequent request to the Credential Endpoint (see (#token-response)). ## Core Concepts @@ -648,8 +648,6 @@ The Authorization Server might decide to authorize issuance of multiple instance In addition to the response parameters defined in [@!RFC6749], the Authorization Server MAY return the following parameters: -* `c_nonce`: OPTIONAL. String containing a nonce to be used when creating a proof of possession of the key proof (see (#credential-request)). When received, the Wallet MUST use this nonce value for its subsequent requests until the Credential Issuer provides a fresh nonce. -* `c_nonce_expires_in`: OPTIONAL. Number denoting the lifetime in seconds of the `c_nonce`. * `authorization_details`: REQUIRED when the `authorization_details` parameter is used to request issuance of a certain Credential Configuration as defined in (#authorization-details). It MUST NOT be used otherwise. It is an array of objects, as defined in Section 7 of [@!RFC9396]. In addition to the parameters defined in (#authorization-details), this specification defines the following parameter to be used with the authorization details type `openid_credential` in the Token Response: * `credential_identifiers`: REQUIRED. Array of strings, each uniquely identifying a Credential Dataset that can be issued using the Access Token returned in this response. Each of these Credential Datasets corresponds to the same Credential Configuration in the `credential_configurations_supported` parameter of the Credential Issuer metadata. The Wallet MUST use these identifiers together with an Access Token in subsequent Credential Requests. @@ -666,8 +664,6 @@ Cache-Control: no-store "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6Ikp..sHQ", "token_type": "bearer", "expires_in": 86400, - "c_nonce": "tZignsnFbp", - "c_nonce_expires_in": 86400, "authorization_details": [ { "type": "openid_credential", @@ -710,6 +706,48 @@ Cache-Control: no-store } ``` +# Nonce Endpoint {#nonce-endpoint} + +This endpoint allows a Client to acquire a fresh `c_nonce` value without the overhead of a full Credential Request. A Credential Issuer that requires `c_nonce` values to be incorporated into proofs in the Credential Request (see (#credential-request)) MUST offer a Nonce Endpoint. + +The `nonce_endpoint` Credential Issuer Metadata parameter, as defined in (#credential-issuer-parameters), contains the URL of the Credential Issuer's Nonce Endpoint. + + +## Nonce Request {#nonce-request} + +A request for a nonce is made by sending an HTTP POST request to the URL provided in the `nonce_endpoint` Credential Issuer Metadata parameter. + +Below is a non-normative example of a Nonce Request: + +``` +POST /nonce HTTP/1.1 +Host: credential-issuer.example.com +Content-Length: 0 +``` + +## Nonce Response {#nonce-response} + +The Credential Issuer provides a nonce value in the HTTP response with a 2xx status code and the following parameters included as top-level members in the message body of the HTTP response using the application/json media type: + +* `c_nonce`: REQUIRED. String containing a nonce to be used when creating a proof of possession of the key proof (see (#credential-request)). +* `c_nonce_expires_in`: OPTIONAL. Number denoting the lifetime in seconds of the `c_nonce`. This value serves only as a hint to the Client, indicating how long the Credential Issuer is likely to accept the `c_nonce` as valid. + +Due to the temporal and contextually sensitive nature of the `c_nonce` value, the Credential Issuer MUST make the response uncacheable by adding a `Cache-Control` header field including the value `no-store`. + +Below is a non-normative example of a Nonce Response: + +``` +HTTP/1.1 200 OK +Content-Type: application/json +Cache-Control: no-store + +{ + "c_nonce": "wKI4LT17ac15ES9bw8ac4", + "c_nonce_expires_in": 120 +} +``` + + # Credential Endpoint {#credential-endpoint} The Credential Endpoint issues one or more Credentials of the same Credential Configuration and Credential Dataset (as approved by the End-User) upon presentation of a valid Access Token representing this approval. Support for this endpoint is REQUIRED. @@ -750,9 +788,9 @@ A Client makes a Credential Request to the Credential Endpoint by sending the fo The `proof_type` parameter is an extension point that enables the use of different types of proofs for different cryptographic schemes. -The proof(s) in the `proof` or `proofs` parameter MUST incorporate the Credential Issuer Identifier (audience), and optionally a `c_nonce` value generated by the Authorization Server or the Credential Issuer to allow the Credential Issuer to detect replay. The way that data is incorporated depends on the key proof type. In a JWT, for example, the `c_nonce` value is conveyed in the `nonce` claim, whereas the audience is conveyed in the `aud` claim. In a Linked Data proof, for example, the `c_nonce` is included as the `challenge` element in the key proof object and the Credential Issuer (the intended audience) is included as the `domain` element. +The proof(s) in the `proof` or `proofs` parameter MUST incorporate the Credential Issuer Identifier (audience), and optionally a `c_nonce` value generated by the Credential Issuer to allow the Credential Issuer to detect replay. The way that data is incorporated depends on the key proof type. In a JWT, for example, the `c_nonce` value is conveyed in the `nonce` claim, whereas the audience is conveyed in the `aud` claim. In a Linked Data proof, for example, the `c_nonce` is included as the `challenge` element in the key proof object and the Credential Issuer (the intended audience) is included as the `domain` element. -The initial `c_nonce` value can be returned in a successful Token Response as defined in (#token-response), or in a Credential Error Response as defined in (#issuer-provided-nonce). +The initial `c_nonce` value can be returned in a Nonce Response as defined in (#nonce-response), or in a Credential Error Response as defined in (#issuer-provided-nonce). Below is a non-normative example of a Credential Request for a Credential in [@ISO.18013-5] format using Credential Format-specific parameters and a key proof type `jwt`: @@ -1044,7 +1082,7 @@ Cache-Control: no-store The Credential Issuer MAY provide the Client with a `c_nonce` as defined in (#credential-response) in a Credential Error Response using `invalid_proof` error code defined in (#credential-error-response) if the Credential Issuer Metadata contains `proof_types_supported` indicating a key proof is required for the requested Credential. Depending on the Credential Issuer policy, this occurs if they receive a Credential Request without a `c_nonce` or with an invalid `c_nonce` value included in the proof(s) in the `proof` or `proofs` parameter. -If the Client has not received a `c_nonce` and the Credential Issuer Metadata contains `proof_types_supported` indicating a key proof is required for the requested Credential, the Client MUST send a Credential Request that contains a `proof` or `proofs` parameter that is fully valid but does not include a `c_nonce` value. It is the Credential Issuer policy whether or not a `c_nonce` value is required in the key proofs. +If the Credential Issuer Metadata contains a `nonce_endpoint` and a `proof_types_supported` indicating a key proof is required for the requested Credential and the Client does not have a valid `c_nonce`, the Client MUST obtain a `c_nonce` value from the `nonce_endpoint` and send a Credential Request that contains a `proof` or `proofs` parameter that includes a `c_nonce` value. It is the Credential Issuer policy whether or not a `c_nonce` value is required in the key proofs. If the Client received a `c_nonce`, the `c_nonce` value MUST be incorporated in the respective parameter in the `proof` or `proofs` object. @@ -1258,6 +1296,7 @@ This specification defines the following Credential Issuer Metadata parameters: * `credential_issuer`: REQUIRED. The Credential Issuer's identifier, as defined in (#credential-issuer-identifier). * `authorization_servers`: OPTIONAL. Array of strings, where each string is an identifier of the OAuth 2.0 Authorization Server (as defined in [@!RFC8414]) the Credential Issuer relies on for authorization. If this parameter is omitted, the entity providing the Credential Issuer is also acting as the Authorization Server, i.e., the Credential Issuer's identifier is used to obtain the Authorization Server metadata. The actual OAuth 2.0 Authorization Server metadata is obtained from the `oauth-authorization-server` well-known location as defined in Section 3 of [@!RFC8414]. When there are multiple entries in the array, the Wallet may be able to determine which Authorization Server to use by querying the metadata; for example, by examining the `grant_types_supported` values, the Wallet can filter the server to use based on the grant type it plans to use. When the Wallet is using `authorization_server` parameter in the Credential Offer as a hint to determine which Authorization Server to use out of multiple, the Wallet MUST NOT proceed with the flow if the `authorization_server` Credential Offer parameter value does not match any of the entries in the `authorization_servers` array. * `credential_endpoint`: REQUIRED. URL of the Credential Issuer's Credential Endpoint, as defined in (#credential-request). This URL MUST use the `https` scheme and MAY contain port, path, and query parameter components. +* `nonce_endpoint`: OPTIONAL. URL of the Credential Issuer's Nonce Endpoint, as defined in (#nonce-endpoint). This URL MUST use the `https` scheme and MAY contain port, path, and query parameter components. If omitted, the Credential Issuer does not support the Nonce Endpoint. * `deferred_credential_endpoint`: OPTIONAL. URL of the Credential Issuer's Deferred Credential Endpoint, as defined in (#deferred-credential-issuance). This URL MUST use the `https` scheme and MAY contain port, path, and query parameter components. If omitted, the Credential Issuer does not support the Deferred Credential Endpoint. * `notification_endpoint`: OPTIONAL. URL of the Credential Issuer's Notification Endpoint, as defined in (#notification-endpoint). This URL MUST use the `https` scheme and MAY contain port, path, and query parameter components. If omitted, the Credential Issuer does not support the Notification Endpoint. * `credential_response_encryption`: OPTIONAL. Object containing information about whether the Credential Issuer supports encryption of the Credential Credential Response on top of TLS. @@ -2206,16 +2245,6 @@ This specification registers the following parameter names in the IANA "OAuth Pa * Change Controller: OpenID Foundation Digital Credentials Protocols Working Group - openid-specs-digital-credentials-protocols@lists.openid.net * Reference: (#token-request) of this specification -* Parameter Name: c_nonce -* Parameter Usage Location: token response -* Change Controller: OpenID Foundation Digital Credentials Protocols Working Group - openid-specs-digital-credentials-protocols@lists.openid.net -* Reference: (#token-response) of this specification - -* Parameter Name: c_nonce_expires_in -* Parameter Usage Location: token response -* Change Controller: OpenID Foundation Digital Credentials Protocols Working Group - openid-specs-digital-credentials-protocols@lists.openid.net -* Reference: (#token-response) of this specification - ## OAuth Dynamic Client Registration Metadata Registry This specification registers the following client metadata name in the IANA "OAuth Dynamic Client Registration Metadata" registry [@!IANA.OAuth.Parameters] established by [@!RFC7591]. @@ -2327,6 +2356,8 @@ The technology described in this specification was made available from contribut * Define Credential Dataset as a term * Define Credential Configuration as a term * remove use of the `authorization_pending` and `slow_down` error codes + * removed `c_nonce` and `c_nonce_expires_in` from the token endpoint response + * added a Nonce Endpoint where a Client can acquire a fresh c_nonce value without the overhead of a full Credential Request -13