Riktlinjer för Mobilt BankID till förlitande part Version 1.0.2

Transcription

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
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
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
Version 1.0.2
Sida 4(28)
Datum:2011-10-26
Samtliga dokument finns tillgängliga via http://www.bankid.com/rp/info.
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.
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.
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
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.
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
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.
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.
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.
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):
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.
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.
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.
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.
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:
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
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
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
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
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.
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.
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-----
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
Installera BankID säkerhetsapp från App Store. Gå in i
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
[email protected] 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.
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:[email protected]. 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].
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
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.
No
ocspResponse
Status of the BankID certificate when the signature
was validated.
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.
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.
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

Riktlinjer för Mobilt BankID till förlitande part Version 1.0.2

Transcription

Similar documents

Mobilt BankID beskrivning

Mobilt BankID – en kort beskrivning

Beskrivning av installation av BankID säkerhetsprogram i

Anvisningar för BankID säkerhetsprogram

Beskrivning av installation av BankID säkerhetsprogram i

Kända avvikelser i BankID säkerhetsprogram 6

Felsökning E-legitimation