Learn how to integrate a claims source into an OID4VCI workflow

Introduction

In an OpenID4VCI issuance workflow, you can enhance the credential issuance process by configuring your tenant to fetch claims directly from a compatible Claims source. These claims can then be used to issue verifiable credentials tailored to the user’s data.

This will guide you through using the Portal to set up an OID4VCI workflow that integrates a claims source to retrieve and utilize claims during credential issuance.

Tutorial overview

The current tutorial builds upon the get started with OID4VCI tutorial by adding the following steps:

Set up a local Claims source: Use the provided sample Node.js application to simulate a claims source by providing a REST API to retrieve claims for specific users.
Integrate the Claims source with MATTR VII: Use the Portal to configure a MATTR VII tenant to connect to and utilize the sample Claims source for retrieving claims during an OID4VCI workflow.

Prerequisites

Ensure you have completed the Get Started with OID4VCI Tutorial, as this tutorial builds upon it.
Download the sample Claims source application , which will be used to simulate a claims source.
You will need a ngrok account to expose your local Claims source to the internet. You can sign up for a free account at ngrok.com .

Set up a local Claims source

Clone the MATTR Sample Apps repo to your machine and navigate to the claims-source-app folder.
Rename the env-example file to .env.
Change the value of NGROK_AUTHTOKEN to your ngrok authentication token.
Open the database.json file and add a new object to represent a user with claims:
- Set email as the email address that matches the email of a user you created in your Auth0 application during the Get Started with OID4VCI Tutorial.
- Set any number as the user’s age.
Start the claims source app either via npm or docker:
Start via npm
```
npm install
npm run start
```
or
Start via docker
```
docker compose up --build
```
Make note of the Public Claims Source URL displayed in the terminal after starting the app. This URL will be used to configure the Claims source in your MATTR VII tenant.

Your claim source is now set up and ready to be used in the OID4VCI workflow. Next, we will configure MATTR VII to connect to this claims source.

Configure the Claims source in your MATTR VII tenant

In the navigation panel on the left-hand side, expand the Credential Issuance menu.
Select Claims sources.
Click the Create new button.
Insert a meaningful name for your Claims source in the Name field.
In the URL field, paste the Public Claims Source URL generated when you started the claims source application.
In the Authorization type section, select API Key as the type.
In the API Key field, paste supersecretapikey. This is the API key used by the sample claims source application to control access. In Production environments, it is strongly recommended to use a more secure API key.
Paste the following code into the Request parameters field:
JSON
```
{
    "email": {
        "mapFrom": "claims.email"
    }
}
```
This maps the user’s email claim (provided by the authentication provider) to a request parameter that will be sent to the claims source to retrieve user-specific information.
Select Save to create the Claims source.

Use the Claim source in a credential configuration

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 “Enriched Credential”.
In the Description text box, enter a clear and descriptive description that will appear on the credential in the wallet, for example “Credential with integrated claims source”.
In the Credential type text box, enter a unique identifier for the credential type, for example com.example.credentialwithclaims.

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"
        },
        "age": {
            "mapFrom": "claims.age",
            "type": "number"
        }
    }
}

The age claim will be retrieved from the Claims source configured in the next step, while the first_name and last_name claims will be retrieved from the authentication provider (e.g., Auth0) during the OID4VCI workflow.

Use the Claim source dropdown to select the Claims source you created in the previous step. This will allow the credential to retrieve claims from the configured Claims source during issuance.
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.

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.

You should now have a credential in your wallet that includes the age claim retrieved from the Claims source.