FSC in uw organisatie

Onderstaand schema schetst de stappen en de aanleidingen om de FSC standaard te adopteren als organisatie.

Aanleidingen

Er kunnen verschillende aanleidingen zijn om FSC te adopteren als standaard. De meest voorkomende worden hieronder verder uitgewerkt.

Migratie van bestaande service-uitwisseling

Een Groep organisaties die gegevens uitwisselt via het WUS-profiel of ebMS2 profiel, besluit deze om te zetten naar een REST profiel. Dit betekent dat bekend is welke services aangeboden worden, afgenomen worden en welke groepsleden er zijn.

Invoering van FSC standaard als generieke voorziening

Een organisatie besluit vanuit haar architectuur visie de FSC standaard te implementeren om het uitwisselen van gegevens te bevorderen. Hiervoor wordt binnen de organisatie een generieke voorziening opgezet waar API’s op aangesloten kunnen worden die de organisatie wil aanbieden en via welke API’s geconsumeerd kunnen worden.

Aanbieden van een service

Een organisatie wil een service aanbieden aan andere organisaties conform de FSC standaard om dit op een beheerbare en veilige manier te doen.

Afnemen van een service

Een organisatie wil een service afnemen, deze wordt aangeboden via FSC.

Stappen

Om gebruik te kunnen maken van FSC is het noodzakelijk dat de runtime componenten die gebruikt worden bij de informatie-uitwisseling geïnstalleerd worden. Parallel hieraan kunnen de on-boarding stappen voor de Groep uitgevoerd worden.

1. Bepaal bij welke Groep u zich wil aansluiten

Een Groep is een verzameling van partijen die conform de FSC-specificatie gebruik maken van elkaars services.

Voor organisaties die een service willen afnemen, een service willen aanbieden of FSC als generieke voorziening willen aanbieden is de eerste stap te bepalen bij welke Groepen zij zich wil aansluiten

Organisaties die bestaande service migreren weten bij welke Groep zij zich willen aansluiten. Zie fsc-standaard.nl voor een overzicht van beschikbare Groepen en best practices voor het oprichten van nieuwe Groepen.

Een Groep bevat:

1. Eén of meer trust anchors, dat de organisatie validatie uitvoert. In het geval van de Groep Nationale Overheid is dit een PKI-overheidscertificaat.
2. Een Groep ID.
3. Eisen aan de ID van de partij (Peer ID).
4. Eisen aan de naam van de partij (Peer name).
5. Een Directory waarin de peers en services gepubliceerd worden.
6. Een beschrijving welke poorten worden gebruikt voor het managen van het verkeer, 8443 voor het bevragen van de Directory en het publiceren van de services in de Directory. 443 voor
7. Eisen voor TLS en cypher suites.

U kunt in de Directory van een Groep services opzoeken via de Directory ui en Peers opvragen. Op deze manier kunt u bepalen of u deel wil uitmaken van de Groep. Deze informatie kan ook via de API opgevraagd worden.

2. Bepaal architectuur

Voordat er begonnen kan worden met het inrichten van de runtime componenten, is het van belang om de architectuur te bepalen. In deze architectuur moet de volgende vragen beantwoord worden:

• Waar plaatst u de Inway, Manager en de Outway in uw netwerk?
• Welke implementatie gaat u gebruiken? De referentie-implementatie, uw eigen implementatie, of een implementatie van derden? Zie
• Maakt u een onderscheid in verschillende Outway(s) en Inway(s), bijvoorbeeld per domein?
• Hoe gaat u om met back-up en recovery?
• Wat zijn de beveiligingseisen?
• Welke netwerk policies moeten ingericht worden/aangepast worden?
• Hoe gaat u om met autorisatie van de services? Regelt dat in uw services of maakt u gebruik van centrale autorisatie die u aan uw Inway en Outway wil koppelen?
• Hoe verbindt u uw clients en API’s aan de Inway(s) en de Outway(s)?
• Hoeveel omgevingen zet u op? Maakt u gebruik van OTAP voor de Open FSC-componenten?
• …

3. Meld u aan bij een Groep

Als u heeft bepaald bij welke Groep u zich aansluit, kunt u zich aanmelden bij die groep en services publiceren. Onderstaande figuur geeft de stappen weer die hiervoor uitgevoerd moeten worden.

1. Richt Manager in voor Groep

Voordat u zich kunt registeren in de Directory, moet u een Manager hebben ingericht voor de Groep. Zie https://docs.open-fsc.nl/fsc-in-production/deployment-strategies voor een instructie.

2. Kondig Peer aan in de Directory van de Groep

Registratie gebeurt door uzelf aan te kondigen bij de Directory. De Directory legt dan de Peer ID, Peer name en het Manager adres vast. Dit betekent dat als iemand de lijst van Groepsleden opvraagt, uw gegevens worden getoond.

Het aankondigen gebeurt via ‘/announce’ met als headerparameter het adres van de Manager die gebruikt wordt. Als u zelf niet de services gaat aanbieden of afnemen, maar een gedelegeerde bent, gebruikt u dezelfde aankondiging.

3. Publiceer services

Het is niet verplicht om services te publiceren in de Directory van de Groep: u kunt ook gegevens uitwisselen met partijen uit de Groep die niet gepubliceerd zijn. Voor de vindbaarheid van de services is het aan te raden deze wel te publiceren.

Voor iedere service die u wilt publiceren in de Directory wordt een contract vastgelegd in de Directory met de volgende gegevens:

1. Een UUID voor het veld contract.iv. U bent verantwoordelijk voor het aanleveren van een UUID.
2. Een hash algoritme dat gebruikt wordt voor de handtekening van het contract
3. Datum dat het contract is gecreëerd. Dit kan niet in de toekomst liggen
4. Datum geldig vanaf (validity_not_before)
5. Datum geldig tot (validity_not_after), deze datum moet groter zijn dan de datum geldig vanaf en moet in de toekomst liggen.
6. De service die u wil publiceren (ServicePublicationGrant)

Van services die u publiceert worden de volgende gegevens vastgelegd in de Directory:

1. PeerID, uw OIN
2. De naam van de service. Dit is een string van minimaal 3 en maximaal 255 karakters
3. Protocol dat gebruikt moet worden, dit is of HTTP 1.1 of HTTP 2

Delegatie

Als u zelf niet de bron bent van de service, maar dit doet namens een bronhouder, dan publiceert u de service via een DelegatedServicePublicationGrant. Voor meer informatie zie https://gitdocumentatie.logius.nl/publicatie/fsc/core/1.1.1/#service-discovery

5. Richt FSC runtime componenten in

Naast de aanmelding bij een Groep en de inrichting van de Manager, moeten de runtime componenten ingericht worden. Deze componenten zijn nodig voor de daadwerkelijke uitwisseling.

Inrichten Inway, Outway en Transactielogging

Merk op dat u geen Inway nodig heeft, als u geen services publiceert en dat u geen Outway nodig heeft als u geen services afneemt. Als u een generieke voorziening implementeert voor uw organisatie heeft u beide nodig.

Inrichten autorisatie

Als u de toegang tot uw eigen gepubliceerde services wil beperken of wil beperken welke services clients kunnen aanroepen, kunt u autorisatie inrichten op de Inway en de Outway. Hiervoor kunt u uw eigen autorisatie service als plug-in definiëren. De Inway en de Outway sturen header informatie (en het pad en certficaat in het geval van de Outway) naar de autorisatieservice. De autorisatie service moet de interface implementeren die is gespecificeerd voor de Inway (zie https://gitlab.com/commonground/fsc/open-fsc/-/blob/main/inway/authorization-interface.yaml) en de Outway (zie https://gitlab.com/commonground/fsc/open-fsc/-/blob/main/outway/authorization-interface.yaml)

6. Vraag service connecties aan

De laatste stap is het aanvragen van service connecties bij de partijen van wie u de service wil gebruiken. Als u geen services wil afnemen kunt u deze stap overslaan. Onderstaande figuur beschrijft de stappen die hiervoor gezet moeten worden.

Zoek Manager adres en service op in Directory

U kunt pas gebruik maken van een service als er een contract is tussen u en de aanbieder van de service. Dit contract wordt afgesloten tussen de manager component van de aanbieder en uw manager component. In de Directory kunt u de url (adres) van de manager van de aanbieder opzoeken en de naam van de service.

Vraag ServiceConnectionGrant aan

Voor het aanvragen van een service connection grant roept u met uw manager de manager van de partij aan die de service verzorgt in de Groep waar u beiden toe behoort. In die call geeft u de volgende gegevens mee:

1. Een IV. Een initialisatievector voor het contract. Dit is een UUID van 36 karakters
2. Groep ID. Het ID van de Groep waarbinnen de uitwisseling valt.
3. Geldigheid a. Datum geldig vanaf (validity_not_before) b. Datum geldig tot (validity_not_after), deze datum moet groter zijn dan de datum geldig vanaf en moet in de toekomst liggen.
4. Grants. Een of meerdere a. GrantServiceConnection i. Type (GRANT_SERVICE_CONNECTION) ii. Outway
5. PeerID. Uw Peer ID.
6. Public key thumbprint b. Service i. Peer ID van de organisatie waarvan u de service wil gebruiken ii. Servicenaam
7. Hash-algoritme (HASH_ALGORITHM_SHA3_512)
8. Datum dat het contract is gecreëerd. Dit kan niet in de toekomst liggen
9. Acceptatie handtekening.

Als u gebruik wil maken van een service namens een Peer, dan doet u dat via een DelegatedServiceConnectionGrant

Koppel clients aan de Outway

De API-client roept niet rechtstreeks de service aan van de aanbieder, maar dit wordt gerouteerd via de Outway. Dit betekent dat de client een call moet doen naar de Outway. De Outway verzorgt dan de connectiviteit en de routering naar de Inway van de partij die service aanbiedt.

Checklist voorbereiding FSC

Deze checklist kunt u gebruiken ter voorbereiding van installatie in een van de OTAP omgevingen

• Groep ID en Directory Peer ID en Directory Peer name zijn bekend. Zie Aansluiten op de Directory
• Componenten waarmee Inway, Manager en Outway worden gerealiseerd zijn geïdentificeerd. Zie Implementatatie scenarios
• Certificaten en domeinnamen voor Inway, Manager en Outway zijn beschikbaar voor het domein
• Netwerkpolicies zijn geupdate en poorten zijn bereikbaar. Zie Netwerk overview