Document toolboxDocument toolbox

Transition from Geosecure to ACM

Owned by oliver.may
Last updated: 05 Oct, 2023 by Jürgen Dooms (Unlicensed)
3 min read

Introduction

During the transition there are 2 major work blocks: changing the authentication and switching to the renewed GIPOD API. 

The renewed GIPOD API ( gipod.api.vlaanderen.be ) will work with both Geosecure and ACM authentication, but the existing GIPOD API ( private-api.gipod.vlaanderen.be ) will only work with Geosecure authentication.

Therefore we recommend switching to the renewed API & changing the authentication in one go.

On the renewed API rate limiting is applied. Each client is allowed to perform 1800 req/min.

TL;DR for CCG with JWK

Beta

Production

  1. Validate in Beheerportaal T&I that your existing client was successfully migrated to ACM, and remember the new client id.

  2. Adapt oauth access token request information and update oauth URLs from beta.oauth.vlaanderen.be/... to authenticatie-ti.vlaanderen.be/... using the client id from step 1.

  3. Update GIPOD API endpoint from private-api.gipod.beta-vlaanderen.be to gipod.api.beta-vlaanderen.be

  4. Validate that your existing client works with the new endpoints and authentication mechanism

  1. Validate in Beheerportaal that your existing client was successfully migrated to ACM, and remember the new client id.

  2. Adapt oauth access token request information and update oauth URLs from oauth.vlaanderen.be/... to authenticatie.vlaanderen.be/... using the client id from step 1.

  3. Update GIPOD API endpoint from private-api.gipod.vlaanderen.be to gipod.api.vlaanderen.be

  4. Validate that your existing client works with the new endpoints and authentication mechanism

Set up clients in ACM 

The current Geosecure clients are being phased out. 

While various integration scenarios are possible in Geosecure, only Client Credential Grant Clients with a JWK are accepted in ACM.  

Digital Flanders prepares the transition from Geosecure clients to ACM clients as much as possible. How far this goes depends on the current integration setup: 

  1. Client Credential Grant-Client (with JWK) at Geosecure => Digital Flanders creates a Client Credential Grant-Client at ACM, the JWK is adopted. 

  2. Client Credential Grant-Client (with secret) at Geosecure => Digital Flanders creates a Client Credential Grant-Client at ACM, you will have to create a JWK yourself. 

  3. B2B Authorization Code Grant-Client at Geosecure => you switch to 1 or more Client Credential Grant-Client(s) at ACM (1:n relationship, one per customer for which you act as a service provider), each with a JWK. The clients will not be automatically created by Digital Flanders via the bulk migration.  

More information about moving from Geosecure clients to ACM clients: https://vlaamseoverheid.atlassian.net/wiki/display/GAEP/Scenario%2527s%2Bvoor%2Boverschakeling%2Bvan%2Bde%2BAPI-clients  

More information about managing Client Credential Grant clients in ACM: https://vlaamseoverheid.atlassian.net/wiki/display/GAEP/Module%2BOAuth%2BClient%2BCredentials%2BGrant%253A%2BAPI-Client%2Bbeheren  

Authenticate on the GIPOD API with an ACM token

GIPOD uses ACM for the authentication and authorization of users. Digital Flanders offers a web application in which users can carry out the complete flow of GIPOD. Digital Flanders also provides services for integrating GIPOD into your own software systems.

Authentication on the GIPOD API is done with an ACM token:

 

To connect to the GIPOD API you need a signed JWT token. To do this, work with a Client credentials grant .

More information about server-server authentication can be found here and about creating a signed JWT token here .

Adjustments of the GIPOD API endpoint

The renewed GIPOD API endpoint ( https://gipod.api.vlaanderen.be ) will work with both Geosecure and ACM authentication, but the existing GIPOD API endpoint ( https://private-api.gipod.vlaanderen.be ) will only work with Geosecure authentication. 

Both API endpoints are functionally identical, apart from the authentication, as both are a gateway to the same GIPOD services.

Guides