Learn how to integrate a claims source into an OID4VCI workflow

Set up a local Claims source

1. Clone the MATTR Sample Apps repo  to your machine and navigate to the claims-source-app folder.

2. Rename the env-example file to .env.

3. Change the value of NGROK_AUTHTOKEN to your ngrok authentication token.

4. Open the database.json file and add a new object to represent a user with claims:

   • Set any number as the user’s age.
   • Set the email value based on the type of flow you are implementing:
     • If you are building on top of the Authorization Code flow tutorial, use the email address that matches the email of the user you created in your Auth0 application.
     • If you are building on top of the Pre-authorized Code flow tutorial, you can use any email address, but make note of it as you will need it later when you create the credential offer.

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

6. 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, as the provided application meets the requirements  for integrating a Claim source into a MATTR VII 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:

POST /v1/claim-sources

Request body

{
    "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 to a request parameter. This parameter is sent to the claims source to retrieve user-specific information.
  • In Authorization code flows it is provided by the Authentication provider.
  • In Pre-authorized code flows it is provided by the issuer as part of the credential offer.

Response

{
    "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 name and e-mail, but also their age from your configured Claims source:

POST /v2/credentials/mobile/configurations

Request body

{
    "type": "com.example.credentialwithclaims",
    "expiresIn": {
        "months": 1
    },
    "claimMappings": {
        "com.example.personaldetails.1": {
            "name": {
                "mapFrom": "claims.name",
                "type": "string"
            },
            "email": {
                "mapFrom": "claims.email",
                "type": "string"
            },
            "age": {
                "mapFrom": "claims.age",
                "type": "number"
            }
        }
    },
    "branding": {
        "name": "My Credential with Claims",
        "description": "For rich credential issuance experience",
        "backgroundColor": "#a22dd8ff"
    },
    "claimSourceId": "<CLAIM_SOURCE_ID>",
    "includeStatus": true
}

• age : This claim represents the user’s age. It is retrieved from the Claims source and stored in the users claims object as a new age property. During credential issuance claims.age will be 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

{
    "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. Make sure you create a credential offer that matches the flow you are implementing.