Integreren met KLIP-webservices

Voor de authenticatie en autorisatie van gebruikers maakt KLIP gebruik van Geosecure. Informatie Vlaanderen biedt een webtoepassing aan waarin gebruikers de volledige flow van KLIP kunnen uitvoeren. Voor het indienen, ophalen, bevestigen en beantwoorden van planaanvragen stelt Informatie Vlaanderen ook services ter beschikking. Deze services kunnen geïntegreerd worden in eigen gebruikerssoftware.

Te volgen stappen om met KLIP te integreren:

1.  Registratie organisatie

De allereerste stap die je moet zetten, is je organisatie registreren bij Informatie Vlaanderen. Neem hiervoor contact op met de Helpdesk van Informatie Vlaanderen en vermeld eventueel een toegangsbeheerder voor je organisatie. De toegangsbeheerder van je organisatie kan zelf suborganisaties aanmaken en/of gebruikers beheren via Geosecure. Meer informatie voor toegangsbeheerders kan je vinden in de documentatie 'Security / Toegangsbeheerder'.

2.   Registratie applicatie (client)    

Neem contact op met Helpdesk Informatie Vlaanderen om je applicatie (client) te registreren. Hiervoor hebben we de volgende gegevens nodig:

  • Het gewenste integratiescenario;
  • De naam van de client;
  • De eigenaar van de client (de persoon die binnen je organisatie verantwoordelijk is voor de client, deze persoon moet geregistreerd zijn in Geosecure);
  • Een tekstuele omschrijving van de client;
  • De #scopes die je wil aanvragen;
  • In geval van integratiescenario 3 of 4: de naam van de organisatie en e-mailadres waaraan de service account gelinkt is.

3.   Rollen voor de gebruikers 

Gebruikers die met KLIP werken, moeten over de juiste rollen beschikken om acties uit te kunnen voeren. Volgende rollen zijn beschikbaar:  

KLB Beheerder De instellingen van je KLB beheren
KLB operator Planaanvragen beantwoorden
Planaanvrager Plannen aanvragen en plannenpakketten bekijken
Raadpleger Plannenpakketten bekijken
ODB Beheerder KLIP gebruiken als openbaardomeinbeheerder

Mogelijke integratiescenario's:

Er zijn verschillende manieren om de KLIP services aan te spreken, en het hangt er van af welke applicatie je maakt. Volgende scenario's zijn mogelijk:

1) Single page webapplication (gebruikersinteractie

Dit scenario is geschikt als je een gedistribueerde client (die geen geheimen kan bewaren) wil integreren met de KLIP services. 

Om je toepassing te kunnen gebruiken moeten gebruikers

  • geregistreerd zijn bij Geosecure;
  • de juiste rollen hebben;
  • zich aanmelden;
  • je toepassing telkens ook expliciet toelating geven om in naam van de gebruiker acties te doen voor KLIP.

Na registratie ontvang je een Client Identifier. Gebruik de OAuth2.0 Implicit Grant, om access tokens voor gebruikers van je applicatie aan te vragen.Voorbeelden: mobile app, desktop-toepassing, single page application

2) Webserver application (gebruikersinteractie)

Om je toepassing te kunnen gebruiken moeten gebruikers

  • geregistreerd zijn bij Geosecure;
  • de juiste rollen hebben;
  • zich aanmelden;
  • je toepassing telkens ook expliciet toelating geven om in naam van de gebruiker acties te doen voor KLIP.

Na registratie ontvang je een Client Identifier en Client Secret. Omdat dit scenario werkt met Client Identifiers en Client Secrets, is dit scenario niet geschikt voor gedistribueerde toepassingen. Voorbeelden: webserverapplicaties

3) B2B met Authorizationcode (zonder gebruikersinteractie)

Dit scenario is geschikt als je wil integreren met KLIP via een batch of server proces (B2B) en je nog geen integratie gedaan hebt met onze soap-services. Deze methode is niet volledig stateless (laatste accesstoken en refreshtoken moet telkens bijgehouden worden).

Dit scenario is optimaal voor klanten die veel klanten hebben die toegang willen tot de API.

Maak je een client voor een klant? Dan moet deze klant een mail sturen naar het Geosecure-team dat jouw client calls mag doen voor je klant. Je klant zal dan een service account krijgen die gekoppeld is aan je client.  Geef duidelijk het emailadres en de naam van de organisatie mee waar deze service account aan gelinkt is.

Na registratie ontvang je een Client Identifier en Client Secret. Omdat dit scenario werkt met Client Identifiers en Client Secrets, is dit scenario niet geschikt voor gedistribueerde toepassingen.

Als de eigenaar van de client zich in dezelfde organisatie bevindt als degene die de API aanroept, dan kijk je best naar het scenario B2B met Client Credentials grant.

Voorbeelden: nachtelijke verwerking van planaanvragen

4) B2B met Client Credentials grant  (zonder gebruikersinteractie)

Dit scenario is geschikt als je wil integreren met KLIP via een batch of server proces (B2B) en je nog geen integratie gedaan hebt met onze soap-services. 

Het kan alleen gebruikt worden door klanten die in het bezit zijn van de Client Secret en waarbij de eigenaar van de client dezelfde is als de klant zelf.  Wil je een client aanmaken voor een andere organisatie dan de jouwe, dan kijk je best naar B2B met Authorizationcode.

Geef duidelijk een emailadres en de naam van je organisatie mee.

Na registratie ontvang je een Client Identifier en Client Secret. Omdat dit scenario werkt met Client Identifiers en Client Secrets, is dit scenario niet geschikt voor gedistribueerde toepassingen.

Voorbeelden: nachtelijke verwerking van planaanvragen

5) B2B met SAML Assertion (zonder gebruikersinteractie)

Dit scenario is geschikt als je wil integreren met KLIP via een batch of server proces (B2B) en

  • je al een integratie hebt met onze omgeving met andere soap-services; 
  • of als je een trust-relatie hebt met Geosecure;
  • of als je volledig stateless wil werken.

Als je op basis van assertion wil werken, heb je een niet self-signed certificaat nodig per organisatie.

Heb je een trust? Dan kan je de rest-services aanspreken met een uitgewisseld token en heb je geen certificaat nodig.  Na registratie ontvang je een Client Identifier en Client Secret. 

Omdat dit scenario werkt met Client Identifiers en Client Secrets, is dit scenario niet geschikt voor gedistribueerde toepassingen.

Voorbeelden: nachtelijke verwerking van planaanvragen

Scopes

De scopes die je nodig hebt hangen af van welke calls je wil doen. Welke scope je nodig hebt voor welke call, kan je vinden in de documentatie van de API's:

Volgende scopes zijn beschikbaar:

  • MapRequestInitiator: aanvragen van plannen
  • MapRequestReader: bekijken van plannen
  • UnaOperator: bevestigen en beantwoorden van planaanvragen
  • UnaReader: bekijken van planaanvragen