Organisation Wallet Suite - On-Premise Deployment
The Organisation Wallet Suite by iGrant.io lets your organisation issue, hold and verify verifiable credentials under eIDAS 2.0, with OpenID4VCI, OpenID4VP and the EU Architecture and Reference Framework. You can use it as a service from iGrant.io, or run it on your own infrastructure: in your data centre or in your private cloud.
An on-premise installation suits organisations that must keep their data and signing keys inside their own security perimeter, under their own compliance, audit and data residency requirements.
Why run the suite on premise
- Control of your data. Credentials, exchange records and logs stay in your data centre or private cloud, under your data residency and retention policies.
- Control of your signing keys. The keys stay in OpenBao or in your hardware security module (HSM), and they never leave it. Organisations can also use cloud KMS key stores and qualified trust service providers.
- A fit with your infrastructure. Standard Kubernetes and Helm, your ingress controller or Gateway, your database server or the bundled one, and your monitoring and backup tools.
- The same product. The same components and the same API as the iGrant.io service, with the same eIDAS 2.0 and EU Architecture and Reference Framework capabilities.
Deployment options
| Installation | Best for | Instructions |
|---|---|---|
| Helm chart | Kubernetes: production installations | Helm chart documentation |
| Docker Compose | One Docker host: tests, pilots and small production installations | Docker Compose README |
Both install the same components, with one database engine for all components.
Architecture
| Component | What it does | Public |
|---|---|---|
| Gateway | The single entry point of the API. It checks every request (API keys, logins, roles) and sends it to the correct 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 acts as the wallet provider. | Yes: the wallet host |
| Enterprise dashboard | The web interface of the organisation admins. | Yes: the dashboard host |
| Database | One PostgreSQL or MariaDB server for all components, or your own server. | No |
| NATS | The messages between the services. | No |
| OpenBao | Keeps the signing keys of the wallet. | No |
| HSM signer (optional) | Signs with keys in an HSM on behalf of the wallet. Set up with each customer (see Hardware security modules). | No |
What the installation needs
Kubernetes (Helm chart)
| Item | Requirement |
|---|---|
| Cluster | Kubernetes 1.25 or later and Helm 3.8 or later, with a default StorageClass for ReadWriteOnce volumes. |
| Ingress | 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. |
| DNS and TLS | Three host names (the API, the organisation wallet and the dashboard) and their certificates. The API and the dashboard must have the same registrable domain. |
| Image registry | Access to the iGrant.io registry for customers and the release tag of your version, or your own mirror. Ask [email protected]. |
| File store | A Google Cloud Storage bucket for the files of the organisation wallet (not public), or a server with the Google Cloud Storage API. |
| Key protection | A choice for the seal of OpenBao (see Key protection), and optionally an HSM for the signing keys. |
One Docker host (Docker Compose)
A Linux host with Docker Engine, Docker Compose 2.24 or later, GNU Make, Bash, OpenSSL and curl; access to the iGrant.io registry; your reverse proxy with TLS and a DNS name for each public service; and outbound HTTPS for the image registries, the trust list service and the services of other issuers, verifiers and wallets. An SMTP server for the e-mails of the API is optional.
Hardware
The images are for Linux x86-64. The minimum for tests, pilots and small installations:
| Item | Tests and pilots (one node or one Docker host) | Small production installation (Kubernetes) |
|---|---|---|
| Nodes | 1 | 3 |
| CPU | 4 vCPU | 4 vCPU for each node |
| Memory | 8 GB RAM | 8 GB RAM for each node |
| Storage | 128 GB SSD | 128 GB SSD for the volumes, with backups |
| Network | 1 Gbit/s | 1 Gbit/s |
The resources grow with the number of organisations, the issuance and verification rate, the number of concurrent API calls and the size of the database. Production installations with high availability, many organisations, a high transaction rate or HSM signing are sized with you, based on your load and availability requirements. Contact [email protected]. See Prerequisites.
Your options
Database
The whole platform uses one database engine: PostgreSQL or MySQL (MariaDB or MySQL 8.0). Each component has its own database and owner user. The chart can run the database server for you (PostgreSQL 18 or MariaDB), or use your own server, with an admin user or with the databases and users that your DBA creates. All components connect with TLS and verify the server certificate. Choose the engine before the install: a later change does not copy the data. See Database.
Key protection
OpenBao keeps the signing keys of the organisation wallet in its Transit engine. The chart runs OpenBao with 3 nodes, or uses your own OpenBao. The seal of OpenBao protects its root key:
| Seal | Unseal | Availability |
|---|---|---|
| Shamir | Manual: an operator unseals each node after each start | In the Helm chart. Plan an operator for each restart and each upgrade. |
| Static key | Automatic, with a key file on the host | In Docker Compose. Keep the key file safe: without it, nobody can read the data. |
| HSM | Automatic, through your HSM | Set up with each customer (see Hardware security modules). |
| Google Cloud KMS | Automatic, through a Google Cloud KMS key | Set up with each customer (see Scaled deployments). |
The local key store of the installation
Every organisation can use the local key store of the installation. By default, its keys are in OpenBao. With HSM support, the keys are created and used in your HSM partition, and they cannot leave it. OpenBao still keeps the holder binding keys and encrypts the key store credentials, so the installation always needs OpenBao.
Hardware security modules (HSM)
The platform uses the standard PKCS#11 interface for hardware security modules. It is tested with Thales Luna Network HSM (on premises) and Thales Luna Cloud HSM (DPoD). We support other PKCS#11 HSMs for each customer after a validation with your HSM and its client library.
An HSM can protect the OpenBao seal, the signing keys of the organisations, or both, so that the keys never leave the HSM. Organisations can also add their own Thales Luna Cloud HSM (DPoD) partition as a key store. We set up HSM support with each customer, based on their HSM, network and security requirements. Contact [email protected]. See Connect your on-premise HSM, Thales Luna Cloud HSM (DPoD) and DPoD key stores.
Organisation key stores
The organisation admins can add key stores of their own in the dashboard or with the Key Management API. The installation decides which types they can add (see Key stores):
| Type | Key store | What the installation needs |
|---|---|---|
vault | An external OpenBao of the organisation (Transit engine) | Access to the address of that OpenBao. |
csc | A qualified trust service provider (QTSP) for remote signing with the CSC API | Access to the CSC address of the QTSP. |
gcp-kms | Google Cloud KMS, including 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 | A Thales Luna Cloud HSM partition (DPoD) of the organisation | Set up with each customer (see Hardware security modules). Not in the default list. |
The default is vault, csc, gcp-kms, aws-kms and azure-key-vault. The cloud key stores call only the official endpoints of their cloud, 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).
The built-in test CA
The built-in test CA issues test certificates for development and testing (see The built-in test CA). They are not on any trusted list. It is on by default. Turn it off when the installation must not offer it, for example in production (see Key stores).
Exposure
The platform has three public hosts: the API, the organisation wallet and the dashboard. The Helm chart creates an Ingress for each host (the default), an HTTPRoute for each host of your Gateway, or only the Services for 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 the CORS checks, the authentication and the rate limits. The proxy must accept request bodies of up to 10 MiB, wait up to 60 seconds for a request, keep the event streams of the API open for up to 3900 seconds without buffering, and pass the client address (the rate limits and the IP allow-lists of API keys use it). The repository documentation gives the settings for ingress-nginx, Envoy Gateway, kgateway and nginx. See Exposure.
Network policies
With the Helm chart, you can turn on Kubernetes network policies when your cluster enforces them. Only your ingress controller or Gateway then reaches the public services, the database and NATS accept only their clients, and the egress profiles name the external targets (for example a cloud KMS on a private address). See Network policies.
Installation
With the Helm chart, the Install page of the chart documentation has seven steps, each with a check: the namespace and the registry access, the keys of the platform (a script of the chart creates them), the values files of your choices, the install, the initialisation of OpenBao, the wait for the platform, and the first admin with its organisation.
With Docker Compose, the Installation section of its README has the steps, from the settings in .env to the first admin and its organisation.
Each organisation gets the local key store of the installation and a default signing key when its wallet is deployed. The organisation admins then add their own key stores and keys (see Key Management).
Operations
To upgrade, set the release tag of the new version and run the upgrade of the chart: the chart and the images of one release belong together. After an uninstall, the volumes and the Secrets of the data stay, so you can install again with the same data. Keys in an HSM also stay: the HSM administrator removes the key pairs that no installation uses. See Upgrade and Uninstall.
Enterprise services
iGrant.io works with each on-premise customer on the parts that depend on their environment:
- access to the iGrant.io registry for customers and the release tags of your version;
- sizing for production, high availability and growth, based on your load and availability requirements;
- integration with your hardware security module (Thales Luna, DPoD and other PKCS#11 HSMs after a validation) and an automatic unseal through your HSM or a Google Cloud KMS key;
- advice for upgrades to new releases.
To plan an installation, contact [email protected].
References
[1] Helm charts repository: https://github.com/L3-iGrant/helmcharts
[2] Helm chart documentation (contents): https://github.com/L3-iGrant/helmcharts#readme
[3] Docker Compose README: https://github.com/L3-iGrant/helmcharts/blob/main/docker-compose/README.md
[4] Reference files of the Helm chart (values, database, exposure, keys, network policies, HSM): https://github.com/L3-iGrant/helmcharts/tree/main/docs
[5] Organisation Wallet Suite overview: https://docs.igrant.io/docs/organisation-wallet-overview/
[6] Organisation Wallet Suite features: https://docs.igrant.io/docs/organisation-wallet-features/