Organisation Wallet Suite - On-Premise Deployment
The Organisation Wallet Suite issues, holds and verifies verifiable credentials under eIDAS 2.0, with OpenID4VCI, OpenID4VP and the EU Architecture and Reference Framework. iGrant.io can host it for you, or you can run it in your own data centre or private cloud. You get the same components and the same API in both cases.
Run it yourself when your data and signing keys must stay inside your own security perimeter, or when you must meet your own compliance, audit or data residency rules.
Two ways to install
| Community installation | Enterprise installation | |
|---|---|---|
| For | Development, tests and evaluation | Production |
| What you get | The public Helm chart and Docker Compose setup. They show the reference architecture and a complete working setup. | The enterprise Helm chart and its installation guide, in a private repository |
| Access | Public | On request: contact [email protected] |
Both installations need access to the iGrant.io image registry and the release tag of your version. Contact [email protected] for access.
The enterprise installation guide covers the parts that depend on your environment:
- Your hardware security module (HSM): Thales Luna Network HSM, Thales Luna Cloud HSM (DPoD) and, after a validation, other PKCS#11 HSMs. The HSM can hold the signing keys of the organisations.
- The automatic unseal of OpenBao through your HSM or a Google Cloud KMS key. A production installation needs it.
- High availability and scale: replicas spread over nodes and zones, disruption budgets, autoscaling of the wallet, and HSM signer groups.
- Sizing for your load, confirmed with a load test.
- Upgrades to new releases.
Architecture
| Component | What it does | Public |
|---|---|---|
| Gateway | The entry point of the API. It checks each request (API keys, logins, roles) and sends it to the right service. | Yes: the API host |
| API | Organisations, admins, credential definitions, webhooks and the OpenID provider. | Through the gateway |
| Webhook handler | Sends the webhook events of your organisations. | No |
| Consent management | Data agreements and consent records. | Through the gateway |
| Organisation wallet | Issues, holds and verifies credentials (OpenID4VCI, OpenID4VP), and is the wallet provider. One image runs in four roles: service (the public routes), config (the configuration routes), workers (background jobs) and clock (which starts the scheduled jobs). | Yes: the wallet host |
| Enterprise dashboard | The web interface of the organisation admins. | Yes: the dashboard host |
| PostgreSQL | One database server for all components: the bundled one, or your own. | No |
| NATS | The messages between the services. | No |
| OpenBao | The key store of the wallet. | No |
| Valkey | The work queue, single-use values and shared caches of the wallet. You can use your own Valkey or Redis. It keeps no records. | No |
| HSM signer | Signs with keys in your HSM for the wallet. Enterprise installation only. | No |
Requirements
Kubernetes (Helm chart):
- Kubernetes 1.25 or later and Helm 3.8 or later, with a default StorageClass for ReadWriteOnce volumes.
- An ingress controller (for example ingress-nginx or Traefik) or a Gateway API implementation (for example Envoy Gateway, kgateway or Istio). The chart does not install one.
- Three host names with TLS certificates: the API, the organisation wallet and the dashboard. The API and the dashboard must have the same registrable domain.
One Docker host (Docker Compose): Linux with Docker Engine, Docker Compose 2.24 or later, GNU Make, Bash, OpenSSL and curl; a reverse proxy with TLS; and a DNS name for each public service. The host needs outbound HTTPS to the image registries, the trusted lists of your organisations, and the issuers, verifiers and wallets that it talks to. An SMTP server for the e-mails of the API is optional.
Sizing
The images are for Linux x86-64.
These values are estimates from load tests on one computer, before optimisation. They are not a commitment. Your peak load (presentations, issuances and WIA requests), your retention rules and your HSM change them. For a production installation, iGrant.io confirms the sizing with a load test.
| Development and tests | Small production | |
|---|---|---|
| Capacity | Up to 10,000 wallet units | Up to 250,000 wallet units |
| Nodes | 1 (or 1 Docker host) | 3 |
| CPU | 8 vCPU | 16 vCPU for each node |
| Memory | 32 GB RAM | 64 GB RAM for each node |
| Storage | 250 GB NVMe SSD | 1 TB NVMe SSD for each node, with backups |
| Network | 1 Gbit/s | 10 Gbit/s |
| Key store | OpenBao, with the Shamir seal (or the static key of Docker Compose) | OpenBao, unsealed by an HSM (PKCS#11) or Google Cloud KMS |
Give a staging installation the topology of production at a smaller size. One node does not test updates, failover or the HSM path.
Larger installations. Above 250,000 wallet units, use application nodes and two database servers: a primary and a synchronous standby. For each 1,000,000 active wallet units, add about:
- 35 vCPU and 45 GB RAM on the application nodes;
- 7 vCPU and 32 GB RAM on each database server, with at least 64 GB RAM;
- 300 P-256 signatures each second of HSM capacity at peak, when the signing keys are in the HSM.
Use 10 Gbit/s over two independent paths, with at most 2 ms round trip between the database servers.
| Active wallet units | Peak presentations and WIA requests each second | Application nodes | Each database server | HSM signatures each second at peak |
|---|---|---|---|---|
| 250,000 | 20 and 30 | 3 × 16 vCPU, 64 GB RAM (the database in the cluster) | – | 75 |
| 1,000,000 | 80 and 120 | 4 × 16 vCPU, 32 GB RAM | 8 vCPU, 64 GB RAM | 300 |
| 4,000,000 | 310 and 460 | 6 × 32 vCPU, 64 GB RAM | 32 vCPU, 256 GB RAM | 1,200 |
In each example, the application nodes use 60 % of their CPU at peak. If one node fails, the other nodes carry the peak.
The load model. Each wallet unit presents a credential 20 times a month, and the peak is 10 times the average. The PID is issued in 2 formats, each as a batch of 10 copies, and a wallet unit asks for a new batch after it uses the last copy. Each wallet unit asks for a new wallet instance attestation (WIA) every day. Without the daily WIA, the CPU need is about 30 % lower and the HSM signs about 40 % less.
Database growth. The database grows with the records that you keep. We measured these average sizes on our test and hosted installations:
| Record | Average size |
|---|---|
| Wallet unit, with its attestations | 26 KB |
| Verification record | 18 to 31 KB |
| WIA | 5 KB |
| Issued credential, each copy | 8 to 17 KB |
| Re-issuance, added to its issuance record | 0.5 MB |
| Audit event, kept 7 years by default | 1 to 2 KB |
For example, 1,000,000 active wallet units that keep all their records add about 1.8 TB to the database each month. Plan the storage and the backups for your retention period.
Your choices
Database
All components use PostgreSQL. Each component has its own database and owner user. Each process of the wallet connects with its own database role, so only the migration step can change the schema. Use the bundled server (PostgreSQL 18) or your own server, with an admin user that the chart uses to make the databases, users and roles. All connections use TLS and check the server certificate. See Database.
Keys
OpenBao keeps the signing keys of the wallet in its Transit engine. Every installation needs OpenBao: it also keeps the holder binding keys and encrypts the credentials of the key stores. The chart runs OpenBao with three nodes, or you use your own OpenBao.
The seal of OpenBao protects its root key:
| Seal | Unseal | Use |
|---|---|---|
| Shamir | Manual: an operator unseals each node after each start | Development and tests (Helm chart) |
| Static key | Automatic, with a key file on the host | Development and tests (Docker Compose) |
| HSM | Automatic, through your HSM | Production (enterprise installation) |
| Google Cloud KMS | Automatic, through a Google Cloud KMS key | Production (enterprise installation) |
Local key store. Each organisation can use the local key store of the installation. Its keys are in OpenBao. With an HSM, each organisation has two local key stores: Local vault (HSM), where new keys are made and used in your HSM and never leave it, and Local vault (OpenBao), which also takes imported keys.
HSM. The platform uses PKCS#11. It is tested with Thales Luna Network HSM and Thales Luna Cloud HSM (DPoD); other PKCS#11 HSMs are supported after a validation. An HSM can protect the OpenBao seal, the signing keys of the organisations, or both. The enterprise installation guide has the steps.
Organisation key stores. Organisation admins can add their own key stores in the dashboard or through the Key Management API. You decide which types they can add (see Key stores):
| Type | Key store | What the installation needs |
|---|---|---|
vault | The organisation's own OpenBao (Transit engine) | Network access to that OpenBao |
csc | A qualified trust service provider (QTSP), with the CSC API | Network access to the CSC endpoint of the QTSP |
gcp-kms | Google Cloud KMS, also Cloud HSM keys | Outbound HTTPS to cloudkms.googleapis.com |
aws-kms | AWS KMS | Outbound HTTPS to kms.<region>.amazonaws.com |
azure-key-vault | Azure Key Vault or Azure Managed HSM | Outbound HTTPS to login.microsoftonline.com and to <vault>.vault.azure.net or <hsm>.managedhsm.azure.net |
dpod | The organisation's own Thales Luna Cloud HSM (DPoD) partition | Enterprise installation; off by default |
The first five types are on by default. The cloud key stores call only the official endpoints of their provider, and the wallet keeps their credentials encrypted in OpenBao. A cloud KMS with HSM keys and a DPoD partition are not certified qualified signature creation devices (QSCD).
Test CA. The built-in test CA issues test certificates for development and tests (see The built-in test CA). They are not on any trusted list. Turn the test CA off in production (see Key stores).
Exposure
The platform has three public hosts: the API, the organisation wallet and the dashboard. The Helm chart makes an Ingress for each host (the default), an HTTPRoute on your Gateway, or only the Services, so that you can write your own routes. With Docker Compose, your reverse proxy sends the requests to three host ports.
Your proxy only routes the traffic: the platform does CORS, authentication and rate limits. The proxy must accept request bodies of up to 10 MiB, allow 60 seconds for a request, keep the event streams of the API open for up to 3,900 seconds without buffering, and pass the client address (the rate limits and the IP allow-lists of API keys use it). See Exposure for ingress-nginx, Envoy Gateway, kgateway and nginx.
Network policies
If your cluster enforces network policies, the Helm chart can add them. Then only your ingress controller or Gateway reaches the public services, the database and NATS accept only their clients, and egress profiles list the external targets that are allowed. See Network policies.
Audit log
The wallet records the actions of the platform in an audit log in its database: for example a configuration change, a key retirement, an issued credential or a refused request. No process of the wallet can change or delete an event. Each hour, the wallet signs an anchor of each part of the log with a key in OpenBao. Events stay 7 years by default.
With the Helm chart, you can also give the wallet a write-once bucket for copies of the anchors and monthly exports: an S3 store with Object Lock in compliance mode, or a Google Cloud Storage bucket with a locked retention policy. Use a store that a team outside the platform operates. See Audit log.
Install and operate
Install. For the Helm chart, follow Install: seven steps, each with a check, from the namespace and registry access to the first platform admin. For Docker Compose, follow Installation in its README. For an enterprise installation, follow the enterprise installation guide.
After the install. The platform operator organisation is also the wallet provider organisation of the installation. Its platform admins add the other organisations, set their features and manage their super admins in the dashboard (see the Platform Admin Guide). A new organisation has Issuer & Verifier on; a platform admin turns on the other features that it needs. Before an organisation can sign credentials or verification requests, an organisation admin makes a signing key with a certificate chain (see Key Management).
Upgrade. Set the release tag of the new version and run the chart upgrade: the chart and the images of a release go together. Read the notes in Upgrade first.
Uninstall. An uninstall keeps the volumes and the Secrets with your data, so you can install again with the same data. Keys in an HSM stay too. See Uninstall.
References
[1] Helm charts repository: https://github.com/L3-iGrant/platform-deployment
[2] Helm chart documentation: https://github.com/L3-iGrant/platform-deployment#readme
[3] Docker Compose README: https://github.com/L3-iGrant/platform-deployment/blob/main/docker-compose/README.md
[4] Organisation Wallet Suite overview: https://docs.igrant.io/docs/organisation-wallet-overview/
[5] Organisation Wallet Suite features: https://docs.igrant.io/docs/organisation-wallet-features/