Skip to main content

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 installationEnterprise installation
ForDevelopment, tests and evaluationProduction
What you getThe 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
AccessPublicOn 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.
Note: This page gives an overview: what the platform needs and which choices you make. The step-by-step instructions, each with a check, are in the Helm charts repository. If this page and the repository differ, follow the repository.

Architecture​

ComponentWhat it doesPublic
GatewayThe entry point of the API. It checks each request (API keys, logins, roles) and sends it to the right service.Yes: the API host
APIOrganisations, admins, credential definitions, webhooks and the OpenID provider.Through the gateway
Webhook handlerSends the webhook events of your organisations.No
Consent managementData agreements and consent records.Through the gateway
Organisation walletIssues, 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 dashboardThe web interface of the organisation admins.Yes: the dashboard host
PostgreSQLOne database server for all components: the bundled one, or your own.No
NATSThe messages between the services.No
OpenBaoThe key store of the wallet.No
ValkeyThe 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 signerSigns 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.

Estimates

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 testsSmall production
CapacityUp to 10,000 wallet unitsUp to 250,000 wallet units
Nodes1 (or 1 Docker host)3
CPU8 vCPU16 vCPU for each node
Memory32 GB RAM64 GB RAM for each node
Storage250 GB NVMe SSD1 TB NVMe SSD for each node, with backups
Network1 Gbit/s10 Gbit/s
Key storeOpenBao, 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 unitsPeak presentations and WIA requests each secondApplication nodesEach database serverHSM signatures each second at peak
250,00020 and 303 × 16 vCPU, 64 GB RAM (the database in the cluster)–75
1,000,00080 and 1204 × 16 vCPU, 32 GB RAM8 vCPU, 64 GB RAM300
4,000,000310 and 4606 × 32 vCPU, 64 GB RAM32 vCPU, 256 GB RAM1,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:

RecordAverage size
Wallet unit, with its attestations26 KB
Verification record18 to 31 KB
WIA5 KB
Issued credential, each copy8 to 17 KB
Re-issuance, added to its issuance record0.5 MB
Audit event, kept 7 years by default1 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:

SealUnsealUse
ShamirManual: an operator unseals each node after each startDevelopment and tests (Helm chart)
Static keyAutomatic, with a key file on the hostDevelopment and tests (Docker Compose)
HSMAutomatic, through your HSMProduction (enterprise installation)
Google Cloud KMSAutomatic, through a Google Cloud KMS keyProduction (enterprise installation)
Keep the seal and the keys: Without the seal key, OpenBao stays sealed and its data is lost. Back up the seal key in the way that your HSM or Google Cloud supports. Keep the recovery or unseal keys and the root token outside the cluster.

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):

TypeKey storeWhat the installation needs
vaultThe organisation's own OpenBao (Transit engine)Network access to that OpenBao
cscA qualified trust service provider (QTSP), with the CSC APINetwork access to the CSC endpoint of the QTSP
gcp-kmsGoogle Cloud KMS, also Cloud HSM keysOutbound HTTPS to cloudkms.googleapis.com
aws-kmsAWS KMSOutbound HTTPS to kms.<region>.amazonaws.com
azure-key-vaultAzure Key Vault or Azure Managed HSMOutbound HTTPS to login.microsoftonline.com and to <vault>.vault.azure.net or <hsm>.managedhsm.azure.net
dpodThe organisation's own Thales Luna Cloud HSM (DPoD) partitionEnterprise 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/