API v2 - enkel Geosecure (wordt uitgefaseerd)

Opgelet: KLIP schakelt over naar authenticatie via ACM. Integraties via Geosecure zullen tegen 2024 moeten omgezet worden naar integraties via ACM.

Onderstaande info heeft enkel betrekking op aansluitingen via Geosecure.

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

Hier vindt u meer informatie terug betreffende:

Te volgen stappen om met KLIP te integreren (ENKEL versie 2 van de API):

1.  Registratie organisatie

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

2.   Registratie applicatie (client)    

Neem contact op met Helpdesk Digitaal Vlaanderen om uw 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 uw organisatie verantwoordelijk is voor de client, deze persoon moet geregistreerd zijn in Geosecure);
  • Een tekstuele omschrijving van de client;
  • De #scopes die u wilt 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 uw KLB beheren (enkel voor beheerders van leidingen die NIET onder de federale gaswet/transport van elektriciteit vallen)
KLIM Beheerder De instellingen van uw KLB beheren (enkel voor beheerders van leidingen die WEL onder de federale gaswet/transport van elektriciteit vallen)
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 u maakt. Volgende scenario's zijn mogelijk:

1) Single page webapplication (gebruikersinteractie

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

Om uw toepassing te kunnen gebruiken moeten gebruikers

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

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

2) Webserver application (gebruikersinteractie)

Om uw toepassing te kunnen gebruiken moeten gebruikers

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

Na registratie ontvangt u 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 u wilt integreren met KLIP via een batch of server proces (B2B) en u 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.

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

Na registratie ontvangt u 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 kijkt u 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 u wilt integreren met KLIP via een batch of server proces (B2B) en u 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.  Wilt u een client aanmaken voor een andere organisatie dan de uwe, dan kijkt u best naar B2B met Authorizationcode.

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

Na registratie ontvangt u 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 u wil integreren met KLIP via een batch of server proces (B2B) en

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

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

Hebt u een trust? Dan kunt u de rest-services aanspreken met een uitgewisseld token en hebt u geen certificaat nodig.  Na registratie ontvangt u 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 u nodig hebt hangen af van welke calls u wilt doen. Welke scope u nodig hebt voor welke call, kunt u 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