These tutorials provide guidance through the necessary steps to use VIDcredentials and VIDconnect. In particular, three different tutorials are presented focusing on different use cases. All use cases together form a user journey that consists of the following steps:
- A User gets his first credential by going through a process that involves scanning his ID card. This process is explained in detail in VIDwallet create credential description.
- The user authenticates towards a website, which requests a verifiable ID presentation. The related process is described in section Authenticating Users with OpenID Connect.
- Once the user is authenticated, he requests a new credential, issued by the government detailed in section Request and Verify credentials.
- Finally, the user presents this credential to his university in order to get a discount. Section Issue Credentials details this process.
1. OpenID Connect User Authentication Flow
The web application needs to be configured to initiate an OpenID Connect flow towards VIDconnect (Valdiated ID's OpenID Connect Provider), and set up a callback URL to receive the
Authorization Code and request the
id_token. This process described in detail in the corresponding VIDconnect Integration Guide.
OpenID Discovery URL You can set up your OIDC client by using OIDC Discovery to:
We strongly recommend the use of an OpenID client library like AppAuth-JS or JSO-OAuth2. Alternatively, you can find a comprehensive list of other certified products on the OpenID website: https://openid.net/developers/certified/ or at https://oauth.net/code/.
OpenID Connect SIOP Flow
The steps of the flow are depicted in the figure as well as described below:
- On a website or webapp, the user selects login using VIDwallet.
- The OpenID Connect Client initiates an authorization code flow. The user is redirected to
https://api.vidchain.net/oauth2/auth?client_id=...&redirect_uri=...where a QR code is shown. It is possible that the relying party request additional identity attributes in this call but in this example a
- The user scans the QR code to authenticate using VIDwallet. The user performs identification and authentication.
- VIDconnect may call the VIDchain backend for additional information such as for resolving the DID.
- The user is redirected to the client’s
/callbackURL along with the authorization code. The web application is using the callback URL to get the
id_tokenfrom the OIDC provider using the authorization code.
- The service provider grants access to their services or resources.
id_token includes the DID of the user, which performed the authentication flow.
The Performed Calls in more Detail
Redirect to OIDP
First, the client redirects the requester to VIDconnet's OID provider with an URL in the following format:
&redirect_uri=<Your callback URL>
&client_id=<Your Client ID>
Once the user is authenticated, the OID provider redirects the user session to the callback URL providing the
After receiving the
code, your OIDC client needs to call the
POST to https://api.vidchain.net/oauth2/token
With the following body:
An example response is shown below:
"scope": "openid VerifiableIdCredential",
2. Verifiable Presentation Flow
In this example, a website requests a presentation of a
VerifiableIdCredential using VIDcredentials service.
This flow is performed after the user has already performed identification and authentication using the flow described in section OpenID Connect SIOP flow.
The following diagram depicts the whole process flow in detail:
Request a Presentation
A website requests from a user to present a verifiable presentation that is based on a verifiable credential.
To do so, a call to the
Verifiable Presentation Service of VIDcredentials is performed, detailed in corresponding OpenAPI description Request a Verifiable Presentation.
Following, an example payload that will be sent to the
/api/v1/verifiable-presentations-requests endpoint to request a
The user will receive a presentation request in VIDwallet. By accepting this request, the user actively gives consent to share the data and VIDwallet will generate a presentation.
Retrieve the Presentation
The VIDcredentials component securely stores the verifiable presentation.
VIDcredentials performs a POST to the defined
callbackUrl during the onboarding process including the following payload:
"message": "Your requested presentation is ready to be downloaded.",
The presentation can be retrieved following the value of the
3. Credential Issuance Flow
The following diagram depicts the process to issue a credential using VIDcredentials:
- The user starts a credential issuance process.
- The entity application calls VIDcredentials to issue a verifiable credential that relates to the user's DID.
- The user’s VIDwallet receives an credential offer.
- The user accepts the credential offering and stores it in VIDwallet.