Release: OAuth-NL-profiel

api/oauth/Use-cases/Use case Digitale Delta.md

@@ -0,0 +1,49 @@
+# Use Case Digitale Delta
+
+## Overview
+
+The Digitale Delta API provides access to measurements and related information.
+It is not an specific implementation of an API, but a template that defines its behaviour and its resources.
+
+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.
+However, also browser based solutions, or Excel users, can be consumers of the data.
+
+For automated requests, interactive scenario's are no feasible. A certificate scenario may not be feasible either.
+
+Next to cunsuming data, the API allows for adding or removing data by using import files or sensor devices.
+
+This also is (mostly) an automated proces. The same situation applies: interactive scenario's may not be usable, and PKI certificates may not be able to be deployed on sensory devices.
+
+The addition to the Authorization Code Flow, the Client Credential Flow can be used to cover the scenario's.
+
+## Resource owner
+
+The resource owner depends on the implementation of the API. In general, it is the provider of the implementation of the API.
+
+## Client
+
+Clients can be a range of systems: 
+
+- Business Intelligence
+- GIS
+- Artificial Intelligence/Machine Learning
+- REST service consumers
+- Web browsers
+- Excel users
+
+## 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.

api/oauth/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.

api/oauth/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.

api/oauth/Use-cases/Usecase rightsdelegation BAG.md

@@ -0,0 +1,25 @@
+# Rights delegation key registry Buildings & adresses
+
+## Overview
+Key registries in Dutch government often have a single registry where all data is collected but multiple source holders are responsible for maintaining parts of the data.  Source holders, such as municipalities, should not be allowed to modify each others data without permission. It is very common to either have commercial cloud providers or partnerships of cooperating municipalities maintain a key registry on behalf of multiple sourceholders. Currently Dutch Cadastre hosts multiple key registries where this is the case each with its own application level solution to allow for this. Within the key registry adresses and buildings a PoC has been executed to show how OAuth can solve this in a generic way. This has the advantage of cutting down on custom code and affering a uniform procedure to source holders who often maintain multiple key registries at Dutch Cadastre.
+
+## Resource owner
+A municipality that is legally required to maintain information on its buildings and adresses.
+
+## Client
+A cloud provider or partnership of cooperating municipalities hosts an application that operates on behalf of the legal entity (municipality) to update and maintain the key registry Buildings & Adresses. This application acts as client that connects to the API of the Dutch Cadastre.
+
+## Authorization server
+manager
+The authorization server is hosted by Dutch Cadastre and provides (among other things) authorizations to municipalities to update and maintain data on buildings and adresses.
+
+## Resource server
+The central server that hosts the key registry for buildings and adresses at dutch Cadastre.
+
+## Scopes & claims
+A JWT token containting the following claim is used:
+The claim "cdi" contains the ID of the municipality delegating its rights to maintain the key registry.
+The delegatee, the cloud provider gets a token containing this claim from the authorization server when providing its credentials. The actual delegation, provding client credentials to the client and delegating rights from the resource owner to the cleint is done out of band as this is not part of the client credentials flow.
+
+## Rationale
+The client credentials flow is used instead of the authorization codeflow because the resource owner is a legal entity and the client acts on behalf of this legal entity, not the individual user working with the application.