GuidesOID4VCITutorial 🎓

Learn how to configure an OID4VCI workflow 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 we will configure an OID4VCI workflow and use it to issue an mDoc into a MATTR GO Hold example app.

User experience

OID4VCI Tutorial Workflow

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

  1. User launches their GO Hold example app and scans a QR code received from an Issuer.
  2. The wallet displays what credential is being offered to the user and by what Issuer.
  3. The user agrees to claiming the offered credentials.
  4. The user is redirected to complete authentication via Auth0.
  5. 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.

Tutorial overview

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

  1. Configure an Auth0 application: We will use this application to authenticate the user as part of the OID4VCI workflow.
  2. Obtain a MATTR VII access token: You need this to access protected endpoints on your MATTR VII tenant.
  3. Configure an Authentication provider: Required to authenticate users before you can issue them credentials.
  4. Create Issuer certificates: Required to sign mDocs.
  5. Create an mDocs credentials configuration: Controls the content and branding of issued Credentials.
  6. Create and share a Credential offer: Used by digital wallets to trigger the issuance workflow.
  7. Claim the credential as the holder: Use your GO Hold example app to claim the offered Credential.

Prerequisites

  • Complete the sign up form to get access to a MATTR VII trial tenant.
  • Install the MATTR GO Hold example app by following the getting started guide.
  • Sign up with Auth0 which we will use to authenticate the holder as part of the issuance workflow.

We recommend using the MATTR VII Postman collection in this tutorial. While this isn’t an explicit prerequisite it can really speed things up.

Configure an Auth0 application

Let’s start by configuring an Auth0 application. This application will be used to authenticate the user as part of the OID4VCI workflow.

Create a new Auth0 application
  1. Log into Auth0.
  2. Skip the Auth0 onboarding tutorials and go straight to your Dashboard.
  3. Select Create Application.
  4. Insert a Name for your application.
  5. Select Regular Web Application.
  6. Select Create.
  7. Select Skip Integration.

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

  1. Record your application Domain, Client ID and Client Secret.
  2. Add a simple Description.
  3. Scroll down to the Application URIs area, locate the Allowed Callback URLs textbox and insert the following URL: https://{your_tenant_url}/core/v1/oauth/authentication/callback (make sure you replace {your_tenant_url} with the tenant_url provided with your MATTR VII access credentials.)
  4. Select the Connections tab.
  5. Enable Username-Password-Authentication under Database.
  6. Disable everything under Social.
Create a User
  1. Select the User Management menu on the left hand side navigation panel and select Users.
  2. Select the Create User button.
  3. Add an Email. This must be different to the one you use to sign up to your Auth0 account.
  4. Add a password.
  5. Select Username-Password-Authentication from the Connection dropdown list.
  6. Select Create. You will be redirected to the new user’s Details tab.
  7. Select Edit under Name and replace the value (Auth0 uses the email by default) with the full user name.
⚠️

Auth0 holds and stores information against user objects, including PII. Before you add any additional data, make sure you understand Auth0’s policies around storing this information.

Obtain a MATTR VII access token

Now that we have an Auth0 application set up, we continue the rest of the workflow configuration on your MATTR VII tenant. All of the MATTR VII endpoints we will use in this tutorial are protected, so you will first need to use your login credentials to make a request of the following structure and obtain an access token:

Request

HTTP
POST https://{auth_server}/oauth/token

Your auth_url is not the same as your tenant_url. auth_url is only used for obtaining an access token, while tenant_url is used for all other requests to your tenant.

Request body

JSON
{
    "client_id": "F5qaeLDdbvnU9zhA0j4eHUGCHwC1bKtt",
    "client_secret": "Wzc8J**********************************************************",
    "audience": "learn.vii.au01.mattr.global",
    "grant_type": "client_credentials"
}
  • Replace client_id, client_secret and audience with your own login credentials.
  • Keep grant_type as client_credentials.

Response

JSON
{
    "access_token": "eyJhb********************************************************************",
    "expires_in": 14400,
    "token_type": "Bearer"
}

Use the returned access_token value as a bearer token for all requests to your MATTR VII tenant in the next steps of this tutorial.

💡

You will need to obtain a new access token whenever it expires. We recommend using our Postman collection to interact with your MATTR VII tenant. This collection includes a pre-request script to obtain an access token when it is missing or expired, as well as pre-configured templates for all available requests.

Configure a MATTR VII Authentication provider

Now that you have an access token, we can make a request to create an Authentication provider configuration based on the details of your Auth0 application. This will be used to authenticate users as part of the OID4VCI workflow.

Request

Make the following API request to your MATTR VII tenant:

HTTP
POST /v1/users/authentication-providers

Request body

JSON
{
    "url": "https://example.us.auth0.com/",
    "scope": ["openid"],
    "clientId": "zH1IGGkRo6q0ofwiNJnlY0bg9fchw3s0",
    "clientSecret": "***********************************************************LFRrZ",
    "tokenEndpointAuthMethod": "client_secret_post",
    "staticRequestParameters": {
        "prompt": "login",
        "maxAge": 10000
    }
}
  • url: Replace with your Auth0 application Domain. Make sure you prefix it with https.
  • clientId: Replace with your Auth0 application Client ID.
  • clientSecret: Replace with your Auth0 application Client Secret.

Create issuer certificates

In this tutorial we are going to issue an mDoc, so we need to have valid IACA and DSC certificates.

Create an IACA

Make the following request to your MATTR VII tenant to create an IACA:

POST /v2/credentials/mobile/iacas

Create a DSC

Make the following request to your MATTR VII tenant to create a DSC:

POST /v2/credentials/mobile/documentsigners

Request body

{
    "active": true
}

Create a MATTR VII mDocs credentials configuration

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

Request

Make the following request to create a simple mDoc credentials configuration that includes the holder’s first name, last name and e-mail:

HTTP
POST /v2/credentials/mobile/configurations

Request body

JSON
{
    "type": "com.example.myfirstcredential",
    "expiresIn": {
        "months": 1
    },
    "claimMappings": {
        "com.example.personaldetails.1": {
            "first_name": {
                "mapFrom": "claims.first_name",
                "type": "string"
            },
            "last_name": {
                "mapFrom": "claims.last_name",
                "type": "string"
            },
            "date_of_birth": {
                "mapFrom": "claims.date_of_birth",
                "type": "date"
            }
        }
    },
    "branding": {
        "name": "My First Credential",
        "description": "For High Assurance Interactions",
        "backgroundColor": "#2d46d8"
    }
}

Response

The response will include an id element. You will use it to create a Credential offer in the next step.

Create a Credential offer

We now have all the pieces in place and we can wrap them all together to generate a Credential offer and share it with the intended holder so that they know what credentials are being offered and by whom.

Request

Make the following request to generate a new Credential offer:

HTTP
POST /v1/openid/offers

Request body

JSON
{
    "credentials": ["945214ad-3635-4aff-b51d-61d69a3c8eee"]
}
  • 945214ad-3635-4aff-b51d-61d69a3c8eee: Replace with the id element returned in the response when you created an mDocs credentials configuration in the previous step.

Response

The response will include a uri element which can be used by a digital wallet to trigger the OID4VCI workflow. Use one of the following tools to convert the uri value to a QR code (make sure you use the Plain text option where available):

MATTR is not affiliated with any of these service providers and cannot vouch for their offerings.

Save the generated QR code on your computer.

Use the MATTR GO Hold example app to claim the credential

  1. Open the GO hold example app.
  2. Select Scan.
  3. Scan the QR code generated in the previous step.
  4. Review the credential offer and select Accept.
  5. Follow the issuance workflow instructions to claim the credential.

Congratulations, you just configured an end-to-end OID4VCI workflow to issue an mDoc into a digital wallet!!!

What’s next?

In this tutorial we have configured a basic OID4VCI workflow. However, you can use MATTR VII to create more complex and rich issuance experience. Check out more resources on MATTR Learn that will enable you to:

  • Configure an Interaction hook to redirect the user to custom components as part of the issuance workflow.
  • Configure a Claims source to retrieve data from compatible data sources and use it in the issued credential.
  • Apply branding to issued credentials as part of creating a Credential configuration.
OID4VCIAuthentication provider