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
This is the user experience we will build in this tutorial:
- User launches their GO Hold example app 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.
Tutorial overview
To build this user experience, the current tutorial comprises the following steps:
- Configure an Auth0 application: We will use this application to authenticate the user as part of the OID4VCI workflow.
- Obtain a MATTR VII access token: You need this to access protected endpoints on your MATTR VII tenant.
- Configure an Authentication provider: Required to authenticate users before you can issue them credentials.
- Create Issuer certificates: Required to sign mDocs.
- Create an mDocs credentials configuration: Controls the content and branding of issued Credentials.
- Create and share a Credential offer: Used by digital wallets to trigger the issuance workflow.
- 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
- 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
andClient 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}/core/v1/oauth/authentication/callback
(make sure you replace{your_tenant_url}
with thetenant_url
provided with your MATTR VII access credentials.) - 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.
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
POST https://{auth_server}/oauth/token
auth_server
: Replace with theauth_url
value from your login credentials.
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
{
"client_id": "F5qaeLDdbvnU9zhA0j4eHUGCHwC1bKtt",
"client_secret": "Wzc8J**********************************************************",
"audience": "learn.vii.au01.mattr.global",
"grant_type": "client_credentials"
}
- Replace
client_id
,client_secret
andaudience
with your own login credentials. - Keep
grant_type
asclient_credentials
.
Response
{
"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:
POST /v1/users/authentication-providers
Request body
{
"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 applicationDomain
. Make sure you prefix it withhttps
.clientId
: Replace with your Auth0 applicationClient ID
.clientSecret
: Replace with your Auth0 applicationClient Secret
.
Create issuer certificates
In this tutorial we are going to issue an mDoc, so we need to have valid IACA.
Make the following request to your MATTR VII tenant to create an IACA:
POST /v2/credentials/mobile/iacas
Create a MATTR VII mDocs credential 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:
POST /v2/credentials/mobile/configurations
Request body
{
"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"
},
"includeStatus": true
}
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:
POST /v1/openid/offers
Request body
{
"credentials": ["945214ad-3635-4aff-b51d-61d69a3c8eee"]
}
945214ad-3635-4aff-b51d-61d69a3c8eee
: Replace with theid
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
- Open the GO hold example app.
- Select Scan.
- Scan the QR code generated in the previous step.
- Review the credential offer and select Accept.
- 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.