Learn how to configure an OID4VCI Authorization Code flow to issue an mDoc into a digital wallet

Introduction

The OpenID4VCI specification is an open standard developed by the OpenID Foundation. It leverages the OpenID protocol to support verifiable credentials issuance and management.

In this tutorial, you will use the Self Service Portal to configure an OID4VCI Authorization Code flow and use it to issue an mDoc into the MATTR GO Hold example app.

User experience

OID4VCI Tutorial Workflow

This is the user experience you will build in this tutorial:

User launches their GO Hold example app (wallet) and scans a QR code received from an Issuer.
The wallet displays what credential is being offered to the user and by what Issuer.
The user agrees to claiming the offered credentials.
The user is redirected to complete authentication via Auth0.
Upon successful authentication, the credential is issued to the user’s GO Hold example app. They can now view the credential and present it for verification.

Prerequisites

Complete the sign up form to get trial access to MATTR VII and the Self Service Portal.
Use the Self Service Portal to create a new tenant.
Install the MATTR GO Hold example app by following the getting started guide.
Sign up with Auth0 so you can create an Auth0 application and user.

Tutorial overview

To build this user experience, the current tutorial comprises the following steps:

Create a tenant that will issue the credential to the user.
Configure an Auth0 application that will authenticate the user as part of the OID4VCI Authorization Code flow.
Configure the Auth0 application as your tenant’s Authentication provider that authenticates users before you can issue them credentials.
Create an IACA certificate that is required to sign mDocs.
Create an mDocs credentials configuration that controls the content and branding of issued credentials.
Create and share a Credential offer that is used by digital wallets to trigger the issuance workflow.
Claim the credential as the holder using your GO Hold example app.

Create a tenant

Every action in the Self Service Portal is performed in the context of a tenant. This means that all configurations, settings, and data you manage are associated with the selected tenant. To create a new tenant, follow these steps:

Select the Create/Switch Tenant button on the top-right side of the screen.
The All tenants window is displayed, listing any existing tenants.
Select the Create new button.
The New tenant form is displayed.
Use the Region dropdown list to select the region your tenant will be hosted in.
Use the Tenant subdomain text box to insert a subdomain for your tenant.
Use the Tenant name text box to insert a meaningful and friendly name for your tenant.
Select the Create button to create the new tenant.
Make note of the displayed tenant_url, you will need it in the next step.

If you already have a tenant, you can skip this step and use the existing tenant to complete the tutorial.

Configure an Auth0 application

Next you will:

Create an Auth0 application that will authenticate the user as part of the OID4VCI Authorization Code flow.
Create a user that you will issue the credential to.

Create a new Auth0 application

Log into Auth0 .
Skip the Auth0 onboarding tutorials and go straight to your Dashboard.
Select Create Application.
Insert a Name for your application.
Select Regular Web Application.
Select Create.
Select Skip Integration.

Your application is created and you will be redirected to the Settings tab under the Applications section.

Record your application Domain, Client ID and Client Secret.
Add a simple Description.
Scroll down to the Application URIs area, locate the Allowed Callback URLs textbox and insert the following URL:
```
https://{your_tenant_url}/v1/oauth/authentication/callback
```
- {your_tenant_url} : Replace with the tenant_url obtained when you created the tenant.
Select the Connections tab.
Enable Username-Password-Authentication under Database.
Disable everything under Social.

Create a User

Select the User Management menu on the left hand side navigation panel and select Users.
Select the Create User button.
Add an Email. This must be different to the one you use to sign up to your Auth0 account.
Add a password.
Select Username-Password-Authentication from the Connection dropdown list.
Select Create. You will be redirected to the new user’s Details tab.
Select Edit under Name and replace the value (Auth0 uses the email by default) with the full user name.

Configure a MATTR VII Authentication provider

Now that you have an Auth0 application, you need to configure it as an Authentication provider in your MATTR VII tenant. This is required so that MATTR VII can use the Auth0 application to authenticate users before issuing them credentials.

In the navigation panel on the left-hand side, expand the Credential Issuance menu.
Select Authentication provider.
Insert your Auth0 application Domain in the Base URL field. Make sure you prefix it with https://.
Insert your Auth0 application Client ID in the Client ID field.
Insert your Auth0 application Client Secret in the Client secret field.
Select Create.

Create an IACA certificate

In this tutorial you are going to issue an mDoc, so you need to have valid IACA:

In the navigation panel on the left-hand side, expand the PLATFORM MANAGEMENT menu.
Select Certificates & identifiers.
Select the Create new button.
Use the Type radio button to select IACA - Issuing Authority Certificate Authority.
Use the Country dropdown list to select an issuing country.
Select the Create button to create the IACA certificate.

Create a credential configuration

Now that you have a valid certificates in place, the next component you need is a Credential configuration to define the structure and branding of the issued credential.

In the navigation panel on the left-hand side, expand the Credential Issuance menu.
Select Mobile credential.
Select the Create new button.
In the Name text box, enter a clear and descriptive title that will appear on the credential in the wallet, for example “My First Credential”.
In the Description text box, enter a clear and descriptive description that will appear on the credential in the wallet, for example “Use For High Assurance Interactions”.
In the Credential type text box, enter a unique identifier for the credential type, for example com.example.myfirstcredential.

Copy and paste the following JSON into the Claim mappings text box:

JSON


{
    "com.example.personaldetails.1": {
        "first_name": {
            "mapFrom": "claims.first_name",
            "type": "string"
        },
        "last_name": {
            "mapFrom": "claims.last_name",
            "type": "string"
        },
        "email": {
            "mapFrom": "claims.email",
            "type": "string"
        }
    }
}

Enter “1” in the Months text box in the Validity for panel to set the credential expiration period.
Select the Create button to create the credential configuration.

Create a Credential offer

You now have all the pieces in place and can wrap them all together to generate a Credential offer and share it with the intended holder:

In the navigation panel on the left-hand side, expand the Credential Issuance menu.
Select Credential offer.
Select the Select button.
Check the checkbox next to the credential configuration you created in the previous step.
Select the Apply button.
Select the Generate button.
Download the displayed QR code and save it somewhere safe.
This QR code will be used by the holder to claim the credential.

Claim the credential

You are now ready to claim the credential using the MATTR GO Hold example app:

Open the GO hold example app.
Select Share.
Select Respond or Collect.
Scan the QR code generated in the previous step.
Review the credential offer and select Proceed.
Follow the issuance workflow instructions to claim the credential.

Congratulations, you just used the Portal to configure an end-to-end OID4VCI Authorization Code flow and issue an mDoc into a digital wallet! 🎉