Installeren en lid worden

Deze pagina gaat over een installatie voor productie of acceptatie. Wil je eerst rondkijken, start dan de simulatie lokaal: die draait de hele dataspace op je eigen machine.

Images en versies

Elke release bestaat uit images in ghcr.io/buildinglinks, voor linux/amd64 en linux/arm64. Als deelnemer draai je er twee:

Image	Wat erin zit	Starten met
connector	control plane, data plane en de beheeromgeving	connector of dataplane
building	de gebouwservice (optioneel)	start vanzelf

Elke versie heeft een eigen tag, zoals 0.2.0; latest wijst naar de laatst gebouwde release. Gebruik in productie altijd een vaste versie. Wat een versienummer betekent en hoe je bijwerkt, staat bij releases en upgraden. De versie van een draaiend onderdeel zie je op /healthz, met de commit erbij, bijvoorbeeld 0.2.0+4ecb134.

Het image connector heeft geen standaardcommando. Geef connector op voor de control plane en dataplane voor de data plane, en zet voor de control plane BL_UI_DIR=/app/ui/connector: zonder die instelling serveert hij geen beheeromgeving, alleen de API.

Configuratie

Je configureert elk onderdeel met environment variables die met BL_ beginnen. Wat niet in de configuratie staat, zoals de naam van je organisatie, je rollen en de koppeling met je identity provider, vul je in de beheeromgeving in. De volledige lijst staat in de naslag bij configuratie. Dit is wat een productie-installatie minimaal nodig heeft.

Control plane

BL_ENVIRONMENT=production
BL_DATABASE_URL=postgres://connector:…@db.intern:5432/connector
BL_REDIS_URL=redis://redis.intern:6379/0

# Zoals andere deelnemers de control plane zien; hieruit volgt de DID
BL_INTERNAL_URL=https://connector.example.nl
# Zoals de browser de beheeromgeving ziet (meestal hetzelfde)
BL_PUBLIC_URL=https://connector.example.nl

# De eigen data plane: intern, publiek, en zoals je apps de gateway zien
BL_DATAPLANE_URL=http://dataplane.intern:8090
BL_DATAPLANE_PUBLIC_URL=https://data.connector.example.nl
BL_DATAPLANE_BROWSER_URL=http://dataplane.intern:8090

# De Trust Authority van de dataspace waar je lid van wordt
BL_AUTHORITY_URL=https://…
BL_AUTHORITY_DID=did:web:…

BL_KEY_SOURCE=file
BL_KEY_DIR=/run/secrets/bl
BL_DID_NEXT_KEY_HASH=…
BL_SESSION_KEY=…
BL_DATA_KEY_FILE=/run/secrets/bl/data.key
BL_UI_DIR=/app/ui/connector
BL_LOG_JSON=true

Data plane

BL_ENVIRONMENT=production
BL_DATABASE_URL=postgres://connector:…@db.intern:5432/connector
BL_DATAPLANE_PUBLIC_URL=https://data.connector.example.nl
# De eigen control plane, voor meldingen over leveringen; in productie met HTTPS
BL_CONTROL_PLANE_URL=https://connector.example.nl
BL_KEY_SOURCE=file
BL_KEY_DIR=/run/secrets/bl-dataplane
# Dezelfde sleutel als de control plane
BL_DATA_KEY_FILE=/run/secrets/bl-dataplane/data.key
BL_LOG_JSON=true

Het adres en de DID van de Trust Authority krijg je van de beheerder van de dataspace. BL_SESSION_KEY maak je met bl key session; hij versleutelt de refresh token van je identity provider in elke sessie. Met een nieuwe sessiesleutel eindigen de lopende sessies bij hun volgende controle bij je identity provider, binnen 10 minuten. BL_DATA_KEY versleutelt de geheimen in de database (zie geheimen in de database); control plane en data plane krijgen dezelfde.

TechnischDe gebouwservice configureren

De gebouwservice gebruikt dezelfde database en praat met de beheer-API van de control plane. Start hem nadat je connector is ingericht: hij heeft een API-sleutel voor de beheer-API nodig, die een admin maakt onder Instellingen, API-sleutels. Zo’n sleutel heeft de rechten van een operator.

BL_DATABASE_URL=postgres://connector:…@db.intern:5432/connector
BL_CONNECTOR_URL=http://connector.intern:8080
BL_CONNECTOR_API_KEY=…
BL_BUILDING_PROXY_SECRET=…
# Optioneel: het energielabel uit EP-online
BL_EP_ONLINE_KEY=…

Geef de control plane BL_BUILDING_URL (het interne adres van de gebouwservice, standaard poort 8080) en hetzelfde BL_BUILDING_PROXY_SECRET.

TechnischWat de database nodig heeft

Control plane en data plane maken de database aan als hij nog niet bestaat. Daarvoor maken ze eerst verbinding met de database postgres op dezelfde server. Bij elke start voeren ze de migraties uit die nog niet zijn gedaan (zie upgraden). De data plane gebruikt standaard een pool van 50 verbindingen, de control plane van 10 en de gebouwservice van 5, per replica, plus een of twee verbindingen buiten de pool; zet max_connections van PostgreSQL ruim hoger dan de som. Met BL_DB_MAX_CONNECTIONS kies je een andere poolgrootte (zie dimensionering).

Omgevingen

Elke installatie heeft een omgeving, ingesteld met BL_ENVIRONMENT: production, acceptance, development of tck. Stel je niets in, dan geldt production.

Een aantal instellingen maakt ontwikkelen en testen makkelijker, maar verzwakt de beveiliging. Zulke versoepelingen zijn losse instellingen. In production en acceptance weigert een onderdeel te starten zolang er een aan staat, en noemt het ze allemaal in de foutmelding. Zo draait een acceptatieomgeving dezelfde controles als productie. In development mogen ze wel; dan staan ze als waarschuwing in het log, in /api/v1/self en als balk bovenin de beheeromgeving. De instellingen voor de conformiteitstests mogen alleen in tck.

De connector stuurt zijn omgeving mee naar de Trust Authority. Een Trust Authority in production of acceptance accepteert alleen connectors uit dezelfde omgeving, en elke omgeving is een eigen dataspace. Een testconnector wordt dus niet per ongeluk lid van de echte dataspace.

Versoepeling	Onderdeel	Toegestaan in
een http://-adres in BL_PUBLIC_URL, BL_INTERNAL_URL, BL_DATAPLANE_PUBLIC_URL of BL_AUTHORITY_URL	control plane	development, tck
een http://-adres in BL_DATAPLANE_PUBLIC_URL of BL_CONTROL_PLANE_URL	data plane	development, tck
BL_DID_HTTP_HOSTS: did:web over HTTP	control plane, data plane	development, tck
BL_PRIVATE_NETWORKS=*: tegenpartijen op elk privé-adres (een lijst met netwerken mag wel)	control plane, data plane	development, tck
BL_KEY_SOURCE=db: private sleutels in de database, of BL_VAULT_ADDR met http://	control plane, data plane	development, tck
BL_ADMIN_TOKEN: het break-glass-token	control plane, data plane	development, tck
geen BL_SESSION_KEY	control plane	development, tck
geen BL_DATA_KEY: de sleutel van de geheimen staat in de database	control plane, data plane	development, tck
een leesbare BL_DATA_KEY of BL_DATA_KEY_PREVIOUS terwijl een KMS hem moet omhullen (BL_DATA_KEY_WRAP, standaard volgens BL_KEY_SOURCE)	control plane, data plane	development, tck
BL_SETUP_CODE, BL_INVITE_CODE, BL_TRUSTED_ISSUERS	control plane	development, tck
BL_EVIDENCE_RETENTION_YEARS onder 5	data plane	development, tck
BL_TCK_MODE	control plane, data plane	tck
BL_TCK_STATIC_TOKEN, BL_TCK_DPS	control plane	tck

Let op BL_KEY_SOURCE: kies je niets, dan staan de sleutels in de database. Dat is een versoepeling, dus voor productie moet je een sleutelbron kiezen.

Sleutels

Wat je connector ondertekent, geldt als handeling van je organisatie. Waar de sleutels staan, kies je met BL_KEY_SOURCE.

Bron	Waar	Voor
pkcs11	een HSM via PKCS#11 (BL_PKCS11_MODULE, BL_PKCS11_TOKEN, BL_PKCS11_PIN of BL_PKCS11_PIN_FILE)	rollen die sturen
vault	de Transit-engine van Vault of OpenBao (BL_VAULT_ADDR, BL_VAULT_TOKEN of BL_VAULT_TOKEN_FILE, BL_VAULT_MOUNT)	rollen die sturen
file	JWK-bestanden in BL_KEY_DIR, bijvoorbeeld uit Docker- of Kubernetes-secrets	rollen die alleen lezen
env	de JWK in een environment variable	platforms die alleen dat bieden
db	de database	alleen development en tck

Met pkcs11 en vault verlaat de private sleutel de HSM of de KMS nooit; de connector vraagt er per handtekening om. Antwoordt de KMS niet, dan faalt het verzoek met 503 en gaat de connector niet ongetekend verder. Een bestand is beter dan een environment variable, want een environment variable lekt makkelijker, via docker inspect of een log.

De Trust Authority eist een sleutel die niet te exporteren is (pkcs11 of vault) voor de rollen die sturen of sturen aanbieden: bms_provider, climate_optimizer en energy_flexibility. Bij de aanmelding verklaart je connector welke bron hij gebruikt. In production en acceptance keurt de Trust Authority zo’n rol alleen goed bij een niet-exporteerbare sleutel.

TechnischWelke sleutels, en hoe je ze maakt

De connector gebruikt vier sleutels, elk met een naam:

Naam	Soort	Wat hij tekent
identity	P-256	tokens, presentaties, protocolberichten en het bewijslog (key-1 in het DID-document)
dataplane	P-256	verzoeken en antwoorden van de data plane (dataplane-1, alleen voor authenticatie)
did-update	Ed25519	de huidige versie van de did:webvh-historie
did-update-next	Ed25519	de volgende versie (pre-rotatie)

Met file maak je ze vooraf. De control plane krijgt identity.jwk, did-update.jwk, did-update-next.jwk en van de data-plane-sleutel alleen het publieke deel, als dataplane.pub.jwk. De data plane krijgt alleen dataplane.jwk.

bl key generate > identity.jwk
bl key generate > dataplane.jwk
bl key public dataplane.jwk > dataplane.pub.jwk
bl key generate --ed25519 > did-update.jwk
bl key generate --ed25519 > did-update-next.jwk
bl key generate --ed25519 > did-update-after.jwk
bl key hash did-update-after.jwk

De uitvoer van bl key hash gaat in BL_DID_NEXT_KEY_HASH. did-update-after.jwk zelf hoeft niet op de server: bewaar hem offline. Verandert het DID-document, dan tekent de connector de nieuwe versie met did-update-next en legt hij de hash uit BL_DID_NEXT_KEY_HASH vast als de sleutel daarna. Zonder die instelling publiceert hij geen nieuwe versie. Bij de wijziging daarna heeft de connector did-update-after wel nodig: zet hem dan als did-update-next.jwk op de server, met de hash van weer een nieuwe sleutel in BL_DID_NEXT_KEY_HASH.

Met pkcs11 of vault maak je de sleutels in de HSM of de KMS, met het voorvoegsel bl- (BL_PKCS11_LABEL_PREFIX, BL_VAULT_KEY_PREFIX): bl-identity en bl-dataplane als P-256 (ecdsa-p256 in Vault), bl-did-update en bl-did-update-next als Ed25519, en bl-data als AES-256-sleutel die de sleutel van de geheimen omhult (zie met een KMS of HSM). Elk onderdeel leest zijn sleutels uit zijn eigen BL_KEY_SOURCE; met een HSM of Vault tekent dus ook de data plane via de KMS.

Met env staan de sleutels in BL_IDENTITY_KEY en BL_DATAPLANE_KEY. De namen voor de did:webvh-sleutels bevatten dan een koppelteken (BL_DID-UPDATE_KEY), wat veel platforms niet toestaan. Kies daarom bij voorkeur file.

Geheimen in de database

Een paar geheimen moet de connector zelf kunnen gebruiken, dus niet alleen een hash van bewaren: de sleutels waarmee de data plane je systemen en koppelingen aanroept, en het client-secret van je identity provider. Die staan versleuteld in de database, met AES-256-GCM onder de sleutel uit BL_DATA_KEY (of het bestand in BL_DATA_KEY_FILE). Wie alleen de database of een back-up heeft, kan ze niet lezen.

bl key data > data.key

Control plane en data plane krijgen dezelfde sleutel. Zonder BL_DATA_KEY maakt de connector zelf een sleutel en bewaart hij die in de database, naast de gegevens. Dat is een versoepeling, alleen voor development en tck. Krijgt een connector die zo draaide later wel BL_DATA_KEY, dan versleutelt hij bij de start alles opnieuw en haalt hij de oude sleutel uit de database.

Elk versleuteld geheim hoort bij zijn plek: de rij, het veld en het adres dat ernaast staat (het adres van het systeem, de issuer van de IdP). Kopieert iemand het in de database naar een ander systeem, of zet hij er een ander adres naast, dan opent het niet meer, en gaat de sleutel dus ook niet naar dat adres.

Met een KMS of HSM: de sleutel omhuld

Gebruik je een KMS of HSM (BL_KEY_SOURCE=vault of pkcs11), dan staat de sleutel van de geheimen niet leesbaar in de configuratie, maar omhuld door een sleutel in die KMS. Bij de start vragen control plane en data plane de KMS één keer om hem te openen. Daarna versleutelen ze zelf, zonder de KMS bij elk verzoek. Wie de configuratie en een back-up van de database heeft, kan de geheimen dan nog steeds niet lezen.

1. Maak in de KMS de sleutel bl-data, die de sleutel van de geheimen omhult.

   • Vault of OpenBao: vault write -f transit/keys/bl-data type=aes256-gcm96. Het token van control plane en data plane heeft update nodig op transit/decrypt/bl-data, en voor het omhullen ook op transit/encrypt/bl-data.
   • HSM: een AES-256-sleutel met label bl-data die mag versleutelen en ontsleutelen, op hetzelfde token als de andere sleutels. Met OpenSC bijvoorbeeld pkcs11-tool --module <bibliotheek> --login --keygen --key-type AES:32 --label bl-data.

2. Laat de connector de sleutel omhullen, op de server:

   docker exec <container> connector wrap-data-key

   Heeft de connector al een BL_DATA_KEY, dan omhult dit commando die sleutel. Het blijft dezelfde sleutel, dus niets in de database hoeft opnieuw versleuteld te worden. Voor een nieuwe installatie maakt --new een nieuwe sleutel; draait de connector nog niet, gebruik dan docker run --rm --env-file <configuratie> <image> connector wrap-data-key --new. Het commando geeft regels als BL_DATA_KEY=bl-wrap:v1:vault:bl-data:vault:v1:…; de nieuwe sleutel zie je nooit leesbaar.

3. Zet die waarde in BL_DATA_KEY (of in het bestand van BL_DATA_KEY_FILE) van control plane én data plane, en herstart ze.

De data plane heeft daarvoor de instellingen van de KMS nodig: BL_VAULT_ADDR en BL_VAULT_TOKEN, of BL_PKCS11_MODULE, BL_PKCS11_TOKEN en BL_PKCS11_PIN. Dat geldt ook als hij met een software-sleutel tekent (BL_KEY_SOURCE=file). Hij opent de sleutel één keer, bij de start. Antwoordt de KMS dan niet, of opent de sleutel niet, dan starten control plane en data plane niet, en noemen ze de sleutel in de KMS.

Met BL_KEY_SOURCE=vault of pkcs11 starten control plane en data plane in production en acceptance niet met een leesbare BL_DATA_KEY of BL_DATA_KEY_PREVIOUS. Met BL_DATA_KEY_WRAP kies je dat los van BL_KEY_SOURCE: vault of pkcs11 om toch te omhullen, ook bij een andere sleutelbron, of none als je naast een KMS bewust een leesbare sleutel gebruikt, bijvoorbeeld bij een HSM zonder AES-sleutels.

TechnischEen andere sleutel nemen

Een nieuwe sleutel neem je in drie stappen, zonder dat de connector stilstaat:

1. Maak een nieuwe sleutel met bl key data. Geef control plane en data plane de nieuwe als BL_DATA_KEY en de oude als BL_DATA_KEY_PREVIOUS (meer oude mag, gescheiden door komma’s), en herstart ze. De control plane versleutelt bij de start alles opnieuw met de nieuwe sleutel; de oude dient alleen nog om te openen.

2. Controleer op de server dat niets de oude sleutel meer nodig heeft:

   docker exec <container> connector reencrypt-secrets --check

   Zonder --check versleutelt dit commando alles opnieuw, zoals de start dat doet.

3. Haal BL_DATA_KEY_PREVIOUS weg en herstart. Bewaar de oude sleutel tot je geen back-up meer hebt die hem nodig heeft.

Met een omhulde sleutel geeft connector wrap-data-key --new de waarden voor stap 1 ineens: een nieuwe BL_DATA_KEY en de huidige als BL_DATA_KEY_PREVIOUS, allebei omhuld.

Een nieuwe sleutel in de KMS vraagt geen nieuwe sleutel voor de geheimen. Roteer je bl-data in Vault (vault write -f transit/keys/bl-data/rotate), of maak je een nieuwe AES-sleutel op de HSM (kies die met --key <label>), dan omhult connector wrap-data-key dezelfde sleutel opnieuw. Zet de nieuwe waarde in BL_DATA_KEY en herstart. De geheimen in de database blijven zoals ze zijn. Een oude versie in Vault opent zolang je min_decryption_version niet ophoogt, en een oude sleutel op de HSM zolang je hem niet verwijdert.

Een versleuteld geheim begint met bl-enc:v1: en de id van de sleutel. Opent een geheim met een sleutel die de connector niet kent, dan start hij niet, en noemt hij die id. Dat voorkomt dat hij draait met een verkeerde BL_DATA_KEY. Geheimen van vóór deze versleuteling versleutelt hij bij de start.

Stap voor stap lid worden

Een verse connector weet niets van je organisatie. Naam, KvK-nummer en rollen vul je in de beheeromgeving in, niet in de configuratie.

1. Starten. Start de control plane en de data plane. Bij de eerste start maakt de control plane de identiteit van de connector aan in de database; de data plane wacht daarop. De control plane gaat in installatiemodus en schrijft een setup-code in het log.
2. Eerste login met de setup-code. Op het inlogscherm staat een blok Eerste installatie. Met de setup-code kom je binnen, maar alleen bij de aanmelding, de koppeling met je identity provider en de identiteit van de connector.
3. Je identity provider koppelen. Onder Instellingen, IdP-koppeling, vul je de gegevens van je identity provider in. Log daarna uit en log in via je identity provider, als iemand met de rol admin. Daarmee is de installatiemodus voorbij en werkt de setup-code niet meer. Hoe dat werkt, staat bij identity provider koppelen.
4. Je organisatie aanmelden. De wizard onder Aanmelden heeft vier stappen: je organisatie (weergavenaam, statutaire naam, KvK-nummer, contact-e-mail), de rollen die je aanvraagt, de tekenbevoegde volgens het Handelsregister, en controleren en versturen. De connector ondertekent de aanvraag met zijn identiteitssleutel en voegt de verklaring over zijn sleutelopslag toe.
5. De tekenbevoegde ondertekent. De Trust Authority mailt de tekenbevoegde een persoonlijke link naar twee documenten: de verklaring dat je organisatie het rulebook aanvaardt, en het mandaat voor deze connector. De tekenbevoegde ondertekent ze met een gekwalificeerde elektronische handtekening.
6. De Trust Authority keurt goed. Een medewerker controleert de handtekeningen en in het Handelsregister of de ondertekenaar je organisatie mag vertegenwoordigen. Pas dan kan hij goedkeuren, en alleen voor de rollen in het ondertekende mandaat.
7. Je connector haalt zijn lidmaatschapsbewijs op. De Trust Authority zet je organisatie in het register en biedt een lidmaatschapsbewijs aan. Je connector bewaart het, en vraagt het na ongeveer twintig seconden zelf op als het aanbod niet aankomt. Vanaf dan ben je lid, en vernieuwt de connector het bewijs zelf.
8. Aan de slag. Nu toont de beheeromgeving alle functies. Koppel je systemen, wijs datahouders aan of vraag toegang aan en geef je apps een sleutel.

TechnischInstallatiemodus en aanvraag in detail

De setup-code bestaat uit twaalf tekens in drie groepen van vier. Zolang de installatie niet klaar is, maakt de connector bij elke herstart een nieuwe. Er zijn tien pogingen per minuut toegestaan. Een sessie met de setup-code bereikt alleen /api/v1/me, /api/v1/self, /api/v1/onboarding, /api/v1/settings/idp en /api/v1/identity, en loopt hooguit acht uur. Koppel je een verkeerde identity provider, dan sluit je jezelf niet buiten: de code blijft geldig tot de eerste admin via je identity provider inlogt. Gaat het later mis, dan opent connector reset-idp --setup op de server de installatiemodus opnieuw (zie als niemand meer binnenkomt).

De aanvraag bevat de DID en het DSP-adres van je connector, het publieke adres van de data plane, de gevraagde rollen, de tekenbevoegde en de sleutelopslag. De connector authenticeert zich bij de Trust Authority met een token dat hij met zijn identiteitssleutel ondertekent. Zo weet de Trust Authority dat de aanvraag van de houder van die DID komt. De Trust Authority keurt een aanvraag pas goed als ze de did:webvh-historie van de connector heeft bevestigd.