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 tutorial focuses on guiding you through the process of setting 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: Configure MATTR VII 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 .

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

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

Request

Make a request of the following structure to configure a new claims source:

HTTP


POST /v1/claim-sources

Request body

JSON


{
    "name": "My tutorial Claims source",
    "url": "<CLAIM_SOURCE_URL>",
    "authorization": {
        "type": "api-key",
        "value": "supersecretapikey"
    },
    "requestMethod": "GET",
    "requestParameters": {
        "email": {
            "mapFrom": "claims.email"
        }
    }
}

url : Replace this with the Public Claims Source URL URL generated when you started the claims source application. The URL should follow this format: https://<YOUR_NGROK_SUBDOMAIN>/claims.
authorization : Specifies how to access the claims source. The sample claims source application uses an API key (supersecretapikey) for access control. For production environments, it is strongly recommended to use a more secure API key.
requestParameters : Maps the user’s email claim (provided by the authentication provider) to a request parameter. This parameter is sent to the claims source to retrieve user-specific information.

Response

JSON


{
    "id": "945214ad-3635-4aff-b51d-61d69a3c8eee"
    // Remaining response properties
}

id : Unique identifier for the configured Claims source. We will use it in the next step to integrate the Claims source into the OID4VCI workflow.

Use the Claim source in a credential configuration

Request

Make the following request to create a simple mDoc credentials configuration that includes the holder’s first name, last name and e-mail, but also the age claim from your configured Claims source:

HTTP


POST /v2/credentials/mobile/configurations

Request body

mDoc Credential configuration


{
    "type": "com.example.credentialwithclaims",
    "expiresIn": {
        "months": 1
    },
    "claimMappings": {
        "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"
            }
        }
    },
    "branding": {
        "name": "My Credential with Claims",
        "description": "For rich credential issuance experience",
        "backgroundColor": "#2d46d8"
    },
    "claimSourceId": "<CLAIM_SOURCE_ID>",
    "includeStatus": true
}

age : This claim represents the user’s age, retrieved from the Claims source. During credential issuance, the claims.age property from the Claims source is mapped to the age claim in the credential.
claimSourceId : Replace this with the id value returned in the response when you configured the Claims source in the previous step.

Response

JSON


{
    "id": "294868aa-3814-4a50-9862-5ff48381a8e5"
    //... rest of your credential configuration
}

id : Unique identifier for the created mDocs credentials configuration. This ID is used 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.

Request

Make the following request to generate a new Credential offer:

HTTP


POST /v1/openid/offers

Request body

JSON


{
    "credentials": ["<CREDENTIAL_CONFIGURATION_ID>"]
}

credentials: Replace this with the id value returned in the response when you created the 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.

Test the workflow

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.

What’s next?

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.
Apply branding to issued credentials as part of creating a Credential configuration.