Configuration
In this section, the configuration of the wallet is explained. Configuration is used based on a config.yaml
file which should be placed in the apps/backend
folder. This config.yaml
file is loaded when booting the application. The values get type checked, and it gives a clear error message if there is a configuration field missing or provided incorrectly. Next to the config.yaml
file, you can also set environment variables. These override the values that are listed in the config.yaml
file.
Databases
By default, the development database is sqlite. We use postgres databases for production type instances of the wallets.
Authentication
Authentication for frontend services can be done via OAuth. This helps users who need to login to several components to authenticate themselves faster. The wallet is tested against Casdoor, with an Helm chart provided alongside the Helm chart of the wallet, but other OAuth services should be usable (e.g. Keycloak, or hosted OAuth services).
DID Method
Two DID methods are currently supported: did:web
and did:tdw
. A comparison between the two is given below. The decision of which configuration to select should be made based on the specific use case of the wallet.
did:web | did:tdw | |
---|---|---|
TSG Configuration value: | did:web: | did:tdw: |
Specification link: | W3C internal document | BCGov specification draft |
Supported version: | Unofficial draft | Draft v1 |
Underlying technology: | Web-based DID method that serves the DID Document as a JSON under a certain endpoint (.well-known path) of a web domain that is accessible by the public. | Web-based DID method that utilizes a public JSON Lines file hosted under a web domain to store each change (create, update, delete) that occurs on a DID Document. The DID Document is then resolved by fetching and processing the JSON Lines file. |
Identifier format: | did:web:{{public web domain}} e.g. did:web:example.com | did:tdw:{{public web domain}}:{{generated self-certifying identifier}} e.g. did:tdw:example.com:b7ep277b2mvxdpcrbja3iergubfy |
Advantages: | Straightforward implementation with no additional processing other than hosting DID Document on web server. | Additional security and validation mechanisms contained in the JSON Lines file that increases trustworthiness of DID Document. |
Disadvantages: | Easily compromisable without notice by resolving parties when malicious access is gained to the web server. | DID Document is not directly available as extra processing to verify signatures and validate entry hashes retrieved from the JSON Lines file needs to be performed to resolve the DID Document. |
Possible configuration parameters
Name | Data Type | Required | Explanation | Default |
---|---|---|---|---|
Database Configuration | ||||
db.type | String | Yes | Type of the database. Must be "sqlite" or "postgres" . | |
db.database | String | Yes | Name of the database. Used as filename when "sqlite" is provided as database type | |
db.host | String | If type is postgres | Hostname of the database | |
db.port | Integer | If type is postgres | Port of the database | |
db.username | String | If type is postgres | Username of the user in the database | |
db.password | String | If type is postgres | Password of the user in the database | |
OAuth Configuration | ||||
auth.enabled | Boolean | Boolean indicating whether an external OAuth server should be used. If false, all other properties under auth are not used | true | |
auth.authorizationURL | URL | If auth is enabled | OAuth Authorization endpoint URL | |
auth.tokenURL | URL | If auth is enabled | OAuth Token endpoint URL for retrieving access token based used when the Wallet communicates with external services | |
auth.introspectionURL | URL | If auth is enabled | OAuth Introspection endpoint URL for validating access tokens | |
auth.callbackURL | URL | If auth is enabled | Callback URL of the Wallet on which it expects callback requests to arrive | |
auth.redirectURL | URL | If auth is enabled | Redirect URL of the Wallet which it used to redirect a user that has logged in | |
auth.clientId | String | If auth is enabled | OAuth client ID | |
auth.clientSecret | String | If auth is enabled | OAuth client secret | |
auth.clientUsername | String | If auth is enabled | OAuth client username of user used by the Wallet for external services | |
auth.clientPassword | String | If auth is enabled | OAuth client password of user used by the Wallet for external services | |
auth.rolePath | String | JSON Path used to translate roles into a simple array of roles, with as starting point the access token JWT payload | "$.roles[*].name" | |
Server Configuration | ||||
server.listen | String | No | IP address to listen on. | "0.0.0.0" |
server.port | Number | No | Port number for the server. | 3000 |
server.publicDomain | String | No | Public domain of the server. | "localhost" |
server.publicAddress | String | No | Public address of the server. | "http://localhost:3000" |
Initial Key Configuration | ||||
initKeys[].type | String | Yes | Key type. Must be "EdDSA" , "ES384" or "X509" | |
initKeys[].id | String | Yes | Key identifier | |
initKeys[].default | Boolean | No | Flag indicating whether this key should be used as default | false |
initKeys[].existingKey | String | No | Existing private key in PKCS#8 format, can be pointed to a file via "file:/path" . Only used for "X509" typed keys | |
initKeys[].existingKey | String | No | Existing certificate in X.509 PEM format, can be pointed to a file via "file:/path" . Only used for "X509" typed keys | |
Initial Credential Configuration | ||||
initCredentials[].context | Array of Strings | No | JSON-LD Context URLs used for the credential | [] |
initCredentials[].type | Array of Strings | No | Verifiable Credential type IRIs used for the credential | [] |
initCredentials[].id | String | Yes | Verifiable Credential identifier | |
initCredentials[].keyId | String | No | Identifier of key that should be used, if empty the default key will be used | |
initCredentials[].credentialSubject | CredentialSubject | Yes | Verifiable Credential credential subject | |
Trust Anchor Configuration | ||||
trustAnchors[].identifier | String | Yes | DID identifier of trusted issuer | |
trustAnchors[].credentialTypes | Array of Strings | Yes | Credential types trusted from the specific issuer | |
JSON-LD Context Configuration | ||||
contexts[].id | String | Yes | Identifier of this context, will be used to make the context resolvable to /context/:id if document is provided | |
contexts[].credentialType | String | Yes | Credential type that can be used with this context | |
contexts[].issuable | Boolean | Yes | Whether this wallet can issue credentials with this context | |
contexts[].documentUrl | String | If document is not provided | Remote reference of the context | |
contexts[].document | Object | If documentUrl is not provided | Content of the JSON-LD document | |
contexts[].schema | Object | JSON-Schema of the context, used to provide UI forms and validation of credential subjects | ||
OpenID4VCI Configuration | ||||
oid4vci.issuer[].holderId | String | Yes | DID Identifier of the targeted holder of the credential | |
oid4vci.issuer[].credentialType | String | Yes | Type of the credential that will be provided | |
oid4vci.issuer[].credentialSubject | CredentialSubject | Yes | Credential subject of the credential that will be provided | |
oid4vci.issuer[].preAuthorizationCode | String | Pre authorization code the holder must use to request the credential | ||
oid4vci.holder[].issuerUrl | String | Yes | The URL of the issuer of the credential, should be the root path of the issuer due to .well-known resolvement of metadata | |
oid4vci.holder[].credentialType | String | Yes | Type of credential that will be requested from the issuer | |
oid4vci.holder[].preAuthorizationCode | String | Yes | Pre authorization code the holder will use to request the credential | |
DID Service Configuration | ||||
didServices[].id | String | Yes | Identifier of the service associated to this wallet (see the DID Services spec) | |
didServices[].type | String | Yes | Type of the service | |
didServices[].serviceEndpoint | String | Yes | Service endpoint of the service | |
Presentation Configuration | ||||
presentation.types | Array of Strings | No | Types of presentation exchanges this Wallet should support. Any of DIRECT , IATP , OID4VP | ["DIRECT", "IATP"] |
Runtime Configuration | ||||
runtime.gaiaXSupport | Boolean | No | Flag indicating whether this wallet should support Gaia-X credentials | false |
runtime.title | String | No | Title of wallet instance that will be used in the UI | |
DID Configuration | ||||
did.method | String | No | DID method to be used by the wallet | did:web: |
Signature Configuration | ||||
signature.default | String | No | Default signature method for signatures requested via the API | DATA_INTEGRITY_PROOF |
signature.credentials | String | No | Default signature method for proofs in verifiable credentials created by this wallet | DATA_INTEGRITY_PROOF |
signature.presentations | String | No | Default signature method for proofs in non-JWT-based verifiable presentations | DATA_INTEGRITY_PROOF |