Gericht aanmelden

De toepassing kan vragen om de gebruiker aan te melden onder een specifieke identiteit

Een gebruiker kan zich potentieel aanmelden onder meerdere identiteiten binnen een toepassing: bijvoorbeeld als burger, namens een specifieke doelgroep of namens een specifieke organisatie. Normaal gezien zal de gebruiker interactief de gewenste identiteit moeten selecteren indien er meerdere opties zijn.

Bij het gericht aanmelden wordt er in het request meegegeven welke identiteit de gebruiker wenst aan te nemen. In dat geval zal het Toegangsbeheer (ACM) valideren of dit een toegelaten identiteit is voor deze persoon. Zoja, dan zal de gebruiker zonder interactie (voor de selectie van zijn/haar identiteit) doorgelaten worden.

Dit “gericht aanmelden” is vooral interessant indien men de gebruiker vanuit de huidige toepassing (zonder gebruikersinteractie) wenst door te schakelen naar een andere toepassing, waarbij dezelfde keuze qua identiteit bewaard blijft.

De gewenste identiteit meesturen

Bij de start van de authenticatie kan men de gewenste identiteit meesturen in de login_hint parameter: cfr de mogelijke parameters bij het aanmelden.

Als login_hint parameter wordt een base64 encoded JSON string van de gewenste identiteit meegestuurd.

Het toegangsbeheer verwacht identiteiten zoals ze uitgeleverd worden aan de toepassing (zoals meestal beschreven in paragraaf 2.1 van het integratiedossier):

als de toepassing bvb. naar Economische Actoren (EA) op organisatieniveau ontsloten is, dan wordt er een identiteit op organisatieniveau verwacht (zie hieronder voor een voorbeeld)
als de toepassing bvb. naar Economische Actoren (EA) op doelgroepniveau ontsloten is, dan wordt er een identiteit op doelgroep verwacht
als de toepassing naar Burgers (BUR) ontsloten werd en men wil de authenticatie als Burger afdwingen, dan dient de BUR-identiteit (doelgroep) gebruikt te worden

Indien men gericht probeert aan te melden met een identiteit op doelgroepniveau waarbij de toepassing ontsloten is op organisatieniveau, dan gaat dit geen match opleveren.

Tip

Je kan in het integratiedossier aangeven dat de huidige geselecteerde identiteit (in base64-encoded JSON-string) mee uitgeleverd moet worden: de huidige geselecteerde identiteit kan dan makkelijk doorgegeven worden aan andere toepassingen.

Voorbeelden van JSON strings als identiteit

Doelgroep

Voor het selecteren van een specifieke doelgroep kan men de doelgroep (BUR, GID, EA, LB of OV) in de key cap_hint meegeven.

Indien men doelgroep GID wil selecteren, dan kan men als login_hint een base64 encoded versie sturen van onderstaande JSON-string:

{
  "cap_hint": "GID"
}

Organisatie

Wanneer de gewenste identiteit een organisatie is, dient het JSON object volgende keys te bevatten:

cap_hint: de gewenste doelgroep
code_hint: identifier van de gewenste organisatie (KBO nummer)

Indien men de organisatie met KBO-nummer 0428315871 (als economische actor) wenst mee te geven, dan kan dit via de base64 encoded versie van onderstaande JSON-string:

{
  "cap_hint": "EA", 
  "code_hint": "0428315871"
}

Voor een organisatie met OVO-code OVO1234567 uit doelgroep GID wordt dit:

{
  "cap_hint": "GID", 
  "code_hint": "OVO1234567"
}

Mandaat

Wanneer de toepassing ook naar mandaten ontsloten werd, dan kan men ook aangeven dat de gebruiker namens een specifiek mandaat wil aanmelden. In dat geval dient de JSON string volgende keys te bevatten:

cap_hint: de gewenste doelgroep
code_hint: identifier van de identiteit die je wil aannemen in de toepassing (mandaatgever)
- dit kan een KBO nummer zijn (indien de identiteit die je wil aannemen in de toepassing een organisatie is)
- dit kan een RRN zijn (indien de identiteit die je wil aannemen een persoon is)
via_hint: identifier van de identiteit die een mandaat ontving (mandaatnemer)
- dit kan een KBO nummer zijn (indien de identiteit die het mandaat ontving een organisatie is)
- dit kan een RRN zijn (indien de identiteit die het mandaat ontving een persoon is)

Indien de mandaatgever de organisatie met KBO-nummer 0878065378 is en de mandaatnemer de organisatie met KBO-nummer 0428315871, dan kan dit via de base64-encoded versie van onderstaande JSON-string:

{
  "cap_hint": "EA",
  "code_hint": "0878065378",
  "via_hint": "0428315871"
}

Indien de mandaatgever een burger met rijksregisternummer 70010100202 is en de mandaatnemer een burger met rijksregisternummer 70010100101, dan kan dit via de base64 encoded versie van onderstaande JSON-string:

{
  "cap_hint": "BUR",
  "code_hint": "70010100202",
  "via_hint": "70010100101"
}

Varianten waar de mandaatgever een burger is en de mandaatnemer een organisatie (of omgekeerd) zijn ook mogelijk (indien de toepassing dit toelaat).

De gewenste identiteit doorgeven aan een andere toepassing

Indien een toepassing wil doorschakelen naar een andere toepassing maar aangeven wat de gewenste identiteit is, dan kunnen beide toepassingen best een manier afspreken om de base64 encoded identiteit door te geven: bijvoorbeeld via een specifieke querystring parameter.

De ontvangende toepassing zal deze querystring-parameter dan moeten doorgeven als login_hint in het authenticatierequest indien de gebruiker nog niet aangemeld is binnen die ontvangende toepassing.

De ontvangende toepassing zal moeten bekijken wat het gewenste gedrag is indien er een gewenste identiteit wordt meegestuurd, maar de gebruiker reeds aangemeld is in de toepassing onder een andere identiteit.

Wisselen van organisatie binnen de eigen toepassing

De functionaliteit om gericht aan te melden kan ook gebruikt worden om te switche van identiteit binnn de eigen toepassing.

In dat geval zal de toepassing de gebruiker (enkel) lokaal moeten afmelden en het Toegangsbeheer (ACM) moeten vragen om de gebruiker aan te melden onder de gewenste identiteit door bij de authenticatie de correcte login_hint mee te sturen. Het toegangsbeheer (ACM) zal dan opmerken dat er nog een geldige sessie aanwezig is en zal de identiteit voor die toepassing updaten naar de gewenste identiteit.