light-mode-image
Learn
Authorization Code flow

OID4VCI Authorization Code flow tutorial

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 Authorization Code flow and use it to issue an mDoc to the MATTR GO Hold example app, showing each step both through the MATTR Portal and via the equivalent API calls.

User experience

OID4VCI Tutorial Workflow

This is the user experience you 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.

Prerequisites

  • Complete the sign up form to get trial access to MATTR VII and the MATTR Portal, and then Create a 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.

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 Authorization Code flow.
  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.

Tutorial steps

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 Authorization Code flow.

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 tenant details).
  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.

Configure a MATTR VII Authentication provider

Next you need to configure your Auth0 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.

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

Step 1: Obtain a MATTR VII access token

All of the MATTR VII endpoints you will use in this tutorial are protected, so you will first need to use your tenant details to make a request of the following structure and obtain an access token:

Request
POST https://{auth_server}/oauth/token
  • auth_server : Replace with the auth_url value from your tenant details.
Request body
{
  "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 tenant details.
  • Keep grant_type as client_credentials.

Response

Response body
{
  "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.

Step 2: Configure an Authentication provider

Now that you have an access token, you 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 Authorization Code flow.

Make the following API request to your MATTR VII tenant:

Request
POST /v1/users/authentication-providers
Request body
{
  "url": "https://example.us.auth0.com/",
  "scope": ["openid", "profile", "email"],
  "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.
  • scope : This determines what claims are returned by the authentication provider following successful authentication. Refer to Auth0 OIDC scopes for more information.
  • clientId : Replace with your Auth0 application Client ID.
  • clientSecret: Replace with your Auth0 application Client Secret.

Create issuer certificates

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

  1. Log into the MATTR Portal.
  2. In the navigation panel on the left-hand side, expand the Platform Management menu.
  3. Select Certificates.
  4. Select the Create new button.
  5. Use the Type radio button to select IACA - Issuing Authority Certificate Authority.
  6. Use the Management method radio button to select MATTR managed.
  7. Use the Country dropdown list to select an issuing country.
  8. Select the Create button to create the IACA certificate.
    The IACA is created as inactive by default.
  9. Use the Status radio button to select Active.
  10. Select the Update button to activate the IACA certificate.
  1. Make the following request to your MATTR VII tenant to create an IACA:
POST /v2/credentials/mobile/iacas

The response will include an id element which you will use in the next step.

  1. Make the following request to activate the IACA you just created:
PUT /v2/credentials/mobile/iacas/{iacaId}
  • iacaId: Replace with the id element returned in the response when you created the IACA in the previous steps.
{
    "active": true
}

Your IACA is now active and can be used to sign mDocs.

Create a MATTR VII mDocs credential configuration

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

  1. In the navigation panel on the left-hand side, expand the Credential Issuance menu.

  2. Select Mobile credential.

  3. Select the Create new button.

  4. 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".

  5. 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".

  6. In the Credential type text box, enter a unique identifier for the credential type, for example com.example.myfirstcredential.

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

    Claim mappings
    {
  "com.example.personaldetails.1": {
    "name": {
      "mapFrom": "claims.name",
      "type": "string"
    },
    "email": {
      "mapFrom": "claims.email",
      "type": "string"
    }
  }
}

  8. Enter "1" in the Months text box in the Validity for panel to set the credential expiration period.

  9. Select the Create button to create the credential configuration.

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

Request
POST /v2/credentials/mobile/configurations
Request body
{
  "type": "com.example.myfirstcredential",
  "expiresIn": {
    "months": 1
  },
  "claimMappings": {
    "com.example.personaldetails.1": {
      "name": {
        "mapFrom": "claims.name",
        "type": "string"
      },
      "email": {
        "mapFrom": "claims.email",
        "type": "string"
      }
    }
  },
  "branding": {
    "name": "My First Credential",
    "description": "For High Assurance Interactions",
    "backgroundColor": "#2d46d8"
  },
  "includeStatus": true
}

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

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 so that they know what credentials are being offered and by whom.

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

Make the following request to generate a new Credential offer:

Request
POST /v1/openid/offers
Request body
{
  "credentials": ["945214ad-3635-4aff-b51d-61d69a3c8eee"]
}
  • credentials: Populate the array with the id element returned in the response when you created an mDocs credentials configuration in the previous step.

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.

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 Authorization Code flow to issue an mDoc into a digital wallet!!!

What's next?

In this tutorial we have configured a basic OID4VCI Authorization Code flow. 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:

How would you rate this page?

Journey pattern

Previous Page

API Reference

Next Page

On this page

IntroductionUser experiencePrerequisitesTutorial overviewTutorial stepsConfigure an Auth0 applicationCreate a new Auth0 applicationCreate a UserConfigure a MATTR VII Authentication providerCreate issuer certificatesCreate a MATTR VII mDocs credential configurationCreate a Credential offerClaim the credentialWhat's next?