Skip to content

Commit 1202f8f

Browse files
web-flowweb-flow
committed
Deploy tsl docs: a9b6974a3abd5994b5909992de1fa4f0b11461e8
1 parent d348f89 commit 1202f8f

2 files changed

Lines changed: 138 additions & 0 deletions

File tree

‎tsl/_sidebar.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66

77
- **Integration Guides**
88
- [Transport Emissie Data Autorisatie](transport-emissie-data-autorisatie.md)
9+
- [Policy inschieten als issuer](transport-emissie-data-policy.md)
910

1011
- **External Links**
1112
- [NoodleBar Docs](../noodlebar/)

‎tsl/transport-emissie-data-policy.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# Policy inschieten als issuer
2+
3+
Deze gids is voor ontwikkelaars aan de **issuer-kant** die een autorisatiebeleid (policy) rechtstreeks via de NoodleBar/TSL API aanmaken, zodat een dataservice consumer transport-emissiedata mag ophalen. Deze gids is het spiegelbeeld van [Transport Emissie Data Autorisatie](transport-emissie-data-autorisatie.md): die beschrijft hoe de datadienst-aanbieder een policy *controleert* via `explained-enforce`; deze gids beschrijft hoe de data-rechthebbende die policy *aanmaakt*.
4+
5+
In deze usecase machtigt **Bob (Greenpack, de wegvervoerder)** de dataservice consumer **David (GreenlinQ / VAA)** om bij **Charlie (BigMile)** transport-emissiedata op te halen voor een specifiek klantnummer van een teler.
6+
7+
> **Belangrijk — standaard schiet een issuer policies voor zichzelf in.** In het standaardpad is de issuer de organisatie waarmee je bent geauthenticeerd. Je mag `issuerId` weglaten (dan wordt het afgeleid uit je token) of expliciet je eigen EUID meesturen. Voor cross-organisatie aanmaak gelden extra voorwaarden: dit kan alleen voor door Poort8 goedgekeurde trusted/control plane clients met delegated rechten.
8+
9+
## Voor wie is deze gids?
10+
11+
Voor applicaties van een **data-rechthebbende (issuer)** die:
12+
13+
- zelf, buiten Keyper om, een policy aanmaken via de TSL API;
14+
- een dataservice consumer willen machtigen voor een specifiek klantnummer;
15+
- de issuer van de policy zelf zijn — je machtigt namens je eigen organisatie.
16+
17+
Deze gids beschrijft niet de Keyper approval-flow. De nadruk ligt op het standaardpad (aanmaken voor je eigen organisatie); delegated/trusted varianten worden hieronder alleen op hoofdlijnen benoemd.
18+
19+
## Rollen in deze usecase
20+
21+
| Rol | Partij | AR-veld | EUID |
22+
| --------------------------------------- | ----------------------------------------------- | ----------------------------- | ---------------- |
23+
| Data-rechthebbende / machtiger (= jezelf) | Bob — Greenpack SSC B.V. (KVK 77118421) | `issuer` / `issuerId` | `NLNHR.77118421` |
24+
| Dataservice consumer | David — GreenlinQ / VAA, Fresh Info B.V. (KVK 60756829) | `subject` / `subjectId` | `NLNHR.60756829` |
25+
| Datadienst-aanbieder | Charlie — BigMile (KVK 73401919) | `serviceProvider` | `NLNHR.73401919` |
26+
| Onderliggende rechthebbende-op-toegang | Alice — teler | `resource` / `resourceId` via klantnummer | bijv. `KLANT-7788` |
27+
28+
De EUID is opgebouwd als `NLNHR.<KVK-nummer>`. Het klantnummer van de teler is rechtstreeks de `resourceId`; er wordt in deze usecase geen resource group-hierarchie gebruikt.
29+
30+
## Procesoverzicht
31+
32+
```mermaid
33+
sequenceDiagram
34+
autonumber
35+
participant Bob as Bob (Greenpack, issuer)
36+
participant Auth as TSL Keycloak
37+
participant AR as TSL Autorisatieregister
38+
39+
Bob->>Auth: Token ophalen (client credentials)
40+
Auth-->>Bob: Bearer token
41+
Bob->>AR: POST /v1/api/policies (issuerId = Greenpack zelf)
42+
AR-->>Bob: 201 Created
43+
```
44+
45+
## Het "standaard voor jezelf"-principe
46+
47+
Wanneer Greenpack zich authenticeert via client credentials, is het verkregen token gekoppeld aan de organisatie Greenpack in het TSL-realm. Het `POST /v1/api/policies`-endpoint leidt de issuer af uit die geauthenticeerde organisatie. `issuerId` is daarom optioneel:
48+
49+
- Laat je `issuerId` weg → de issuer wordt afgeleid uit je token (Greenpack).
50+
- Zet je `issuerId` op je eigen EUID → de policy wordt aangemaakt.
51+
- Zet je `issuerId` op de EUID van een andere organisatie zonder delegated/trusted rechten → de aanvraag wordt geweigerd (`403 Forbidden`).
52+
53+
Dit is bewust: een organisatie kan alleen toegang verlenen tot data waarover zij zelf de rechthebbende is, tenzij een trusted/control plane app met delegated rechten dit expliciet namens deelnemers mag doen. De beleidsaanmaak blijft dan op hetzelfde policies-endpoint, maar met aanvullende autorisatieregels en governance. Zie ter achtergrond [NoodleBar Scopes](../noodlebar/11%20-%20Scopes.md).
54+
55+
## Voorwaarden
56+
57+
| Wat | Hoe |
58+
| --------------------------------------------------------------- | -------------------------------------------------------- |
59+
| Greenpack (issuer) geregistreerd in het TSL Participantenregister, inclusief app | Wegvervoerder / Poort8 |
60+
| API-toegang tot `noodlebar-api` | Via de catalogus in de portal |
61+
| Keycloak `client_id` + `client_secret` voor de TSL-omgeving | Wordt bij het registreren van de app uitgegeven |
62+
| Consumer (GreenlinQ / VAA) en serviceProvider (BigMile) bekend en geregistreerd | Zie het TSL Participantenregister |
63+
| Klantnummer van de teler bekend | Uit de eigen administratie van de wegvervoerder |
64+
| Voor cross-org aanmaak: trusted/control plane registratie + delegated rechten | Alleen na expliciete goedkeuring door Poort8 |
65+
66+
## Stap 1 — Token ophalen
67+
68+
Authenticeer tegen de TSL Keycloak-omgeving via OAuth 2.0 client credentials met scope `noodlebar-api`. Het verkregen `access_token` autoriseert je app om namens Greenpack de TSL API aan te roepen.
69+
70+
```
71+
POST https://auth.poort8.nl/realms/tsl/protocol/openid-connect/token
72+
Content-Type: application/x-www-form-urlencoded
73+
74+
grant_type=client_credentials
75+
&client_id=<YOUR_CLIENT_ID>
76+
&client_secret=<YOUR_CLIENT_SECRET>
77+
&scope=noodlebar-api
78+
```
79+
80+
## Policy-velden
81+
82+
| Veld | Beschrijving | Voorbeeld |
83+
| ----------------- | ----------------------------------------------------- | ------------------------ |
84+
| `issuerId` | Data-rechthebbende (standaard: jezelf), als EUID | `NLNHR.77118421` |
85+
| `subjectId` | Dataservice consumer (GreenlinQ / VAA), als EUID | `NLNHR.60756829` |
86+
| `serviceProvider` | Datadienst-aanbieder (BigMile), als EUID | `NLNHR.73401919` |
87+
| `action` | Toegestane actie | `GET` |
88+
| `resourceId` | Klantnummer van de teler | `KLANT-7788` |
89+
| `type` | Resource type | `transport-emissie-data` |
90+
| `attribute` | Data-attributen | `*` |
91+
| `useCase` | Use case-model | `unspecified` |
92+
| `expiration` | Geldigheid van het mandaat als Unix timestamp | `2147483647` |
93+
94+
Alleen `subjectId`, `action` en `resourceId` zijn technisch verplicht; de overige velden zijn optioneel. Vul `issuerId`, `serviceProvider`, `type`, `attribute` en `useCase` echter altijd in overeenstemming met de latere `explained-enforce`-check in, anders vindt het Autorisatieregister geen passende policy.
95+
96+
## Stap 2 — Policy aanmaken
97+
98+
Maak de policy aan die de consumer machtigt om voor het opgegeven klantnummer transport-emissiedata op te halen. In het standaardpad zet je `issuerId` op je eigen EUID (of laat je het veld weg).
99+
100+
```
101+
POST https://tsl.poort8.nl/v1/api/policies
102+
Authorization: Bearer <ACCESS_TOKEN>
103+
Content-Type: application/json
104+
```
105+
106+
```json
107+
{
108+
"useCase": "unspecified",
109+
"issuerId": "NLNHR.77118421",
110+
"subjectId": "NLNHR.60756829",
111+
"serviceProvider": "NLNHR.73401919",
112+
"action": "GET",
113+
"resourceId": "<KLANTNUMMER>",
114+
"type": "transport-emissie-data",
115+
"attribute": "*",
116+
"expiration": 2147483647
117+
}
118+
```
119+
120+
Een geslaagde aanmaak levert `201 Created` met de aangemaakte policy (inclusief `policyId`). Zie de [TSL API documentatie ➚](https://tsl.poort8.nl/scalar/v1) voor het volledige schema.
121+
122+
## Policy bijwerken of verwijderen
123+
124+
- `PUT /v1/api/policies` — werk een bestaande policy bij, bijvoorbeeld om de `expiration` te verlengen.
125+
- `DELETE /v1/api/policies/{id}` — verwijder een policy en trek daarmee de machtiging in.
126+
127+
De data-rechthebbende die de policy heeft aangemaakt kan deze te allen tijde intrekken. Zie de [TSL API documentatie ➚](https://tsl.poort8.nl/scalar/v1) voor de endpoint-specificaties.
128+
129+
## Omgevingsgegevens
130+
131+
| Service | URL |
132+
| ---------------- | ----------------------------------------------------------------- |
133+
| Token endpoint | `https://auth.poort8.nl/realms/tsl/protocol/openid-connect/token` |
134+
| Policies endpoint | `https://tsl.poort8.nl/v1/api/policies` |
135+
| API documentatie | [TSL API docs ➚](https://tsl.poort8.nl/scalar/v1) |
136+
137+
Vragen? Neem contact op met Poort8 via **<hello@poort8.nl>**.

0 commit comments

Comments
 (0)