- Status: Notes
- JIRA: None
- Discussion: OpenID for Verifiable Credential Issuance #17616
NOTE: These are notes as mentioned in the "Status" field above and hence it is not set in stone if all the mentioned things will be implemented and/of if they are implemented exactly in a way mentioned here.
OpenID Verifiable Credential Issuance (OID4VC) has been discussed a lot in the Self-Soverin Identity (SSI) especially due to European Commission having released a Framework for eIDASv2. The later tends to chose OID4VC as a protocol to issue Verifiable Credential (VC) and to present Verifiable Presentation (VP).
For simplicity, Verifiable Credential (VC) is a token generally either JSON-LD / JWT format issued by OpenID Provider to the User whereas a Verifiable Presentation (VP) is a token presented by User to Relying Party for authentication and authorizations purposes. A VP can be the result of an aggregation of multiples VCs or simply a subset of attributes of a single VC. OID4VP and SIOPv2 have been introduced for the purposes of presenting Verifiable Presentation from USER to Relying Party.
Currently, they are many competing standards in the world of VC data formats:
We will be focussing on implementing the first format SD-JWT VC in this document.
This format build on top of the IETF Draft: Selective Disclosure for JWTs
This document outlines the design specifications for integrating OID4VC (including OID4VCI and OID4VP) into Keycloak. The implementation aims to ensure interoperability with the GAIN POC and the HAIP profile, while also incorporating additional features relevant to organizational use within Keycloak. This will be pursued as long as contributions are thoroughly reviewed and accepted by the Keycloak maintenance team.
The following table displays some competing initiatives, all implementing OID4VC. This table is managed by OIDF GAIN PoC working group at OID4VC Profiles. There is a attempt to define a baseline profile, that will be supported by all initiatives.
Keycloak being the largest SSO open source software, we want to use this initiative to secure implementation of OID4VC into Keycloak.
- there is an existing POC from FIWARE
We are calling for any other contribution out there.
The following map from Chris provides an OID4VC Breakdown of all the functionalities for each participant type in the verifiable credential world.
This part addresses the functionality associated with the issuer of a verifiable credential. Keycloak will play both the role of an authorization server and a credential issuer. All yellow cards are relevant for the first steps as outlined in Visuals. Cads with a red square are future or optional features.
In this first step, we will extend Keycloak to act as a VC Issuer. We will implement the following flows:
In the second step, we will equip keycloak with verifier functionality to fit into many federation use cases currently in use with Keycloak. To approach this second step, we will need a detailed design suggestion that outlines where to start, which includes new endpoints and the existing affected endpoints.
At the moment, it is not within the scope of Keycloak to operate as a web wallet, even though this seems like a natural extension of an identity provider. If use cases justify the integration of a web wallet functionality into Keycloak, the corresponding rationales and design suggestions will be added to this architectural document.
The issuance of verifiable presentation will generally be performed by edge wallets. We will be working on wallet prototypes to test and demo use cases implemented into keycloak.
For the implmentation of an interoperable OID4VC solution, we will be dealing with following technologies
All emerging SSI standards are including selective disclosure as a core feature to address privacy. Selective disclosure is an essential requirement in the eIDAS2.0 directive of the EU.
For the purpose of the work, SD-JWT VC defines a mechanism for selective disclosure of individual elements of a JSON object used as the payload of a JSON Web Signature (JWS) structure.
Index Sites
- A collection of implementations can be found in the IETF OAuth Working Group - SD-JWT.
- A couple of repositories at the open wallet foundation are also addressing the topic. We have no java implementation there yet.
Other Sites
- This waltid kotlin implementation was archived and is being redesigned
- This is a Java Implementation from Authlete.
ToDo: SD-JWT lib For the purpose of this work, we will have to decide on how to setup and implement (or select and use) an SD-JWT library that corelates with the governance model of keycloak components.
SD-JWT-based Verifiable Credentials describes data formats as well as validation and processing rules to express Verifiable Credentials with JSON payloads based on the Selective Disclosure for JWTs (SD-JWT)
Index Sites As for existing implementations, a pure context free implementation of SD-JWT VC is not to be found in public repositories.
ToDo: SD-JWT-VC lib For the purpose of this work, we will have to decide on how to setup and implement an SD-JWT-VC library that corelates with the governance model of keycloak components.
There is a lot of implementation out there with the VCDM credential format. But many technical implementation have run into complexity trying to implement selective disclosure on top of VCDM.
ToDo: VCDM Support In this work, we will have to discuss on wether VCDM is to be supported, and if yes, if the VCDM support will include any type of selective disclosure (annoncred, ...). We will also be discussing on the need to include this part and the existance of stake holders. For the time beeing, eIDAS2.0 is leading toward SD-JWT and ISO mDLs.
IDO mDL defines the technical specifications for implementing a driving licence on a mobile device. It's essentially a blueprint for creating "mobile driving licences" (mDLs) that function securely and consistently across different platforms.
This technology is being prototyped in many US states and is also included into the list of format supported by the eIDAS2.0 directive.
mDLs also provides selective disclosure.
Index Sites
- The Open Wallet Foundation - Identity Credential is a repository of Java libraries addressing different aspects of ISO mDLs.
Other Sites
- This Waltid kotlin implementation was archived and is being redesigned
- This is a Java Implementation from Authlete.
ToDo: SD-JWT lib For the purpose of this work, we will have to decide on how to setup and implement (or select and use) an mdoc library that corelates with the governance model of keycloak components.
Purpose
Digital signature is used in following area of the OID4VC:
- For Credential Issuance: An verifiable credential is allways signed by it issuer.
- For Credential Presentation, when key binding is included in the presented VC.
SD-JWT-VC and/or mDLs
- Signature Type: ES256 (both for JOSE and COSE)
ToDo: Keycloak Integration
For the purpose of this work, we will have be:
- Analyzing how to reuse the ES256 crypto implementation libraries allready available in keycloak for the production and verification of signatures.
- Design Credential Format and Selective Disclosure libs, such as to have them share tose libs already in use by keycloak.
In case the issuer wants to binds the verifiable credential to a key controlled by the holder, this key (or a reference thereof) must be included into the produced credential. For the purpose of interoperability, implementations will have to decide on where and how to proceed.
SD-JWT-VC and/or mDLs
- For the GAIN/HAIP POCs, we will be expecting the key to be a jwk in the cnf claim of the JWT, or
- In the common base profile in negotiation, it can be a kid (with did:jwk) in the cnf claim of the JWT.
A party validating a VC or VP has to be able to retrieve and validate the key used by the issuer to produce the presentation. For this reason, we need to define how to embed or reference the issuer key in the VC.
- For the GAIN/HAIP POCs, we are looking at:
- jwt-issuer specification from the OIDF.
- X509 certificate chains (e.g x5t)
- For the baseline profile in negotiation, did:web and jwt-issuer will both be supported.
In matter of trust anchors, we might endup having some static list of x509 root certificates (incl. eIDAS Certificates) or even using OpenId Federation like described in these slides from our coleague Giuseppe. But nothing is decide yet and most POC will be run with peer Issuer Key exchanges.