Configuring Verifiable Credentials
Prerequisites
- Hyperledger Aries Cloud Agent - Python running and accessible via HTTP/HTTPS. Refer to the section below for configuration details and a sample configuration file.
- OPTIONAL - Hyperledger Indy Tails Server running and accessible via HTTP/HTTPS.
The Hyperledger Indy Tails Server is required only for internal test environments if you have set up a second cloud agent to act as the Issuer and if that cloud agent requires the Indy Tails Server. - An instance of the Hyperledger Indy Blockchain running somewhere.
- An Issuer and Verifier of verifiable credentials, providing a QR code or connection creation data in order to establish a connection with them.
important
Any Issuer and Verifier that is used with the FPX Wallet must first be registered. Unregistered Issuers/Verifiers will not be recognized and honoured by the system. Refer to Configuring Verifiable Credentials with API for more details.
Configuration Details
In order to set up your FPX Wallet to function as a Holder for verifiable credentials, the following items need to be configured:
- Hyperledger Aries Cloud Agent
- Wallet Server (static and runtime configurations)
Hyperledger Aries Cloud Agent
Hyperledger Aries Cloud Agent-Python Configuration Details
The following parameters in the Hyperledger Aries Cloud Agent-Python configuration file need to defined per environment:
| Parameter | Description | Accepted Values |
|---|---|---|
| log-level | Defines the detail of logging to apply. | Trace, Debug, Info, Warn, Error |
| admin-insecure-mode | Must be set to false for production environments - if set to true, the Cloud Agent Admin API requires no API key to access. | True / False |
| admin-api-key | This defines the API key required to access the cloud agent's Admin API. The Wallet Server's application.yml API key must match the one specified in this parameter. Refer to security.api-key for the corresponding parameter in the Wallet Server configuration section. | API Key value |
| admin | Specify the host and port on which to run the administrative server. If not provided, no admin server is made available. | Host and Port (e.g. '0.0.0.0, 8071') |
| webhook-url | This should always be /webhooks/vc#, where the Webhook API key should match the one specified in the Wallet Server's config (see webhook-security-key) | Webhook URL with the webhook API key appended at the end. e.g. [ws_base_url]/[path or subpath]#[webhook_api_key]` which can be as follows: http://192.168.178.66:8084/webhooks/vc#testKeyTestKey |
| no-ledger | Specifies that the Cloud Agent will run with no ledger configured. This must be set if running in no-ledger mode. Overrides any specified ledger or genesis configurations. | true or false (default) |
| wallet-type | Specifies the type of Indy wallet provider to use. Supported internal storage types are 'basic' (memory) and 'indy'. | indy or basic (default) |
| seed | This is a 32-character string which is used to generate a unique DID for use by this Wallet Server's cloud agent. It should ideally be one that isn't already being used by another environment. | Alpha-numeric string |
| endpoint | Specifies the endpoints to put into DIDDocs to inform other agents of where they should send messages destined for this agent. Each endpoint could be one of the specified inbound transports for this agent, or the endpoint could be that of another agent (e.g. 'https://example.com/agent-endpoint') if the routing of messages to this agent by a mediator is configured. The first endpoint specified will be used in invitations. The endpoints are used in the formation of a connection with another agent. | Endpoint URL |
| genesis-url | This specifies the location of a Genesis file for the cloud agent to initialize itself with the Hyperledger ledger it is to use. This will only differ when connecting to a different ledger, and is a URL provided by the ledger host. | Location (URL) of the Genesis file. |
| inbound-transport | Defines the inbound transport(s) on which the agent listens for receiving messages from other agents. This parameter can be specified multiple times to create multiple interfaces. Built-in inbound transport types include 'http' and 'ws'. However, other transports can be loaded by specifying an absolute module path. | transport type, host and port |
| outbound-transport | Defines the outbound transport(s) on which the agent will send outgoing messages to other agents. This parameter can be passed multiple times to support multiple transport types. Built-in inbound transport types include 'http' and 'ws'. | http or ws |
| wallet-name | Name of the Wallet. | Alpha-numeric string. |
| wallet-key | Specifies the master key value to use to open the Wallet. | Alpha-numeric string specifying the Wallet key. |
| replace-public-did | If this parameter is set and an agent already has a public DID, and the '--seed' parameter specifies a new DID, the agent will use the new DID in place of the existing DID. | true or false (default) |
| auto-provision | If the requested profile does not exist, initialize it with the given parameters. | true or false |
| wallet-storage-type | Specifies the type of Indy Wallet backend to use. | Supported internal storage types are 'basic' (memory), 'default' (sqlite), and 'postgres_storage'. The default, if not specified, is 'default'. |
| wallet-storage-config | This defines the location of the Postgres database which the cloud agent will use. | Location (URL) of the Postgres database used by the cloud agent. Can also carry additional values for DB configuration. |
| wallet-storage-creds | This defines the credentials for connecting to the database. | Credentials in a username, password format |
| multitenant | Must be set to 'true' if the Hyperledger Aries Cloud Agent is being used with the FPX Wallet. | true or false |
| jwt-secret | Specify the secret to be used for JSON Web Token (JWT) creation and verification. The JWTs are used to authenticate and authorize multitenant Wallets. | JWT Secret |
| multitenant-admin | Specify whether to enable the multitenant Admin API. | Always set to 'true'. |
| multitenancy-config | Specify multitenancy configuration ("wallet_type" and "wallet_name"). For example: "{"wallet_type":"askar-file","wallet_name":"askar-profile-name"}""wallet_name" is only used when "wallet_type" is "askar-profile" | Wallet Type and Wallet Name |
| public-invites | Send invitations out, and receive connection requests, using the public DID for the agent. | true or false (default) |
| monitor-revocation-notification | Specifies that the cloud agent will emit webhooks on notification of revocation received. | true or false |
| debug-connections | Enable additional logging around connections. | true or false (default) |
| debug-credentials | Enable additional logging around credential exchanges. | true or false (default) |
| read-only-ledger | Set this value to 'true' if the ledger being used is configured with restrictions on who can make edits to it. Setting the value to 'false' will allow edits to be made to the ledger (if supported by the ledger operator). If the parameter is set to 'false' and if the ledger operator does not allow edits to be made to the ledger, an error will be returned. | true or false (default) |
Sample Configuration File
Sample Configuration File for Hyperledger Aries Cloud Agent
# Run with:
# PORTS="8070:8070 8071:8071 8060:8060" ./scripts/run_docker start --arg-file <path_to_this_file>
log-level: info
admin-insecure-mode: true
admin-api-key: apiKey
# This port is where the api will be accessible from
admin: [0.0.0.0, 8071]
webhook-url: https://wallet.verifiable-credentials.dev.identos.ca#test-webhook-api-key
no-ledger: false
wallet-type: indy
seed: ABCDEF0123456789ABCDEF0123456789
endpoint: https://agent.verifiable-credentials.dev.identos.ca
genesis-url: http://dev.greenlight.bcovrin.vonx.io/genesis
inbound-transport:
- [http, 0.0.0.0, 8070]
outbound-transport: http
wallet-name: verifiable_credentials_mainwallet
wallet-key: verifiable_credentials_mainwallet_key
replace-public-did: false
auto-provision: true
# before running aca-py, run a local postgres (docker) like:
# docker run --name postgres-local-container -e POSTGRES_PASSWORD=password -d -p 5555:5432 postgres:10
wallet-storage-type: postgres_storage
#wallet-storage-type: basic
# could be sent using env var ACAPY_WALLET_STORAGE_CONFIG
wallet-storage-config: '{"url":"identos-postgres-development.co81mhts8zg9.ca-central-1.rds.amazonaws.com:5432","max_connections":15}'
# could be sent using env var ACAPY_WALLET_STORAGE_CREDS
wallet-storage-creds: '{"account":"verifiable_credentials","password":"95TGqBnknnU5TVGk","admin_account":"verifiable_credentials","admin_password":"95TGqBnknnU5TVGk"}'
multitenant: true
jwt-secret: testjwtsecret
multitenant-admin: true
multitenancy-config: '{"wallet_type": "askar-profile", "wallet_name":"verifiable_credentials"}'
public-invites: true
monitor-revocation-notification: true
debug-connections: true
debug-credentials: true
read-only-ledger: false
Wallet Server Configuration
Wallet Server Configuration Details - application.yml
In addition to the general configuration of the Wallet Server, the application.yml file also contains parameters that need to be configured to enable the use of the Wallet as a holder of Verifiable Credentials. The sample code block above highlights the parameters that need to be present in the file to enable Verifiable Credentials. Parameters that need to be configured are detailed below, and must be located in a verifiable-credentials section
| Parameter | Description | Accepted Values |
|---|---|---|
| verifiable-credentials.cloud-agent-base-url | This value should be the base URL of the Hyperledger Aries Cloud Agent's Admin API. | URL of the Hyperledger Aries Cloud Agent Admin API. |
| verifiable-credentials.webhook-host-override | Parameter used to override the webhook host during testing only. | Host path. |
| verifiable-credentials.webhook-security-key | The security key used to authenticate a webhook request coming from the cloud agent. This must match the webhook API key segment of the cloud agent webhook URL configuration (see webhook-url). If this cannot be validated in the incoming webhook request to the wallet-server, the request will be rejected. If this value is empty no validation will be done and all webhooks will be accepted. This value must never be left blank for Production environments as it may pose a serious security risk. | Webhook security key |
| verifiable-credentials.security.secure | This is a Boolean value which toggles Admin API key security on/off. It should be turned 'On' if the Admin API security on the cloud agent is also turned on (Refer to admin-insecure-mode). | true or false |
| verifiable-credentials.security.api-key | This API key is sent with all requests to the cloud agent if verifiable-credentials.security.secure is turned on. (See admin-api-key in the Hyperledger Aries Cloud Agent configuration section) | API Key |
| verifiable-credentials.connection-platform-links | Key-value pairs under this denote where the /verifiable-credentials/connection-redirect endpoint should redirect to depending on the user's detected platform. These will generally stay the same between environments unless the front-end implementation changes. | - verifiable-credentials.connection-platform-links.ios: ${web-host}/profile - verifiable-credentials.connection-platform-links.android: ${mobile-host}/profile - verifiable-credentials.connection-platform-links.web: ${mobile-host}/profile |
| verifiable-credentials.default-cloud-agent-account-image-url | This value is used as the profile image URL for internal accounts at the cloud agent. This is unused for display at the Wallet Server, but if another server were to access the same cloud agent, they would see this URL as a cloud agent account's image URL. | ${server-host}/images/{cloud-agent-default-account-image.png} |
Sample Configuration File
A sample Wallet Server section within the configuration file (application.yml) is provided below. Refer to the highlighted section for the parameters specifically required to enable and configure Verifiable Credentials.
Sample Section within configuration file application.yml for Wallet Server to configure Verifiable Credentials
mobile-host: com.identos.demo.wallet://fpx-wallet/
web-host: http://wallet-ui.demourl
verifiable-credentials:
cloud-agent-base-url: http://127.0.0.1:8071
# This allows you to override the host used in webhook urls -
# for local debugging since the cloud agent cannot use localhost due to being in a container, but can use the machine's local IP
webhook-host-override: http://10.0.0.208:8084
webhook-security-key:
security:
secure: false
api-key: apiKey
# When the wallet server receives a request to start a VC connection flow, it must send the user to an app depending on the user agent.
# Since connection starting links do not include any app hints as part of the spec, we cannot use the same redirect lookup config that exists higher in this file
connection-platform-links:
web: ${web-host}/profile
ios: ${mobile-host}/profile
android: ${mobile-host}/profile
default-cloud-agent-account-image-url: ${server-host}/images/cloud-agent-default-account-image.png