Functionele beschrijving DigiD - Inloggen met app2app

Inleiding

Het document is geen handleiding voor het implementeren van app2app en bevat geen technische details; daarvoor dient de Koppelvlakspecificatie SAML-DigiD of DigiD OIDC for (Mobile) Apps, afhankelijk van de aansluitwijze van de dienstaanbieder.

Voor functionele informatie over DigiD in het algemeen zijn resp. de Functionele beschrijving DigiD app en de Functionele beschrijving DigiD beschikbaar. Deze pagina is daar een uitbreiding op: al het daar beschrevene is ook van toepassing op de DigiD app en de app2app-koppeling. Op deze pagina wordt die algemene DigiD-informatie bekend verondersteld.

Aansluiten op app2app

Een dienstaanbieder die zijn gebruikers een app aanbiedt waarvoor zij moeten inloggen met DigiD, dient daartoe zijn app met de DigiD app te integreren via een app2app-koppeling. Daarvoor zijn 2 aansluitwijzen beschikbaar:

1. Aansluiten op app2app als onderdeel van een algemene DigiD-aansluiting.

Voorwaarden daarbij zijn:

• Dat hij al een werkende aansluiting heeft op DigiD
• Dat die aansluiting via het SAML-koppelvlak verloopt.

Een dienstaanbieder die nieuw wenst aan te sluiten op DigiD, raadpleegt hiervoor de Handleiding Aansluiten DigiD.

2. Direct aansluiten op app2app (zonder algemene DigiD-aansluiting).

Dit is vooral geschikt voor dienstaanbieders zonder webdienst, met alleen een app. Deze aansluiting werkt volgens het OIDC-protocol. Zie DigiD OIDC for (Mobile) Apps.

Noot: Deze aansluitvorm is nog niet algemeen beschikbaar voor dienstaanbieders.

Technisch zijn deze aansluitingen verschillend; functioneel (wat de gebruiker er van ziet) niet.

DigiD app

DigiD app in het kort

DigiD kent naast gebruikersnaam en wachtwoord (eventueel aangevuld met sms-controle) nog een inlogmiddel: de DigiD app. Die is ontwikkeld omdat steeds meer burgers hun zaken met de overheid op hun mobiele device afhandelen. Na een initiële activatie, waarbij de gebruiker zichzelf moet authentiseren met een van zijn andere DigiD inlogmiddelen, en een pincode moet kiezen, is de app klaar om mee in te loggen. Dat gaat als volgt:

De gebruiker vraagt toegang tot afgeschermde gegevens op de website van een dienstaanbieder (webdienst). De dienstaanbieder vraagt hem om met DigiD in te loggen en geeft hem daarbij ook de mogelijkheid dat via de DigiD app te doen. De gebruiker hoeft dan alleen zijn pincode in te voeren. De DigiD app zoekt vervolgens contact met de DigiD backend om de authenticatie uit te voeren. Is die succesvol, dan mag de dienstaanbieder de gebruiker toegang verlenen tot de gevraagde gegevens.

Omdat het een tweefactorauthenticatie betreft, is het betrouwbaarheidsniveau gelijk aan dat van gebruikersnaam en wachtwoord, aangevuld met sms-controle (Midden). Als de gebruiker ook nog een eenmalige ID-check heeft toegevoegd aan zijn app, is het niveau zelfs Substantieel.

Uitbreiding met app2app

In eerste instantie was de DigiD app alleen geschikt voor inloggen op een website van een dienstaanbieder. Maar steeds meer dienstaanbieders introduceren een app waarin de gebruiker met DigiD moet inloggen. Ook zijn er zelfs dienstaanbieders met alleen een app, zonder bijbehorende webdienst. Om de inlogflow voor gebruikers van alle varianten herkenbaar en vertrouwd te houden, heeft Logius de DigiD app voorzien van een app2app-oplossing, die kortgezegd hierop neerkomt:

De app van een dienstaanbieder opent de DigiD app (op hetzelfde apparaat) op het moment dat authenticatie vereist is; de gebruiker voert in de DigiD app zijn pincode in die op de DigiD backend wordt gecontroleerd. Is de authenticatie succesvol, dan leidt de DigiD app de gebruiker terug naar de app van de dienstaanbieder, die hem toegang verleent tot de afgeschermde gegevens.

Het volgende hoofdstuk gaat hier in meer detail op in.

App2app-functionaliteit

Schermflow

Figuur 1 toont de schermen die de gebruiker doorloopt als hij wil inloggen op de app van een dienstaanbieder. De Berichtenbox app dient hier als voorbeeld van zo’n app:

1. Het inlogscherm in de app van de dienstaanbieder. Dit scherm verzoekt de gebruiker in te loggen met de DigiD app. Als de gebruiker hier gehoor aan geeft door op de DigiD-link of -knop te klikken, dan opent de DigiD app vanzelf.
2. Het pincodescherm in de DigiD app. Dit scherm vraagt de gebruiker om zijn pincode. Zodra de gebruiker het laatste cijfer van zijn pincode intoetst, en die pincode is correct, toont de app het volgende scherm.
3. Het bevestigingsscherm in de DigiD app. Hierop bevestigt de gebruiker dat hij bij de dienstaanbieder wil inloggen. Het scherm toont het icoon en de naam van de dienstaanbieder app. Zodra de gebruiker op ‘Inloggen’ klikt, schakelt de DigiD app terug naar app van de dienstaanbieder.
4. Het informatiescherm in de app van de dienstaanbieder. De dienstaanbieder app heeft van DigiD vernomen dat de gebruiker zich succesvol heeft geauthentiseerd, en geeft die gebruiker toegang tot de gevraagde gegevens. Met andere woorden: de gebruiker is ingelogd in de app van de dienstaanbieder.

Figuur 1: Schemflow app2app

Bovenstaande sequentie beschrijft de ‘happy flow’: de gebruiker heeft, voordat hij begon met inloggen, de DigiD app minimaal geactiveerd op het betrouwbaarheidsniveau dat de dienstaanbieder vereist. Dat hoeft niet het geval te zijn:

• Als hij zijn app nog niet geactiveerd heeft, kan hij toch vanuit de app van de dienstaanbieder inloggen met de DigiD app. Hij zal dan tijdens de inlogflow eerst de activatie moeten uitvoeren. Slaagt hij daarin, dan is hij daarna meteen ingelogd in de app van de dienstaanbieder.
• Als de dienstaanbieder niveau ‘substantieel’ vereist voor inzage in de gegevens, maar de gebruiker heeft de ID-check nog niet aan zijn app toegevoegd, dan zal hij tijdens het inloggen zijn identiteitsbewijs moeten scannen. Lukt hem dat, dan is hij daarna meteen ingelogd.

Deze uitgebreidere flows behoren tot de standaard functionaliteit van de DigiD app en zijn niet specifiek voor app2app. Daarom worden ze in dit document niet verder belicht.

Als de gebruiker de DigiD app in het geheel nog niet op zijn toestel heeft staan, zal het operating systeem van zijn device hem niet kunnen openen. In dat geval zal een DigiD-pagina getoond worden in de browser, waarvandaan de gebruiker zelf verdere actie kan ondernemen. Dit zal later in dit document verder toegelicht worden.

Procesflow

Via het SAML-protocol

Het proces van app2app-inloggen verloopt als volgt (de stapnummers komen overeen met de nummers in figuur 2):

1. De gebruiker heeft de app van de dienstaanbieder geopend, wil inzage in gegevens waarvoor een DigiD-authenticatie vereist is en is zodoende op de inlogpagina beland. Daar kiest hij voor inloggen met DigiD.
2. De app van de dienstaanbieder vraagt aan zijn backend toegang tot de afgeschermde informatie. De backend van de dienstaanbieder geeft als antwoord een authenticatieverzoek (SAML) terug.
3. De app van de dienstaanbieder stuurt dat authenticatieverzoek door naar de DigiD app via Android App link of iOS Universal link.
4. De DigiD app vraagt met dat authenticatieverzoek een authenticatiesessie aan bij de DigiD backend.
5. De DigiD app vraagt de gebruiker om zijn pincode.
6. De DigiD app stuurt de pincode naar de DigiD backend ter controle. Die meldt het resultaat van de authenticatie terug.
7. Als de authenticatie geslaagd is, vraagt de DigiD app aan de DigiD backend om een verwijzing naar het authenticatiebericht.
8. De DigiD app stuurt die verwijzing via Android App link of iOS Universal link naar de app van de dienstaanbieder.
9. De app van de dienstaanbieder stuurt de verwijzing door naar zijn backend.
10. De backend van de dienstaanbieder vraagt met de verwijzing bij de DigiD backend het echte authenticatiebericht op (dat het BSN van de gebruiker bevat).
11. De backend van de dienstaanbieder verstuurt de in stap 2 opgevraagde gegevens naar de dienstaanbieder app.
12. De app van de dienstaanbieder toont de gegevens aan de gebruiker.

Figuur 2: Inlogflow app2app via SAML

Via het OIDC-protocol

Noot: Deze aansluitvorm is nog niet algemeen beschikbaar voor dienstaanbieders.

Het proces van app2app-inloggen via OIDC verloopt als volgt (de stapnummers komen overeen met de nummers in figuur 3):

1. De gebruiker heeft de app van de dienstaanbieder geopend, wil inzage in gegevens waarvoor een DigiD-authenticatie vereist is en is zodoende op de inlogpagina beland. Daar kiest hij voor inloggen met DigiD.
2. De dienstaanbieder doet een inlogverzoek bij DigiD.
3. DigiD opent de DigiD app zodat de gebruiker zich kan authentiseren.
4. De DigiD app vraagt de gebruiker om zijn pincode.
5. De DigiD app stuurt de pincode naar de DigiD backend ter controle. Die meldt het resultaat van de authenticatie terug aan de app.
6. DigiD leidt de gebruiker terug naar de dienstaanbieder app met een verwijzing naar de gelukte authenticatie.
7. De dienstaanbieder wisselt die verwijzing bij DigiD in voor het BSN van de gebruiker.
8. De app van de dienstaanbieder toont de gegevens aan de gebruiker.

Figuur 3 - Inlogflow app2app via OIDC

Beheer en rapportage

Registratie dienstaanbieder app

Om zijn app aan te sluiten op de DigiD app zal een dienstaanbieder hem moeten registreren. 

Registratie bij een bestaande DigiD-aansluiting (SAML)

De dienstaanbieder voegt zijn app toe aan zijn al bestaande aansluiting van zijn webdienst op DigiD. Hij kan bij zijn aansluiting maximaal drie apps aanmelden. Al die apps vereisen per definitie het zelfde betrouwbaarheidsniveau als de bijbehorende webdienst.

DigiD legt voor elke app de volgende gegevens vast:

• Naam app: de naam die de DigiD app toont ter bevestiging aan de gebruiker tijdens het inloggen.
• Return-URL: de URL waar de DigiD app na de authenticatie naartoe terugschakelt om de dienstaanbieder app weer te openen.

De DigiD app toont tijdens het inloggen op het bevestigingsscherm ook het app-icoon van de dienstaanbieder, maar dat dient deze bij elk authenticatieverzoek mee te sturen. Ook de return-URL dient in dat verzoek te staan, zodat DigiD daarop een controle kan uitvoeren (zie paragraaf Onjuiste return-URL).

Een dienstaanbieder kan bij zijn aansluiting maximaal drie apps aanmelden.

Registratie als losse aansluiting (OIDC)

Noot: Deze aansluitvorm is nog niet algemeen beschikbaar voor dienstaanbieders.

De dienstaanbieder registreert zijn app als op zichzelf staande aansluiting. Hij dient daartoe de volgende gegevens aan te leveren:

• Naam organisatie: de naam van de organisatie die de dienstaanbieder app aanbiedt.
• Naam app: de naam die de DigiD app toont ter bevestiging aan de gebruiker tijdens het inloggen.
• Minimaal betrouwbaarheidsniveau: het inlogniveau dat de gebruiker minimaal moet hebben om in de app in te kunnen loggen.
• Return-URL: de URL waar DigiD na de authenticatie naartoe terugschakelt om de dienstaanbieder app te weer te openen.
• Logo-URL: endpoint op het domein van de dienstaanbieder waar DigiD het icoon van de dienstaanbieder app kan ophalen om het te tonen in de DigiD app.
• Metadata-URL: endpoint op het domein van de dienstaanbieder waar DigiD de publieke sleutels kan ophalen waarmee de dienstaanbieder zijn berichten ondertekent.

Rapportage over authenticaties

Logius levert maandelijks rapportages op die inzicht geven in het aantal authenticaties bij een dienstaanbieder. De app2app-authenticaties zijn daarin opgenomen.

Foutsituaties

Dit hoofdstuk beschrijft de foutsituaties die kunnen optreden tijdens het inloggen met app2app, en hoe die worden afgehandeld.

DigiD app niet gevonden

Als de app van de dienstaanbieder naar de DigiD app schakelt om de gebruiker te laten inloggen, kan het zijn dat de DigiD app niet geopend kan worden. Dat kan verschillende oorzaken hebben:

• De gebruiker heeft de DigiD app niet op zijn apparaat geïnstalleerd.
• Universal links werken niet (iOS): Sinds de release van iOS 13.0 worden de Universal links – die nodig zijn om een app te herkennen op het apparaat – niet altijd direct geïnstalleerd na het downloaden van een app. Zonder die registratie lijkt het alsof de DigiD app niet op het apparaat staat terwijl dat wel zo is; de gebruiker kan onterecht niet inloggen in de dienstaanbieder app.

Als de DigiD app niet geopend kan worden, toont DigiD een webpagina in de browser. Omdat niet bekend is om welke de reden de app niet geopend kon worden, reikt die pagina de gebruiker voor beide oorzaken een oplossing aan:

• Voor het geval de DigiD app nog niet op het apparaat staat: De gebruiker kan via een link de store openen om de app te downloaden. Pas als hij dat gedaan heeft, kan hij opnieuw proberen in te loggen in de app van de dienstaanbieder.
• Voor het geval de app wel op het apparaat staat, maar de Universal links niet werken: De gebruiker kan de DigiD app alsnog handmatig openen via een URL-schema.
  • De werking van dit uitwijkmechanisme wordt alleen gegarandeerd als de dienstaanbieder zijn authenticatieverzoek via redirect binding verstuurt; zie voor meer informatie Koppelvlakspecificatie SAML-DigiD.
  • Het wordt de dienstaanbieder aangeraden datzelfde mechanisme te implementeren voor het geval dat zijn app na het inloggen met de DigiD app niet geopend kan worden: ook hij kan de gebruiker de app handmatig laten openen vanaf een webpagina.

DigiD app niet geactiveerd

Als blijkt dat de gebruiker de DigiD app nog niet heeft geactiveerd, wordt zijn authenticatie niet afgebroken, maar zal hij tijdens de inlogflow de activatie moeten uitvoeren. Slaagt hij daarin, dan kan hij daarna de authenticatie vervolgen.

Zie hoofdstuk Schermflow.

DigiD app op te laag betrouwbaarheidsniveau

Als blijkt dat de gebruiker de DigiD app niet geactiveerd heeft op het betrouwbaarheidsniveau dat de dienstaanbieder vereist, wordt zijn authenticatie niet afgebroken, maar zal hij tijdens het inloggen de ID-check moeten uitvoeren. Slaagt hij daarin, dan kan hij daarna de authenticatie vervolgen.

Zie hoofdstuk Schermflow.

Inloggen met DigiD app uitgeschakeld

Op de DigiD backend kan het inloggen met de DigiD app in zijn geheel worden uitgeschakeld. Is dat het geval, dan kan een gebruiker ook niet met app2app inloggen bij zijn dienstaanbieder.

De dienstaanbieder kan Logius vragen app2app voor zijn eigen app(s) op te heffen via een wijzigingsformulier op de website van Logius.

App2app voor dienstaanbieder uitgeschakeld

Voor een dienstaanbieder kan op de DigiD backend de app2app-functionaliteit worden uitgeschakeld.

• SAML-aansluiting: Gaat het om een SAML-aansluiting dan In dat geval zal een gebruiker in géén van de apps van die dienstaanbieder kunnen inloggen met de DigiD app. 
• OIDC-aansluiting: In het OIDC-protocol staat elke dienstaanbieder app op zichzelf, en kan elke app dus ook apart aan-of uitgezet worden. 

Noot: Deze aansluitvorm is nog niet algemeen beschikbaar voor dienstaanbieders.

Onjuiste return-URL

De dienstaanbieder heeft bij het aanmelden van zijn app2app-aansluiting de return-URL van zijn app opgegeven. Hij dient die ook in elk authenticatieverzoek mee te sturen, zodat DigiD kan controleren of de meegestuurde URL overeenkomt met de geregistreerde. Is dat niet het geval, dan breekt DigiD de authenticatie af.

Onjuiste pincode

Als de gebruiker er niet in slaagt de juiste pincode in te voeren in de DigiD app, raakt hij niet ingelogd. Hij krijgt drie kansen; daarna breekt DigiD de authenticatie af en deactiveert de DigiD app.

Gebruiker annuleert

Als de gebruiker het inloggen in de DigiD app annuleert, breekt DigiD de authenticatie af.

Sessie verlopen

Als de gebruiker te lang de tijd neemt tijdens het inloggen, en de DigiD backend ontvangt 15 minuten lang geen bericht van de DigiD app, dan breekt DigiD de authenticatie af. Dat gebeurt ook als de gebruiker het toestel waarop hij de DigiD app heeft geactiveerd in ‘private mode’ heeft staan.

Technische storing

Er kan een technische storing optreden in de koppeling tussen DigiD en de dienstaanbieder, of intern bij DigiD, waardoor inloggen niet mogelijk is.

Woordenlijst

Documentbeheer