Aanmelden met eenvoudig of gekoppeld toegangsbeheer

1 Eenvoudig vs. gekoppeld toegangsbeheer
2 Integratie van de global header met eenvoudig toegangsbeheer (ACM)
3 Integratie van de global header met gekoppeld toegangsbeheer (ACM + Single Sign-on)
- 3.1 Activiteitstracking
  - 3.1.1 Activiteit tracken voor websites met ACM
    - 3.1.1.1 De status van de sessie rapporteren
    - 3.1.1.2 De endpoints overschrijven
    - 3.1.1.3 De sessie verlengen op basis van activiteit
  - 3.1.2 De aanvragen voor applicatie-logout afhandelen via JavaScript
- 3.2 Aanmelden
  - 3.2.1 Aanmelden succesvol afgehandeld
  - 3.2.2 Aanmelden mislukt
- 3.3 Afmelden
  - 3.3.1 Fallback door featuredetectie
  - 3.3.2 Fallback in SSO-callbackpagina

Eenvoudig vs. gekoppeld toegangsbeheer

De global header integreren op een gastwebsite kan op de volgende 2 manieren:

Met eenvoudig toegangsbeheer: gebruikers kunnen alleen als burger aanmelden. Hiervoor moet de gastwebsite de embed-code toevoegen, zoals gedocumenteerd hier Widgets toevoegen aan een webpagina | Een widget toevoegen aan een webpagina via embedcode .

Ook bij een global header met eenvoudig toegangsbeheer is de link naar het e-loket ondernemers en het Verenigingsloket beschikbaar.

Met gekoppeld toegangsbeheer: gebruikers kunnen meteen aanmelden in verschillende doelgroepen via ACM/IDM, bijv. als burger, als ambtenaar en/of als economische actor. De gastwebsite moet hiervoor de doelgroepswissel expliciet toevoegen. Het openen van het pad dat bij die wissel hoort (switchCapacityUrl), start de flow voor gericht aanmelden. Zie ook: Wisselen van account (doelgroepen)

Om gericht te kunnen aanmelden en de gebruiker de keuze te geven tussen meerdere doelgroepen, moet Toegangsbeheer (ACM) eerst valideren dat de gevraagde identiteit een toegelaten identiteit is. Zie ook de ACM-technische informatie “Gericht aanmelden”. De doelgroep zelf wordt bepaald in de ACM-schermen. De global header reageert op basis van de informatie in de ACM-schermen.

Zie ook: https://www.vlaanderen.be/acm-idm-standaard-aansluitingsproces

Integratie van de global header met eenvoudig toegangsbeheer (ACM)

Voor elke gastwebsite die de global header aanbiedt, moet er een integratie bestaan die de activiteit van de burger met de global header meldt aan de header. Hiervoor moet er minimaal eenvoudig toegangsbeheer (AuthentiCation Management of ACM) aanwezig zijn zodat:

de gebruiker zich kan aanmelden
het gedrag tussen de website en de global header consistent blijft

Voor meer informatie over een koppeling met ACM, zie https://www.vlaanderen.be/acm-idm-standaard-aansluitingsproces .

Start de koppeling met de global header en kies in het formulier voor eenvoudig toegangsbeheer.

Integratie van de global header met gekoppeld toegangsbeheer (ACM + Single Sign-on)

Naast de algemene integratieregels, die van toepassing zijn voor elke website, bestaan er ook een aantal extra vereisten voor websites met gekoppeld toegangsbeheer.

Activiteitstracking
De status van de sessie rapporteren
De aanvragen voor applicatie logout afhandelen
Login en Logout endpoint

Start de koppeling met de global header en kies in het formulier voor gekoppeld toegangsbeheer.

Activiteitstracking

Met activiteitstracking wordt nagegaan of een gebruiker actief is met de global header. Bij inactiviteit van 20 minuten wordt de gebruiker automatisch afgemeld.

Activiteitstracking is optioneel en enkel te gebruiken indien de gastwebsite bijv. bijkomende user tracking nodig heeft. Dit kan het geval zijn wanneer er een iframe op de pagina dat niet standaard getraceerd wordt.

Om de activiteitstracking voor een webpagina correct te laten werken, moet de extensie op de hoogte blijven van activiteit op de webpagina. In het onderstaande codevoorbeeld staat een eenvoudige manier om activiteit van een gebruiker te detecteren en te rapporteren aan de extensie.

// Capture any widget that is present or will be present on the webpage.
vl.widget.client.capture(function (widget) {
  // Only process the widget if widget is a global header.
  if (widget.getPluginTypeId() === 'global_header') {
    // Get the Citizen Profile Session extension from the global header widget.
    widget.getExtension('citizen_profile.session').then(function (session) {
      
      /**
       * Event handler which extends a Citizen Profile session.
       */
      function activityEventHandler() {
        // Inform the Citizen Profile Session extension about activity.
        session.extend();
      }

      // Build a list of event names which should be used for activity tracking.
      var eventNames = [
        'mousedown', 
        'mousemove', 
        'mousewheel', 
        'DOMMouseScroll', 
        'scroll', 
         'wheel', 
         'keydown', 
         'keypress', 
         'touchmove', 
         'touchstart'
      ];
      // Iterate through the events names.
      for (var i = 0; i < eventNames.length; i++) {
        // Register our event handler given event name.
        window.addEventListener(eventNames[i], activityEventHandler);
      }
    });
  }
});

Activiteit tracken voor websites met ACM

Elke website moet activiteit tracken. Maar websites met SSO-ondersteuning (en ACM) hebben een aantal bijkomende vereisten voor veiligheid en integratie, zoals getoond in de onderstaande voorbeelden:

De status van de sessie rapporteren

// Capture any widget that is present or will be present on the webpage.
vl.widget.client.capture(function (widget) {
  // Only process the widget if widget is a global header.
  if (widget.getPluginTypeId() === 'global_header') {
    // Get the Citizen Profile Session extension from the global header widget.
    widget.getExtension('citizen_profile.session').then(function (session) {
      // This variable is purely to indicate which values are allowed (true / false).
      var websiteHasAuthenticatedSession = false;
      // Inform the session extension about the current session state of the website.
      session.configure({
        active: websiteHasAuthenticatedSession,
        endpoints: {
          loginUrl: '/login',
          loginRedirectUrl: '/profile',
          logoutUrl: '/logout'
        }
      });
    });
  }
});

Als de aanmeldstatus op de gastwebsite moet wijzigen, moet de logout-methode worden opgeroepen zodat de nodige flows gestart worden om correct af te melden.

De endpoints overschrijven

De standaard login/logout-endpoints kunnen altijd overschreven worden door een eigenschap toe te voegen aan het object in de configure-methode. Het codevoorbeeld hieronder toont hoe de endpoints te overschrijven en een lokale ontwikkeling mogelijk te maken. Een concreet voorbeeld is het hergebruik van de header voor verschillende loketfuncties. De endpoints mogen ook een relatief pad gebruiken t.o.v. de documentroot.

// Capture any widget that is present or will be present on the webpage.
vl.widget.client.capture(function (widget) {
  // Only process the widget if widget is a global header.
 if (widget.getPluginTypeId() === 'global_header') {
    // Get the Citizen Profile Session extension from the global header widget.
    widget.getExtension('citizen_profile.session').then(function (session) {
      // This variable is purely to indicate which values are allowed (true / false).
      var websiteHasAuthenticatedSession = false;
      // Inform the session extension about the current session state of the website. Keep in mind
      // this operation can only be performed once on every page load.
      session.configure({
        active: websiteHasAuthenticatedSession,
        endpoints: {
          loginUrl: '/login',
          loginRedirectUrl: '/profile',
          logoutUrl: '/logout'
        }
      });
     });
    }
  });

De sessie verlengen op basis van activiteit

De gastwebsite informeert ook over activiteit en kan op basis daarvan de eigen sessie verlengen. Dit is alleen van toepassing als de gastwebsite zelf de maximumduur van een sessie beperkt.

De aanvragen voor applicatie-logout afhandelen via JavaScript

Aanmelden

Om de Mijn Burgerprofiel-extensie een login te laten uitvoeren voor een website, moet de login-URL, die de aanmeldflow kan starten, beschikbaar zijn. De modal met aanmeldopties is de start van die aanmeldflow.

Zo lang de gebruiker niet is aangemeld, blijft het beletselteken rechts bovenaan actief.

Zodra de gebruiker is aangemeld, moet de callback-pagina van de gastwebsite een bericht verzenden met daarin de status van het aanmelden: gelukt of mislukt.

Aanmelden succesvol afgehandeld

Als de website een succesvolle aanmeldflow doorloopt, redirect de Burgerprofiel-extensie automatisch naar de geconfigureerde LoginRedirectUrl, zoals meegegeven bij het rapporteren over de status van de websitesessie:

De loginRedirectUrl verwijst naar de landingspagina waar standaard aangemelde gebruikers op moeten terechtkomen. In veel gevallen is dat de startpagina of bijv. /profile, /login, /...

Voor meer informatie over rapporteren van de website sessiestatus, zie Technische documentatie Widget-platform | Activiteit tracken voor websites met ACM ondersteuning

Aanmelden mislukt

Als de aanmeldflow een fout genereert, geef dan in de onderstaande code een foutboodschap mee.

Afmelden

Om de Mijn Burgerprofiel-extensie een afmelding te laten uitvoeren voor een website, moet de logout-URL, die de logout-flow kan starten, beschikbaar zijn. Wanneer een gebruiker op Afmelden klikt, gebeurt er automatisch een redirect naar de logout-URL, zoals geconfigureerd bij de endpoints.

Fallback door featuredetectie

De login- en logout-URL's van de Mijn Burgerprofiel-extensie zorgen dus voor het aan- en afmelden vanuit de global header door de nodige informatie op te vragen via de ACM-integratie. Maar wanneer de global header uitzonderlijk niet beschikbaar is, bijvoorbeeld omdat het Widget-platform niet actief is, is het aangeraden om de Burgerprofiel-feature detectie uit te voeren.

Het onderstaande voorbeeld toont een combinatie van de status detecteren van de Mijn Burgerprofiel-sessie met die featuredetectie.

Fallback in SSO-callbackpagina

De featuredetectie is voldoende voor de Mijn Burgerprofiel-extensie om de aanmeld- en afmeldflows te starten.

De enige uitzondering hierop is de callback-pagina die wordt opgeroepen door ACM (Toegangsbeheer). Standaard verzendt deze pagina een melding naar de Mijn Burgerprofiel-extensie om de modal te sluiten. Maar in het fallback scenario is er geen Burgerprofiel-extensie beschikbaar en zal de pagina niet opgeroepen worden vanuit de modal. Hierdoor is een extra controle nodig om een iframe te detecteren. Als er geen iframe beschikbaar is, moet de redirect manueel worden uitgevoerd; zowel bij een geslaagde als een gefaalde aanmelding.

In het onderstaande codevoorbeeld is de aanmelding geslaagd.

Documentatie voor partners en klanten van Digitaal Vlaanderen - bouwstenen Mijn Burgerprofiel, Verenigingsloket en e-loketondernemers

Documentatie voor klanten en partners van Digitaal Vlaanderen - bouwstenen Mijn Burgerprofiel, Verenigingsloket en e-loketondernemers