new preview build

OAuth-Inleiding/opaque_token/LICENSE

@@ -0,0 +1,17 @@
+The W3C SOFTWARE NOTICE AND LICENSE (W3C)
+
+https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document
+
+This work is being provided by the copyright holders under the following license. By obtaining and/or copying this work, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions.
+
+Permission to copy, modify, and distribute this work, with or without modification, for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the work or portions thereof, including modifications:
+1. The full text of this NOTICE in a location viewable to users of the redistributed or derivative work.
+2. Any pre-existing intellectual property disclaimers, notices, or terms and conditions. If none exist, the W3C Software and Document Short Notice (https://www.w3.org/Consortium/Legal/2015/copyright-software-short-notice.html) should be included.
+3. Notice of any changes or modifications, through a copyright statement on the new code or document such as "This software or document includes material copied from or derived from [title and URI of the W3C document]. Copyright © [YEAR] W3C® (MIT, ERCIM, Keio, Beihang)."
+
+
+THIS WORK IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENT WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
+
+COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENT.
+
+The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to the work without specific, written prior permission. Title to copyright in this work will at all times remain with copyright holders.

OAuth-Inleiding/opaque_token/Orkestratie/inleiding_orkestratie.md

@@ -0,0 +1,55 @@
+# Inleiding
+
+ API orkestratie is een cruciaal concept binnen de moderne  ICT-architectuur, vooral in de context van het integreren van  verschillende applicaties en services. Het stelt organisaties in staat  om complexe workflows te beheren door verschillende API's te coördineren en hun interacties te stroomlijnen. Dit biedt voordelen zoals verhoogde efficiëntie, verbeterde dataconsistentie en een betere  gebruikerservaring.
+
+## Wat is API Orkestratie?
+
+API orkestratie verwijst naar het proces waarbij meerdere  API-aanroepen worden gecoördineerd om een specifieke taak of workflow  uit te voeren. Dit kan bijvoorbeeld inhouden dat gegevens van  verschillende bronnen worden samengevoegd of dat meerdere services in  een bepaalde volgorde worden aangeroepen om een einddoel te bereiken.
+
+## Uitgangspunten
+
+Uitgangspunt is de bestaande registraties met de bestaande registratie-processen.
+
+Met betrekking tot security zijn er diverse aandachtspunten:
+
+- Data integriteit. Dmv signing zou van individuele gegevens kunnen worden aangetoond wat de authentieke bron is en of dat deze identiek zijn aan de authentieke gegevens. Interessant vraagstuk is wat dit betekent als gegevens tijdens het orkestreren worden getransformeerd. Mogelijk raakvlakken met de [RDF Dataset Canonicalization](https://www.w3.org/TR/rdf-canon/) standaard.
+- Authenticatie/autorisatie. Bij orkestratie worden verschillende requests uitgevoerd vanuit mogelijk verschillende identiteiten, verschillende identity stores en verschillende scopes/audiences. Hierbij kan zowel een transparant als niet-transparant model worden toegepast. Deze willen we beiden beschrijven. Relevante standaarden zijn [FSC](https://commonground.gitlab.io/standards/fsc/) en [OAuth Token Exchange](https://datatracker.ietf.org/doc/html/rfc8693).
+
+## Use cases
+
+Er zijn reeds enkele voorbeelde van uwe cases waarbij orkestratie een belangrijke rol speelt:
+
+- [IMX-Geo](https://www.geonovum.nl/geo-standaarden/imx-geo-semantisch-model-basis-en-kernregistraties) (Geonovum), Bestuurlijke Gebieden (BZK), Gebouwdossier (Kadaster)
+- Diverse Digital Twin use cases (navraag doen bij Bart en/of Koos)
+- [Digilab](https://digilab.overheid.nl/) use cases: opkopersbescherming (RVIG/VNG), maximale huurverhoging (Belastingdienst)
+
+## Aandachtsgebieden van Orkestratie
+
+Interessante onderwerpen die sterk gerelateerd zijn aan orkestratie zij:
+
+- Fouttolerantie (graceful degradation, resiliency, retry policies, automatisch terugmelden).
+- Doodlopende links (afwijkingen van informatiemodel, actualiteits-issues, etc.)
+- Mapping en herleidbaarheid (zie IMX)
+- Historie en tijdreizen (separate module in concept)
+- Batching (separate module in concept)
+
+- Orkestratie in OAuth (o.a. Token Exchange, eHerkenning, FSC, etc.)
+
+## IMX
+
+Kadaster heeft in samenwerking met Geonovum het IMX initiatief gestart. Dit initiatief heeft als ambitie om basisregistraties (en andere bronnen) in samenhang te kunnen bevragen door middel van API orkestratie. Om op een efficiënte manier te kunnen orkestreren moeten bron API’s voldoen aan diverse randvoorwaarden. De uitdaging is om te onderzoeken welke randvoorwaarden dit zijn en op welke manier deze gestandaardiseerd zouden kunnen worden als design rules.
+
+## Arazzo
+
+De [Arazzo-specificatie](https://www.openapis.org/arazzo) is een nieuwe, door de gemeenschap gedreven  standaard die is ontwikkeld onder het OpenAPI-initiatief, met als doel  de documentatie en interactie van API's te verbeteren. Het biedt een **programmeertaal-onafhankelijk** kader om reeksen API-aanroepen en hun afhankelijkheden te definiëren, waardoor de communicatie van workflows duidelijker wordt.
+
+Dit project bevindt zich echter nog in een vroeg stadium. Ook is het maar de vraag in hoeverre (commerciële) software vendors erbij gebaat zouden zijn een dergelijke standaard te implenteren. Verder wordt de kanttekening geplaatst dat benodigde stappen bij orkestratie ook dynamisch kunnen worden berekend, zoals bij IMX wordt gedaan. In dat geval is het specificeren van een workflow niet relevant.
+
+### Belangrijkste Kenmerken
+
+- **Deterministische Workflows**: Arazzo maakt zowel menselijke leesbare als machine-leesbare  documentatie mogelijk, wat de ervaring voor API-aanbieders en  -gebruikers verbetert.
+- **Toepassingen**: Interactieve workflowdocumentatie Automatische documentgeneratie Code- en SDK-generatie op basis van functionele gebruiksgevallen Automatisering van testgevallen en nalevingscontroles AI-gestuurde deterministische API-aanroep
+
+### Relatie met OpenAPI
+
+Arazzo aanvult de bestaande OpenAPI-specificatie door beschrijvingen van **groepen API's** en hun interacties mogelijk te maken, in plaats van alleen individuele  API's. Deze bredere scope ondersteunt automatisering en codegeneratie,  met als uiteindelijke doel de waarde die uit API's wordt gehaald te  maximaliseren.Het project staat open voor deelname van de gemeenschap, met  middelen beschikbaar op GitHub voor degenen die geïnteresseerd zijn in  bijdragen of meer willen leren over de specificatie.

OAuth-Inleiding/opaque_token/Orkestratie/orkestratie_beveiliging.md

@@ -0,0 +1,131 @@
+# Orkestratie beveiliging
+
+## Context
+
+Orkestratie services bieden over het algemeen een oplossing voor een complexe vraag en een antwoord wat input uit meerdere databronnen bevat.  Conform de [Api Strategie architectuur typologie](https://docs.geostandaarden.nl/api/API-Strategie-architectuur/#systeem-proces-convenience) is het daarmee een zogenaamde "Composite API" die meerdere systeem API's aanroept.
+
+Voor de beveiliging van een dergelijke composite API is het belangrijkste verschil of de API kennis heeft van de inhoud van de gegevensuitwisseling en  van die inhoud ook logging bijhoudt of dat de Composite API geen kennis heeft van de inhoud en daarmee ook geen logging hoeft bij te houden. 
+
+Wanneer de Composite API geen kennis heeft van de inhoud en geen logging vasthoud noemen we dit transparant.
+
+> we focussen in deze context op het bevragen van services en niet op de transactionele kant 
+>
+> We gaan in onderstaande situaties er vanuit dat er vertrouwelijke gegevens worden bevraagd. Voor het bevragen open data is dergelijke beveiliging niet noodzakelijk.
+>
+> We gaan er van uit dat OAuth wordt gebruikt voor de authorisatie van de Services.
+
+## Use cases
+
+In deze context onderkennen we vier use cases
+
+- De Client bevraagt direct de bronnen en heeft de orkestratie daarmee ingebed in de client software (deze use case wordt verder niet uitgediept)
+- De User Identity wordt onderbroken door de orkestratie (Implicit Identity reuse)
+- De User Identity propageert door tot de bronnen (Identity propagation)
+- De user bevraagt 1 bron en de service van de bron bevraagt nog een andere bron zonder dat de user of client hier weet van heeft (deze use case wordt verder niet uitgediept)
+
+## Begrippen
+
+- OAuth:
+- Identity propagation:
+- Identity reuse:
+- Vertrouwelijke gegevens:
+- Open Data:
+- Token Exchange:
+- Identity Service Provider:
+
+## Implicit Identity reuse - token based
+
+### Rationale
+
+- er is een ontkoppeling tussen de Services en de client. Dit is geen probleem bij open data maar wel bij vertrouwelijke gegevens. 
+- In de praktijk is dit wel hoe bijvoorbeeld een huisarts werkt en hoe veel balies en overheidsorganisaties werken.
+- De token / OAuth flow die wordt geschetst kan in deze situaties ook een andere vorm van authenticatie of identificatie zijn 
+- Deze situatie is vaak in gebruik binnen 1 organisatie waarbij alle onderdelen van de orkestratie onder verantwoording van 1 organisatie vallen en de User ook in dienst is bij deze organisatie
+
+### Identity
+
+- Service A,B & C kennen de identity van Service Y, niet van Client X of User U
+
+- Service Y kent de Identity van User U en of Client X
+
+### Authenticiteit
+
+- De Authenticiteit van Client X wordt gegarandeerd door Identity Service Provider Z
+
+- De Authenticiteit van Client X wordt geverifieerd door Service Y en Identity Service Provider Z
+
+- De Authenticiteit van Service Y moet worden geverifieerd door Client X
+
+- De Authenticiteit van Service A,B & C moet worden geverifieerd door Service Y
+
+### Autorisatie
+
+- De autorisatie is bepaald in en door de Service provider Y, Service A,B & C weten niet dat hun gegevens wordt gedeeld met Client X en User U of een andere client of user
+
+- Service Y moet geautoriseerd zijn bij Service A,B & C om namens Client X en/of User U gegevens op te vragen
+
+- Service A,B & C delegeren toegang tot hun gegevens aan Service Y
+
+![Schematische weergave van Niet Transparante-Orkestratie](../../../media/orkestratie-Niet-transparante-Orkestratie.drawio.svg)
+
+### Implicaties
+
+- Er is een sterke vertrouwensband nodig tussen zowel de Client & Service alsook de Service en de Services. Deze vertrouwensband zal waarschijnlijk worden vertaald naar eisen, audits en contracten.
+- De aanbieder van Service Y, stel een gemeente, zal zorgvuldig moeten borgen en vastleggen dat de service die ze aanbieden alleen gegevens opvraagt bij de Services wanneer daar ook een expliciete vraag voor is van de User U. Er moet worden voorkomen dat in deze situatie een kwaadwillende toegang krijgt tot de service en daarmee alle Services van alle users kan bevragen.
+- Deze oplossing is technisch waarschijnlijk makkelijker te realiseren en vaker in gebruik maar kent ook veel grotere risico's dan de transparante orkestratie.
+
+## Identity propagation - token based
+
+### Rationale
+
+Er is een direct verband tussen de Services en de identity van de client/gebruiker. Dit is maakt het mogelijk om ook privacy vertrouwelijke gegevens veilig te gebruiken in de orkestratie. 
+- In de praktijk wordt deze vorm van orkestratie ook vaak client side gedaan door vanuit de client direct meerdere API's aan te roepen,
+- en is er bij de orkestratie service vaak geen sprake van filtering van gegevens,
+- het betreft dan meer een bundeling van meerdere bronnen dan echt orkestratie,
+- het lijkt bij bevragingen vaak meer op het composition patroon dan een orkestratie patroon.
+
+### Identity
+
+- Service A,B&C kennen de Identity van user U 
+  (de recources zijn namelijk aan de User gerelateerd of de User is vanuit zijn functie gemachtigd de Services te raadplegen)
+- Service Y kent de Identity van user U niet
+
+### Authenticiteit
+
+- De Authenticiteit van Client X wordt gegarandeerd door Identity Service Provider Z
+- De Authenticiteit van Service Y wordt geverifieerd door A,B & C 
+- De Authenticiteit van Service Y moet worden geverifieerd door Client X
+- De Authenticiteit van Service A,B & C moet worden geverifieerd door Service Y
+
+### Autorisatie
+
+- De autorisatie is per Service dynamisch in te stellen
+- Service Y moet overweg kunnen met het feit dat Service A,B & C de autorisatie kunnen weigeren
+
+![Schematische weergave van Transparante-Orkestratie](../../../media/orkestratie-Transparante-Orkestratie.drawio.svg)
+
+## Variatie - Federated Identity Propagation
+
+1. Identity Service Provider Z kan ook de toegang zijn tot een gefedereerde omgeving van Identity providers waarbij Z door middel van  [OAuth Token Exchange](https://datatracker.ietf.org/doc/html/rfc8693) de Access tokens worden opgehaald bij de Identity providers van de verschillende Services en deze tokens door de client worden meegegeven bij het request
+
+![Schematische weergave van Federatieve Transparante-Orkestratie](../../../media/orkestratie-Federatief-Transparante-Orkestratie.drawio.svg)
+
+### Implicaties Identity propagation
+
+- Er is een sterke vertrouwensband nodig tussen zowel de Client & Service alsook de composite Service en de system Services. Deze vertrouwensband zal waarschijnlijk worden vertaald naar eisen, audits en contracten om te voorkomen dat de Service Y toch de gegevens inziet die de resouces terugsturen aan de client.
+
+- Organisatorisch zullen X, Y, Z, A & B praktisch gezien niet allemaal van verschillende organisaties zijn. Het is logischer wanneer A, B & Y van 1 organisatie zijn of wanneer X & Y van 1 organisatie zijn. Service Y wordt namelijk alleen ontwikkeld als er een vraag is en een voordeel voor de Services of de client.
+
+- Afhankelijk van de situatie is het waarschijnlijk dat Identity provider Z een algemene dienst is van de overheid (denk aan DigiD of eHerkenning) of dat dit een dienst is van 1 van de organisaties in de orkestratie.
+
+## Conclusies en Adviezen
+
+- Voor een moderne API architectuur is een identity service provider cruciaal.
+
+- Niet alleen om IAM toe te passen op de eigen Service maar ook om achterliggende services aan te kunnen spreken.
+
+- Met de groei van het aantal system APIs en vraag naar Composite APIs groeit het beveiligingsvraagstuk exponentieel mee.
+
+- Bereid API’s voor op de IAM mbv Oauth.
+
+- Houd er rekening mee en faciliteer token exchange als onderdeel van je roadmap / groei / maturity level.

OAuth-Inleiding/opaque_token/Use-cases/Use case Digitale Delta.md

@@ -0,0 +1,12 @@
+## Overview
+
+The Digitale Delta API provides access to measurements and related information.
+Consumers of the data, in general, will be automated processes or systems such as Business Intelligence or GIS systems.
+Since not all data may be open or public, access to certain data must be restricted.
+
+For this scenario, an interactive authentication method is not feasible and not all devices may equiped with PKI Overheid certificates.
+
+Next to requesting data, the API allows for adding or removing data by using import files or sensor devices. 
+
+Client credential flow does offer the required functionality.
+

OAuth-Inleiding/opaque_token/Use-cases/Usecase AirSensors.md

@@ -0,0 +1,29 @@
+# Rights delegation Air sensors network
+
+## Overview
+
+With the deployment of an endless number of air sensors the quality of the gathered data depends on the security of the sensor network. In this usecase the sensors are connected to a LoRaWAN network and equiped with a unique ID (GUID) for authentication. This prevents the injection of unindentifiable data into the network.
+
+## Resource owner
+
+The resource owner is the sensor owner. In this case the the sensors are provided to citizens by the Resource owner, e.g. a local government or city.
+
+## Client
+
+The Air sensor itself functions as a client, uploading each measurement to the API of the Resource owner via the LoRaWAN network.
+
+## Authorization server
+
+In this use case the resource owner also provides the Authorization server. The unique id's of the sensors are preloaded in the authorization server.
+
+## Resource server
+
+The resource server is provided by the sensor provider, e.g. a local government or city, the resource server provides the API where all sensors write their data.
+
+## Scopes & claims
+
+not applicable
+
+## Rationale
+
+To mitigate the risk of incorrect data or manipulation of sensor data the sensor will connect to the authorization server first while onboarding (Step 1). The authorization server checks the provided sensor ID and provides the sensor with a token (Step 2). The sensor then starts to collect data and upload the data to the provided API and includes the token with each request to the resource server.

OAuth-Inleiding/opaque_token/Use-cases/Usecase DSO.md

@@ -0,0 +1,29 @@
+# Use Case Digital System Environmental Law
+
+## Overview
+
+In this use case, the client credential flow is used in a digital system that enables citizens to request permits for activities they want to undertake in their environment. For example when a citizen wants to cut down a tree or change the exterior of their house they have to request a permit. The citizen can start a permit request in the web interface of the Digitaal Stelsel Omgevingswet - Digital System Environmental Law (hereafter: DSO) and this system will determine what local authorized authority (e.g. a municipality) is responsible. Once the permit request is ready, a trigger is sent to the system of the local authorized authority to use the client credential flow to retrieve the data associated with the request. The request can then be completed in the client software of that local authority.
+
+## Resource owner
+
+The resource owner is the citizen that provided the information during the permit request. 
+
+## Client
+
+In this use case the client is the software that the authorized authority (e.g. the local authority, municipality, county etc.) who wants to retrieve information from the digital system, uses. 
+
+## Authorization server
+
+The authorization server is owned by the DSO, it is part of their API Management platform. 
+
+## Resource server
+
+The resource server is the backend server of the DSO where the permit request is available.
+
+## Scopes & claims
+
+The scopes and claims used in this system are defined by the DSO, and are related to the CRUD actions of the API's available. 
+
+## Rationale
+
+The DSO exposes API's secured on different levels. To standardise as much as possible, OAuth is used in several of the authentication and authorization flows. Therefore besides the Authorization code flow where an enduser is involved, the client credentials flow is used between systems in order to use the same authorization mechanism for as many usecases as possible.