Finansiell ID-Teknik BID AB Riktlinjer för Mobilt BankID till förlitande part Version 1.0.2 Sida 1(28) Datum:2011-10-26 Riktlinjer för Mobilt BankID till förlitande part Version 1.0.2 2011-10-26 Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part Version 1.0.2 Sida 2(28) Datum:2011-10-26 Innehållsförteckning 1 Dokumenthistorik ............................................................................................................... 3 2 Inledning ............................................................................................................................. 3 2.1 Plattformsstöd .................................................................................................................. 3 3 Referenser ........................................................................................................................... 3 4 Översikt Mobilt BankID ..................................................................................................... 5 4.1 5 Exempelanvändning........................................................................................................ 6 Webbtjänst ........................................................................................................................... 8 5.1 Flöde ................................................................................................................................ 8 5.2 Alternativflöden ............................................................................................................... 8 6 Mobil webbtjänst ................................................................................................................. 9 6.1 Flöde ................................................................................................................................ 9 6.2 Alternativflöden ............................................................................................................. 10 7 App..................................................................................................................................... 13 7.1 Flöde .............................................................................................................................. 13 7.2 Alternativflöden ............................................................................................................. 13 8 URL-schema ..................................................................................................................... 14 8.1 iOS .................................................................................................................................. 14 8.2 Android .......................................................................................................................... 15 9 RP Interface ...................................................................................................................... 15 9.1 Flöde och riktlinjer ........................................................................................................ 15 9.2 Krav på teknisk lösning ................................................................................................. 18 9.3 Riktlinjer för meddelanden ........................................................................................... 19 10 Anslutningsinformation ................................................................................................ 21 11 Testmiljö......................................................................................................................... 22 12 Support ........................................................................................................................... 24 13 BankID säkerhetsapp RP Interface Description .......................................................... 25 13.1 Introduction ................................................................................................................ 25 13.2 References .................................................................................................................. 25 13.3 Authenticate ............................................................................................................... 25 13.4 Sign ............................................................................................................................. 25 13.5 Collect ......................................................................................................................... 26 13.6 Fault ........................................................................................................................... 27 14 Rekommenderade termer .............................................................................................. 28 Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part 1 Version 1.0.2 Sida 3(28) Datum:2011-10-26 Dokumenthistorik Version Datum Beskrivning 1.0 2011-05-17 Första versionen av riktlinjer för Mobilt BankID. 1.0.1 2011-06-13 Kompletterat avsnittet Felkoder med meddelande för SIGN_VALIDATION_FAILED. Kompletterat avsnittet Krav på teknisk lösning med nytt börkrav RFT10. Uppdaterat avsnittet Riktlinjer för meddelanden med nytt meddelande RFA3. Uppdaterat avsnittet Testmiljö. 1.0.2 2011-10-26 Uppdaterat avsnittet Mobil webbtjänst med avseende på begränsningar i JavaME-stödet samt ett designförtydligande. Ändrat BankID-URL:en för iOS i avsnittet Programmatisk start av BankID säkerhetsapp 2 Inledning Det här dokumentet beskriver hur en förlitande part (FP) kan använda Mobilt BankID för inloggning (legitimering) och underskrift (signering) i egna tjänster och integrera mot Mobilt BankID. Mobilt BankID har tre huvudanvändningsfall. 1) 2) 3) Webbtjänst - Legitimering/underskrift med förlitande parts tjänst på annan enhet, t.ex. webbläsare i en PC. Mobil webbtjänst - Legitimering/ underskrift med förlitande parts tjänst i mobil webbläsare. App - Legitimering/underskrift med förlitande parts mobilapp. Det här dokumentet beskriver hur FP integrerar mot Mobilt BankID i de olika fallen och på de olika mobilplattformarna. 2.1 Plattformsstöd Mobilt BankID finns idag för mobiltelefoner och viss annan hårdvara baserad på Android-, iOS-plattformar och JavaME-plattformar. Aktuell information om vilken hårdvara som stöds finns på http://support.bankid.com/mobil. 3 Referenser [1] BankID-app RP Interface Description rev. X.Y, kapitel 13 [2] Rekommenderade termer, kapitel 14 Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part Version 1.0.2 Sida 4(28) Datum:2011-10-26 Samtliga dokument finns tillgängliga via http://www.bankid.com/rp/info. Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part 4 Version 1.0.2 Sida 5(28) Datum:2011-10-26 Översikt Mobilt BankID För att inloggning eller underskrift med Mobilt BankID ska vara möjlig måste användaren först ha installerat BankID säkerhetsapp i sin telefon och hämtat ett BankID. Detta gör användaren med hjälp av funktioner i sin bank. En FP som vill låta sina användare logga in eller skriva under information med Mobilt BankID gör webbserviceanrop till en tjänst som BankID tillhandahåller. Det finns speciella funktioner för att begära legitimering och underskrift samt för att kontrollera resultatet. Kommunikationen är asynkron i betydelsen att FP först begär att funktionen ska utföras och därefter regelbundet kontrollerar om det finns något resultat. Det tekniska gränssnittet beskrivs i [1]. BankIDs webbservice kan endast nås av FP som har ett giltigt SSL klientcertifikat (ett ”FP-certifikat”). FP-certifikat erhålls från den bank som FP har tecknat avtal om BankID med. Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part Version 1.0.2 Sida 6(28) Datum:2011-10-26 Om BankID säkerhetsapp är installerad på samma mobiltelefon som den användaren använder för att nå tjänsten (till exempel genom att surfa med webbläsare i telefonen eller en app i telefonen), så kan BankID säkerhetsapp i de flesta fall startas automatiskt. Om användaren når tjänsten på annat sätt (till exempel genom att surfa till den med en webbläsare i en dator) så måste användaren själv starta BankID säkerhetsapp. Notera att användande av Mobilt BankID inte ger något skydd av data och information som presenteras i tjänsten. Det är helt och hållet förlitande parts ansvar att skydda denna, exempelvis genom användande av SSL och stabil sessionshantering 4.1 Exempelanvändning Legitimering Underskrift Legitimeringen visas med FP:s namn (”BankID – Demo”). Användaren kan välja att avbryta eller att skriva in sin säkerhetskod och slutföra legitimeringen. Underskriften visas med FP:s namn (”BankID – Demo”) och texten som ska undertecknas. Användaren kan välja att avbryta eller att skriva in sin säkerhetskod och slutföra underskriften. Tangentbordet visas när användaren trycker på inmatningsfältet för Säkerhetskod. FP:s namn visas så som det är angett i FP-certifikatet. Innan ett BankID kan användas måste användaren hämta ett BankID från sin internetbank. Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part Version 1.0.2 Via en meny i BankID säkerhetsapp når man funktioner för att: 1. Hämta ett BankID från användarens internetbank 2. Byta säkerhetskod 3. Byta språk 4. Få information om namn och giltighetstid m.m. Sida 7(28) Datum:2011-10-26 Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part 5 Version 1.0.2 Sida 8(28) Datum:2011-10-26 Webbtjänst FP har en tjänst som vill använda BankID säkerhetsapp legitimering/underskrift. FPtjänsten används inte på samma enhet som BankID säkerhetsapp. Ett typiskt exempel är en tjänst i webbläsare i en dator men det kan också vara en app eller webbläsare i en annan mobil enhet, t.ex. läsplatta. I det här fallet måste FP-tjänsten be användaren att själv starta BankID säkerhetsapp när FP-tjänsten vill legitimera/skriva under. FPtjänsten behöver inte återstartas eftersom den hela tiden är igång på en annan enhet. 5.1 Flöde 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. Användaren fyller i sitt personnummer i FP-tjänsten (om det inte är sparat sedan tidigare) och vid underskrift även de uppgifter som ska användas för signaturen. FP-tjänsten visar rörlig väntesymbol. FP skickar legitimerings-/underskriftsbegäran till BankID med hjälp av [1]. FP-tjänsten ber användaren att starta BankID säkerhetsapp med meddelandet MEDDELANDE_STARTA_BANKID_APP. FP frågar BankID med hjälp av [1] efter svar (görs periodiskt till slutligt svar erhålls). FP erhåller tillfälligt svar och uppdaterar kontinuerligt informationen till användaren enligt Gemensam fortsättning för legitimering/underskrift. BankID skickar legitimerings-/underskriftsbegäran till BankID säkerhetsapp. BankID säkerhetsapp visar namnet på FP (så som det är angett i FPcertifikatet) och information om att legitimering/underskrift efterfrågas, användaren matar in säkerhetskod eller väljer att avbryta. FP erhåller slutligt svar. FP-tjänsten slutar visa rörlig väntesymbol. I detta användningsfall finns inget automatiskt sätt att kontrollera om BankID säkerhetsapp är installerad eller inte. Andra tekniska fel som kan uppstå beskrivs i avsnittet RP Interface. 5.2 Alternativflöden 1. Legitimerings/underskriftsbegäran i 3 misslyckas. Flödet avbryts och FP ska inte be användaren starta BankID säkerhetsapp. Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part 6 Version 1.0.2 Sida 9(28) Datum:2011-10-26 Mobil webbtjänst FP har en webbapplikation (FP-mobilwebb) som kan användas i webbläsaren på en enhet med Android eller iOS och vill använda BankID säkerhetsapp legitimering/underskrift i samma enhet som webbläsaren. Med hjälp av mobilplattformen/operativsystemet kan FP-mobilwebb starta BankID säkerhetsapp på enheten och via sin serverkomponent starta legitimering/underskrift med hjälp av [1] (detaljerad beskrivning i avsnittet RP Interface). Start av BankID säkerhetsapp från FP-mobilwebb skiljer sig inte mellan Android, iOS och JavaME. BankID säkerhetsapp startas genom att i webbapplikation öppna följande länk bankid://redirect=[RETURNURL] Länken fungerar i iOS och Android när den inbygga webbläsaren används och i JavaME om JSR-211 stöds. Länken fungerar inte i enheter från Nokia p.g.a. begränsningar i Nokias JSR-211-implementation. BankID säkerhetsapp använder URL-parametern redirect för att starta FP-mobilwebb efter utförd legitimering/underskrift. Redirect måste vara URL UTF-8-kodad och innehålla korrekt URL och eventuella request-parametrar för att användaren ska kunna återta sin session hos FP utan att förlita sig på att samma webbläsarsession och/eller att HTTP cookies används. OBS: basera inte designen på antagandet att samma webbläsarfönster kommer att användas när FP-mobilwebb återstartas. Exempel på redirect före URL UTF8-kodning: https://www.bank_x.com/path?p1=v1&p2=v2 Samma redirect URL UTF-8-kodad: https%3A%2F%2Fwww.bank_x.com%2Fpath%3Fp1%3Dv1%26p2%3Dv2 Exempel på fullständig länk: bankid://redirect= https%3A%2F%2Fwww.bank_x.com%2Fpath%3Fp1%3Dv1%26p2%3Dv2 OBS: URL:en får inte innehålla ett värdnamn (host), endast schemat (bankid) och parametern (redirect). HTTPS ska användas i redirect. 6.1 Flöde Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part 1. 2. 3. 4. 5. 6. 7. 8. 9. Version 1.0.2 Sida 10(28) Datum:2011-10-26 Användaren fyller i sitt personnummer i FP-mobilwebb (om det inte är sparat sedan tidigare) och vid underskrift även de uppgifter som ska användas för signaturen. FP förvissar sig om att användaren använder en mobil webbläsare. Om inte fortsätter flödet i Webbtjänst punkt 2. FP ber användaren bekräfta1 om BankID säkerhetsapp finns installerad i samma enhet som webbläsaren. Om inte fortsätter flödet i Webbtjänst punkt 2. Följande formuleringar bör användas a. ” Jag vill logga in med BankID säkerhetsapp i den här mobiltelefonen” b. ” Jag vill logga in med BankID säkerhetsapp i en annan mobiltelefon”. FP skickar legitimerings-/underskriftsbegäran till BankID med hjälp av [1] när användaren väljer legitimering eller underskrift. FP-mobilwebb startar BankID säkerhetsapp. BankID skickar legitimerings-/underskriftsbegäran till BankID säkerhetsapp. BankID säkerhetsapp visar namnet på FP (så som det är angett i FPcertifikatet) och information om att legitimering/underskrift efterfrågas, användaren fyller i sin säkerhetskod eller väljer att avbryta. BankID säkerhetsapp använder URL-parametern redirect och startar webbläsaren. FP frågar BankID med hjälp av [1] efter svar. 6.2 Alternativflöden 1. 2. 3. 4. 5. FP upptäcker i 2 att användaren inte använder en mobil webbläsare. Flödet fortsätter i Webbtjänst punkt 2. Användaren svarar i 3 att han eller hon vill använda BankID säkehetsapp i en annan mobiltelefon eller surfplatta. Flödet fortsätter i Webbtjänst punkt 2. Legitimerings/underskriftsbegäran i 4 misslyckas. Flödet avbryts och FP ska inte starta BankID säkerhetsapp. BankID säkerhetsapp är inte installerad i enheten. Webbläsaren i Android och iOS informerar i 5 användaren om att den inte kan öppna länken (se exempel nedan). I JavaME får användaren ingen information i webbläsaren, inget händer när användaren trycker på länken. FP-mobilwebb kommer inte att få återkoppling från webbläsaren/operativsystemet utan måste fånga detta fel genom timeout i RP interface eller genom instruktioner till användaren och fortsätta flödet i Webbtjänst punkt 2. FP-mobilwebb kan i 5 inte starta BankID säkerhetsapp. Flödet fortsätter i Webbtjänst punkt 2. Andra tekniska fel som kan uppstå beskrivs i avsnittet RP Interface. 1 Bekräftelse från användaren krävs därför att det är möjligt att användaren vill använda Mobilt BankID i en annan mobiltelefon eller surfplatta. Det är inte heller tekniskt möjligt att från FPmobilwebb känna av om BankID säkerhetsapp är installerad. Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part Version 1.0.2 Sida 11(28) Datum:2011-10-26 Exempel på felmeddelande i mobil webbläsare när BankID säkerhetsapp inte kan startas eller inte är installerad (I JavaME visas inget felmeddelande): Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part Version 1.0.2 Sida 12(28) Datum:2011-10-26 iOS Android En ”pop-up” öppnas och användaren är kvar i FP-mobilwebb efter OK En ny sida öppnas och användaren måste välja ”tillbaka” för att komma tillbaka till FP-mobilwebb Ett sätt att bättre hantera telefoner som inte genererar någon användbar felinformation är att göra anropet till BankID appen i en egen iFrame i webbsidan. iFramen kan döljas helt. Efter att webservices anropet har gått bra och anropet att starta appen gjorts startas också en funktion som visar texten ”Om inte din BankID säkerhetsapp startas automatiskt så behöver du själv starta den i din mobil/surfplatta” efter 5 sekunder och döljs igen efter 30 sekunder. Om appen inte startas så kommer användaren att få se texten med information om att starta appen och om den startas så kommer användaren att inte att se den då BankID säkerhetsapp har fokus. Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part 7 Version 1.0.2 Sida 13(28) Datum:2011-10-26 App FP har en mobilapp (FP-app) för Android eller iOS (ej möjligt för JavaME) och vill använda BankID säkerhetsapp för legitimering/underskrift i samma enhet som FPapp är installerad i. FP-appen kan starta BankID säkerhetsapp på enheten och via sin serverkomponent starta legitimering/underskrift med hjälp av [1] (detaljerad beskrivning i avsnittet RP Interface). 7.1 Flöde 1. 2. 3. 4. 5. 6. 7. Användaren fyller i sitt personnummer i FP-appen (om det inte är sparat sedan tidigare) och vid underskrift de uppgifter som ska användas för signaturen. FP skickar legitimerings-/underskriftsbegäran till BankID med hjälp av [1]. FP-appen startar BankID säkerhetsapp programmatiskt (beskrivs i avsnittet Programmatisk start av BankID säkerhetsapp). BankID skickar legitimerings/underskrifts-begäran till BankID säkerhetsapp. BankID säkerhetsapp visar namnet på FP (så som det är angett i FPcertifikatet) och information om att legitimering/underskrift efterfrågas, användaren skriver sin säkerhetskod eller väljer att avbryta. BankID säkerhetsapp startar FP-appen. I iOS används URL-parametern redirect som skickades av FP-appen och BankID säkerhetsapp startar FPapp på samma sätt som FP-app tidigare startade BankID säkerhetsapp. I Android anropas onActivityResult() i FP-appen när BankID säkerhetsapp är klar med aktiviteten som FP-appen startade. Om FP-appen ej har stöd för bakgrundskörning måste FP implementera funktionalitet för att spara sitt tillstånd då BankID säkerhetsapp startas och sedan kunna återskapa sessionen eftersom FP-appen kan komma att avslutas då BankID säkerhetsapp startas. Det exakta beteendet beror på plattform och implementation av FP-app. FP frågar BankID med hjälp av [1] efter svar. 7.2 Alternativflöden 1. 2. 3. BankID säkerhetsapp är inte installerad i enheten. Anropet i 3 returnerar i så fall en felkod (NO i iOS och android.content.ActivityNotFoundException i Android) och flödet avbryts av FP-appen. Följande meddelande ska då visas för användaren MEDDELANDE_DEVICESW_SAKNAS. Användaren avslutar sin BankID säkerhetsapp innan BankID säkerhetsapp har återstartat FP-app. Användaren måste då själv återstarta FP-app. Legitimerings/underskriftsbegäran i 2 misslyckas. Flödet avbryts och FP ska inte starta BankID säkerhetsapp. Andra tekniska fel som kan uppstår beskrivs i avsnittet RP Interface. Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part Version 1.0.2 Sida 14(28) Datum:2011-10-26 7.2.1 Programmatisk start av BankID säkerhetsapp 7.2.1.1 iOS openURL:[NSURL URLWithString: @”bankid:// redirect=fp_app_x://bank_x”] 7.2.1.2 Android Intent intent = new Intent(); intent.setPackage("com.bankid.bus"); intent.setAction(Intent.ACTION_VIEW); intent.addCategory(Intent.CATEGORY_BROWSABLE); //optional intent.addCategory(Intent.CATEGORY_DEFAULT); //optional intent.setType("bankid"); intent.setData(Uri.parse("bankid://www.bankid.com?redirect=null")) ; startActivityForResult(intent, 0); 8 URL-schema För att BankID säkerhetsapp ska kunna återstarta FP-app efter legitimering/underskrift måste FP: 1. registrera ett unikt URL-schema i FP-app, samt 2. hantera fallet då FP-app startas med URL-schema-förfarandet. Hur detta görs beskrivs för respektive plattform här. I exemplen används URLschemat fp_app_x. FP ska ändra fp_app_x till det URL-schema FP vill använda. 8.1 iOS 8.1.1 Registrera schema I Xcode: 1. Öpnna Info.plist. 2. Högerklicka, välj ”Add Row” och ”URL Types”. 3. Öppna ”Item 0” och ange ”URL Identifier”, praxis är omvänt domännamn t.ex. se.företag.appnamn. 4. Högerklicka på ”Item 0”, välj ”Add Row” och ”URL Schemes”. 5. Ge nyckeln URL Schemes / Item 1 värdet fp_app_x. Exempel: Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part Version 1.0.2 Sida 15(28) Datum:2011-10-26 8.1.2 Hantera anrop I UIApplicationDelegate: implementera funktionen BOOL(application):(UIApplication *)application handleOpenURL:(NSUrl *)url. 8.2 Android 8.2.1.1 Inkludera intent filter Inkludera följande intent-filter i filen AndroidManifest.xml: 8.2.1.2 <intent-filter 8.2.1.3 android:label=”FP-App Webstart” android:priority=”100”> <action android:name="android.intent.action.VIEW”/> <category android:name="android.intent.category.DEFAULT"/> <category android:name="android.intent.category.BROWSABLE"/> <data android:scheme="fp_app_x"/> </intent-filter> 8.2.2 Hantera anrop Inget speciellt behöver göras, onResume() kommer att anropas på samma sätt som när FP-App startas manuellt av användaren. 9 RP Interface 9.1 Flöde och riktlinjer Här beskrivs rekommenderad användning för de olika användningsfallen. Fullständig beskrivning av RP Interface finns i avsnittet BankID säkerhetsapp RP Interface Description. 9.1.1 Legitimering 1. 2. Anropa BankID med funktionen Authenticate. SOAP-ramverket indikerar om anropet gick bra, legitimeringen behandlas nu av BankID-systemet. 9.1.2 Underskrift 1. 2. Anropa BankID med funktionen Sign. SOAP-ramverket indikerar om anropet gick bra, underskriften behandlas nu av BankID-systemet. 9.1.3 Gemensam fortsättning för legitimering/underskrift 3. Anropa BankID med funktionen Collect för att få slutlig status på legitimering/underskrift. Anropet görs upprepade tills statuskoden COMPLETE returneras, i avsnittet Statuskoder beskrivs samtliga statuskoder i detalj. Om Collect returnerar en felkod avbryts legitimeringen/underskriften Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part 4. Sida 16(28) Datum:2011-10-26 Version 1.0.2 och FP ska inte fortsätta att anropa Collect, i avsnittet Felkoder beskrivs samtliga felkoder i detalj. Collect returnerar med statusvärdet COMPLETE och legitimeringen/underskriften är klar. Personuppgifter returneras i parametern userInfo och kan användas för vidare bearbetning av FP. I ett typiskt flöde returneras först OUTSTANDING_TRANSACTION (användaren har inte startat BankID säkerhetsapp), sedan USER_SIGN (legitimeringen eller underskriften visas i telefonen) och till sist COMPLETE om användaren skrev in säkerhetskoden eller felkoden USER_CANCEL om användaren valde att avbryta. 9.1.4 Statuskoder I tabellen nedan beskrivs samtliga statuskoder i detalj. Statuskod Var har hänt? OUTSTANDING_ TRANSACTION USER_SIGN BankID säkerhetsapp är inte startad. BankID säkerhetsapp har tagit emot ordern. COMPLETE Användaren har skrivit in sin säkerhetskod och slutfört legitimeringen eller underskriften. Meddelande som FP bör använda RFA1 Visas i BankID säkerhetsapp RFA9 Legitimeringen eller underskriften. Om BankID säkerhetsapp startades av FP avslutas nu BankID säkerhetsapp och FP återstartas. 9.1.5 Felkoder I tabellen nedan beskrivs samtliga felkoder i detalj. FP ska inte fortsätta att anropa Collect efter att ha mottagit en felkod. Felkod Var har hänt? INVALID_PARA METERS Felaktigt anrop. FP ska inte försöka igen med samma anrop. Det här är ett internt fel hos FP och ska inte kommuniceras till användaren som ett BankID-fel. Meddelan de som FP bör använda Visas i BankID säkerhetsap p Inget Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part Felkod Var har hänt? ACCESS_DENIE D_RP FP är inte behörig. FP ska inte försöka igen. Det här är ett internt tekniskt fel hos FP och ska inte kommuniceras till användaren som ett BankID-fel. Internt tekniskt fel. FP bör inte försöka automatiskt igen. Ska inte kommuniceras till användaren som ett BankID-fel. Tillfälligt tekniskt fel i systemet. Internt tekniskt fel i systemet. FP bör inte försöka automatiskt igen. 1) Användaren finns inte i systemet eller användaren har inget giltigt BankID. FP ska inte försöka igen utan att först ha försäkrat sig om att användaren har hämtat ett BankID. SIGN_VALIDATI ON_FAILED RETRY INTERNAL_ERR OR UNKNOWN_USE R Sida 17(28) Datum:2011-10-26 Version 1.0.2 2) Användaren har skrivit in fel säkerhetskod upprepade gånger och har fått sin säkerhetskod permanent låst. När det inträffar kan användaren inte använda sitt BankID. 3) Användarens BankID är spärrat. 4) Användarens BankID är ogiltigt. ALREADY_COLL FP har fortsatt att anropa Collect ECTED efter att COMPLETE har returnerats. Internt tekniskt fel hos FP som inte ska försöka igen. Ska Meddelan de som FP bör använda Visas i BankID säkerhetsap p Inget RFA5 Inget RFA5 RFA5 Inget Inget RFA4 1) Inget 2) ”Din säkerhetsko d är låst, du måste hämta ett nytt BankID hos din internetbank ” 3) ”Ditt BankID är spärrat, du måste hämta ett nytt hos din internetbank ” 4) Giltighetstid en på ditt BankID har gått ut, du måste hämta ett nytt hos din internetbank ” Inget Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part Felkod EXPIRED_TRAN SACTION INVALID_DEVIC ESW ALREADY_IN_P ROGRESS USER_CANCEL TIME_BLOCKED Sida 18(28) Datum:2011-10-26 Version 1.0.2 Var har hänt? inte kommuniceras till användaren som ett BankID-fel. Legitimeringen har passerat bästföre-datum. Det kan bero på att användaren inte startade BankID säkerhetsapp eller att användaren besvarade legitimeringen/underskriften men FP väntade för länge mellan Collect-anropen. Fel på BankID säkerhetsapp, äkthetsverifieringen misslyckades. Meddelan de som FP bör använda Visas i BankID säkerhetsap p RFA8 ”Legitimeri ngen avbruten p.g.a. inaktivitet” RFA12 ”Ickegodkänd användare” Inget Användaren har redan en pågående RFA3 legitimering eller underskrift. FP ska inte automatiskt försöka igen. Användaren har valt att avbryta RFA6 legitimeringen eller underskriften i BankID säkerhetsapp. Användarens säkerhetskod är tillfälligt låst p.g.a. användaren har skrivit in fel säkerhetskod upprepade gånger. RFA11 Om BankID säkerhetsap p startades av FP avslutas nu BankID säkerhetsap p och FP återstartas. ”Din säkerhetsko d är tillfälligt låst” OBS: I produktion är systemet konfigurerat så att TIME_BLOCKED inte kan inträffa, istället kommer säkerhetskoden bli permanent låst efter 5 på varandra felaktig försök. Vid permanent låst säkerhetskod kommer felkoden UNKNOWN_USER att returneras. 9.2 Krav på teknisk lösning Riktlinjer RFT1 När BankID säkerhetsapp anropas med hjälp av en URL skall query-delen Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part Version 1.0.2 Sida 19(28) Datum:2011-10-26 av URL:en vara kodad med URL UTF-8-formatet. RFT2 BankID säkerhetsapp anropas med hjälp av en URL skall requestparametern redirect inte vara längre än 2048 tecken. RFT3 När BankID säkerhetsapp anropas med hjälp av en URL bör redirect innehålla schemat https (dvs använda SSL). RFT4 Personnummer i RP-interface ska anges med 12 siffror (ååååmmddxxxx) RFT5 Text-to-be-signed i RP-interface kan formateras genom att inkludera tecknet \n som kommer att visas som radbrytning RFT6 När Collect returnerar COMPLETE ska parametrarna signature, verificationStatus, userInfo och ocspResonse läsas ut och arkiveras av FP. FP behöver inte verifiera signaturen då detta görs av BankID. RFT7 FP kontaktar BankID RP Interface på följande adress: https://appapi.bankid.com/RpServiceEjb/RpService/RpService RFT8 FP ska autentisera sig med klient-SSL mot BankID och skall för detta använda sitt FP-certifikat. RFT9 Collect bör anropas en gång varannan sekund och ska inte anropas oftare än en gång per sekund. RFT10 FP bör i sin webbtjänst visa en rörlig väntesymbol i väntan på slutligt svar från Collect. 9.3 Riktlinjer för meddelanden RFA1 MEDDELANDE_STARTA_BANKID_APP: Starta din BankID säkerhetsapp. RFA2 MEDDELANDE_DEVICESW_SAKNAS: Du har inte BankID säkerhetsapp installerad. Kontakta din bank för att installera BankID säkerhetsapp och för att hämta BankID. RFA3 MEDDELANDE_PÅGÅENDE_OPERATION: En inloggning för det här personnumret är redan påbörjad, tryck avbryt i BankID säkerhetsapp och försök igen. RFA4 MEDDELANDE_USER_DENIED: Det BankID du valde går inte att använda. Välj att använda ett annat BankID eller kontakta din bank för att beställa ett nytt. RFA5 MEDDELANDE_PERMANENT_FEL: Det har inträffat ett internt tekniskt fel i systemet. Försök igen. RFA6 MEDDELANDE_USER_CANCEL: Åtgärden avbruten. RFA7 Avsiktligt tom, används ej längre. RFA8 MEDDELANDE_USER_TIMEOUT: Inget svar från mobiltelefonen eller surfplattan. Kontrollera att du har startat din BankID säkerhetsapp och att du har täckning. Följ instruktionerna i mobiltelefonen och försök igen. RFA9 MEDDELANDE_GODKÄNN_ELLER_AVBRYT: Skriv in säkerhetskoden till ditt BankID i din mobiltelefon eller surfplatta och välj Legitimera / Skriv under eller välj att avbryta. RFA10 Avsiktligt tom, används ej längre. Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part Version 1.0.2 Sida 20(28) Datum:2011-10-26 RFA11 MEDDELANDE_TIME_BLOCKED: Du har skrivit in fel säkerhetskod upprepade gånger och din säkerhetskod är tillfälligt låst. Försök igen senare. RFA12 MEDDELANDE_INVALID_DEVICE_SW: Det har inträffat ett internt tekniskt fel . Uppdatera din BankID säkerhetsapp och försök igen. Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part Version 1.0.2 Sida 21(28) Datum:2011-10-26 10 Anslutningsinformation Beskrivning SSL-certifikat (FPcertifikat) URL till webbservices Specifikation av webbservice Servercert Plats/Information/Värde Erhålls från den bank som ni tecknat avtal om BankID med. https://appapi.bankid.com/RpServiceEjb/RpService/RpService https://appapi.bankid.com/RpServiceEjb/RpService/RpService?wsdl Servercertifikatet är utgivet av följande CA: CN = BankID SSL Root Certification Authority OU = Infrastructure CA O = Finansiell ID-Teknik BID AB Cert: -----BEGIN CERTIFICATE----MIID6jCCAtKgAwIBAgIQSvZNAy61UF6qO2zWqvN/3zANBgkqhkiG9w0BAQUFADB0 MSQwIgYDVQQKDBtGaW5hbnNpZWxsIElELVRla25payBCSUQgQUIxGjAYBgNVBAsM EUluZnJhc3RydWN0dXJlIENBMTAwLgYDVQQDDCdCYW5rSUQgU1NMIFJvb3QgQ2Vy dGlmaWNhdGlvbiBBdXRob3JpdHkwHhcNMDgxMjE5MDg1OTAxWhcNMTkwNjAxMjE0 NTAwWjB0MSQwIgYDVQQKDBtGaW5hbnNpZWxsIElELVRla25payBCSUQgQUIxGjAY BgNVBAsMEUluZnJhc3RydWN0dXJlIENBMTAwLgYDVQQDDCdCYW5rSUQgU1NMIFJv b3QgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkwggEiMA0GCSqGSIb3DQEBAQUAA4IB DwAwggEKAoIBAQCzqv7Rn43VFyTGicb+qjSGNeJga6GWQkMEXn9NvqCfknpaz4kf RbNHoQvtmw7CsiL83hMNU5y0EI6wC45Whn8ZXJ5/eqj1zBSu7QqKctEbMjWf6sf2 VUyE7lns6FxRFAgbhM2RS5LnWCfRsSgjKLXbJk7S2O/qVWdlxU1fAYfjbja1xhQm jArtvCYv9D2f8MBgH9sOsabVdLEKtiXj9NpBiXIi+c9DUpzvY1qnY02dsSudVwm3 IwJlEljLfjcBQDtJlm/7TbKsnqvW8s+NT6JBputUZT8Mqsv63meEbhxcq6vNcNKZ SgeHZDmr9lY2hmmVK9TcgfWHHkymUAWTGRQzAgMBAAGjeDB2MA8GA1UdEwEB/wQF MAMBAf8wEwYDVR0gBAwwCjAIBgYqhXBOAQQwDgYDVR0PAQH/BAQDAgEGMB0GA1Ud DgQWBBS2GCMB5GeakO2/WOqKJJXGAop6tTAfBgNVHSMEGDAWgBS2GCMB5GeakO2/ WOqKJJXGAop6tTANBgkqhkiG9w0BAQUFAAOCAQEAe4vukBbEjzsYC8Mv1xLcUQVD gYTgnqvP8Lr8yABfNfhh+iIoFK7QvVD3Z+bIBnGEGutB5K78UTadKINittSKA4T4 3Uy/p/blqew8Sqhv0I5MVlW71++HiPth4xwHAoxfe4oyTQaJRgls1CCsCBnuT9IF 6nGUNziC46RqIlhiY7zDzROtBWjqJzq+QvO07s73m+GPk8kZVwQrtyFT2IuYMH23 od/sRe2W5GClo2d62SBrzywYJZAaBNY9yl6weMdqWRqJz0mYZHrvLCQ1xrq4nvpL bMDfs1wD3vctSXLBFfBU9qw+CYTBN4UJ7BHQw1r2KGeAjm5grkL7Z7lQzTWSqw== -----END CERTIFICATE----- Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part Version 1.0.2 Sida 22(28) Datum:2011-10-26 11 Testmiljö BankID tillhandahåller en testmiljö så att FP kan utveckla och testa mot ett system med riktiga gränssnitt. För att använda testmiljön behöver FP: 1. ett SSL-certifikat (FP-certifikat) för att identifiera sig för BankID:s webbservice. 2. URL till BankID:s webservice för inloggning och signering. 3. Konfigurera utgivare av servercertifikat som skyddar webbservicen som ”trusted” i sin applikationsserver från vilken anrop till BankID görs. 4. Testversion av BankID Säkerhetsapp installerat i en telefon. 5. Ett testbankid utgivet till aktuell telefon. Beskrivning SSL-certifikat (FPcertifikat) för test Pinkod för ovanstående certifikat URL till webbservices Specifikation av webbservice Utgivare av servercert Plats/Information/Värde http://bankid.com/RP/Info qwerty123 https://appapi.test.bankid.com/RpServiceEjb/RpService/RpService https://appapi.test.bankid.com/RpServiceEjb/RpService/RpService? wsdl CN = BankID SSL Root Certification Authority TEST OU = Infrastructure CA O = Finansiell ID-Teknik BID AB Certifikat: -----BEGIN CERTIFICATE----MIID8zCCAtugAwIBAgIRAODr4WfulmxifqSx8UEMbyIwDQYJKoZIhvcNAQEFBQAw eTEkMCIGA1UECgwbRmluYW5zaWVsbCBJRC1UZWtuaWsgQklEIEFCMRowGAYDVQQL DBFJbmZyYXN0cnVjdHVyZSBDQTE1MDMGA1UEAwwsQmFua0lEIFNTTCBSb290IENl cnRpZmljYXRpb24gQXV0aG9yaXR5IFRFU1QwHhcNMDgxMjA0MTMyNTU1WhcNMTkw NjAxMTIxODAwWjB5MSQwIgYDVQQKDBtGaW5hbnNpZWxsIElELVRla25payBCSUQg QUIxGjAYBgNVBAsMEUluZnJhc3RydWN0dXJlIENBMTUwMwYDVQQDDCxCYW5rSUQg U1NMIFJvb3QgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkgVEVTVDCCASIwDQYJKoZI hvcNAQEBBQADggEPADCCAQoCggEBAOZh4Y7AkqrGb4LL/HCnqx0AmCdaHXKmJqbt NyIE3ppEnWYR6hGrZcSKRAYkU8ShS0Sf647Bj4tXiVQYg1msIvYgZ8h4QJqkqMYY 2nwJC2cDbtc3TL6ppXQVmIiS6wZewV1GL2xKUEPbKgDPiSgFyh3W1d/QihUwnwoa CGQ/crivftaNTnp4ZqQod9k35WfBy8xdB7cLHFeznfHoP1ZLOHza9bprT0F8YzEa u5CoCMxWPe0sY9aQC8oO3gKyohJrxnxTlDY2cMLXTCiUWIYh+ubybZ3Hqw1YFEmE 4IyiGyT9+LUChFhM0p53eR3GRUU7laxFVbVLuVdbIV0ZRL+0Eb8CAwEAAaN2MHQw DwYDVR0TAQH/BAUwAwEB/zARBgNVHSAECjAIMAYGBCoDBAUwDgYDVR0PAQH/BAQD AgEGMB0GA1UdDgQWBBSlaUGnPvmNu9R9LsDgulauQCwrvTAfBgNVHSMEGDAWgBSl aUGnPvmNu9R9LsDgulauQCwrvTANBgkqhkiG9w0BAQUFAAOCAQEAY1zWz1oV3ZMC 78uhGYA+j6Zktps9IXzIw3v1T3wtYclUoJI594w7vmTMqFY9z2mnms+gKTxCO/70 MpCNMgKSLj2bGsrMWHCvnDWpmYY5ZkDP2GWB6aqy+ehRmlYjUbPhjD44Xfjh/Stq 1yXCUfesLUHZDcBxpDspOwldWl7rhkE7QPj5hdSP85l04oIcnYiMyOPTt+4LNYN+ ncb0a/ZkJcUL7Q9NGJfmEhAmHcCpK8j1coSh36D8JMeSblVTBEWpnBMP5zXKAkzf OzZLGyy9RnV51NhRMRnQtDOFCZ9vQuuyCE/TZeOp4IgZctEvt2Aab23fx5jWBbzC EtEmq/VqaQ== -----END CERTIFICATE----- Testversion BankID säkerhetsapp för Android Installationsinstruktion Testversion BankID http://bankid.com/RP/Info http://bankid.com/RP/Info Installera BankID säkerhetsapp från App Store. Gå in i Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part Säkerhetsapp för iOS Version 1.0.2 Sida 23(28) Datum:2011-10-26 Inställningar BankID Utvecklare Server. Skriv in 194.242.109.185. Denna inställning innebär att BankID säkerhetsapp kommer att kommunicera med ett testsystem istället för produktionssystemet. Notera: För att återställa denna inställning måste appen avinstalleras och installeras igen. Surfa till m.test.bankid.com med din telefon. Testversion BankID Säkerhetsapp för JavaME Mobilt BankID för test Gör steg 1-4 först och bekräfta att du kan göra de tekniska anropen till BankID-Servern. Rutin för att erhålla Mobilt BankID för test: Tills vidare görs detta med en manuell rutin. Skicka ett mail till mobiltbankid@bankid.com och beskriv var du arbetar, syftet med din utveckling och telefonnummer. Rutinen går i korthet sedan till så att vi kontaktar er och manuellt initierar utgivning av ett testbankid, ni matar in uppgifter i BankID Säkerhetsapp och vi verifierar att det nyligen utgivna BankID:t fungerar. Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part Version 1.0.2 Sida 24(28) Datum:2011-10-26 12 Support För tekniska frågor ska ni i första hand vända er till mailto:mobiltbankid@bankid.com. I övriga frågor hänvisas till den bank som ni har avtal med om användandet av BankID. Riktlinjer RFS1 Förlitande part bör informera användare vad användaren skall göra när han/hon glömt sin säkerhetskod (d.v.s. kontakta utfärdare). RFS2 Förlitande part ska ge användare support för sin egen tjänst. RFS3 Vid användarproblem ska förlitande part uppmana användaren att testa BankID säkerhetsapp på BankIDs testplats (test.bankid.com) för felsökning. 1. Om test inte kan genomföras med godkänt resultat på BankIDs testplats ska förlitande part a. hänvisa användaren till utfärdarens support om användaren har problem med BankID. b. hänvisa användare till mobiloperatör om användare har telekommunikationsorienterat problem. 2. Om användare inte har problem att legitimera sig och underteckna på BankIDs testplats ska användare hänvisas till support hos förlitande part. RFS4 Förlitande part bör ha en egen FAQ. Underlag finns i referens [5]. Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part Version 1.0.2 Sida 25(28) Datum:2011-10-26 13 BankID säkerhetsapp RP Interface Description 13.1 Introduction This document describes the RP web service interface for the BUS Server. This interface will be used by an RP to request authentication and signature from a mobile device client. The resulting signature is validated before it is returned to the RP. The web service contains the methods described below and is defined by the WSDL [1]. SSL/TLS is used to secure the transport towards the web service. Client authentication is required with SSL/TLS client certificates. The client certificate is issued by BankID RP CA (“FP-certifikat”). 13.2 References Reference [1] Document title RpService.wsdl Version 0.1 [2] Signature Profile for BankID 1.4.5 13.3 Authenticate 13.3.1 Input The input parameters to Authenticate are the following: Parameter personalNumber Description The Personal Number (i.e “personnummer”) of the End User to enroll Format is 12 digits Required Yes 13.3.2 Output Output parameters from Authenticate are the following: Parameter orderRef Description An identifier to be used later in the Collect method to collect the Authenticate response and to query status. The operation succeeds as long as there are at least one valid BankID else the fault UNKNOWN_USER is thrown. 13.3.3 Fault If the operation fails a fault will be returned. This fault will contain a code (an XML enumeration) and a detailed description, see Fault chapter. 13.4 Sign 13.4.1 Input The input to this method is wrapped in an element called SignRequest, which contains the following sub-elements: Parameter personalNumber Description The Personal Number (i.e “personnummer”) of the end user to enroll Format is 12 digits Required Yes userVisibleData The text to be displayed and signed. Must be UTF-8 encoded. The value should be Base64encoded. Max 100Kb (after Base64encoding). Yes userNonVisibleData Data that is not displayed to the user at time of No Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part Version 1.0.2 Sida 26(28) Datum:2011-10-26 signature computation. The value should be Base64-encoded. Max 5Mb (after Base64encoding). 13.4.2 Output Output parameters from Sign are the following: Parameter orderRef Description An identifier used later in the Collect method to collect the signature response and to query status. The operation succeeds as long as there are at least one valid BankID else the fault UNKNOWN_USER is thrown. 13.4.3 Fault If the operation fails a fault will be returned. This fault will contain a code (an XML enumeration) and a detailed description, see Fault chapter. 13.5 Collect This method is used to collect a signature after the method Authenticate or Sign has been called successfully. The method also shows the status of the Authenticate or Sign operation. 13.5.1 Input The input parameters to Collect are the following: Parameter orderRef Description The identifier returned by Authenticate or Sign 13.5.2 Output Output parameters from Collect are the following: Parameter progressStatus Description An enumeration describing at what stage the processing of the Authenticate or Sign order, see 13.5.3 below Required Yes signature A validated Signature (XML format according to [2]) (only present if status is COMPLETE) No userInfo Name of user, serial number (personnummer) and validity time of current used BankID. (only present if status is COMPLETE) No ocspResponse Status of the BankID certificate when the signature was validated. (only present if status is COMPLETE) No 13.5.3 Status The response message from the Collect method is called ProgressStatusType and can contain one of several different status codes. It has the following elements: Status COMPLETE Description The signature is complete and is included in the response. USER_SIGN The request has been delivered to the End User (mobile client). OUSTANDING_TRANSACTION The request has not yet been sent to the End User. Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part Version 1.0.2 Sida 27(28) Datum:2011-10-26 13.6 Fault All Services methods return Fault if an error occurs. It has the following sub-elements: Parameter faultStatus Description An fault status enumeration of type FaultStatusType described below, see 13.6.1 detailedDescription Additional information describing the error. 13.6.1 Fault status All faults are of the FaultStatusType enumeration type. It has the following elements: Status INVALID_PARAMETERS Description Input parameters are missing or invalid. ACCESS_DENIED_RP The security configuration of the RP does not allow the requested operation. This can be if the RP is not configured at all, that the RP is not enabled or that the RP does not have access to the order (i.e. the order belongs to another RP) SIGN_VALIDATION_FAILED The PKI validation of the signature for Authentication or Sign failed. RETRY Some kind of temporary problems. This is if the OCSP server has temporary problems that prevent the verification of the End User for signatures. Retry at a later time. INTERNAL_ERROR Internal error in RpService. This is some kind of unexpected error in the system, e.g. problems with network or database. Also of the OCSP server can’t be contacted. UNKNOWN_USER The End User is unknown or not valid. The reason for this can be that the End user is never enrolled or that the BankID is expired, revoked or blocked. This fault is also returned if the End User is not valid when verifying a signature. ALREADY_COLLECTED The signature has already been collected; it can only be collected once. EXPIRED_TRANSACTION The queried transaction has expired. The check for expired transaction is done first, before starting to handle the collect request. This fault will only be returned when the order becomes expired, repeated calls will return INVALID_PARAMETERS TIMEOUT Not used INVALID_DEVICESW The mobile client is invalid. ALREADY_IN_PROGRESS The End User already has a request to process. There can only be one request for an End User at a time. Cancel the order in the mobile client or retry later when the order has expired. USER_CANCEL The mobile client reported that the End User cancelled the Authenticate or Sign request. TIME_BLOCKED The End User has entered invalid security code too many times and is now blocked for a period of time. After that time the End User can use the mobile client again. After a number of TIME_BLOCKED situations the End User is permanently blocked and UNKNOWN_USER is returned. Finansiell ID teknik BID AB Riktlinjer för Mobilt BankID till förlitande part Version 1.0.2 14 Rekommenderade termer Beskrivning Rekommenderad term Säkerhetskod/lösenord/PIN-kod Säkerhetskod Underteckna/signera Underteckna Underskrift/Signatur Underskrift Identifiera/autentisera/legitimera sig Legitimera sig Identifiering/autentisering/legitimering Legitimering Sida 28(28) Datum:2011-10-26
© Copyright 2024