Aanvraagmodule - Third-party cookies

Probleemstelling

Wanneer een aanvraagformulier wordt geïntegreerd met Mijn Burgerprofiel wordt een iframe getoond met daarin een aanvraag, gehost door het extern loket. Afhankelijk van de vereisten voor het formulier, zijn cookies nodig om een gebruikerssessie bij te houden, persistentie aan te bieden binnen het formulier, …

De afgelopen jaren leggen browsers echter meer beperkingen op het gebruik van cookies, zeker in third-party context. Het gaat dan om een cookies voor een domein anders dan het domein van de zichtbare website.

Als een aanvraagformulier cookies moet kunnen bijhouden om correct te functioneren, en het formulier is gehost op een URL die niet onder https://burgerprofiel.be valt, dan zullen veel browsers de verwachte cookies niet opslaan.

Oplossing: first-party cookies a.d.h.v. een domein-alias (voorkeur)

De meeste beperkingen zijn niet van toepassing wanneer cookies op hetzelfde domein als de actieve website worden gezet. 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.

Oplossing: third-party cookie API-endpoint (alternatief)

Als de bovenstaande aanpak geen optie is (bijv. door technische beperkingen), dan is er dit alternatief: door specifieke API-endpoints te voorzien en mee te geven in de Forms-API, kan er in Mijn Burgerprofiel eerst worden gekeken of er cookies op uw domein kunnen worden gezet.

Is dat niet mogelijk omdat de browser third-party cookies blokkeert, dan tonen we in Mijn Burgerprofiel een relevante foutboodschap. We verwijzen de gebruiker door naar het externe loket = de fallback-link van de aanvraag.

:

Open

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 (API-specificaties voor aanbieders van formulieren | GET /api/v1/forms) wordt bovenstaand endpoint met extern domein gedefinieerd als _links.thirdPartyCookieApi

Bij het openen van een aanvraag zal Mijn Burgerprofiel:

1. kijken of de aanvraag een thirdPartyCookieApi link heeft

2. een POST doen naar het geconfigureerde endpoint

3. een GET doen naar het geconfigureerde endpoint

4. de relevante UI tonen aan de gebruiker

   1. de foutboodschap met doorverwijzing indien er een endpoint is geconfigureerd in stap 1, en stap 2 of 3 een fout geven

   2. de geconfigureerde aanvraag indien er geen endpoint is geconfigureerd, of stap 2 en 3 zonder problemen werden uitgevoerd

API-definitie van het endpoint om te implementeren