Skip to main content

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

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

Hyperledger Aries Cloud Agent-Python Configuration Details

The following parameters in the Hyperledger Aries Cloud Agent-Python configuration file need to defined per environment:

ParameterDescriptionAccepted Values
log-levelDefines the detail of logging to apply.Trace, Debug, Info, Warn, Error
admin-insecure-modeMust 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-keyThis 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
adminSpecify 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-urlThis 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-ledgerSpecifies 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-typeSpecifies the type of Indy wallet provider to use. Supported internal storage types are 'basic' (memory) and 'indy'.indy or basic (default)
seedThis 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
endpointSpecifies 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-urlThis 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-transportDefines 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-transportDefines 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-nameName of the Wallet.Alpha-numeric string.
wallet-keySpecifies the master key value to use to open the Wallet.Alpha-numeric string specifying the Wallet key.
replace-public-didIf 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-provisionIf the requested profile does not exist, initialize it with the given parameters.true or false
wallet-storage-typeSpecifies 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-configThis 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-credsThis defines the credentials for connecting to the database.Credentials in a username, password format
multitenantMust be set to 'true' if the Hyperledger Aries Cloud Agent is being used with the FPX Wallet.true or false
jwt-secretSpecify 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-adminSpecify whether to enable the multitenant Admin API.Always set to 'true'.
multitenancy-configSpecify 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-invitesSend invitations out, and receive connection requests, using the public DID for the agent.true or false (default)
monitor-revocation-notificationSpecifies that the cloud agent will emit webhooks on notification of revocation received.true or false
debug-connectionsEnable additional logging around connections.true or false (default)
debug-credentialsEnable additional logging around credential exchanges.true or false (default)
read-only-ledgerSet 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)

Wallet Server Configuration

Sample Configuration File

A sample Wallet Server configuration file (application.yml) is provided below. Refer to the highlighted section for the parameters specifically required to enable and configure Verifiable Credentials.

Sample Configuration File for Wallet Server with Verifiable Credentials


server.tomcat.remote_ip_header: x-forwarded-for
server.tomcat.protocol_header: x-forwarded-proto
server.tomcat.use-relative-redirects: true
server.error.whitelabel.enabled: false
server.port: 8084

i18n:
defaultLang: en
allLanguages: fr, en
basename: classpath:./i18n/messages
cacheEvictFixedRateString: PT30S

# ---------------
# Global OIDC Parameters
# ---------------
oidc:
provider:
issuer: ${server-host}
authzEndpoint: /transaction/authorize
client:
redirectHost: ${server-host}
datasource:
redirectHost: ${server-host}
---
mobile-permission-path: consent_request
mobile-host: com.identos.demo.wallet://fpx-wallet/
server-host: http://localhost:8084
web-host: http://localhost:443
idn:
oidc:
issuer: http://localhost:8081
clientId: fraser-client
clientSecret: fraser-client
oidc:
provider:
issuer: ${server-host}
client:
redirectHost: ${server-host}
datasource:
redirectHost: ${server-host}

navigator:
fallbackBaseUrl: ${web-host}
redirectInterval: 100
multiNav: true
redirects:
- baseUrl: ${mobile-host}
idpPath: /oauth_callback
consentPath: ${mobile-permission-path}
dsPath: /oauth_callback
errorPath: /error
- baseUrl: ${web-host}
idpPath: /idp-callback
consentPath: /as-authorize
dsPath: /rs-callback
errorPath: /login
app:
redirect:
platforms:
ios:
oauthCallback: ${mobile-host}
userConsentRequest: ${mobile-host}${mobile-permission-path}
android:
oauthCallback: ${mobile-host}
userConsentRequest: ${mobile-host}${mobile-permission-path}
web:
oauthCallback: ${web-host}/idp-callback
userConsentRequest: ${web-host}/as-authorize
rsCallback: ${web-host}/rs-callback
errorPageRedirectUrl: ${web-host}/login
device:
verificationUrl: ${mobile-host}${mobile-permission-path}
idpManageUrl: https://keycloak.dev.identos.ca/
idpUserDeleteUrl: https://keycloak.dev.identos.ca/auth/realms/user-portal/me/delete
# --
# CORS
# --
cors:
origins:
- http://localhost:3000

fpxwallet.walletserver.resources.login-page.css: ${server-host}/style.css
idp.user.account.delete.enable: true

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

# --------------------
# Database connections
# --------------------
spring:
thymeleaf:
cache: false
prefix: classpath:./templates/
web:
resources:
static-locations: classpath:./static/
datasource:
driverClassName: com.mysql.cj.jdbc.Driver
url: jdbc:mysql://localhost/wallet_identos?createDatabaseIfNotExist=true
username: idnTester
password: idnTester_SuperSecurePassword
jpa:
hibernate.ddl-auto: validate
generate-ddl: false
show-sql: false
flyway:
enabled: true
locations: classpath:db/development
logging:
level:
com.identos.fpxwallet.walletserver: DEBUG
org.hibernate.SQL: DEBUG
org.hibernate.type: DEBUG
location: ../logs

---

spring.jpa.open-in-view: false


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:

ParameterDescriptionAccepted Values
cloud-agent-base-urlThis value should be the base URL of the Hyperledger Aries Cloud Agent's Admin API.URL of the Hyperledger Aries Cloud Agent Admin API.
webhook-host-overrideParameter used to override the webhook host during testing only.Host path.
webhook-security-keyThe 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
security.secureThis 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
security.api-keyThis 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
connection-platform-linksKey-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.- connection-platform-links.ios: ${web-host}/profile

- connection-platform-links.android: ${mobile-host}/profile

- connection-platform-links.web: ${mobile-host}/profile
default-cloud-agent-account-image-urlThis 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}