Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents

Info

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.

Authenticatie via Vlaams Toegangsbeheer

Vanuit Bij Mijn Burgerprofiel maken gebruiken we gebruik van het Vlaams Toegangsbeheer om authenticatie te faciliteren. Deze component voorziet automatisch single sign-on-functionaliteit (SS0-functionaliteit) zodat een burger zich niet telkens opnieuw moet aanmelden in verschillende applicaties.

Voor de Aanvraagmodule kan een formulier geraadpleegd worden op 2 manieren:

  • Embedded (verankerd) in Mijn Burgerprofiel

  • Stand-alone (als aparte applicatie)

De SSO-functionaliteit is gebonden aan deze beperkingen:

  • een beperkte levensduur - kies een duurtijd van < 5 minuten

  • aanmelden moet in dezelfde browserinstantie

  • geen garantie dat de gebruikerscontext bewaard blijft tussen de verschillende applicaties

...

  • bij embedded gebruik kan de functionaliteit geïmpacteerd worden door de third-party cookieproblematiek

Single Sign-on via token

Note

U kunt deze Deze functionaliteit is alleen gebruiken beschikbaar als de applicatie waarmee u wilt koppelen, Aanvraagmodule beschikt over een OpenID-Connect integratie met het Vlaams Toegangsbeheer.

Om een aantal beperkingen op te lossen bij de klassieke manier waarop werking van single sign-on werktop te lossen, gebruiken we Token Exchange om een OAuth Access Token te generen die de Mijn Burgerprofiel-applicatie dat de Aanvraagmodule kan gebruiken om een sessie op te starten.

...

Voorwaarde

  • De applicatie Aanvraagmodule moet een trust aanvragen voor -relatie hebben met de Mijn Burgerprofiel Client-ID (- zie Bijlage: Mijn- Mijn Burgerprofiel-Client-ID)

  • De applicatie beschikt over ondersteuning voor Token Exchange grant type

  • De applicatie beschikt over ondersteuning voor Client Credential grant type

Implementatie

Single Sign-on vanuit een applicatie begint door het verkrijgen van een OpenID Connect Access Token (OIDC Access Token) via de authorization code grant.

Zodra de applicatie het OIDC Access Token heeft, kan de uitwisseling via de Token Exchange beginnen om een OAuth Access Token te generen dat de Mijn Burgerprofiel-applicatie kan verwerken.

Opmerking: de maximale duur van de Mijn Burgerprofiel applicatieve sessie is gekoppeld aan de resterende tijdsduur van het OIDC Access Token. Om ervoor te zorgen dat een gebruiker zo lang mogelijk kan aangemeld blijven, is het aangeraden om eerst een refresh uitvoeren.

Token Exchange

Zodra de applicatie een OIDC Access Token heeft, kan er een OAuth Access Token worden aangevraagd via delegatie volgens de Token Exchange RFC. Dit betekent dat subject en actor token moeten meegegeven worden tijdens de Token Exchange.

Code Block
POST /op/v1/token HTTP/1.1
Host: authenticatie-ti.vlaanderen.be
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&audience=<MBP-CLIENT-ID>
&subject_token=<OIDC-ACCESS-TOKEN>
&subject_token_type=urn:ietf:params:oauth:token-type:access_token
&actor_token=<OIDC-ACCESS-TOKEN>
&actor_token_type=urn:ietf:params:oauth:token-type:access_token
&client_id=<APP-CLIENT-ID>
&client_secret=<APP-CLIENT-SECRET>

...

Naam

...

Beschrijving

...

<MBP-CLIENT-ID>

...

Bevat de Mijn Burgerprofiel Client-ID (zie Bijlage - Mijn Burgerprofiel Client-ID)

...

<OIDC-ACCESS-TOKEN>

...

OpenID Connect Access Token verkregen door gebruik te maken van authorization code grant of via uitvoeren van refresh

...

<APP-CLIENT-ID>

...

Client-ID van de applicatie (zie Client Authenticatie voor alternatieven)

...

<APP-CLIENT-SECRET>

...

Client Secret van de applicatie (zie Client Authenticatie voor alternatieven).

Info

Opmerking: in het codevoorbeeld gebruiken we een Client-ID en Secret. Deze informatie kan ook als Basic Authentication toegevoegd worden.

Bij een asymmetrisch sleutelpaar is client assertion nodig. Zie ook Client Authenticatie voor meer informatie en voorbeelden.

Wanneer de Token Exchange met succes is uitgevoerd, krijgt de applicatie het onderstaande antwoord:

Code Block
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache, no-store

{
  "issued_token_type":"urn:ietf:params:oauth:token-type:access_token",
  "access_token": "ZC5-A1AkXUzXRKb71sAIHBl9F87F18anzEaQy6G6KFD",
  "expires_in": 3600,
  "scope": "profile rrn",
  "token_type": "Bearer"
}

Gebruikerscontext doorgeven aan Mijn Burgerprofiel

Om de gebruikerscontext door te geven aan Mijn Burgerprofiel moet het OAuth Access Token - verkregen via de voorgaande Token Exchange - worden doorgegeven. Gezien de gevoeligheid van het OAuth Access Token moet dit altijd via een server-to-server operatie verlopen.

...

docExpansionlist

...

Stroomdiagram

Drawio
zoom1
simple0
inComment0
custContentId5866062908
pageId5848175061
lbox1
diagramDisplayNameformulieren-sso-token-exchange.drawio
contentVer1
revision1
baseUrlhttps://vlaamseoverheid.atlassian.net/wiki
diagramNameformulieren-sso-token-exchange.drawio
pCenter0
width941
links
tbstyle
height641

Implementatie

Standaard maakt de Aanvraagmodule gebruik van OpenID Connect (op basis van Authorization Code grant) voor geauthenticeerde formulieren. Dit verloopt vlot voor formulieren die in stand-alone modus getoond worden.

Note

Voor formulieren die embedded worden getoond, kan de burger een fout te zien krijgen tijdens het OpenID Connect-aanmeldproces omdat de Identity Provider (ACM) cookies nodig heeft. Doordat de Identity Provider op een ander domein werkt dan burgerprofiel.be, zal hij die niet kunnen opslaan. Vandaag blokkeren de meeste browsers immers Third Party Cookies. Als de browser wel Third Party Cookies toelaat, is er geen probleem.

Gebruikerscontext doorgeven aan een Aanvraagmodule

Hiervoor moet mijn Burgerprofiel het OAuth Access Token - verkregen via de Token Exchange - doorgeven. Door de gevoeligheid van het OAuth Access Token moet dit altijd via een server-to-server operatie verlopen als volgt:

  1. De Aanvraagmodule moet een API-endpoint voorzien volgens de onderstaande API-specificaties.

  2. Mijn Burgerprofiel (server) roept dat API-endpoint aan om een OAuth Access token te registreren.

  3. Het resultaat van die registratie moet een tijdelijk, éénmalig te gebruiken token zijn, dat wordt doorgegeven zodra de Aanvraagmodule wordt geopend in de browser.

Info

Opmerking: Mijn Burgerprofiel zal gebruik maken van de Client-ID vermeld in de Formulieren API response om de “audience” claim correct in te stellen tijdens het Token Exchange proces.

Aanvraagmodule - SSO Token (Swagger)

Swagger integration
docExpansionlist
{
  "openapi": "3.0.2",
  "info": {
    "title": "Aanvraagmodule - SSO Token",
    "version": "1.0"
  },
  "components": {
    "schemas": {
      "RequestToken": {
        "type": "object",
        "required": [
          "token",
          "token_type"
        ],
        "properties": {
          "token": {
            "type": "string",
            "description": "Token ontvangen via IdP Token Exchange"
          },
          "token_type": {
            "type": "string",
            "description": "Type token ontvangen via IdP Token Exchange",
            "requiredenum": [
          "token",    "urn:ietf:params:oauth:token-type:access_token"
            ]
   "token_type"       }
 ],       }
 "properties": {    },
      "tokenResponseTempToken": {
 
          "type": "stringobject",
        "required": [
  "description": "Token ontvangen via IdP Token Exchange"
        "token"
        ],
         },"properties": {
          "token_type": {
            "type": "string",
            "description": "Type token ontvangen via IdP Token Exchange",Tijdelijk SSO Token"
          }
      "enum": [ }
      },
      "urn:ietf:params:oauth:token-type:access_token"ClientError": {
        "type": "object",
  ]      "required": [
   }       "error"
 }       }],
        "ResponseTempTokenproperties": {
          "typeerror": "object", {
            "requiredtype": "string",
  [          "description": "tokenFoutmelding"
          }
 ],       }
 "properties": {    },
      "tokenServerError": {
   
        "type": "string",
      }
    }
  },
  "descriptionservers": "Tijdelijk[
SSO Token"   {
       }
"description": "Form provider",
       }
 "url": "https://formulier.vlaanderen.be"
    },
  ],
   "ClientErrorpaths": {
   
    "type/auth/v1/token": "object",
 {
      "requiredpost": [{
          "errorrequestBody":     {
   ],         "propertiescontent": {
            "errorapplication/json": {
              "typeschema": "string", {
                "description$ref": "Foutmelding#/components/schemas/RequestToken"
          }    }
     }       },
      "ServerError": {         "type": "string""application/x-www-form-urlencoded": {
        }     } "schema": {
},   "servers": [     {       "description$ref": "TNI",#/components/schemas/RequestToken"
         "url": "https://burgerprofiel.tni-vlaanderen.be"     }
      },     { }
     "description": "Productie",    }
  "url": "https://www.burgerprofiel.be"     },
     ],   "pathsresponses": {
    "/auth/v1/token      "200": {
            "postdescription": {"Vraagstelling is geaccepteerd en een tijdelijk token werd  "requestBody": {gegenereerd",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RequestTokenResponseTempToken"
                }
              },
             "application/x-www-form-urlencoded": {}
          },
          "schema400": {
   
            "$refdescription": "#/components/schemas/RequestToken"
  Vraagstelling ontbreekt verplichte velden",
           } "content": {
          }    "application/json": {
     }         },  "schema": {
     "responses":  {           "200$ref": {"#/components/schemas/ClientError"
            "description": "Vraagstelling is geaccepteerd en}
een tijdelijk token werd gegenereerd",          }
  "content": {         }
     "application/json": {    },
            "schema401": {
            "description": "Ongeldig of vervallen token in "$ref":de "#/components/schemas/ResponseTempToken"vraagstelling",
            "content": {
  }            "application/json": {
 }             }  "schema": {
       },           "400$ref": {"#/components/schemas/ClientError"
               "description": "Vraagstelling ontbreekt verplichte velden", }
              }
"content": {           }
   "application/json": {      },
          "schema500": {
            "description": "Onverwacht probleem opgetreden in de "$ref": "#/components/schemas/ClientError"applicatie bij het verwerken van het token",
            "content": {
  }            "text/html": {
 }             }  "schema": {
       },           "401$ref": { "#/components/schemas/ServerError"
              "description": "Ongeldig of vervallen token in de vraagstelling", }
             "content": {  }
            "application/json": {}
          }
      "schema": { }
      }
    }
     "$ref": "#/components/schemas/ClientError"
                }
              }
            }
          },
          "500": {
            "description": "Onverwacht probleem opgetreden in de applicatie bij het verwerken van het token",
            "content": {
              "text/html": {
                "schema": {
                  "$ref": "#/components/schemas/ServerError"
                }
              }
            }
          }
        }
      }
    }
  }
}

Info

Opmerking: het tijdelijk token via de API-endpoint kan maar één keer gebruikt worden. Bovendien vervalt het na ongeveer 2 min.

Tot slot moet het tijdelijk token worden doorgegeven als query parameters van de Mijn Burgerprofiel-URL. Een aantal voorbeelden van dit type URL's:

...

TNI:

  • https://burgerprofiel.tni-vlaanderen.be/?token=<MBP-TEMP-TOKEN>

  • https://burgerprofiel.tni-vlaanderen.be/meldingen?token=<MBP-TEMP-TOKEN>

Productie:

...

https://www.burgerprofiel.be/?token=<MBP-TEMP-TOKEN>

...

}
}

Mijn Burgerprofiel geeft het tijdelijke token door als query-parameter via de formulier URL. De exacte waarde die gebruikt wordt voor de query-parameternaam moet doorstroome via de Formulieren API-specificatie.

Voor een overzicht van relevante foutboodschappen, zie ook https://vlaamseoverheid.atlassian.net/wiki/spaces/IKPubliek/pages/2076934790/Algemene+REST+API-specificaties#Standaard-foutberichten en https://vlaamseoverheid.atlassian.net/wiki/spaces/IKPubliek/pages/2076934790/Algemene+REST+API-specificaties#Specifieke-foutberichten

Voorbeeld:

https://formulier.vlaanderen.be/f6d35977-f45d-4710-befc-21e2812d83ea?token=<TEMP-TOKEN>

Het token verwerken in de Aanvraagmodule

Doorloop de volgende stappen nadat de Aanvraagmodule het token heeft ontvangen:

  1. Controleer dat het tijdelijke token niet vervallen is.
    Bijvoorbeeld: een aanvraagmodule kan het geregistreerde access token samen met het tijdelijk token voor 2 minuten opslaan in een cache. Op het moment dat een tijdelijk token dan gebruikt wordt, kan de aanvraagmodule controleren of het nog in de cache aanwezig is (en het token dan ook uit de cache verwijderen, zodat het niet meermaals gebruikt kan worden).

  2. Controleer dat het tijdelijk token nog niet gebruikt is.

  3. Valideer het uitgewisselde OAuth Access Token, zie ook https://authenticatie.vlaanderen.be/docs/beveiligen-van-api/oauth-rest/rest-namens-gebruiker/rest-token-exchange/valideer-access-token/

Indien aan alle voorwaarden is voldaan, kan de Aanvraagmodule een nieuwe sessie opstarten op basis van de gebruikerscontext die beschikbaar is via het OAuth Access Token.

Anchor
bijlage-mbp-client-id
bijlage-mbp-client-id
Bijlage - Mijn Burgerprofiel Client-ID

Client-ID

Omgeving

URL

80689076-8c4a-4bef-abc4-82805e17988d

TNI

https://burgerprofiel.tni-vlaanderen.be

88f04968-d331-4ae0-99d9-c6efb845841f

Productie

https://www.burgerprofiel.be