Disclaimer: Deze pagina’s worden regelmatig bijgewerkt zodat ze altijd de meeste recente informatie bevatten. Aarzel niet om feedback te geven mochten er aanpassingen nodig zijn.
Probleemstelling
Bij een aanvragen-integratie in Mijn Burgerprofiel wordt een iframe getoond met daarin een aanvraag die gehost wordt door het extern loket. Afhankelijk van de vereisten voor het formulier, zijn cookies mogelijk nodig (om een gebruikerssessie bij te houden, persistentie aan te bieden binnen het formulier, …). De afgelopen jaren hebben browsers echter steeds meer beperkingen gelegd op het gebruik van cookies, zeker in “Third Party” context (wanneer cookies bijgehouden worden voor een domein dat niet hetzelfde is als de zichtbare website).
Als het aanvraagformulier cookies moet kunnen bijhouden om correct te functioneren, en het is gehost op een URL die niet onder https://burgerprofiel.be valt, dan zullen veel browsers de verwachte cookies niet opslaan.
Voor een gedetailleerd overzicht van wat Third Party Cookies zijn en hoe verschillende browsers ermee omgaan, zie https://web.archive.org/web/20220817000041/https://clearcode.cc/blog/browsers-first-third-party-cookies/ .
Oplossing met voorkeur: First Party Cookies ahv domein alias
De meeste beperkingen zijn niet van toepassing wanneer cookies gezet worden op hetzelfde domein als de actieve website. Subdomeinen vallen onder dezelfde regels.
De aanbevolen oplossing houdt in dat het loket een CNAME alias krijgt onder *.formulieren.burgerprofiel.be. De formulieren die in de API gedefinieerd worden, moeten dan dat domein gebruiken voor de embed link.
Als onderdeel van uw aansluitingsdossier zal deze alias eenmalig vastgelegd worden. De loketapplicatie die het aanvraagformulier host, moet dan ook correct omgaan met de afgesproken alias.
Alternatieve oplossing: Third-party cookie API endpoint
Als bovenstaande aanpak geen optie is (vanwege technische beperkingen), dan bieden we alsnog een alternatief aan: door specifieke API endpoints te voorzien (en mee te geven in Forms API), kunnen we in Mijn Burgerprofiel eerst kijken of cookies op uw domein gezet kunnen worden. Als dat niet mogelijk is (omdat de browser Third Party Cookies blokkeert) tonen we in Mijn Burgerprofiel een relevante foutboodschap, en verwijzen de burger door naar het externe loket (de fallback link van de aanvraag):
Technische invulling
Het loket voorziet (als onderdeel van de forms API die sowieso voorzien moet worden) een endpoint /api/v1/third-party-cookies. Het endpoint moet publiek zijn (want zal geen Authorization headers binnenkrijgen).
Bij een POST op dit endpoint moet een response gegeven worden met status 200 en een Set-Cookie response header (de naam en inhoud van de op te slagen cookie is vrij te kiezen). Er moet geen response body gegeven worden.
Bij een GET op dit endpoint moet nagekeken worden of in de request headers een overeenkomstige cookie aanwezig is met de verwachte waarde. Als dat niet zo is, moet een response met status 404 gegeven worden.
In de definitie van de aanvraag in Forms API (https://vlaamseoverheid.atlassian.net/wiki/spaces/IKPubliek/pages/5873176651/API-specificaties+voor+aanbieders+van+formulieren+v1+-+Draft#GET-%2Fapi%2Fv1%2Fforms) wordt bovenstaand endpoint met extern domein gedefinieerd als _links.thirdPartyCookieApi
Bij het openen van een aanvraag zal Mijn Burgerprofiel:
kijken of de aanvraag een
thirdPartyCookieApilink heefteen POST doen naar het geconfigureerde endpoint
een GET doen naar het geconfigureerde endpoint
de relevante UI tonen aan de gebruiker
de foutboodschap met doorverwijzing indien er een endpoint is geconfigureerd in stap 1, en stap 2 of 3 een fout geven
de geconfigureerde aanvraag indien er geen endpoint is geconfigureerd, of stap 2 en 3 zonder problemen werden uitgevoerd