Configure agent
Configure the agent
1. Copy the configuration folder to a location of your choosing
Now it is time to configure the agent. First we are going to copy the examples configuration directory called packages/agent/conf/examples
to
another directory
of choice. For instance into packages/agent/conf/exercises
. This allows you to always compare your changes against the original example folder. The
rest of
this page assumes you are using the folder packages/agent/conf/exercises
.
conf
folder will always overwrite data in de databaseGlobal replace to ensure that your ngrok is being used everywhere
We will look into the configuration files. But firt make sure that in the entire conf folder you globally replace this value
http://my-hostname-or-ip:5010
into https://your-ngrok-url
from setup development
The reason is that the wallet will need to access your agent. In order to do that you need to be on the same network, or you need to have a solution like ngrok that forwards the URL to your local agent.
2. Let’s have a look into the dids
folder
The dids
folder contains any DIDs you want created during the start of the agent. See DIDs on the documentation site for more
background about DIDs. Every file in the folder with a .json
extension will result in a key being created with a DID associated. That could be did:
jwk, did:key, did:web or did:ebsi (more advanced). Open the single file in the folder, to see the structure
3. The OID4VCI folder
The OID4VCI folders contain files related to the OpenID for Verifiable Credentials Issuance protocol. The agent supports hosting multiple issuers at the same time. The files are split into 2 folders:
oid4vci_options
: This folder is mainly used to link keys or DIDs from the DIDs folder to the configuration. Every file with.json
extension in there corresponds to a single issuer instance.
OID4VCI Options file
Let’s explain what is in the OID4VCI file by providing an example first:
key | explanation | |
---|---|---|
correlationId | The correlationId is used to correlate configuration files belonging together. We suggest to always use http://your-computer-ip/oid4vci | |
definitionId | This is the definition id . This value will be exposed in the URL. For instance if your issuer is configured with a base URL of http://192.168.2.90:5010/oid4vci then this specific issuer base url will become http://192.168.2.90:5010/oid4vci/example | |
issuerOpts | This is an object mainly linking keys and other configuration values to the issuer | |
checkLinkedDomains | This option can be ignored as it is for more advanced use cases where a DNS domain is being linked to a DID using the well-known DIDs specification. The if_present is a good default. Meaning it will be detected and used automatically if present | |
identifierOpts | An object linking an identifier and key managed by the agent to the issuer. Every issuer has one key associated an optionally a DID. For exercises we suggest to use DIDs, as keys only would require X.509 certificates. | |
identifier | A DID associated with this issuer. Use one of the DIDs the agent manages. Although the DID comes from the database, typically you would find the value in the dids configuration folder | |
kmsKeyRef | This is a key reference from the Key Management system. During startup the agent should recreate any keys configured from the dids configuration folder. You would have to use key assoicated with above DID (DIDs can have multiple keys) |
The OID4VCI Metadata files
There are 2 types of metadata files for OID4VCI. One is for the integrated Authorization Server, the other is for the actual credential issuer.
Issuer metadata
The correlationId should correspond to above correlationId. Again use the IP address on your local network.
key | explanation |
---|---|
overwriteExisting | Whether the metadata in this configuration file will overwrite any configuration already stored in the agent database or not. |
metadata | The actual metadata that the issuer will expose to wallets. This is data defined in the OID4VCI specification |
credential_issuer | The URL a wallet will use to access the issuer. See the note about external URLs below |
Note that the issuer has 2 credentials configured. You can issue both a regular JWT as well as a SD-JWT.
Example:
packages/agent/conf/exercises/example-issuer.json
Authorization server metadata
The agent has a built-in authorization server. This is mainly used for access tokens in the pre-authorized code flow. Although we do support an authorization code flow, unfortunately we could not make that easily accessible as part of these exercises yet
OID4VCI Template files
In the folder packages/agent/conf/exercise/templates
you will find 2 template files using so called Handlebars templates. These templates are linked
from the OID4VCI metadata per credential. It maps the input data supplied during session creation, onto the actual structure of the credential as
defined in the template files. Have a look into both hbs.json files in this folder.
4. The OID4VP files
OID4VP Options
The OID4VP options file in packages/conf/exercises/oid4vp_options
defines options for Authorization Requests
Presentation Definitions
In packages/agent/conf/exercises/presentation_definitions
you will find Presentation Definitions that the agent imports from disk. Look into the
example file, but there are separate exercises on OID4VP.
5. Environment variables
In packages/agent
there is a file called .env.example
. First copy this file to .env.local
. This will make sure that you can configure
environment variables in this file, which are local to your environment.
Open the file and make sure that you update the CONF_PATH to ./conf/exercises
otherwise it would keep loading the configuration files from the
original conf/examples
folder.
6. Start the agent
Now we are finaly ready to start the agent, exposed using the ngrok URL.
Run the following command and make sure the agent keeps running. There could be a few warning messages, but that is okay for now.
Make sure you are in the correct folder: packages/agent
The agent should now be running, and you are now ready to start the exercises.