OpenID Connect for Verifiable Credential Issuance

Table of Contents

1. Introduction

This specification defines an API designated as Credential Endpoint and corresponding OAuth-based authorization mechanisms for issuance of verifiable credentials, e.g., in the form of W3C Verifiable Credentials. This allows existing OAuth deployments and OpenID Connect OPs to extend their service and become credential issuers. It also allows new applications built using Verifiable Credentials to utilize OAuth and OpenID Connect as integration and interoperability layer.¶

OpenID Connect would be an obvious choice for this use case since it already allows Relying Parties to request identity assertions. However, early implementation experience suggests adoption is made easier if the base protocol only focuses on the credential issuance, without mandating certain [OpenID.Core] features, such as asserting a stable sub values. Thus the working group decided to use OAuth as a base protocol. Deployments can nevertheless provide a combined implementation of OpenID Connect and the Credential Endpoint since OpenID Connect is built on top of OAuth.¶

Verifiable Credentials are very similar to identity assertions in that they allow an Issuer to assert End-User claims. However, in contrast to the identity assertions, a verifiable credential follows a pre-defined schema (the credential type) and is bound to key material allowing the End-User to prove the legitimate possession of the credential. This allows direct presentation of the credential from the End-User to the RP, without involvement of the credential issuer. This specification caters for those differences.¶

2. Terminology

Credential¶

A set of one or more claims made by an issuer (see [VC_DATA]). Note that this definition differs from that in [OpenID.Core].¶

Verifiable Credential (VC)¶

A verifiable credential is a tamper-evident credential that has authorship that can be cryptographically verified. Verifiable credentials can be used to build verifiable presentations, which can also be cryptographically verified (see [VC_DATA]).¶

Presentation¶

Data derived from one or more verifiable credentials, issued by one or more issuers, that is shared with a specific verifier (see [VC_DATA]).¶

Verified Presentation (VP)¶

A verifiable presentation is a tamper-evident presentation encoded in such a way that authorship of the data can be trusted after a process of cryptographic verification. Certain types of verifiable presentations might contain data that is synthesized from, but do not contain, the original verifiable credentials (for example, zero-knowledge proofs) (see [VC_DATA]).¶

W3C Verifiable Credential Objects¶

Both verifiable credentials and verifiable presentations¶

Credential Manifests¶

A resource format that defines preconditional requirements, Issuer style preferences, and other facets User Agents utilize to help articulate and select the inputs necessary for processing and issuance of a specified credential (see [DIF.CredentialManifest]).¶

Deferred Credential Issuance¶

Issuance of credentials not directly in the response to a credential issuance request, but following a period of time that can be used to perform certain offline business processes.¶

3. Use Cases

4. Requirements

This section describes the requirements this specification aims to fulfill beyond the use cases described above.¶

• Proof of possession of key material¶

  • Support all kinds of proofs (e.g., signatures, blinded proofs) but also issuance w/o proof¶

  • The proof mechanisms shall be complementary to OAuth/OpenID Connect mechanisms for request signatures, client authentication, and PoP to allow for its parallel usage.¶

• It shall be possible to request a single credential as well to request multiple credentials in the same request. Examples of the latter include:¶

  • credentials containing different claims for the same user (micro/mono credentials) bound to the same key material¶

  • batch issuance of multiple credentials of the same type bound to different key material (see mDL)¶

• It shall be possible to issue multiple credentials based on same consent (e.g., different formats and/or keys - did:key followed by did:ebsi)¶

• Support for deferred issuance of credentials¶

• User authentication and identification¶

  • Issuer shall be able to dynamically obtain further data and be able to authenticate the user at their discretion¶

  • Application used by the End-User shall be able to pass existing credentials (as presentations) or identity assertions to the issuance flow¶

  • Assisted flow (utilizing credential manifest)¶

  • Presentations/assertions must be protected against replay¶

• It shall be possible to request standard OpenID Connect claims and credentials in the same flow (to implement wallet onboarding, see EBSI/ESSIF onboarding)¶

• Support for Credential metadata (Application used by the End-User shall be able to determine the types of credentials an issuer is able to issue)¶

• Ensure OAuth 2.0 Authorization Server is authoritative for respective credential issuer (OP (OpenID Connect issuer URL) <-> Issuer ID (DID))¶

• Incorporate/utilize existing specs¶

  • W3C VC HTTP API(?)¶

  • DIF Credential manifest(?)¶

5. Overview

This specification defines the following mechanisms to allow wallet applications (acting as OAuth and Credential Issuance API clients) used by the End-User to request credential issuers (acting as OAuth Authorization Servers and Credential Issuance API providers) to issue Verifiable Credentials via the Credential Issuance API:¶

• An optional mechanism to pre-obtain a Credential Manifest¶

• An extended authorization request syntax that allows to request credential types to be issued¶

• Ability to bind an issued credential to a proof submitted by the Client¶

• A newly defined Credential Endpoint from which credentials can be issued one at a time¶

• A mechanism that allows issuance of multiple credentials of same or different type (c_nonce)¶

• A mechanism for the Deferred Credential Issuance (acceptance_token)¶

The following figure shows the overall flow.¶

+--------------+   +-----------+                                         +-------------+
| User         |   |   Wallet  |                                         |   Issuer    |
+--------------+   +-----------+                                         +-------------+
        |                |             interact                                 |
        |---------------------------------------------------------------------->|
        |                |          (1) initiate issuance                       |
        |                |<-----------------------------------------------------|
        |    interacts   |                                                      |
        |--------------->|                                                      |
        |                |  (2) [opt] obtain credential manifest                |
        |                |----------------------------------------------------->|
        |                |              credential manifest                     |
        |                |<-----------------------------------------------------|
        |                |                                                      |
        |                |  (4) authorization req (claims, [opt] input, etc. )  |
        |                |----------------------------------------------------->|
        |                |                                                      |
        |     (4.1) User Login                                                  |
        |                |                                                      |
        |                |  (4.2) [opt] request additional VCs (OIDC4VP)        |
        |                |<-----------------------------------------------------|
        |                |                                                      |
    (4.2.1) [opt] User selects credentials                                      |
        |                |                                                      |
        |                |  (4.2.2) VCs in Verifiable Presentations             |
        |                |----------------------------------------------------->|
        |                |                                                      |
        |   (4.3) User consents to credential issuance                          |
        |                |                                                      |
        |                |  (5) authorization res (code)                        |
        |                |<-----------------------------------------------------|
        |                |                                                      |
        |                |  (6) token req (code)                                |
        |                |----------------------------------------------------->|
        |                |      access_token, id_token                          |
        |                |<-----------------------------------------------------|
        |                |                                                      |
        |                |  (7) credential req (access_token, proofs, ...)      |
        |                |----------------------------------------------------->|
        |                |      credential req (credentials OR acceptance_token)|
        |                |<-----------------------------------------------------|
        |                |                                                      |
        |                |  (8) [opt] poll_credentials (acceptance_token)       |
        |                |----------------------------------------------------->|
        |                |      credentials OR not_ready_yet                    |
        |                |<-----------------------------------------------------|

This flow is based on OAuth and the code grant type. Use with other grant types, such as CIBA, will be possible as well.¶

The starting point is an interaction of the user with her wallet. The user might, for example,¶

• want to present a credential and found out there is no suitable credential present in her wallet or¶

• have visited the web site of a Credential Issuer and wants to obtain a credential from that issuer.¶

(1) (OPTIONAL) The issuer sends a request to the wallet to initiate the issuance flow. This request contains information about the credential(s) the End-User wants to obtain from that issuer, e.g., in the form of credential manifest IDs or credential types, and further data, e.g., hints about the user when the user is already logged in with the Issuer.¶

(2) (OPTIONAL) obtain credential manifest (as defined in [DIF.CredentialManifest]) from the issuer with an information of which Verifiable Credentials the Issuer can issue, and optionally what kind of input from the user the Issuer requires to issue that credential.¶

Note: The wallet MAY also obtain the information about the credential issuer's capabilities using other means, which is out of scope of this specification.¶

(4) In this step, the wallet sends an authorization request to the issuer. This request determines the types of verifiable credentials the wallet (on behalf of the user) wants to obtain.¶

The wallet SHOULD use a pushed authorization request (see [RFC9126]) to first send the payload of the authorization request to the issuer and subsequently use the request_uri returned by the issuer in the authorization request. This ensures integrity and confidentiality of the request data and prevents any issues raised by URL length restrictions regarding the authorization request URL.¶

Note: Signed and encrypted request objects would also ensure integrity and confidentiality. However, this approach would further increase the URL size, which might decrease robustness of the process.¶

The issuer takes over user interface control at this point and interacts with the user. The implementation of this step is at the discretion of the issuer.¶

(4.1) The issuer will typically authenticate the user in the first step of this process. For this purpose, the issuer might use a local or federated login, potentially informed by an id_token_hint (see [OpenID.Core]).¶

(4.2) (OPTIONAL) The issuers MAY call back to the wallet to fetch verifiable credentials it needs as prerequisite to issuing the requested credentials. The decision of what credentials are requested may depend on the user identity determined in step 4.1.¶

From a protocol perspective, the issuers acts now as verifier and sends a request as defined in OpenID Connect for Verifiable Presentations [OIDC4VP] to the wallet.¶

(4.2.1) (CONDITIONAL) The wallet shows the content of the presentation request to the user. The user selects the appropriate credentials and consents.¶

(4.2.2) (CONDITIONAL) The wallet responds with one or more verifiable presentations to the issuer.¶

(4.3) The issuer asks the user for consent to issue the requested credentials.¶

(5) The issuer responds with an authorization code to the wallet.¶

(6) The wallet exchanges the authorization code for an Access Token and an ID Token.¶

(7) This Access Token is used to request the issuance of the actual credentials. The types of credentials the wallet can request is limited to the types approved in the authorization request in (5). The credential request passes the key material the respective credential shall be bound to. If required by the issuer, the wallet also passes a proof of possession for the key material. This proof of possession uses the SHA-256 hash of the Access Token as cryptographic nonce. This ensures replay protection of the proofs. The format of key material and proof of possession depends upon the proof scheme and is expressed in a polymorphic manner at the protocol level.¶

The Issuer will either directly respond with the credentials or issue an Acceptance Token, which is used by the wallet to poll for completion of the issuance process.¶

(8) (OPTIONAL) The wallet polls the issuer to obtain the credentials previously requested in step (6). The issuer either responds with the credentials or HTTP status code "202" indicating that the issuance is not completed yet.¶

Note: If the issuer just wants to offer the user to retrieve a pre-existing credential, it can encode the parameter set of step (6) in a suitable representation and allow the wallet to start with step (6). One option would be to encode the data into a QR Code.¶

6. Endpoints

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

 {
   "issuer":"https://server.example.com",
   "authorization_endpoint":"https://server.example.com/connect/authorize",
   "token_endpoint":"https://server.example.com/connect/token",
   ...
   "credential_manifests":[
      {
         "id":"WA-DL-CLASS-A",
         "version":"0.1.0",
         "issuer":{
            "id":"did:example:123?linked-domains=3",
            "name":"Washington State Government"
          },
         "output_descriptors":[
            {
               "schema":"http://washington-state-schemas.org/1.0.0/driver-license.json",
               "id": "output descriptor 1"
            }
         ],
         "presentation_definition":{}
     }
   ]
  }

  GET /initiate_issuance?
    issuer=https%3A%2F%2Fserver%2Eexample%2Ecom
    &credential_type=https%3A%2F%2Fdid%2Eexample%2Eorg%2FhealthCard
    &op_state=eyJhbGciOiJSU0Et...FYUaBy

{
   "type":"openid_credential",
   "credential_type":"https://did.example.org/healthCard",
   "format":"ldp_vc"
}

HTTP/1.1 302 Found
Location: https://server.example.com/authorize?
  response_type=code
  &client_id=s6BhdRkqt3
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &authorization_details=%5B%7B%22type%22:%22openid_credential%22,%22credential_type
  %22:%22https://did.example.org/healthCard%22,%22format%22:%22ldp_vc%22%7D,%7B%22ty
  pe%22:%22openid_credential%22,%22credential_type%22:%22https://did.example.org/mDL
  %22%7D%5D
  &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb

[
   {
      "type":"openid_credential",
      "credential_type":"https://did.example.org/healthCard",
      "format":"ldp_vc"
   },
   {
      "type":"openid_credential",
      "credential_type":"https://did.example.org/mDL"
   }
]

HTTP/1.1 302 Found
Location: https://server.example.com/authorize?
  response_type=code
  &client_id=s6BhdRkqt3
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &scope=openid%20email
  &authorization_details=%5B%7B%22type%22:%22openid_credential%...7D%5D
  &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb

openid_credential:<credential-type>

HTTP/1.1 302 Found
Location: https://server.example.com/authorize?
  response_type=code
  &scope=openid_credential:healthCard
  &client_id=s6BhdRkqt3
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb

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=...

{
   "type":"openid_credential",
   "manifest_id":"WA-DL-CLASS-A",
   "format":"jwt_vc"
}

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

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

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

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

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

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
   "error": "invalid_request"
}

{
  "proof_type": "jwt",
  "jwt": "eyJraWQiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEva2V5cy8
  xIiwiYWxnIjoiRVMyNTYiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJzNkJoZFJrcXQzIiwiYXVkIjoiaHR
  0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJpYXQiOiIyMDE4LTA5LTE0VDIxOjE5OjEwWiIsIm5vbm
  NlIjoidFppZ25zbkZicCJ9.ewdkIkPV50iOeBUqMXCC_aZKPxgihac0aW9EkL1nOzM"
}

{
  "alg": "ES256",
  "typ": "JWT",
  "kid":"did:example:ebfeb1f712ebc6f1c276e12ec21/keys/1"
}.
{
  "iss": "s6BhdRkqt3",
  "aud": "https://server.example.com",
  "iat": "2018-09-14T21:19:10Z",
  "nonce": "tZignsnFbp"
}

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

type=https%3A%2F%2Fdid%2Eexample%2Eorg%2FhealthCard
format=ldp%5Fvc
did=did%3Aexample%3Aebfeb1f712ebc6f1c276e12ec21
proof=%7B%22type%22:%22...-ace0-9c5210e16c32%22%7D

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

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

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

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

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

{
  "error": "invalid_or_missing_proof"
  "error_description":
       "Credential issuer requires proof element in credential request"
  "c_nonce": "8YE9hCnyV2",
  "c_nonce_expires_in": 86400
}

POST /credential_deferred HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: BEARER 8xLOxBtZp8

7. Pre-Authorized Code Flow

This section specifies an additional flow to obtain an access token for credential issuance. It is intended to support scenarios where the user starts a process on an issuer's website that ultimately results in one or more credentials being issued to the user's wallet. The process on the issuer's website may include uploading documents and presenting verifiable credentials to the issuer. Moreover, the End-user may be accessing the issuer's website on a device different from the one with the wallet application so the credential issuance process needs to be transfered to another device where the user's wallet resides.¶

In contrast to the flow specified in Section 6, this flows is initiated by the Issuer when the credentials are "ready" and need to be "picked up" by the wallet application. How the user provides information required for the issuance of a requested credential to the Issuer and the business processes conducted by the Issuer to issue a credential are out of scope of this specification.¶

1. To initiate the flow, the Issuer needs to communicates to the wallet two parameters: the pre-authorized code and the credential type the code is valid for. The Issuer can send them in two different ways. Either the issuer sends them in an issuance initiation request to the Issuance Initiation Endpoint of the wallet as described in Section 6.4.1. Or the issuer renders a QR code containing the issuance initiation request with these parameters. In this case, the user scans the QR code with her wallet on a different device in order to proceed.¶

2. When initiating the flow, the Issuer also indicates if the PIN is required. If it is, sends PIN to the wallet using a channel different from an issuance initiation request.¶

3. The wallet sends the pre-authorized code to the issuer's Token Endpoint. This request MUST contain a user PIN if requested by the issuer.¶

4. The issuer responds with an access token valid for credential issuance.¶

5. The wallet sends a credential issuance request to the credential endpoint as defined in Section 6.7.2 using the credential type as indicated in the first step from the issuer to the wallet.¶

6. The issuer returns the requested credential as defined in Section 6.7.3.¶

Steps 1 through 3 constitute a new kind of pre-authorized code flow that is implemented using an additional initiate issuance endpoint and a new OAuth grant type "urn:ietf:params:oauth:grant-type:pre-authorized_code". Steps 4 through 6 conform to the process specified in Section 6.¶

Note that the pre-authorized code is sent to the Token Endpoint and not to the Authorization Endpoint of the Issuer.¶

The following sections specify the extensions of a pre-authorized code flow.¶

  GET /initiate_issuance?
    issuer=https%3A%2F%2Fserver%2Eexample%2Ecom
    &credential_type=https%3A%2F%2Fdid%2Eexample%2Eorg%2FhealthCard
    &pre-authorized_code=SplxlOBeZQQYbYS6WxSbIA

openid_initiate_issuance://?
    issuer=https%3A%2F%2Fserver%2Eexample%2Ecom
    &credential_type=https%3A%2F%2Fdid%2Eexample%2Eorg%2FhealthCard
    &pre-authorized_code=SplxlOBeZQQYbYS6WxSbIA
    &user_pin_required=true

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

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

8. Security Considerations

9. Implementation Considerations

10. Privacy Considerations

TBD¶

Appendix A. IANA Considerations

register "urn:ietf:params:oauth:grant-type:pre-authorized_code"¶

Appendix B. Acknowledgements

We would like to thank David Chadwick, John Bradley, Alen Horvat, Michael B. Jones, and David Waite for their valuable contributions to this specification.¶

Appendix C. Notices

Copyright (c) 2022 The OpenID Foundation.¶

The OpenID Foundation (OIDF) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft or Final Specification solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts and Final Specifications based on such documents, provided that attribution be made to the OIDF as the source of the material, but that such attribution does not indicate an endorsement by the OIDF.¶

The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this specification make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The OpenID Intellectual Property Rights policy requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. The OpenID Foundation invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that may cover technology that may be required to practice this specification.¶

Appendix D. Document History

[[ To be removed from the final specification ]]¶

-05¶

• added support for pre-authorized code flow¶

• changed base protocol to OAuth¶

-04¶

• added support for requesting credential authorization with scopes¶

• removed support to pass VPs in the authorization request¶

• reworked "proof" parameter definition and added "jwt" proof type¶

-03¶

• added issuance initiation endpoint¶

• Applied cleanups suggested by Mike Jones post adoption¶

-02¶

• Adopted as WG document¶

-01¶

• Added Request & Response syntax and descriptions¶

• Reworked and extended sequence diagram¶

-00¶

• initial revision¶

Authors' Addresses