OpenID for Verifiable Credential Issuance - draft 13

1.1. Requirements Notation and Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119].¶

3.1. Credential Issuer

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 Section 7).¶
• An optional Batch Credential Endpoint from which multiple Credentials can be issued in one request (see Section 8).¶
• An optional Deferred Credential Endpoint to allow for the deferred delivery of credentials (see Section 9).¶
• 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 Section 4).¶
• A mechanism for the Credential Issuer to publish metadata about the Credentials it is capable of issuing (see Section 10.2).¶

Both the Credential and the Batch Credential Endpoints have the (optional) ability to bind an issued Credential to certain cryptographic key material. Both requests therefore enable conveying proof of possession for the key material. Multiple key proof types are supported.¶

3.2. OAuth 2.0

Every Credential Issuer utilizes an OAuth 2.0 [RFC6749] Authorization Server to authorize access. The same OAuth 2.0 Authorization Server can protect one or more Credential Issuers. Wallets determine the Credential Issuer's Authorization Server using the Credential Issuer's metadata (see Section 10.2).¶

All OAuth 2.0 Grant Types and extensions mechanisms can be used in conjunction with the credential issuance API. Aspects not defined in this specification are expected to follow [RFC6749].¶

Existing OAuth 2.0 mechanisms are extended as following:¶

• A new Grant Type "Pre-Authorized Code" is defined to facilitate flows where the preparation of the credential issuance is conducted before the actual OAuth flow starts (see Section 3.5).¶
• A new authorization details [RFC9396] type openid_credential is defined to convey the details about the Credentials (including formats and types) the Wallet wants to obtain (see Section 5.1.1).¶
• New token response error codes authorization_pending and slow_down are added to allow for deferred authorization of credential issuance. These error codes are supported for the Pre-Authorized Code grant type.¶
• Client metadata is used to convey Wallet's metadata. A new metadata parameter credential_offer_endpoint is added to allow a Wallet (acting as OAuth 2.0 client) to publish its Credential Offer Endpoint (see Section 10.1).¶
• Authorization Endpoint: An additional parameter issuer_state is added to convey state in the context of processing an issuer-initiated Credential Offer (see Section 5.1). 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, Credential Endpoint and Batch 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 Section 6.2).¶

3.3. Core Concepts

The Wallet sends one Credential Request per individual Credential to the Credential Endpoint. The Wallet MAY use the same Access Token to send multiple Credential Requests to request issuance of the following:¶

• multiple Credentials of different types/doctypes bound to the same proof, or¶
• multiple Credentials of the same type/doctype bound to different proofs, or¶
• multiple Credentials of the different types/doctypes bound to different proofs.¶

Note: "type" and "doctype" are terms defined by an individual credential format. For details, see Appendix E.¶

The Wallet MAY send one Batch Credential Request to the Batch Credential Endpoint to request the following in the Batch Credential Response:¶

• multiple Credentials of different types/doctypes bound to the same proof, or¶
• multiple Credentials of the same type/doctype bound to different proofs, or¶
• multiple Credentials of different types/doctypes bound to different proofs.¶

In the course of the authorization process, the Credential Issuer MAY also request Credential presentation as a means to authenticate or identify the End-User during the issuance flow, as illustrated in a use case in Appendix D.5.¶

At its core, this specification is Credential format agnostic and allows implementers to leverage specific capabilities of Credential formats of their choice. Multiple Credential formats can be used within the same transaction.¶

The specification achieves this by defining the following:¶

• Extension points to add Credential format specific parameters or claims in the Credential Issuer metadata, Credential Offer, Authorization Request, Credential Request and Batch Credential Request,¶
• Credential format identifiers to identify Credential format specific set of parameters and claims to be applied at each extension point. This set of Credential format specific set of parameters and claims is referred to as a "Credential Format Profile" in this specification.¶

This specification defines Credential Format Profiles for W3C Verifiable Credentials as defined in [VC_DATA] and ISO/IEC 18013-5 mDL as defined in [ISO.18013-5] in Appendix E that contain Credential Format specific parameters to be included at each extension point defined in this specification. Other specifications or deployments can define their own Credential Format Profiles using the above-mentioned extension points.¶

The issuance can have multiple characteristics, which can be combined depending on the use cases:¶

• Authorization Code Flow or Pre-Authorized Code Flow: The Credential Issuer can obtain user information to turn into a Verifiable Credential using user authentication and consent at the Credential Issuer's Authorization Endpoint (Authorization Code Flow) or using out-of-band mechanisms outside of the issuance flow (Pre-Authorized Code Flow).¶
• Wallet initiated or Issuer initiated: The request from the Wallet can be sent to the Credential Issuer without any gesture from the Credential Issuer (Wallet Initiated) or following the communication from the Credential Issuer (Issuer Initiated).¶
• Same-device or Cross-device Credential Offer: The End-User may receive the Credential Offer from the Credential Issuer either on the same device as the device the Wallet resides on, or through any other means, such as another device or physical mail, so that the Credential Offer can be communicated to the Wallet.¶
• Immediate or Deferred: The Credential Issuer can issue the Credential directly in response to the Credential Request (immediate) or requires time and needs the Wallet to come back to retrieve Credential (deferred).¶

The following subsections illustrate some of the authorization flows supported by this specification.¶

3.4. Authorization Code Flow

Below is a diagram of a Credential issuance using the Authorization Code Flow, using grant type authorization_code as defined in [RFC6749].¶

The diagram shows how a Wallet-initiated flow use case as described in Appendix D.4 is implemented with the Credential Issuance API defined in this specification. Note that the diagram does not illustrate all the optional features of this specification.¶

+--------------+   +-----------+                                    +-------------------+
| User         |   |   Wallet  |                                    | Credential Issuer |
+--------------+   +-----------+                                    +-------------------+
        |                |                                                    |
        |    interacts   |                                                    |
        |--------------->|                                                    |
        |                |  (1) Obtains Issuer's Credential Issuer metadata   |
        |                |<-------------------------------------------------->|
        |                |                                                    |
        |                |  (2) Authorization Request                         |
        |                |      (type(s) of Credentials to be issued)         |
        |                |--------------------------------------------------->|
        |                |                                                    |
        |   User Authentication / Consent                                     |
        |                |                                                    |
        |                |  (3)   Authorization Response (code)               |
        |                |<---------------------------------------------------|
        |                |                                                    |
        |                |  (4) Token Request (code)                          |
        |                |--------------------------------------------------->|
        |                |      Token Response (access_token)                 |
        |                |<---------------------------------------------------|
        |                |                                                    |
        |                |  (5) Credential Request (access_token, proof(s))   |
        |                |--------------------------------------------------->|
        |                |      Credential Response                           |
        |                |      (credential(s) OR transaction_id)           |
        |                |<---------------------------------------------------|

(1) The Wallet uses the Credential Issuer's metadata as described in Section 10.2 to learn what credential types and formats the Credential Issuer supports and to determine the issuer URL of the OAuth 2.0 Authorization Server the Credential Issuer relies on. Note in this example, the Credential Issuer also provides the OAuth 2.0 Authorization Server. This specification enables deployments where the Credential Issuer API and the Authorization Server are different services, perhaps even provided by different entities.¶

(2) The Wallet sends an Authorization Request to the Authorization Endpoint. The Authorization Endpoint processes the Authorization Request, which typically includes user authentication and gathering of user consent.¶

(3) The Authorization Endpoint returns an Authorization Response with the Authorization Code upon successfully processing the Authorization Request.¶

Note: Steps (2) and (3) happen in the front channel, by redirecting the End-User via the User Agent. Those steps are defined in Section 5.¶

(4) The Wallet sends a Token Request to the Token Endpoint with the Authorization Code obtained in step (3). The Token Endpoint returns an Access Token in the Token Response upon successfully validating Authorization Code. This step happens in the back-channel communication (direct communication between two systems using HTTP requests and responses without using redirects through an intermediary such as a browser). This step is defined in Section 6.¶

(5) The Wallet sends a Credential Request to the Credential Issuer's Credential Endpoint with the Access Token and (optionally) the proof of possession of the public key to which the issued VC shall be bound to. Upon successfully validating Access Token and proof, the Credential Issuer returns a VC in the Credential Response if it can issue a Credential right away. This step is defined in Section 7.¶

If the Credential Issuer requires more time to issue a Credential, the Credential Issuer MAY return a transaction_id to the Wallet with information about when the Wallet can start sending a Deferred Credential Request to obtain an issued Credential, as defined in Section 9.¶

If the Credential Issuer wants to issue multiple Credentials in one response, the Credential Issuer MAY support the Batch Credential Endpoint and the Wallet MAY send a Batch Credential Request to the Batch Credential Endpoint as defined in Section 8.¶

With grant type authorization_code, it is RECOMMENDED to use PKCE as defined in [RFC7636] to prevent authorization code interception attacks and Pushed Authorization Requests [RFC9126] to ensure integrity and authenticity of the authorization request.¶

Note: This flow is based on OAuth 2.0 and the Authorization Code Grant type, but this specification can be used with other OAuth 2.0 grant types as well.¶

3.5. Pre-Authorized Code Flow

Figure 2 is a diagram of a Credential issuance using the Pre-Authorized Code Flow. In this flow, before initiating the flow with the Wallet, the Credential Issuer first conducts the steps required to prepare the Credential issuance, e.g., user authentication and authorization. Consequently, the Pre-Authorized Code is sent by the Credential Issuer to the Wallet. This flow does not use the Authorization Endpoint, and The Wallet exchanges the Pre-Authorized Code for the Access Token directly at the Token Endpoint. Access Token is then used to request Credential issuance at the Credential Endpoint. See Appendix D.2 for a use case.¶

How the End-User provides information required for the issuance of a requested Credential to the Credential Issuer and the business processes conducted by the Credential Issuer to prepare a Credential are out of scope of this specification.¶

This flow uses the newly defined OAuth 2.0 Grant Type "urn:ietf:params:oauth:grant-type:pre-authorized_code".¶

The diagram is based on a Credential Issuer initiated flow illustrated in a use case in Appendix D.2 and does not illustrate all the optional features.¶

+--------------+   +-----------+                                    +-------------------+
| User         |   |   Wallet  |                                    | Credential Issuer |
+--------------+   +-----------+                                    +-------------------+
        |                |                                                    |
        |                |  (1) User provides  information required           |
        |                |      for the issuance of a certain Credential      |
        |-------------------------------------------------------------------->|
        |                |                                                    |
        |                |  (2) Credential Offer (Pre-Authorized Code)        |
        |                |<---------------------------------------------------|
        |                |  (3) Obtains Issuer's Credential Issuer metadata   |
        |                |<-------------------------------------------------->|
        |   interacts    |                                                    |
        |--------------->|                                                    |
        |                |                                                    |
        |                |  (4) Token Request (Pre-Authorized Code, pin)      |
        |                |--------------------------------------------------->|
        |                |      Token Response (access_token)                 |
        |                |<---------------------------------------------------|
        |                |                                                    |
        |                |  (5) Credential Request (access_token, proof(s))   |
        |                |--------------------------------------------------->|
        |                |      Credential Response                           |
        |                |      (credential(s))                               |
        |                |<---------------------------------------------------|

(1) The Credential Issuer successfully obtains consent and user data required for the issuance of a requested Credential from the End-User using Issuer-specific business process.¶

(2) The flow defined in this specification begins as the Credential Issuer generates a Credential Offer for certain Credential(s) and communicates it to the Wallet, for example, as a QR code or as a link.¶

(3) The Wallet uses information from the Credential Offer to obtain the Credential Issuer's metadata including details about the Credential that this Credential Issuer wants to issue. This step is defined in Section 10.2.¶

(4) The Wallet sends the Pre-Authorized Code obtained in step (2) in the Token Request to the Token Endpoint. The Wallet will send a PIN provided by the User, if it was required by the Credential Issuer. This step is defined in Section 6.¶

(5) This step is the same as Step 5 in the Authorization Code Flow.¶

It is important to note that anyone who possesses a valid Pre-Authorized Code, without further security measures, would be able to receive a VC from the Credential Issuer. Implementers MUST implement mitigations most suitable to the use case.¶

One such mechanism defined in this specification is the usage of PIN. If in the Credential Offer the Credential Issuer indicated that the PIN is required, the End-User is requested to type in a PIN sent via a channel different than the issuance Flow and the PIN is sent to the Credential Issuer in the Token Request.¶

For more details and concrete mitigations, see Section 11.3.¶

4.1. Credential Offer

The Credential Issuer sends Credential Offer as an HTTP GET request or an HTTP redirect to the Wallet's Credential Offer Endpoint defined in Section 10.1.¶

The Credential Offer object, which is a JSON object with the Credential Offer parameters, can be sent by value or by reference.¶

The Credential Offer contains a single URI query parameter credential_offer or credential_offer_uri:¶

• credential_offer: A JSON object with the Credential Offer parameters. This MUST NOT be present when credential_offer_uri parameter is present.¶
• credential_offer_uri: A URL using the https scheme referencing a resource containing a JSON object with the Credential Offer parameters. This MUST NOT be present when credential_offer parameter is present.¶

The Credential Issuer MAY render a QR code containing the Credential Offer that can be scanned by the End-User using a Wallet, or a link that the End-User can click.¶

For security considerations, see Section 11.2.¶

{
   "credential_issuer": "https://credential-issuer.example.com",
   "credentials": [
      "UniversityDegree_JWT",
      {
         "format": "mso_mdoc",
         "doctype": "org.iso.18013.5.1.mDL"
      }
   ],
   "grants": {
      "authorization_code": {
         "issuer_state": "eyJhbGciOiJSU0Et...FYUaBy"
      },
      "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
         "pre-authorized_code": "adhjhdjajkdkhjhdj",
         "user_pin_required": true
      }
   }
}

  GET /credential_offer?credential_offer=%7B%22credential_issuer%22:%22
  https://credential-issuer.example.com%22,%22credentials%22:%5B%22UniversityDegree_JWT
  %22,%7B%22format%22:%22mso_mdoc%22,%22doctype%22:%22org.iso.18013.5.1.mDL%22%7D%5D,%22
  grants%22:%7B%22authorization_code%22:%7B%22issuer_state%22:%22eyJhbGciOiJSU0Et...FYUaBy
  %22%7D,%22urn:ietf:params:oauth:grant-type:pre-authorized_code%22:%7B%22
  pre-authorized_code%22:%22adhjhdjajkdkhjhdj%22,%22user_pin_required%22:true%7D%7D%7D

openid-credential-offer://?credential_offer=%7B%22credential_issuer%22:%22
  https://credential-issuer.example.com%22,%22credentials%22:%5B%22UniversityDegree_JWT
  %22,%7B%22format%22:%22mso_mdoc%22,%22doctype%22:%22org.iso.18013.5.1.mDL%22%7D%5D,%22
  grants%22:%7B%22authorization_code%22:%7B%22issuer_state%22:%22eyJhbGciOiJSU0Et...FYUaBy
  %22%7D,%22urn:ietf:params:oauth:grant-type:pre-authorized_code%22:%7B%22
  pre-authorized_code%22:%22adhjhdjajkdkhjhdj%22,%22user_pin_required%22:true%7D%7D%7D

GET /credential_offer HTTP/1.1
Host: server.example.com

openid-credential-offer://?
  credential_offer_uri=https%3A%2F%2Fserver%2Eexample%2Ecom%2Fcredential-offer.json

HTTP/1.1 200 OK
Content-Type: application/json

{
    "credential_issuer": "https://credential-issuer.example.com",
    "credentials": [
        {
            "format": "jwt_vc_json",
            "credential_definition": {
                "type": [
                    "VerifiableCredential",
                    "UniversityDegreeCredential"
                ]
            }
        }
    ],
    "grants": {
        "authorization_code": {
            "issuer_state": "eyJhbGciOiJSU0Et...FYUaBy"
        }
    }
}

{
   "credential_issuer": "https://credential-issuer.example.com",
   "credentials": [
      "UniversityDegree_LDP"
   ],
   "grants": {
      "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
          "pre-authorized_code": "adhjhdjajkdkhjhdj",
          "user_pin_required": true
      }
  }
}

4.2. Credential Offer Response

The Wallet is not supposed to create a response. UX control stays with the Wallet after completion of the process.¶

5.1. Authorization Request

An Authorization Request is an OAuth 2.0 Authorization Request as defined in section 4.1.1 of [RFC6749], which requests to grant access to the Credential Endpoint as defined in Section 7.¶

There are two possible ways to request issuance of a specific Credential type in an Authorization Request. One way is to use of the authorization_details request parameter as defined in [RFC9396] with one or more authorization details objects of type openid_credential, per Section 5.1.1. The other is through the use of scopes as defined in Section 5.1.2.¶

[
   {
      "type": "openid_credential",
      "format": "jwt_vc_json",
      "credential_definition": {
         "type": [
            "VerifiableCredential",
            "UniversityDegreeCredential"
         ]
      }
   }
]

[
   {
      "type": "openid_credential",
      "locations": [
         "https://credential-issuer.example.com"
      ],
      "format": "jwt_vc_json",
      "credential_definition": {
         "type": [
            "VerifiableCredential",
            "UniversityDegreeCredential"
         ]
      }
   }
]

GET /authorize?
  response_type=code
  &client_id=s6BhdRkqt3
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &authorization_details=%5B%7B%22type%22%3A+%22openid_credential%22
    %2C+%22format%22%3A+%22jwt_vc_json%22%2C+%22credential_definition
    %22%3A+%7B%22type%22%3A+%5B%22VerifiableCredential%22%2C+%22Unive
    rsityDegreeCredential%22%5D%7D%7D%5D
  &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb

Host: https://server.example.com

[
   {
      "type":"openid_credential",
      "format": "ldp_vc",
      "credential_definition": {
         "@context": [
            "https://www.w3.org/2018/credentials/v1",
            "https://www.w3.org/2018/credentials/examples/v1"
         ],
         "type": [
            "VerifiableCredential",
            "UniversityDegreeCredential"
         ]
      }
   },
   {
      "type":"openid_credential",
      "format": "mso_mdoc",
      "doctype":"org.iso.18013.5.1.mDL"
   }
]

GET /authorize?
  response_type=code
  &scope=UniversityDegree_JWT
  &resource=https://credential-issuer.example.com
  &client_id=s6BhdRkqt3
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
Host: https://server.example.com

POST /op/par HTTP/1.1
Host: as.example.com
Content-Type: application/x-www-form-urlencoded

response_type=code
&client_id=CLIENT1234
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
&code_challenge_method=S256
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
&authorization_details=...

5.2. Successful Authorization Response

Authorization Responses MUST be made as defined in [RFC6749].¶

Below is a non-normative example of a successful Authorization Response:¶

HTTP/1.1 302 Found
Location: https://Wallet.example.org/cb?
    code=SplxlOBeZQQYbYS6WxSbIA

5.3. Authorization Error Response

Authorization Error Response MUST be made as defined in [RFC6749].¶

When the requested scope value is invalid, unknown, or malformed, the AS should respond with the error code invalid_scope defined in Section 4.1.2.1 of [RFC6749].¶

Below is a non-normative example of an unsuccessful Authorization Response.¶

HTTP/1.1 302 Found
Location: https://client.example.net/cb?
    error=invalid_request
    &error_description=Unsupported%20response_type%20value

6.1. Token Request

Upon receiving a successful Authorization Response, a Token Request is made as defined in Section 4.1.3 of [RFC6749].¶

The following are the extension parameters to the Token Request used in a Pre-Authorized Code Flow:¶

• pre-authorized_code: The code representing the authorization to obtain Credentials of a certain type. This parameter MUST be present if the grant_type is urn:ietf:params:oauth:grant-type:pre-authorized_code.¶
• user_pin: OPTIONAL. String value containing a user PIN. This value MUST be present if user_pin_required was set to true in the Credential Offer. The string value MUST consist of a maximum of eight numeric characters (the numbers 0 - 9). This parameter MUST only be used if the grant_type is urn:ietf:params:oauth:grant-type:pre-authorized_code.¶

Requirements around how the Wallet identifies and, if applicable, authenticates itself with the Authorization Server in the Token Request depends on the Client type defined in Section 2.1 of [RFC6749] and the Client authentication method indicated in the token_endpoint_auth_method Client metadata. The requirement as described in Sections 4.1.3 and 3.2.1 of [RFC6749] MUST be followed.¶

For the Pre-Authorized Code Grant Type, authentication of the client is OPTIONAL, as described in Section 3.2.1 of OAuth 2.0 [RFC6749], and, consequently, the client_id parameter is only needed when a form of Client Authentication that relies on this parameter is used.¶

If the Token Request contains an authorization_details parameter of type openid_credential and the Credential Issuer's metadata contains an authorization_server parameter, the authorization_details object MUST contain the Credential Issuer's identifier in the locations element.¶

If the Token Request contains a scope value related to credential issuance and the Credential Issuer's metadata contains an authorization_server parameter, it is RECOMMENDED to use a resource parameter [RFC8707] whose value is the Credential Issuer's identifier value to allow the AS to differentiate Credential Issuers.¶

When Pre-Authorized Grant Type is used, it is RECOMMENDED that the Credential Issuer issues an Access Token valid only for the Credentials indicated in the Credential Offer (see Section 4.1). The Wallet SHOULD obtain a separate Access Token if it wants to request issuance of any of the Credentials that were not included in the Credential Offer, but were discoverable from the Credential Issuer's credentials_supported metadata parameter.¶

Below is a non-normative example of a Token Request in an Authorization Code Flow:¶

POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
&redirect_uri=https%3A%2F%2FWallet.example.org%2Fcb

Below is a non-normative example of a Token Request in a Pre-Authorized Code Flow (without Client Authentication):¶

POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:pre-authorized_code
&pre-authorized_code=SplxlOBeZQQYbYS6WxSbIA
&user_pin=493536

6.2. Successful Token Response

Token Responses are made as defined in [RFC6749].¶

In addition to the response parameters defined in [RFC6749], the AS MAY return the following parameters:¶

• c_nonce: OPTIONAL. JSON string containing a nonce to be used to create a proof of possession of key material when requesting a Credential (see Section 7.2). When received, the Wallet MUST use this nonce value for its subsequent Credential Requests until the Credential Issuer provides a fresh nonce.¶
• c_nonce_expires_in: OPTIONAL. JSON integer denoting the lifetime in seconds of the c_nonce.¶

Below is a non-normative example of a Token Response:¶

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

  {
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6Ikp..sHQ",
    "token_type": "bearer",
    "expires_in": 86400,
    "c_nonce": "tZignsnFbp",
    "c_nonce_expires_in": 86400
  }

6.3. Token Error Response

If the Token Request is invalid or unauthorized, the Authorization Server constructs the error response as defined as in Section 5.2 of OAuth 2.0 [RFC6749].¶

The following additional clarifications are provided for some of the error codes already defined in [RFC6749]:¶

invalid_request:¶

• The Authorization Server does not expect a PIN in the Pre-Authorized Code Flow but the client provides a PIN.¶
• The Authorization Server expects a PIN in the Pre-Authorized Code Flow but the client does not provide a PIN.¶

invalid_grant:¶

• The Authorization Server expects a PIN in the Pre-Authorized Code Flow but the client provides the wrong PIN.¶
• The End-User provides the wrong Pre-Authorized Code or the Pre-Authorized Code has expired.¶

invalid_client:¶

• The client tried to send a Token Request with a Pre-Authorized Code without Client ID but the Authorization Server does not support anonymous access.¶

Below is a non-normative example Token Error Response:¶

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store

{
   "error": "invalid_request"
}

This specification also uses the error codes authorization_pending and slow_down as defined in [RFC8628] for the Pre-Authorized Code grant type.¶

authorization_pending:¶

• This error code is used if the Authorization Server is waiting for an End-User interaction or downstream process to complete. The Wallet SHOULD repeat the access token request to the token endpoint (a process known as polling). Before each new request, the Wallet MUST wait at least the number of seconds specified by the interval claim of the Credential Offer (see Section 4.1.1) or the authorization response (see Section 5.2), or 5 seconds if none was provided, and respect any increase in the polling interval required by the "slow_down" error.¶

slow_down:¶

• A variant of authorization_pending error code, the authorization request is still pending and polling should continue, but the interval MUST be increased by 5 seconds for this and all subsequent requests.¶

7.1. Binding the Issued Credential to the Identifier of the End-User Possessing that Credential

Issued Credential SHOULD be cryptographically bound to the identifier of the End-User who possesses the Credential. Cryptographic binding allows the Verifier to verify during the presentation of a Credential that the End-User presenting a Credential is the same End-User to whom that Credential was issued. For non-cryptographic type of binding and Credentials issued without any binding, see Implementation Considerations in Section 12.1 and Section 12.2.¶

Note: Claims in the Credential are usually about the End-User who possesses it, but can be about another entity.¶

For cryptographic binding, the Client has the following options to provide cryptographic binding material for a requested Credential as defined in Section 7.2:¶

1. Provide proof of control alongside key material (proof that includes sub_jwk or did)¶
2. Provide only proof of control without the key material (proof that does not include sub_jwk or did)¶

7.2. Credential Request

A Client makes a Credential Request to the Credential Endpoint by sending the following parameters in the entity-body of an HTTP POST request using the application/json media type.¶

• format: REQUIRED. Format of the Credential to be issued. This Credential format identifier determines further parameters required to determine the type and (optionally) the content of the credential to be issued. Credential Format Profiles consisting of the Credential format specific set of parameters are defined in Appendix E.¶

• proof: OPTIONAL. JSON object containing proof of possession of the key material the issued Credential shall be bound to. The proof object MUST contain a following claim:¶

  • proof_type: REQUIRED. JSON string denoting the key proof type. The value of this claim determines other claims in the key proof object and its respective processing rules. Key proof types defined in this specification can be found in Section 7.2.1.¶
• credential_encryption_jwk: OPTIONAL. A JSON object containing a single public key as a JWK used for encrypting the Credential Response.¶
• credential_response_encryption_alg: OPTIONAL. JWE [RFC7516] alg algorithm [RFC7518] REQUIRED for encrypting Credential and/or Batch Credential Responses. The default, if omitted, is that no encryption is performed. If credential_response_encryption_alg is present, credential_encryption_jwk MUST be present.¶
• credential_response_encryption_enc: OPTIONAL. JWE [RFC7516] enc algorithm [RFC7518] REQUIRED for encrypting Credential Responses. If credential_response_encryption_alg is specified, the default for this value is A256GCM. When credential_response_encryption_enc is included, credential_response_encryption_alg MUST also be provided.¶

The proof_type claim is an extension point that enables the use of different types of proofs for different cryptographic schemes.¶

The proof element MUST incorporate the Credential Issuer Identifier (audience), and 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 is conveyed in the nonce claims 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.¶

Initial c_nonce value can be returned in a successful Token Response as defined in Section 6.2, in a Credential Error Response as defined in Section 7.3.2, or in a Batch Credential Error Response as defined in Section 8.3.¶

Below is a non-normative example of a Credential Request for a credential in JWT VC format (JSON encoding) with a key proof type jwt:¶

POST /credential HTTP/1.1
Host: server.example.com
Content-Type: application/json
Authorization: BEARER czZCaGRSa3F0MzpnWDFmQmF0M2JW

{
   "format": "jwt_vc_json",
   "credential_definition": {
    "type": [
        "VerifiableCredential",
        "UniversityDegreeCredential"
    ]
   },
   "proof": {
      "proof_type": "jwt",
      "jwt": "eyJraWQiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEva2V5cy8
      xIiwiYWxnIjoiRVMyNTYiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJzNkJoZFJrcXQzIiwiYXVkIjoiaHR
      0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJpYXQiOjE1MzY5NTk5NTksIm5vbmNlIjoidFppZ25zbk
      ZicCJ9.ewdkIkPV50iOeBUqMXCC_aZKPxgihac0aW9EkL1nOzM"
   }
}

The Client MAY request encrypted responses by providing its encryption parameters in the Credential Request.

The Credential Issuer MAY require encrypted responses by including `require_credential_response_encryption` in the Credntial Issuer Metadata.

{
  "proof_type": "jwt",
  "jwt": "eyJraWQiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEva2V5cy8
  xIiwiYWxnIjoiRVMyNTYiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJzNkJoZFJrcXQzIiwiYXVkIjoiaHR
  0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJpYXQiOjE1MzY5NTk5NTksIm5vbmNlIjoidFppZ25zbk
  ZicCJ9.ewdkIkPV50iOeBUqMXCC_aZKPxgihac0aW9EkL1nOzM"
  }

{
  "alg": "ES256",
  "kid": "did:example:ebfeb1f712ebc6f1c276e12ec21/keys/1"
}.
{
  "iss": "s6BhdRkqt3",
  "aud": "https://server.example.com",
  "iat": 1659145924,
  "nonce": "tZignsnFbp"
}

{
  "alg": "ES256",
  "x5c": [<key certificate + certificate chain for attestation>]
}.
{
  "iss": "s6BhdRkqt3",
  "aud": "https://server.example.com",
  "iat": 1659145924,
  "nonce": "tZignsnFbp"
}

7.3. Credential Response

Credential Response can be immediate or deferred. The Credential Issuer MAY be able to immediately issue a requested Credential and send it to the Client.¶

In other cases, the Credential Issuer MAY NOT be able to immediately issue a requested Credential and would want to send a transaction_id parameter to the Client to be used later to receive a Credential when it is ready. The HTTP status code MUST be 202 (section 10.2.3 of [RFC2616]).¶

If the Client requested encrypted responses, the Credential Issuer MUST encode the claims in the Credential Reponse as a JWT with credential_response_encryption_alg and credential_response_encryption_enc. The JWT MUST be encrypted to the public key specified by credential_encryption_jwk in the Credential Request. If the Credential Response is encrypted, the media type of the reponse MUST bet set to application/jwt. If encryption was negotiated in the Credential Request and the Credential Response is not encrypted, the Client SHOULD reject the Credential Response.¶

If the Credential Response is not encrypted, the media type of the response MUST be set to application/json.¶

The following claims are used in the Credential Response:¶

• format: REQUIRED. JSON string denoting the format of the issued Credential.¶
• credential: OPTIONAL. Contains issued Credential. MUST be present when transaction_id is not returned. MAY be a JSON string or a JSON object, depending on the Credential format. See Appendix E for the Credential format specific encoding requirements.¶
• transaction_id: OPTIONAL. A JSON string identifying a Deferred Issuance transaction. This claim is contained in the response if the Credential Issuer was unable to immediately issue the credential. The value is subsequently used to obtain the respective Credential with the Deferred Credential Endpoint (see Section 9). It MUST be present when the credential parameter is not returned. It MUST be invalidated after the credential for which it was meant has been obtained by the Wallet.¶
• c_nonce: OPTIONAL. JSON string containing a nonce to be used to create a proof of possession of key material when requesting a Credential (see Section 7.2). When received, the Wallet MUST use this nonce value for its subsequent credential requests until the Credential Issuer provides a fresh nonce.¶
• c_nonce_expires_in: OPTIONAL. JSON integer denoting the lifetime in seconds of the c_nonce.¶

The format Claim determines the Credential format and encoding of the credential in the Credential Response. Details are defined in the Credential Format Profiles in Appendix E.¶

Credential formats expressed as binary data MUST be base64url-encoded and returned as a JSON string.¶

Below is a non-normative example of a Credential Response in an immediate issuance flow for a credential in JWT VC format (JSON encoded):¶

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "format": "jwt_vc_json",
  "credential": "LUpixVCWJk0eOt4CXQe1NXK....WZwmhmn9OQp6YxX0a2L",
  "c_nonce": "fGFF7UkhLa",
  "c_nonce_expires_in": 86400
}

Below is a non-normative example of a Credential Response in a deferred flow:¶

HTTP/1.1 202 Accepted
Content-Type: application/json
Cache-Control: no-store

{
  "transaction_id": "8xLOxBtZp8",
  "c_nonce": "wlbQc6pCJp",
  "c_nonce_expires_in": 86400
}

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store

{
   "error": "invalid_request"
}

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store

{
  "error": "invalid_proof"
  "error_description":
       "Credential Issuer requires key proof to be bound to a Credential Issuer provided nonce.",
  "c_nonce": "8YE9hCnyV2",
  "c_nonce_expires_in": 86400
}

8.1. Batch Credential Request

The Batch Credential Endpoint allows a client to send multiple Credential Request objects (see Section 7.2) to request the issuance of multiple credential at once. Batch Credential Request MUST be sent using the application/json media type.¶

The following claims are used in the Batch Credential Request:¶

• credential_requests: REQUIRED. JSON array that contains Credential Request objects as defined in Section 7.2.¶

Below is a non-normative example of a Batch Credential Request:¶

POST /batch_credential HTTP/1.1
Host: server.example.com
Content-Type: application/json
Authorization: BEARER czZCaGRSa3F0MzpnWDFmQmF0M2JW

{
   "credential_requests":[
      {
         "format":"jwt_vc_json",
         "credential_definition": {
           "type":[
             "VerifiableCredential",
             "UniversityDegreeCredential"
           ]
         },
         "proof":{
            "proof_type":"jwt",
            "jwt":"eyJraWQiOiJkaWQ6ZXhhbXBsZTpl...C_aZKPxgihac0aW9EkL1nOzM"
         }
      },
      {
         "format":"mso_mdoc",
         "doctype":"org.iso.18013.5.1.mDL",
         "proof":{
            "proof_type":"jwt",
            "jwt":"eyJraWQiOiJkaWQ6ZXhhbXBsZ...KPxgihac0aW9EkL1nOzM"
         }
      }
   ]
}

8.2. Batch Credential Response

A successful Batch Credential Response MUST contain all the requested credentials. The Batch Credential Response MUST be sent using the application/json media type.¶

The following claims are used in the Batch Credential Response:¶

• credential_responses: REQUIRED. JSON array that contains Credential Response objects as defined in Section 7.2 and/or Deferred Credential Response objects as defined in Section 9.1. Every entry of the array corresponds to the Credential Request object at the same array index in the credential_requests parameter of the Batch Credential Request.¶
• c_nonce: OPTIONAL. The c_nonce as defined in Section 7.3.¶
• c_nonce_expires_in: OPTIONAL. The c_nonce_expires_in as defined in Section 7.3.¶

Below is a non-normative example of a Batch Credential Response in an immediate issuance flow:¶

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "credential_responses": [{
    "format": "jwt_vc_json",
    "credential": "eyJraWQiOiJkaWQ6ZXhhbXBsZTpl...C_aZKPxgihac0aW9EkL1nOzM"
  },
  {
    "format": "mso_mdoc",
    "credential": "YXNkZnNhZGZkamZqZGFza23....29tZTIzMjMyMzIzMjMy"
  }],
  "c_nonce": "fGFF7UkhLa",
  "c_nonce_expires_in": 86400
}

Below is a non-normative example of a Batch Credential Response that contains Credential Response and Deferred Credential Response objects:¶

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
   "credential_responses":[
      {
         "transaction_id":"8xLOxBtZp8"
      },
      {
         "format":"jwt_vc_json",
         "credential":"YXNkZnNhZGZkamZqZGFza23....29tZTIzMjMyMzIzMjMy"
      }
   ],
   "c_nonce":"fGFF7UkhLa",
   "c_nonce_expires_in":86400
}

8.3. Batch Credential Error Response

The Batch Credential Endpoint MUST respond with an HTTP 400 (Bad Request) status code in case of an error, unless specified otherwise.¶

Error codes extensions defined in Section 7.3.1 apply.¶

The Batch Credential Request MUST fail entirely if there is even one credential failed to be issued. transaction_id MUST NOT be returned in this case.¶

When the Credential Issuer requires proof objects to be present in the Batch Credential Request, but does not receive them, it will return a Batch Credential Error Response with a c_nonce using invalid_proof error code as defined in Section 7.3.2.¶

9.1. Deferred Credential Request

The Deferred Credential Request is an HTTP POST request. It MUST be sent using the application/json media type.¶

The following claims are used in the Batch Credential Response:¶

• transaction_id: REQUIRED. JSON String identifying a Deferred Issuance transaction.¶

Credential Issuer MUST invalidate transaction_id after the credential for which it was meant was obtained by the Wallet.¶

The following is a non-normative example of a Deferred Credential Request:¶

Host: server.example.com
Content-Type: application/json
Authorization: BEARER czZCaGRSa3F0MzpnWDFmQmF0M2JW

{
   "transaction_id":"8xLOxBtZp8"
}

9.2. Deferred Credential Response

The Deferred Credential Response uses the format and credential parameters as defined in Section 7.3.¶

Deferred Credential Response MUST be sent using the application/json media type.¶

9.3. Deferred Credential Error Response

When the Deferred Credential Request is invalid or unauthorized, or the credential is not available yet, the Credential Issuer constructs the error response as defined in this section.¶

The following additional clarifications are provided for the following parameters already defined in section 3.1 of [RFC6750]:¶

invalid_request:¶

• Credential Request was malformed, e.g., the parameter transaction_id is missing or malformed.¶

invalid_token:¶

• Credential Request contains the wrong Access Token or the Access Token is missing.¶

The following additional error codes are specified:¶

• issuance_pending - The credential issuance is still pending. The error response will also contain another claim interval determining the minimum amount of time in seconds that the Wallet SHOULD wait between requests to the Deferred Credential Endpoint. If no value is provided, clients MUST use 5 as the default.¶
• invalid_transaction_id - Deferred Credential Request contained an invalid transaction_id, i.e., it was not issued by the respective Credential Issuer or was already used to obtain the Credential.¶

This is a non-normative example of a Credential Error Response:¶

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store

{
   "error": "invalid_request"
}

10.1. Client Metadata

This specification defines the following new Client Metadata parameter in addition to [RFC7591] for Wallets acting as OAuth 2.0 client:¶

• credential_offer_endpoint: OPTIONAL. Credential Offer Endpoint of a Wallet.¶

10.2. Credential Issuer Metadata

{
    "format": "jwt_vc_json",
    "id": "UniversityDegree_JWT",
    "cryptographic_binding_methods_supported": [
        "did:example"
    ],
    "cryptographic_suites_supported": [
        "ES256K"
    ],
    "credential_definition":{
        "type": [
            "VerifiableCredential",
            "UniversityDegreeCredential"
        ],
        "credentialSubject": {
            "given_name": {
                "display": [
                    {
                        "name": "Given Name",
                        "locale": "en-US"
                    }
                ]
            },
            "family_name": {
                "display": [
                    {
                        "name": "Surname",
                        "locale": "en-US"
                    }
                ]
            },
            "degree": {},
            "gpa": {
                "display": [
                    {
                        "name": "GPA"
                    }
                ]
            }
        }
    },
    "proof_types_supported": [
        "jwt"
    ],
    "display": [
        {
            "name": "University Credential",
            "locale": "en-US",
            "logo": {
                "url": "https://exampleuniversity.com/public/logo.png",
                "alt_text": "a square logo of a university"
            },
            "background_color": "#12107c",
            "text_color": "#FFFFFF"
        }
    ]
}

10.3. OAuth 2.0 Authorization Server Metadata

This specification also defines a new OAuth 2.0 Authorization Server metadata [RFC8414] parameter to publish whether the AS that the Credential Issuer relies on for authorization supports anonymous Token Requests with the Pre-Authorized Grant Type. It is defined as follows:¶

• pre-authorized_grant_anonymous_access_supported: OPTIONAL. A JSON Boolean indicating whether the Credential Issuer accepts a Token Request with a Pre-Authorized Code but without a client id. The default is false.¶

11.1. Trust between Wallet and Issuer

Credential Issuers often want to know what Wallet they are issuing Credentials to and how private keys are managed for the following reasons:¶

• The Credential Issuer MAY want to ensure that private keys are properly protected from exfiltration and replay to prevent an adversary from impersonating the legitimate Credential holder by presenting her Credential.¶
• The Credential Issuer MAY also want to ensure that the Wallet managing the Credentials adheres to certain policies and, potentially, was audited and approved under a certain regulatory and/or commercial scheme.¶

The following mechanisms in concert can be utilized to fulfill those objectives:¶

Key attestation is a mechanism where the device or security element in a device asserts the key management policy to the application creating and using this key. The Android Operating System, for example, provides apps with a certificate including a certificate chain asserting that a particular key is managed, for example, by a hardware security module [ref]. The Wallet can provide this data along with the proof of possession in the Credential Request (see Section 7.2 for an example) to allow the Credential Issuer to validate the key management policy. This requires the Credential Issuer to rely on the trust anchor of the certificate chain and the respective key management policy. Another variant of this concept is the use of a Qualified Electronic Signature as defined by the eIDAS regulation [ref]. This signature will not reveal the properties of the associated private key to the Credential Issuer. However, as one example, due to the regulatory regime of eIDAS, the Credential Issuer can deduce that the signing service manages the private keys according to this regime and fulfills very high security requirements. As another example, FIDO2 allows RPs to obtain an attestation along with the public key from a FIDO authenticator. That implicitly asserts the key management policy since the assertion is bound to a certain authenticator model and its key management capabilities.¶

App Attestation: Key attestation, however, does not establish trust in the application storing the Credential and producing presentation of that Credential. App attestation as provided by mobile operating systems, e.g., iOS's DeviceCheck or Android's SafetyNet, allows a server system to ensure it is communicating to a legitimate instance of its genuine app. Those mechanisms can be utilized to validate the internal integrity of the Wallet (as a whole).¶

Device Attestation: Device Attestation attests the health of the device on which the Wallet is running, as a whole. It helps prevent compromises such as a malicious third-party application tampering with a Wallet that manages keys and Credentials, which cannot be captured only by obtaining app attestation of a Wallet.¶

Client Authentication allows a Wallet to authenticate with a Credential Issuer. To securely authenticate, the Wallet needs to utilize a backend component managing the key material and processing the secure communication with the Credential Issuer. The Credential Issuer MAY establish trust with the Wallet based on its own auditing or a trusted third-party attestation of the conformance of the Wallet to a certain policy.¶

Directly using key, app and/or device attestations to prove certain capabilities towards a Credential Issuer is an obvious option. However, this at least requires platform mechanisms that issue signed assertions that third parties can evaluate, which is not always the case (e.g., iOS's DeviceCheck). Also, such an approach creates dependencies on platform specific mechanisms, trust anchors, and platform specific identifiers (e.g., Android apkPackageName) and it reveals information about the internal design of a Wallet. Implementers should take these consequences into account.¶

The approach recommended by this specification is that the Credential Issuer relies on the OAuth 2.0 Client Authentication to establish trust in the Wallet and leaves it to the Wallet to ensure its internal integrity using app and key attestation (if required). This establishes a clean separation between the different components and a uniform interface irrespective of the Wallet's architecture (e.g., native vs. Web Wallet). Client Authentication can be performed with assertions registered with the Credential Issuer or with assertions issued to the Wallet by a third party the Credential Issuer trusts for the purpose of Client Authentication.¶

11.2. Credential Offer

The Wallet MUST consider the parameter values in the Credential Offer as not trustworthy since the origin is not authenticated and the message integrity is not protected. The Wallet MUST apply the same checks on the Credential Issuer that it would apply when the flow is started from the Wallet itself since the Credential Issuer is not trustworthy just because it sent the Credential Offer. An attacker might attempt to use a Credential Offer to conduct a phishing or injection attack.¶

The Wallet MUST NOT accept Credentials just because this mechanism was used. All protocol steps defined in this specification MUST be performed in the same way as if the Wallet would have started the flow.¶

The Credential Issuer MUST ensure the release of any privacy-sensitive data in Credential Offer is legally based.¶

11.3. Pre-Authorized Code Flow

11.4. Credential Lifecycle Management

The Credential Issuer is supposed to be responsible for the lifecycle of its Credentials. This means the Credential Issuer will invalidate Credentials when it deems appropriate, e.g., if it detects fraudulent behavior.¶

The Wallet is supposed to detect signs of fraudulent behavior related to the Credential management in the Wallet (e.g., device rooting) and to act upon such signals. Options include Credential revocation at the Credential Issuer and/or invalidation of the key material used to cryptographically bind the Credential to the identifier of the End-User possessing that Credential.¶

11.5. Key Proof replay

If an adversary is able to get hold of a key proof defined in Section 7.2.1, the adversary could get a Credential issued that is bound to a key pair controlled by the victim.¶

Note: For the attacker to be able to present to the Verifier a Credential bound to a replayed Key Proof, the attacker also needs to obtain the victim's private key. To limit this, servers are RECOMMENDED to check how the Wallet protects the private keys, using mechanisms such as Key Based Client Authentication defined in [I-D.looker-oauth-attestation-based-client-auth].¶

nonce parameter is the primary countermeasure against key proof replay. To further narrow down the attack vector, the Credential Issuer SHOULD bind a unique nonce parameter to the respective Access Token.¶

Note: To accommodate for clock offsets, the Credential Issuer server MAY accept proofs that carry an iat time in the reasonably near future (on the order of seconds or minutes). Because clock skews between servers and clients may be large, servers MAY limit key proof lifetimes by using server-provided nonce values containing the time at the server rather than comparing the client-supplied iat time to the time at the server. Nonces created in this way yield the same result even in the face of arbitrarily large clock skews.¶

Server-provided nonces are an effective means for further reducing the chances for successful key proof replay by an attacker. A Wallet can keep using a certain nonce until the Credential Issuer provides a fresh nonce. This way the Credential Issuer determines how often a certain nonce can be used. Servers MUST have a clear policy whether the same key proof can be presented multiple times and for how long, or whether each Credential Request MUST have a fresh key proof.¶

11.6. TLS Requirements

Implementations MUST follow [BCP195].¶

Whenever TLS is used, a TLS server certificate check MUST be performed, per [RFC6125].¶

12.1. Claim-based Binding of the Credential to the End-User possessing the Credential

Credentials not cryptographically bound to the identifier of the End-User possessing it (see Section 7.1), should be bound to the End-User possessing the Credential, based on the claims included in that Credential.¶

In claim-based binding, no cryptographic binding material is provided. Instead, the issued Credential includes user claims that can be used by the Verifier to verify possession of the Credential by requesting presentation of existing forms of physical or digital identification that includes the same claims (e.g., a driving license or other ID cards in person, or an online ID verification service).¶

12.2. Binding of the Credential without Cryptographic Binding or Claim-based Binding

Some Credential Issuers might choose to issue bearer Credentials without either cryptographic binding or claim-based binding, because they are meant to be presented without proof of possession.¶

One such use case is low assurance Credentials, such as coupons or tickets.¶

Another use case is when the Credential Issuer uses cryptographic schemes that can provide binding to the End-User possessing that Credential without explicit cryptographic material being supplied by the application used by that End-User. For example, in the case of the BBS Signature Scheme, the issued Credential itself is a secret and only derivation of a Credential is presented to the Verifier. Effectively, Credential is bound to the Credential Issuer's signature on the Credential, which becomes a shared secret transferred from the Credential Issuer to the End-User.¶

12.3. Multiple Accesses to the Credential Endpoint

The Credential Endpoint can be accessed multiple times by a Wallet using the same Access Token, even for the same Credential. The Credential Issuer determines if the subsequent successful requests will return the same or an updated Credential, such as having a new expiration time or using the most current End-User claims.¶

The Credential Issuer MAY also decide to no longer accept the Access Token and a re-authentication or Token Refresh (see [RFC6749], section 6) MAY be required at the Credential Issuer's discretion. The policies between the Credential Endpoint and the Authorization Server that MAY change the behavior of what is returned with a new Access Token are beyond the scope of this specification (see Section 7 of [RFC6749]).¶

The action leading to the Wallet performing another Credential Request can also be triggered by a background process, or by the Credential Issuer using an out-of-band mechanism (SMS, email, etc.) to inform the End-User.¶

12.4. Relationship between the Credential Issuer Identifier in the metadata and the Issuer Identifier in the Issued Credential

Credential Issuer Identifier is always a URL using the https scheme as defined in Section 10.2.1. Depending on the Credential format, the issuer identifier in the issued Credential may not be a URL using the https scheme. Some other forms that it can take are a DID included in the issuer property in a [VC_DATA] format, or the Subject value of the document signer certificate included in the x5chain element in a [ISO.18013-5] format.¶

When the Issuer identifier in the issued Credential is a DID, below is a non-exhaustive list of mechanisms the Credential Issuer MAY use to bind to the Credential Issuer Identifier:¶

1. Use the [DIF.Well-Known_DID] Specification to provide binding between a DID and a certain domain.¶
2. If the Issuer identifier in the issued Credential is an object, add to the object a credential_issuer claim, as defined in Section 10.2.1.¶

The Wallet MAY check the binding between the Credential Issuer Identifier and the Issuer identifier in the issued Credential.¶

12.5. Refreshing Issued Credentials

After a Verifiable Credential has been issued to the Holder, claim values about the subject of a Credential, or a signature on the Credential may need to be updated. There are two possible mechanisms to do so.¶

First, the Wallet may receive an updated version of a Credential from a Credential Endpoint or a Batch Credential Endpoint using a valid Access Token. This does not involve interaction with the End-User. If the Credential Issuer issued a Refresh Token to the Wallet, the Wallet would have to obtain a fresh Access Token by making a request to the Token Endpoint as defined in Section 6 of [RFC6749].¶

Second, the Credential Issuer can reissue the Credential by starting the issuance process from the beginning. This would involve interaction with the End-User. A Credential needs to be reissued if the Wallet does not have a valid Access Token or a valid Refresh Token. With this approach, when a new Credential is issued, the Wallet might need to check if it already has a Credential of the same type and, if necessary, delete the old Credential. Otherwise, the Wallet might end up with more than one Credential of the same type, without knowing which one is the latest.¶

Credential Refresh can be initiated by the Wallet independently from the Credential Issuer, or the Credential Issuer can send a signal to the Wallet asking it to request Credential refresh. How the Credential Issuer sends such a signal is out of scope for this specification.¶

It is up to the Credential Issuer whether to update both the signature and the claim values, or only the signature.¶

12.6. Protecting the Access Token

Access Tokens represent End-User authorization and consent to issue certain Credential(s). Long-lived Access Tokens giving access to credentials MUST not be issued unless sender-constrained. Access Tokens with lifetimes longer than 5 minutes are, in general, considered long lived.¶

To sender-constrain Access Tokens, see the recommendations in Section 4.10.1 in [I-D.ietf-oauth-security-topics]. If Bearer Access Tokens are stored by the Wallet, they MUST be stored in a secure manner, for example, encrypted using a key stored in a protected key store.¶

A.1. Sub-Namespace Registration

This section registers the value "urn:ietf:params:oauth:grant-type:pre-authorized_code" in the IANA "OAuth URI" registry established by "An IETF URN Sub-Namespace for OAuth" [RFC6755].¶

• URN: urn:ietf:params:oauth:grant-type:pre-authorized_code¶
• Common Name: Pre-Authorized Code¶
• Change Controller: AB/Connect Working Group - openid-specs-ab@lists.openid.net¶
• Specification Document: Section 6.1 of this document¶

A.2. Well-Known URI Registry

This specification registers the well-known URI defined in Section 10.2.2 in the IANA Well-Known URI registry defined in RFC 5785 [RFC5785].¶

• URI suffix: openid-credential-issuer¶
• Change controller: AB/Connect Working Group - openid-specs-ab@lists.openid.net¶
• Specification document: Section 10.2.2 of this document¶
• Related information: (none)¶

D.1. Credential Offer - Same-Device

While browsing the university's home page, the End-User finds a link "request your digital diploma". The user clicks on this link and is being redirected to a digital Wallet. The Wallet notifies the End-User that a Credential Issuer offered to issue a diploma Credential. User confirms this inquiry and is taken to the university's Credential issuance service's user experience. After authenticating at the university and consenting to the issuance of a digital diploma, the End-User is sent back to the Wallet, where she can check the successful creation of the digital diploma.¶

D.2. Credential Offer - Cross-Device (with Information Pre-Submitted by the End-User)

The End-User is starting a job at a new employer. An employer has requested the End-User to upload certain documents to the employee portal. A few days later, the End-User receives an email from the employer notifying her that the employee Credential is ready and asking her to scan a QR code to retrieve it. The End-User scans the QR code with her smartphone, which opens her Wallet. Meanwhile, the End-User has received a text message with a PIN code to her smartphone. After entering that PIN code in the Wallet for security reasons, the End-User confirms the Credential issuance, and receives Credential into the Wallet.¶

D.3. Credential Offer - Cross-Device & Deferred

The End-User wants to obtain a digital criminal record. She visits the local administration's office and requests the issuance of the official criminal record as a digital Credential. After presenting her ID document, she is asked to scan a QR code with her Wallet. She is being told that the actual issuance of the Credential will take some time due to necessary background checks by the authority.¶

In the Wallet, the End-User sees an indication that issuance of the digital record is under way. A few days later, the End-User receives a notification from her Wallet that requested Credential was successfully issued. When the End-User opens the Wallet, she is asked whether she wants to download the Credential. She confirms, and the new Credential is retrieved and stored in the Wallet.¶

D.4. Wallet Initiated Issuance during Presentation

An End-User comes across a verifier app that is requesting the End-User to present a Credential, e.g., a driving license. The Wallet determines the requested Credential type(s) from the presentation request and notifies the End-User that there is currently no matching Credential in the Wallet. The Wallet selects a Credential Issuer capable of issuing the lacking Credential and, upon user consent, sends the End-User to the Credential Issuer's user experience (Web site or app). Upon being authenticated and providing consent to issue the Credential into her Wallet, the End-User is sent back to the Wallet. The Wallet informs the End-User that Credential was successfully issued into the Wallet and is ready to be presented to the verifier app that originally requested presentation of that Credential.¶

D.5. Wallet Initiated Issuance during Presentation (Requires Presentation of Additional Credentials During Issuance)

An End-User comes across a verifier app that is requesting the End-User to present a Credential, e.g., a university diploma. The Wallet determines the requested Credential type(s) from the presentation request and notifies the End-User that there is currently no matching Credential in the Wallet. The Wallet then offers the End-User a list of Credential Issuers, which might be based on a Credential Issuer list curated by the Wallet provider. The End-User picks the university she graduated from and is sent to that university's user experience (Web site or app).¶

The End-User logs in to the university, which determines that the respective user account is not verified yet. Among multiple identification options, the End-User chooses to present a Credential from her Wallet. The End-User is sent back to the Wallet where she consents to present requested Credential(s) to the university. The End-User is sent back to the university user experience. Based on the presented Credential, the university completes the user verification, looks up user data in its database, and offers to issue a diploma as a Verifiable Credential.¶

Upon providing consent, the End-User is sent back to the Wallet. The Wallet informs the user Credential was successfully issued into the Wallet and is ready to be presented to the verifier app that originally requested presentation of that Credential.¶

E.1. W3C Verifiable Credentials

Sections 6.1 and 6.2 of [VC_DATA] define how Verifiable Credentials MAY or MAY NOT use JSON-LD. As acknowledged in Section 4.1 of [VC_DATA], implementations can behave differently regarding processing of the @context property whether JSON-LD is used or not.¶

This specification therefore differentiates the following three Credential formats for W3C Verifiable Credentials:¶

• VC signed as a JWT, not using JSON-LD (jwt_vc_json)¶
• VC signed as a JWT, using JSON-LD (jwt_vc_json-ld)¶
• VC secured using Data Integrity, using JSON-LD, with proof suite requiring Linked Data canonicalization (ldp_vc)¶

Note: VCs secured using Data Integrity MAY NOT necessarily use JSON-LD and MAY NOT necessarily use proof suites requiring Linked Data canonicalization. Credential Format Profiles for them may be defined in the future versions of this specification.¶

Distinct Credential format identifiers, extension parameters/claims, and processing rules are defined for each of the above-mentioned Credential formats.¶

It is on purpose that the Credential Offer does not contain credentialSubject property, while Authorization Details and Credential Request do. This is because this property is meant to be used by the Wallet to specify which claims it is requesting to be issued out of all the claims the Credential Issuer is capable of issuing for this particular Credential (data minimization), while Credential Offer is a mere "invitation" from the Credential Issuer to the Wallet to start the issuance flow.¶

{
    "format": "jwt_vc_json",
    "id": "UniversityDegree_JWT",
    "cryptographic_binding_methods_supported": [
        "did:example"
    ],
    "cryptographic_suites_supported": [
        "ES256K"
    ],
    "credential_definition":{
        "type": [
            "VerifiableCredential",
            "UniversityDegreeCredential"
        ],
        "credentialSubject": {
            "given_name": {
                "display": [
                    {
                        "name": "Given Name",
                        "locale": "en-US"
                    }
                ]
            },
            "family_name": {
                "display": [
                    {
                        "name": "Surname",
                        "locale": "en-US"
                    }
                ]
            },
            "degree": {},
            "gpa": {
                "display": [
                    {
                        "name": "GPA"
                    }
                ]
            }
        }
    },
    "proof_types_supported": [
        "jwt"
    ],
    "display": [
        {
            "name": "University Credential",
            "locale": "en-US",
            "logo": {
                "url": "https://exampleuniversity.com/public/logo.png",
                "alt_text": "a square logo of a university"
            },
            "background_color": "#12107c",
            "text_color": "#FFFFFF"
        }
    ]
}

{
    "credential_issuer": "https://credential-issuer.example.com",
    "credentials": [
        {
            "format": "jwt_vc_json",
            "credential_definition": {
                "type": [
                    "VerifiableCredential",
                    "UniversityDegreeCredential"
                ]
            }
        }
    ],
    "grants": {
        "authorization_code": {
            "issuer_state": "eyJhbGciOiJSU0Et...FYUaBy"
        }
    }
}

[
    {
        "type": "openid_credential",
        "format": "jwt_vc_json",
        "credential_definition": {
            "type": [
                "VerifiableCredential",
                "UniversityDegreeCredential"
            ],
            "credentialSubject": {
                "given_name": {},
                "family_name": {},
                "degree": {}
            }
        }
    }
]

{
   "format": "jwt_vc_json",
   "credential_definition": {
      "type": [
         "VerifiableCredential",
         "UniversityDegreeCredential"
      ],
      "credentialSubject": {
         "given_name": {},
         "family_name": {},
         "degree": {}
      }
   },
   "proof": {
      "proof_type": "jwt",
      "jwt":"eyJraWQiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEva2V5cy8
      xIiwiYWxnIjoiRVMyNTYiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJzNkJoZFJrcXQzIiwiYXVkIjoiaHR
      0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJpYXQiOiIyMDE4LTA5LTE0VDIxOjE5OjEwWiIsIm5vbm
      NlIjoidFppZ25zbkZicCJ9.ewdkIkPV50iOeBUqMXCC_aZKPxgihac0aW9EkL1nOzM"
   }
}

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
    "format": "jwt_vc_json",
    "credential": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2YyI6eyJAY29udGV4dCI
    6WyJodHRwczovL3d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSIsImh0dHBzOi8vd3d3Ln
    czLm9yZy8yMDE4L2NyZWRlbnRpYWxzL2V4YW1wbGVzL3YxIl0sImlkIjoiaHR0cDovL2V4YW1wb
    GUuZWR1L2NyZWRlbnRpYWxzLzM3MzIiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwi
    VW5pdmVyc2l0eURlZ3JlZUNyZWRlbnRpYWwiXSwiaXNzdWVyIjoiaHR0cHM6Ly9leGFtcGxlLmV
    kdS9pc3N1ZXJzLzU2NTA0OSIsImlzc3VhbmNlRGF0ZSI6IjIwMTAtMDEtMDFUMDA6MDA6MDBaIi
    wiY3JlZGVudGlhbFN1YmplY3QiOnsiaWQiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxY
    zI3NmUxMmVjMjEiLCJkZWdyZWUiOnsidHlwZSI6IkJhY2hlbG9yRGVncmVlIiwibmFtZSI6IkJh
    Y2hlbG9yIG9mIFNjaWVuY2UgYW5kIEFydHMifX19LCJpc3MiOiJodHRwczovL2V4YW1wbGUuZWR
    1L2lzc3VlcnMvNTY1MDQ5IiwibmJmIjoxMjYyMzA0MDAwLCJqdGkiOiJodHRwOi8vZXhhbXBsZS
    5lZHUvY3JlZGVudGlhbHMvMzczMiIsInN1YiI6ImRpZDpleGFtcGxlOmViZmViMWY3MTJlYmM2Z
    jFjMjc2ZTEyZWMyMSJ9.z5vgMTK1nfizNCg5N-niCOL3WUIAL7nXy-nGhDZYO_-PNGeE-0djCpW
    AMH8fD8eWSID5PfkPBYkx_dfLJnQ7NA",
    "c_nonce": "fGFF7UkhLa",
    "c_nonce_expires_in": 86400
}

{
    "format": "ldp_vc",
    "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://www.w3.org/2018/credentials/examples/v1"
    ],
    "type": [
        "VerifiableCredential",
        "UniversityDegreeCredential"
    ],
    "cryptographic_binding_methods_supported": [
        "did:example"
    ],
    "cryptographic_suites_supported": [
        "Ed25519Signature2018"
    ],
    "credentials_definition": {
        "@context": [
            "https://www.w3.org/2018/credentials/v1",
            "https://www.w3.org/2018/credentials/examples/v1"
        ],
        "type": [
            "VerifiableCredential",
            "UniversityDegreeCredential"
        ],
        "credentialSubject": {
            "given_name": {
                "display": [
                    {
                        "name": "Given Name",
                        "locale": "en-US"
                    }
                ]
            },
            "family_name": {
                "display": [
                    {
                        "name": "Surname",
                        "locale": "en-US"
                    }
                ]
            },
            "degree": {},
            "gpa": {
                "display": [
                    {
                        "name": "GPA"
                    }
                ]
            }
        }
    },
    "display": [
        {
            "name": "University Credential",
            "locale": "en-US",
            "logo": {
                "url": "https://exampleuniversity.com/public/logo.png",
                "alt_text": "a square logo of a university"
            },
            "background_color": "#12107c",
            "text_color": "#FFFFFF"
        }
    ]
}

{
    "credential_issuer": "https://credential-issuer.example.com",
    "credentials": [
        {
            "format": "ldp_vc",
            "credential_definition": {
                "@context": [
                    "https://www.w3.org/2018/credentials/v1",
                    "https://www.w3.org/2018/credentials/examples/v1"
                ],
                "type": [
                    "VerifiableCredential",
                    "UniversityDegreeCredential"
                ]
            }
        }
    ]
}

[
    {
        "type": "openid_credential",
        "format": "ldp_vc",
        "credential_definition": {
            "@context": [
                "https://www.w3.org/2018/credentials/v1",
                "https://www.w3.org/2018/credentials/examples/v1"
            ],
            "type": [
                "VerifiableCredential",
                "UniversityDegreeCredential"
            ],
            "credentialSubject": {
                "given_name": {},
                "family_name": {},
                "degree": {}
            }
        }
    }
]

{
   "format": "ldp_vc",
   "credential_definition": {
      "@context": [
         "https://www.w3.org/2018/credentials/v1",
         "https://www.w3.org/2018/credentials/examples/v1"
      ],
      "type": [
         "VerifiableCredential",
         "UniversityDegreeCredential"
      ],
      "credentialSubject": {
         "degree": {
            "type": {}
         }
      }
   },
   "proof": {
      "proof_type": "jwt",
      "jwt": "eyJraWQiOiJkaWQ6ZXhhbXBsZ...KPxgihac0aW9EkL1nOzM"
   }
}

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
    "format": "ldp_vc",
    "credential": {
        "@context": [
            "https://www.w3.org/2018/credentials/v1",
            "https://www.w3.org/2018/credentials/examples/v1"
        ],
        "id": "http://example.edu/credentials/3732",
        "type": [
            "VerifiableCredential",
            "UniversityDegreeCredential"
        ],
        "issuer": "https://example.edu/issuers/565049",
        "issuanceDate": "2010-01-01T00:00:00Z",
        "credentialSubject": {
            "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
            "degree": {
                "type": "BachelorDegree",
                "name": "Bachelor of Science and Arts"
            }
        },
        "proof": {
            "type": "Ed25519Signature2020",
            "created": "2022-02-25T14:58:43Z",
            "verificationMethod": "https://example.edu/issuers/565049#key-1",
            "proofPurpose": "assertionMethod",
            "proofValue": "zeEdUoM7m9cY8ZyTpey83yBKeBcmcvbyrEQzJ19rD2UXArU2U1jPGoEt
                           rRvGYppdiK37GU4NBeoPakxpWhAvsVSt"
        }
    },
    "c_nonce": "fGFF7UkhLa",
    "c_nonce_expires_in": 86400
}

E.2. ISO mDL

This section defines a Credential Format Profile for credentials complying with [ISO.18013-5].¶

{
    "format": "mso_mdoc",
    "doctype": "org.iso.18013.5.1.mDL",
    "cryptographic_binding_methods_supported": [
        "mso"
    ],
    "cryptographic_suites_supported": [
        "ES256", "ES384", "ES512"
    ],
    "display": [
        {
            "name": "Mobile Driving License",
            "locale": "en-US",
            "logo": {
                "url": "https://examplestate.com/public/mdl.png",
                "alt_text": "a square figure of a mobile driving license"
            },
            "background_color": "#12107c",
            "text_color": "#FFFFFF"
        },
        {
            "name": "在籍証明書",
            "locale": "ja-JP",
            "logo": {
                "url": "https://examplestate.com/public/mdl.png",
                "alt_text": "大学のロゴ"
            },
            "background_color": "#12107c",
            "text_color": "#FFFFFF"
        }
    ],
    "claims": {
        "org.iso.18013.5.1": {
            "given_name": {
                "display": [
                    {
                        "name": "Given Name",
                        "locale": "en-US"
                    },
                    {
                        "name": "名前",
                        "locale": "ja-JP"
                    }
                ]
            },
            "family_name": {
                "display": [
                    {
                        "name": "Surname",
                        "locale": "en-US"
                    }
                ]
            },
            "birth_date": {}
        },
        "org.iso.18013.5.1.aamva": {
            "organ_donor": {}
        }
    }
}

{
    "credential_issuer": "https://credential-issuer.example.com",
    "credentials": [
        {
            "format": "mso_mdoc",
            "doctype": "org.iso.18013.5.1.mDL"
        }
    ],
    "grants": {
        "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
            "pre-authorized_code": "adhjhdjajkdkhjhdj",
            "user_pin_required": true
        }
    }
}

[
    {
        "type": "openid_credential",
        "format": "mso_doc",
        "doctype": "org.iso.18013.5.1.mDL",
        "claims": {
            "org.iso.18013.5.1": {
                "given_name": {},
                "family_name": {},
                "birth_date": {}
            },
            "org.iso.18013.5.1.aamva": {
                "organ_donor": {}
            }
        }
    }
]

{
   "format": "mso_mdoc",
   "doctype": "org.iso.18013.5.1.mDL",
   "claims": {
      "org.iso.18013.5.1": {
         "given_name": {},
         "family_name": {},
         "birth_date": {}
      },
      "org.iso.18013.5.1.aamva": {
         "organ_donor": {}
      }
   },
   "proof": {
      "proof_type": "jwt",
      "jwt": "eyJraWQiOiJkaWQ6ZXhhbXBsZ...KPxgihac0aW9EkL1nOzM"
   }
}