Demo agent setup

​

Table of contents

1. Agent Configuration Guide
   1. Configuration Directory Structure
      1. dids
      2. oid4vci_metadata
      3. oid4vci_options
      4. oid4vp_options
      5. presentation_definitions
      6. templates
   2. .env variables
2. Starting the agent

​

Example Demo Agent Configuration Guide

Welcome to the agent setup guide. This document will walk you through configuring your agent module by leveraging the settings defined in your .env file. Specifically, the CONF_PATH property in your .env file dictates where the agent retrieves its configuration from.

Be aware that this agent configuration is for demo purposes only. The expectation is that you create the code around the agent yourself, or integrate the agent in your own application.

The agent code being used in this README is available in the following repository: https://github.com/Sphereon-Opensource/web-wallet

​

Configuration Directory Structure

Within your packages/agent/conf directory, navigate to the examples subfolder. Here, you will find six key directories, each integral to the agent’s configuration:

​

1. dids

This directory is designated for storing Decentralized Identifiers (DIDs) documents. These DID documents will be used throughout or oid4vci and oid4vp/siop process. An example using did:jwk can be found here

​

2. oid4vci_metadata

In this folder, you’ll find JSON files that detail the metadata required by the VCI specification and some values that are essential for configuring this agent. Following is a table of values that should be set for a json file inside oid4vci_metadata:

Be aware that each file you put in this directory represents an actual exposed separate credential issuer instance. There is a distinction between OID4VCI issuer metadata and OAuth2 Authorization server metadata files. You need both typically unless you are using an external Authorization Server.

Example OID4VCI metadata can be found here and OAuth2 Authorization Server metadata here

​

3. oid4vci_options

This is the directory where custom OID4VCI options are maintained. An example can be found here

​

4. oid4vp_options

Here, you will store configuration files related to OpenID for Verifiable Presentations (OID4VP). Be aware that any configuration file in this directory represents an individual Relying Party instance. Also be aware that a single Relying Party can host multiple Presentation definitions at the same time.

​

5. presentation_definitions

The content of this directory is essential for defining how the agent understands and processes presentation requests. This is only applied if your demo application is asking the user for their VerifiableCredential(s) from the wallet. For an in-depth explanation of presentation_definition, refer to the Presentation Exchange Documentation. To understand its role in the context of the OID4VP specification, please consult the provided link.

​

6. templates

This directory features templates designed to dynamically create Verifiable Credentials. We use Handlebars to fill the templates with data received from the demo application. Ensure that your form configuration/ requested VerifiableCredential (in above section) provides the necessary data for this process. Examples within this directory illustrate how to implement this approach. Below is one such example:

   {
       "@context": ["https://www.w3.org/2018/credentials/v1"],
       "type": ["VerifiableCredential", "GuestCredential"],
       "expirationDate": "{{{ dateTimeAfterDays 7 }}}",
       "credentialSubject": {
           "firstName": "{{firstName}}",
           "lastName": "{{lastName}}",
           "email": "{{email}}",
           "type": "Sphereon Guest"
       }
   }

Each directory plays a critical role in the configuration of the agent and the successful deployment of the verifiable credential issuance ecosystem within your application. It is essential to carefully craft the contents of these directories in alignment with your specific use cases and the standards of the decentralized identity space.

​

.env variables

Your .env.local file should contain the following variables with values tailored to your setup:

Note: If you intend to access the agent through a mobile device, ensure that you do not use localhost or 127.0.0.1. Instead, use a local IP address that is reachable from your mobile device within the same network.

​

Starting the agent

To start your agent:

1. Create the above-mentioned folders at the location specified by CONF_PATH in your .env or .env.local file.
2. Populate the folders with your specific configurations, such as credential metadata and presentation definitions.
3. Launch your agent using either start:dev for development or start:prod for production environments.