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 een bestaande service-uitwisseling

Een groep organisaties die gegevens uitwisselt via het Digikoppeling WUS-profiel of ebMS2 profiel, besluit deze om te zetten naar een REST API 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 conform de FSC standaard om dit op een beheerbare en veilige manier te doen.

Delegatie

Een organisatie wil gebruik maken van de delegatie functionaliteit van FSC. Dit betekent dat de organisatie niet zelf een API gaat aanbieden of afnemen maar een andere organisatie machtigt om dit namens de organisatie te doen.

Stappen

Om gebruik te kunnen maken van FSC is het noodzakelijk dat de componenten die gebruikt worden bij de data-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, FSC als generieke voorziening willen aanbieden of gebruik willen maken van delegatie 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.

Bekijk de Groepen pagina voor een overzicht van beschikbare Groepen en best practices voor het oprichten van nieuwe Groepen.

U kunt in de Directory van een Groep Services en groepsleden (Peers) opzoeken. 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 FSC 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 combinatie van beide? Zie implementatie scenarios
• Gaat u zelf APIs aanbieden of afnemen hoe maakt u dan 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 u 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 aan de Outway(s) en API’s aan de Inway(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. x

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 niet zelf de Services gaat aanbieden of afnemen, maar andere machtigt om dat namens uw organisatie te doen, gebruikt u dezelfde aankondiging. Als u gebruikt maakt van de OpenFSC componenten dan zal de Manager zichzelf automatisch aanmelden bij het opstarten.

3. Publiceer Services (optioneel)

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)

De ServicePublicationGrant bevat de volgende gegevens die worden vastgelegd in de Directory:

1. PeerID van de Directory
2. PeerID van de Service aanbieder, uw Peer ID
3. De naam van de Service. Dit is een string van minimaal 3 en maximaal 255 karakters
4. Protocol dat gebruikt moet worden, dit is of HTTP 1.1 of HTTP 2

4. Inrichten FSC componenten voor de data-uitwisseling (optioneel)

Naast de aanmelding bij een Groep en de inrichting van de Manager, moeten de componenten ingericht voor de daadwerkelijke data-uitwisseling. Deze componenten heeft u alleen nodig als u zelf APIs gaat aanbieden of afnemen.

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. Als u uitsluitend gebruik maakt van de delegatie functionaliteit dan heeft u geen van 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. Als u gebruikt maakt van OpenFSC dan kunt u hiervoor uw eigen Autorisatie Service als plug-in definiëren. De Inway en de Outway sturen beide informatie over het request naar de Autorisatie Service. De Autorisatie Service moet de interface implementeren die is gespecificeerd voor de Inway en de Outway

5. Maak Service connecties aan (optioneel)

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.

Maak 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.

6. Delegateer de machtiging voor het afnemen of publiceren van Services (optioneel)

Met FSC is het mogelijk om andere organisaties te machtigen om Services namens uw organisatie te publiceren en/of te bevragen.

Als u een organisatie wilt machtigen om een Service namens u te publiceren gebruikt u een DelegatedServicePublicationGrant. De inhoud is nagenoeg gelijk aan de ServicePublicationGrant alleen bevat deze ook een Delegator object met daarin uw Peer ID. De Peer ID van de Service aanbieder is het Peer ID van degene die u machtig om namens uw organisatie de Service aan te bieden.

Als u een organisatie wilt machtigen om een Service namens u af te nemen dan gebruikt u een DelegatedServiceConnectionGrant. De inhoud is nagenoeg gelijk aan de ServiceConnectionGrant alleen bevat deze ook een Delegator object met daarin uw Peer ID. Het Outway object bevat het Peer ID van degene die u machtigt om namens uw organisatie de Service af te nemen.

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 Groepen
• U heeft bepaald hoe u de FSC componenten wil realiseren. Zie Implementatatie scenarios
• Certificaten en domeinnamen voor Inway, Manager en Outway zijn verkregen en bepaald
• Netwerkpolicies zijn bijgewerkt en poorten zijn bereikbaar. Zie Netwerk overview