idin Implementatiegids

idin Implementatiegids CM Identity Services November 2017 V1.3

Inhoud: 1 Algemeen... 2 1.1 Doelgroep... 2 1.2 Verschillende partijen... 2 1.3 Algemene aandachtspunten... 3 2. Dienstbeschrijving... 4 2.1 Beschikbare gegevens... 6 2.1.1. Uniek nummer voor inloggen... 6 2.1.2. Geverifieerde gegevens van (eind)gebruikers:... 6 2.1.3 Gegevens verstrekt door (eind)gebruiker aan de Issuer:... 6 2.2 Kwaliteit van de verstrekte gegevens... 6 2.3 Diversiteit bij verstrekte gegevens... 7 3 Stijlgids idin... 9 3.1 Visuele huisstijl... 9 3.1.1 Voorlichting (eind)gebruikers... 9 3.1.2 Lijst van banken... 10 4 Technische implementatie... 13 4.1 Test en acceptatie traject... 13 4.1.1 Test cases... 14 4.1.2 Live gang... 14 Pagina 1

1 Algemeen Deze implementatiegids kun je als leidraad gebruiken voor het stapsgewijs implementeren van idin in de organisatie. Mochten er onverhoopt toch nog vragen of onduidelijkheden zijn neem dan contact op met CM via 076 752 7000 of via idin@cmdisp.com 1.1 Doelgroep Dit document is bedoeld voor klanten van CM die idin afnemen en dient ter aanvulling op de beschikbaar gestelde API-documentatie. Naast idin biedt de API de mogelijkheid om ook van andere authenticatiediensten van CM gebruik te maken. In deze implementatiegids worden eerst de verschillende partijen zoals die vertegenwoordigd zijn binnen het idin Scheme 1 toegelicht. Daarna wordt idin als dienst verder toegelicht en lees je meer over de te gebruiken huisstijl. In het laatste hoofdstuk wordt stilgestaan bij het testen van de implementatie en de te ondernemen stappen voordat de implementatie live gezet kan worden. 1.2 Verschillende partijen In het idin Scheme zijn verschillende rollen vertegenwoordigd. Om duidelijk te maken hoe de rolverdeling en het beheer van idin eruit ziet is onderstaande flowchart gemaakt. De rollen worden daarna tekstueel verder toegelicht. 1 Het idin Scheme is een stelsel van functionele, organisatorische en technische afspraken zoals nader beschreven in de Rules & Regulations; beheerd door Currence idin BV Pagina 2

Rol (Eind)Gebruiker Klant DISP (Digital Identity Service Provider) Issuer Acquirer Toelichting De natuurlijke persoon die toegang heeft tot de online dienstverlening van zijn bank (de Issuer) en daarvoor gebruik maakt van een door die bank aan hem verstrekt toegangsmiddel. Zijn/haar gegevens worden vastgelegd door de bank/issuer Een bedrijf/dienst/instelling die eindgebruikers de mogelijkheid wil bieden zichzelf online te identificeren en een contractrelatie heeft met CM Identity Services. Een door Currence/iDIN BV gecertificeerde partij die namens het Scheme afspraken mag maken en contracten mag afsluiten met haar klanten over idin; in dit geval CM Identity Services Betreft de bank waarmee de (eind)gebruiker toegang heeft tot de middelen om zich via idin te identificeren. Deze bank heeft een licentieovereenkomst met Currence/iDIN BV afgesloten. Betreft de partij waarmee CM Identity Services een contract heeft afgesloten voor de inkoop van idin transacties. Deze partij heeft een Licentieovereenkomst met Currence/iDIN BV afgesloten. 1.3 Algemene aandachtspunten Met idin krijg je toegang tot persoonlijke gegevens en deze vallen daarom onder de wet persoonsgegevens. Deze dienen dus zorgvuldig te worden gebruikt en verwerkt, volgende de actuele richtlijnen. Daarom vragen wij aandacht voor onderstaande: Vraag alleen de gegevens op die je nodig hebt. Bij het afsluiten van het contract met CM wordt vastgelegd welke persoonsgegevens via idin uitgevraagd gaan worden. Indien op een later moment de wens ontstaat om ook andere gegevens uit te vragen kun je contact opnemen met CM. Pagina 3

2. Dienstbeschrijving idin biedt verschillende gegevens die individueel of gecombineerd opgevraagd kunnen worden. In onderstaande flowchart is weergegeven welke communicatie plaatsvindt tussen CM Identity Services, Klant en (eind)gebruiker. De communicatie die daarnaast plaatsvindt tussen de Issuïng en de Acquiring bank is daarom weergegeven in een stippellijn. In paragraaf 2.1 worden de beschikbare gegevens verder toegelicht. 1. Bankselectie De (eind)gebruiker selecteert op jouw website de bank via wie de (eind)gebruiker zich wil identificeren. 2. Transactie De transactie wordt gestart en via CM wordt bij de geselecteerde issuïng bank de gewenste consumentdata aangevraagd. Zie hieronder een voorbeeld van een transactieverzoek. TRANSACTION REQUEST { merchant_token : GUID, identity : true, name : true, gender : true, address : true, date_of_birth : true, 18y_or_older : true, email_address : true, telephone_number : true, issuer_id : BANKID, entrance_code : string, merchant_return_url : string, language : nl } Pagina 4

3. Communicatie tussen Issuïng en Acquiring bank De (eind)gebruiker verlaat jouw website en wordt naar de internetbankieren omgeving van zijn of haar bank gestuurd. 4. Communicatie tussen Issuïng en Acquiring bank De (eind)gebruiker geeft in de bankomgeving goedkeuring om de uitgevraagde data de verstrekken. 5. Status Afhankelijk van de respons van de (eind)gebruiker in de internetbankieren omgeving krijgt de idin transactie een status toegekend. Deze status met geaccordeerde data attributen wordt via de Issuer en Acquirer aan CM verstuurd. 6. Webpagina klant CM zorgt ervoor dat de (eind)gebruiker wordt teruggestuurd naar jouw website en jij de geaccordeerde data ontvangt. Zie hieronder een voorbeeld van een succesvolle status met geaccordeerde data attributen. Na het afronden van deze transactie wordt door CM enkel onderstaande data bewaard gedurende een periode van 14 maanden: Tijdstip van de transactie Transactie ID Status Issuer Acceptant reference De overige data kan enkel via CM worden opgevraagd bij de betreffende Acquiring of Issuïng bank. Pagina 5

2.1 Beschikbare gegevens 2.1.1. Uniek nummer voor inloggen Bij iedere idin transactie wordt een uniek nummer mee gegeven. Er worden twee mogelijkheden onderscheiden: BIN staat voor Bank Identificatie Nummer en wordt samengesteld uit 3 kenmerken: de Issuer, Klant en de (eind)gebruiker. BIN is geschikt voor herhaal inlog aangezien de (eind)gebruiker zich hiermee uniek identificeert bij Klant. Transient_ID; Transitieve transacties worden gebruikt indien gegevens slechts eenmalig opgevraagd hoeven worden. Dit is een uniek nummer dat wordt toegekend door de Issuer aan het desbetreffende idin bericht. 2.1.2. Geverifieerde gegevens van (eind)gebruikers: Afkomstig van een onafhankelijke bron, het wettelijk identiteitsbewijs: Naam: voorletters (s), voorvoegsels, achternaam (geslachtsnaam/legal last name) Leeftijdsindicatie: 18 jaar of ouder; dan wel Geboortedatum Geslacht 2.1.3 Gegevens verstrekt door (eind)gebruiker aan de Issuer: Achternaam die de voorkeur heeft van (eind)gebruiker; zoals bijvoorbeeld preferred name/partner last name Woonadres: straat, huisnummer (toevoeging), postcode, stad Emailadres Telefoonnummer (eind)gebruikers hebben voor de gegevens emailadres en telefoonnummer de mogelijkheid om te besluiten deze niet mee te sturen en bij sommige banken om deze te overschrijven met de gewenste gegevens. 2.2 Kwaliteit van de verstrekte gegevens Met specifieke eisen is bepaald waaraan de elektronische identificatiemiddelen van een Issuer moeten voldoen om te worden toegelaten in het idin Scheme. De basis voor deze eisen komt voort uit de eidas regulering. Bij idin dienen Issuers minimaal een elektronisch identificatiemiddel aan te bieden dat voldoet aan het betrouwbaarsheidsniveau Substantieel. Dit heeft de volgende hoofdkenmerken: Identiteit van de (eind)gebruiker is geverifieerd aan de hand van en op basis van een geldig legitimatiebewijs. Er wordt gebruik gemaakt van twee factor authenticatie. Pagina 6

Naast bovenstaande hoofdkenmerken vanuit eidas, zijn er eisen gesteld aan de kwaliteit van de gegevens die door de Issuers verstrekt worden. De gebruikers doelgroep van idin voldoet aan de volgende randvoorwaarden: Natuurlijke personen; Met toegang tot internet en/of mobiel bankieren; Zijn Wwft-compliant geïdentificeerd door de bank De kwaliteitsbeoordeling van gegevens kennen onderstaande meetcriteria met de daarbij vastgestelde normen: Meetcriteria Uitleg Norm Accuraatheid De mate waarin idin-datavelden overeenkomen met de werkelijkheid/ hetgeen er is vastgelegd in de kopie identiteitsbewijs. 95 99 % Compleetheid De mate waarin idin-data aanwezig is: de datavelden uit het datamodel zijn gevuld. 98 100 % Correctheid De mate waarin idin-data voldoet aan het vereiste veldformaat: voldoet aan de formatting rules zoals beschreven in de meest recente versie van de technische specificaties van idin. Een attribuut moet kunnen worden geleverd conform de formatting rules. 99 % Uniciteit De mate waarin idin-data (i.c. BSN) uniek is: slechts één keer voorkomt bij een Issuer. 97 % 2.3 Diversiteit bij verstrekte gegevens Hieronder wordt de diversiteit in gegevens beschreven waarvan wij adviseren om er rekening mee te houden in de implementatie. Voor de attributen naam, adres en email zijn niet-latijnse karakters mogelijk. Zo is bijvoorbeeld A Żaiŀenoŕ een geldige naam die via idin geleverd zou kunnen worden. Naam Het is mogelijk dat de legal last name ontbreekt, maar in plaats hiervan de preferred last name geleverd is. Het is mogelijk dat de last name prefix is afgekort (bijvoorbeeld vd of v.d. in plaats van van de ). In sommige gevallen bevat de legal last name niet alleen de legal last name, maar is deze vooraf gegaan of opgevolgd door de partner last name. Pagina 7

Als de (eind)gebruiker een samengevoegde achternaam heeft met twee prefixes (bijvoorbeeld de Vries van Dijk ), wordt alleen de eerste prefix in het last name prefix veld geleverd, de rest van de naam wordt in het last name element geleverd. In uitzonderingsgevallen kan het voorkomen dat de initialen van de (eind)gebruiker niet aanwezig zijn. Geboortedatum In uitzonderingsgevallen kan het voorkomen dat de maand of dag van de geboortedatum van de (eind)gebruiker onbekend is, omdat het geboorteland de exacte geboortedatum niet geregistreerd heeft. In dit geval wordt de waarde 00 voor de onbekende dag of maand gebruikt. Wanneer bijvoorbeeld de dag onbekend is zou de geboortedatum 1955-01-00 kunnen zijn, of wanneer zowel de dag als datum onbekend is zou de geboortedatum 1955-00-00 kunnen zijn. Adres Er zijn vier scenario s om rekening mee te houden wanneer er een adres wordt geleverd: Het is mogelijk dat je alleen de postcode en het huisnummer ontvangt, of de straatnaam, het huisnummer en de stad. Beide zijn te herleiden tot een uniek adres. Sommige (eind)gebruikers hebben geen huisnummer (bijvoorbeeld wanneer zij wonen op een woonboot), in dit geval wordt het veld addressextra gebruikt om het adres nader te specificeren. Sommige (eind)gebruikers hebben een internationaal adres, wat bestaat uit andere velden dan een Nederlands adres. Wanneer dit voorkomt wordt een apart veld voor het internationale adres geleverd. Straatnamen kunnen afgekort zijn (bijvoorbeeld Mr. J.F. Vietorstraat of Kerkstr ). Telefoonnummer Er zijn twee mogelijke scenario s om rekening mee te houden: Het telefoonnummer begint met een + gevolgd door de landcode en de rest van het telefoonnummer. Bijvoorbeeld +31612345678 voor mobiele nummers en +31203051900 voor vaste nummers. Het telefoonnummer heeft een formaat dat haakjes, spaties, + en/of bevat. Bijvoorbeeld 06-12345678 voor mobiele nummers en (020)3051900 voor vaste nummers. Pagina 8

3 Stijlgids idin De banken hebben een stijlgids opgesteld voor het gebruik van het merk idin, waaraan klanten van CM Identity Services zich dienen te houden. In dit hoofdstuk lichten we toe welke elementen hierin op jullie van toepassing zijn en waar rekening mee gehouden moet worden in de implementatie van idin. Te beginnen met de visuele huisstijl. Naast het verplicht gebruik van de aangeboden visuele huisstijl gelden er vereisten omtrent de manier waarop (eind)gebruikers worden voorgelicht (3.1.1), presentatie van de bankenlijst (3.1.2) gevolgd door aanbevolen teksten (3.1.3), en foutafhandeling (3.1.4). 3.1 Visuele huisstijl idin en het logo zijn geregistreerde merken van de Betaalvereniging Nederland. De te gebruiken logo s zijn te vinden via deze link. Informatie omtrent correct gebruik van de logo s voor wat betreft kleurstelling, compositie en dergelijke tref je het huisstijl\handboek via deze link. 3.1.1 Voorlichting (eind)gebruikers Vanuit idin BV zijn er vereisten opgesteld omtrent de manier waarop (eind)gebruikers worden voorgelicht over idin en de toepassing. Hieronder wordt beschreven wat de vereisten zijn en worden wat voorbeelden gegeven. Vereisten: Het moet duidelijk zijn dat de (eind)gebruiker gebruik gaat maken van idin Het moet duidelijk zijn voor de (eind)gebruiker voor welk doeleinde de gegevens opgevraagd gaan worden Er dient gebruik gemaakt te worden van een https-verbinding, met een minimale score van A op https://www.ssllabs.com/ssltest/. Uitleg idin aan de (eind)gebruiker: Korte versie: Makkelijk en veilig online identificeren met uw bank. Uitgebreide versie (voorkeur): Met idin kunt u zich online identificeren bij een bedrijf of instelling. Gemakkelijk, vertrouwd en veilig met de inlogmethode van uw bank. Uitleg voordelen idin aan de (eind)gebruiker: 1. Makkelijk en veilig online identificeren. 2. Met de vertrouwde inlogmethode van uw bank. 3. Eén manier van inloggen bij bedrijven en instellingen. 4. Geen aparte gebruikersnamen en wachtwoorden meer onthouden. 5. Zelf invullen van persoonlijke gegevens is niet meer nodig. Op de volgende pagina tref je een voorbeeld. Pagina 9

Een voorbeeld: 3.1.2 Lijst van banken Om ervoor te zorgen dat een idin-transactie voor de (eind)gebruiker altijd op dezelfde wijze verloopt, dienen klanten de volgende presentatie aan te houden voor de lijst van banken op hun verwijzingsscherm: Alle banken uit de lijst van banken moeten worden getoond in een dropdown listbox. Het eerste element van deze lijst is Kies uw bank... ; dit is ook het element dat voorgeselecteerd is. Indien idin in meerdere landen geboden wordt, wordt de landsnaam van het voorkeursland van de klant getoond (ofwel het land waar de klant is gevestigd ofwel het land waar de (eind)gebruiker, vermoedelijk, vandaan komt). De namen van alle banken uit het voorkeursland worden vervolgens getoond in afzonderlijke elementen, in dezelfde (alfabetische) volgorde. Daarna worden de namen van andere landen en de bijbehorende banken getoond, ook weer in dezelfde (alfabetische) volgorde als in de lijst van banken. De klant moet een foutmelding genereren indien de (eind)gebruiker een van de elementen Kies uw bank... of een landsnaam kiest. Het is aan te bevelen het HTML value attribuut van de items in de lijst van banken in te stellen op issuer_id (BIC) van de betreffende Issuer, omdat deze nodig is in vervolgberichten. Het is de klant niet toegestaan om zelf Issuers (tijdelijk) uit de lijst van banken te verwijderen c.q. uit te grijzen. Een voorbeeld: Zolang gebruik gemaakt wordt van de Directory call van CM, wordt voldaan aan de gestelde eisen. Pagina 10

3.1.3 Aanbevolen teksten happy flow idin biedt verschillende gegevens, die door idin BV zijn onderverdeeld in vier use cases. In deze paragraaf tref je na het beschrijven van de use cases, per use case aanbevolen teksten aan. Toelichting use cases: 1. Gegevens verstrekken/versturen: De (eind)gebruiker kiest ervoor gegevens te verstrekken met idin, dit kan met of zonder het aanmaken van een account. Klant vraagt deze gegevens op met of zonder BIN. Hieronder valt bijvoorbeeld ook het verstrekken van de geboortedatum of NAW-gegevens met/zonder BIN; 2. Inloggen: De (eind)gebruiker logt in met idin. Er worden geen gegevens verstrekt, alleen een BIN; 3. Leeftijd bevestigen: Bevestiging leeftijd 18+ (met of zonder (BIN)). Dit kan worden gebruikt voor zowel verificatie van leeftijd boven als van onder 18 jaar; 4. Bankbevestiging: (Eind)gebruiker bevestigt dat hij klant is van een bepaalde Issuer. Aanbevolen teksten per use case: Use case Aanbeveling Klant verwijzingsscherm 2 Aanbeveling Klant returnwebpagina 3 1. Gegevens verstrekken Maak uw account aan met idin Gegevens verstrekken/versturen met idin Uw gegevens zijn succesvol ontvangen Wij hebben de volgende gegevens ontvangen: [overzicht gegevens] 2. Inloggen Inloggen met idin U bent ingelogd met idin Tonen laatste inlog (verplicht) 3. Leeftijd bevestigen Leeftijd bevestigen met idin Bedankt voor het bevestigen van uw leeftijd Direct toegang tot de site 4. Bankbevestiging Bevestig dat u klant bent bij uw bank met idin U heeft bevestigd dat u klant bent bij [naam Issuer] 2 Het verwijzingsscherm van de klant is het scherm waar de (eind)gebruiker kiest voor het gebruik van idin. 3 De return-webpagina is de webpagina van de klant waar de (eind)gebruiker terugkeert nadat deze de transactie heeft goedgekeurd in zijn internetbankieromgeving. Pagina 11

3.1.4. Aanbevolen teksten non happy flow Bij het afronden van de transactie wordt een status mee gegeven. Het is belangrijk om ook bij een status anders dan success, de (eind)gebruiker de correcte feedback te geven. Geef bij eventuele fouten of een status anders dan success, indien mogelijk, de optie om het nogmaals te proberen met een nieuwe idin-transactie. Je kunt ook de optie bieden om op een andere manier in te loggen dan wel de gegevens met een andere methode te verstrekken. Hieronder volgen aanbevolen teksten bij een status anders dan success: 1: expired Helaas is het idin verzoek niet binnen de daarvoor geldende periode afgerond. Probeer het nogmaals. 2: cancelled Het idin verzoek is door u afgebroken 3: failure of open Er is een fout opgetreden bij het idin verzoek. Probeer het nogmaals. Er kan ten alle tijden een fout optreden. De API van CM geeft in een error resultaat altijd een object met informatie mee. Het message attribuut van dit object bevat meer informatie die aan de (eind)gebruiker getoond dient te worden. Deze kan afhankelijk van de opgegeven taal in het Nederlands of het Engels zijn. Voorbeelden van foutmeldingen zijn: De geselecteerde bank is op dit moment niet beschikbaar. Probeer het later nog een keer. De geselecteerde bank is op dit moment niet beschikbaar i.v.m. onderhoud tot naar verwachting [datum en tijdstip]. Probeer het later nog een keer. Pagina 12

4 Technische implementatie Met de verkregen credentials 4 heb je initieel via onze API slechts toegang tot dummydata. Voordat er daadwerkelijk persoonsgegevens kunnen worden uitgevraagd, dienen de testcases succesvol doorlopen te zijn. Deze test cases worden in dit hoofdstuk verder toegelicht. Voor de technische implementatie biedt CM naast documentatie ook een Swagger specificatie. Om de implementatie te vergemakkelijken heeft CM Identity Services plugins beschikbaar voor Magento en Woocommerce. Nog een kleine tip vooraf: gebruik bij het aanspreken van de API een User-Agent header die de implementatie herkenbaar maakt. De API is bedoeld voor serverside gebruik en is niet geschikt om rechtstreeks vanuit een browser aan te spreken. 4.1 Test en acceptatie traject Tijdens de implementatie krijg je toegang tot dummy data en kun je de volledige idin flow doorlopen met behulp van een bank simulatie. Zo kun door tijdens dit proces op de knop Developer te klikken verschillende test cases doorlopen door het antwoord van de test service steeds te wijzigen. Ook na het verkrijgen van toegang tot consumenten data kun je met behulp van https://idin.cmtelecom.com/idin/v1.0/test/ nog altijd de dummy data en bank simulatie benaderen. 4 De door CM verstrekte credentials zijn vertrouwelijk en dienen niet verder verspreid te worden. Heb je nog geen credentials ontvangen? Je kunt ze direct zelf aanvragen via deze link. Pagina 13

4.1.1 Test cases Hieronder zijn de minimaal te doorlopen test cases benoemd: Het ophalen van de lijst van banken Het initiëren van een transactie Het afronden van een transactie in de 5 mogelijke statussen; success, cancelled, failure, expired en open Het afhandelen van een foutbericht Het niet bereikbaar zijn van een verbinding met de CM idin API Het gebruik van gegevens attributen om verschillende dummy data op te halen Het niet beschikbaar zijn van gegevens die worden opgevraagd. 4.1.2 Live gang Heb je alle tests doorlopen en ben je helemaal klaar om live te gaan? Neem dan contact op met ons via idin@cmdisp.com. Vermeld hierbij de volgende gegevens: Naam en bedrijfsnaam Een link naar de implementatie of screenshots van de implementatie Een korte beschrijving van hoe een eindconsument idin gaat gebruiken in de website. We kijken graag even met je mee voordat je live gaat. Goed om te weten is dat wij een controle zullen doen op: Het gebruik van een user agent header Het gebruik van een https-verbinding Of de consument correct wordt voorgelicht zoals beschreven in de eerdere hoofdstukken. Of de webpagina s voldoen aan de huisstijl van idin Zodra we de implementatie hebben bekeken en met jullie hebben afgestemd zal het account worden geactiveerd voor toegang tot live data en kun je aan de slag. Pagina 14