1. No category

Finansiell ID-Teknik BID AB
Riktlinjer för Mobilt BankID till förlitande part
Version 1.0.7
Sida 1(29)
Datum:2013-06-03
Riktlinjer för Mobilt BankID
till förlitande part
Version 1.0.7
2013-06-03
Finansiell ID teknik BID AB
Riktlinjer för Mobilt BankID till förlitande part
Version 1.0.7
Sida 2(29)
Datum:2013-06-03
Innehållsförteckning
1
Dokumenthistorik ............................................................................................................... 4
2
Inledning ............................................................................................................................. 5
2.1
Plattformsstöd .................................................................................................................. 5
3
Referenser ........................................................................................................................... 5
4
Översikt Mobilt BankID ..................................................................................................... 6
4.1
5
Exempelanvändning........................................................................................................ 7
Webbtjänst ........................................................................................................................... 8
5.1
Flöde ................................................................................................................................ 8
5.2
Alternativflöden ............................................................................................................... 8
6
Mobil webbtjänst ................................................................................................................. 9
6.1
Flöde .............................................................................................................................. 10
6.2
Alternativflöden ............................................................................................................. 10
7
App..................................................................................................................................... 12
7.1
Flöde .............................................................................................................................. 12
7.2
Alternativflöden ............................................................................................................. 12
7.3
Programmatisk start av BankID säkerhetsapp ............................................................ 13
7.4
Återstart av FP-app i iOS .............................................................................................. 13
7.1
Återstart av FP-app i Android....................................................................................... 14
7.2
Återstart av FP-app i Windows Phone 8 ...................................................................... 14
8
RP Interface ...................................................................................................................... 15
8.1
Flöde och riktlinjer........................................................................................................ 16
8.2
Krav på teknisk lösning ................................................................................................. 18
8.3
Riktlinjer för meddelanden ........................................................................................... 19
8.1
Speciella noteringar om Webbservicen ........................................................................ 20
9
Anslutningsinformation ................................................................................................... 21
10
Testmiljö......................................................................................................................... 22
11
Support ........................................................................................................................... 24
12
BankID säkerhetsapp RP Interface Description .......................................................... 25
12.1
Introduction ................................................................................................................ 25
12.2
Version ........................................................................................................................ 25
12.3
URL............................................................................................................................. 25
12.4
References .................................................................................................................. 25
12.5
Authenticate ............................................................................................................... 25
12.6
Sign ............................................................................................................................. 26
Finansiell ID teknik BID AB
Riktlinjer för Mobilt BankID till förlitande part
Version 1.0.7
Sida 3(29)
Datum:2013-06-03
12.7
Collect ......................................................................................................................... 27
12.8
EndUserInfo Type ...................................................................................................... 28
12.9
Fault ........................................................................................................................... 28
13
Rekommenderade termer .............................................................................................. 29
Finansiell ID teknik BID AB
Riktlinjer för Mobilt BankID till förlitande part
1
Version 1.0.7
Sida 4(29)
Datum:2013-06-03
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
1.0.3
2012-01-24
Uppdaterat RFA3 och RFA4
Uppdaterat instruktionerna i avsnittet Mobil webbtjänst.
1.0.4
2012-04-24
Ny version av det tekniska gränssnittet RP Interface, se avsnitt
RP Interface och BankID säkerhetsapp RP Interface
Description.
Uppdaterat avsnittet Underskrift med avseende på
formateringsmöjligheter.
Tagit bort instruktionerna till FP om att på Android registrera
ett eget Intent-filter, då detta inte behövs längre.
Inkluderat brandväggsinformation i avsnitten
Anslutningsinformation och Testmiljö.
1.0.5
2013-04-03
Uppdaterade testinstruktioner för iOS i avsnittet Testmiljö.
Uppdaterade brandväggsinstruktioner i avsnitten
Anslutningsinformation och Testmiljö.
Uppdaterat RFT6 och RFT7.
Maxgränsen för userVisibleData-parametern sänkt från 100k
till 40k.
Java ME avvecklat
1.0.6
2013-03-05
Noteringar om webbservicen (versioner, testmiljön och
soapAction).
1.0.7
2013-06-03
Stöd för Windows Phone 8.
Finansiell ID teknik BID AB
Riktlinjer för Mobilt BankID till förlitande part
2
Version 1.0.7
Sida 5(29)
Datum:2013-06-03
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 surfplattor baserade på Android och
iOS samt mobiltelefoner baserade på Windows Phone 8. Aktuell information om
vilken hårdvara som stöds finns på http://support.bankid.com/mobil.
3
Referenser
[1] BankID-app RP Interface Description, kapitel 12
[2] Rekommenderade termer, kapitel 13
Aktuell version av detta dokument finns tillgängligt 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.7
Sida 6(29)
Datum:2013-06-03
Ö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.
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.
Finansiell ID teknik BID AB
Riktlinjer för Mobilt BankID till förlitande part
Version 1.0.7
Sida 7(29)
Datum:2013-06-03
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.
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.
Finansiell ID teknik BID AB
Riktlinjer för Mobilt BankID till förlitande part
5
Version 1.0.7
Sida 8(29)
Datum:2013-06-03
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.7
Sida 9(29)
Datum:2013-06-03
Mobil webbtjänst
FP har en webbapplikation (FP-mobilwebb) som kan användas i webbläsaren på en
enhet med Android, iOS, eller Windows Phone 8 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).
BankID säkerhetsapp startas genom att i webbapplikation öppna följande länk:
bankid://redirect=[RETURNURL]
Länken fungerar i iOS,Android och Windows Phone 8 när den inbygga webbläsaren
används.
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
RETURNURL bör innehålla den URL som användaren befinner sig på i FP
mobilwebb. Användandet av exakt samma URL ökar sannolikheten att sidan öppnas i
samma webbläsarflik som användes innan BankID säkerhetsapp startades.
Om användaren har flera webbläsare installerade i sin Android-telefon måste
användaren ibland välja vilken webbläsare som skall användas då tillbakaväxling
sker från BankID säkerhetsapp till FP mobilwebb. På Android-enheter kan den
speciella URL:en bankid://redirect=null användas för undvika detta val.
Om redirect=null används kommer BankID säkerhetsapp istället avsluta sig
själv och FP mobilwebb kommer att visas utan att frågor ställs. Observera att
beteendet är unikt för Android, redirect=null resulterar på iOS i att ingen
tillbakaväxling till FP mobilwebb sker.
FP mobilwebb bör konstrueras så att flödet automatiskt återupptas efter
tillbakaväxlingen från BankID säkerhetsapp till FP mobilwebb. T.ex. genom att
automatiskt ladda om sidan.
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:
Finansiell ID teknik BID AB
Riktlinjer för Mobilt BankID till förlitande part
Version 1.0.7
Sida 10(29)
Datum:2013-06-03
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).
6.1 Flöde
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
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.
Om en felkod returneras avbryts flödet här och FP ska då inte starta
BankID säkerhetsapp.
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 (observera specialfallet redirect=null ovan).
FP frågar BankID med hjälp av [1] efter svar.
6.2 Alternativflöden
1.
2.
3.
4.
1
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).
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
5.
Version 1.0.7
Sida 11(29)
Datum:2013-06-03
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.
Exempel på felmeddelande i mobil webbläsare när BankID säkerhetsapp inte kan
startas eller inte är installerad:
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
I Windows Phone får användaren en fråga om att öppna Windows Phone Store om
BankID säkerhetsapp inte är installerad.
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.7
Sida 12(29)
Datum:2013-06-03
App
FP har en mobilapp (FP-app) för Android, iOS eller Windows Phone 8 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.
8.
9.
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].
Om en felkod returneras avbryts flödet här och FP ska då inte starta
BankID säkerhetsapp.
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.7
Sida 13(29)
Datum:2013-06-03
7.3 Programmatisk start av BankID säkerhetsapp
7.3.1
iOS
openURL:[NSURL URLWithString: @”bankid://
redirect=fp_app_x://bank_x”]
7.3.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);
7.3.1
Windows Phone 8
Om inte Mobilt BankID finns installerat när URL anropas kommer användaren att få
en fråga att ansluta till Windows Store för att hämta ner den.
// Create the URI string
var uriToLaunch = @"bankid://www.bankid.com/redirect=" +
Uri.EscapeDataString("fp-app-x://bank_x");
// Create the URI to launch from a string.
var uri = new Uri(uriToLaunch);
// Launch the URI.
bool success = await Windows.System.Launcher.LaunchUriAsync(uri);
7.4 Återstart av FP-app i iOS
För att BankID säkerhetsapp i iOS 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.
I exemplen används URL-schemat fp_app_x. FP ska ändra fp_app_x till det URLschema FP vill använda.
7.4.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”.
Finansiell ID teknik BID AB
Riktlinjer för Mobilt BankID till förlitande part
Version 1.0.7
Sida 14(29)
Datum:2013-06-03
5. Ge nyckeln URL Schemes / Item 1 värdet fp_app_x.
Exempel:
7.4.2 Hantera anrop
I UIApplicationDelegate: implementera funktionen
BOOL(application):(UIApplication *)application
handleOpenURL:(NSUrl *)url.
7.1 Återstart av FP-app i Android
I Android krävs ingen hantering motsvarande registrering av URL-schema i iOS.
Efter utförd eller avbruten legitimering/underskrift avslutas BankID säkerhetsapp och
FP App kommer åter att hamna i förgrunden och onResume() anropas i FP App.
7.2 Återstart av FP-app i Windows Phone 8
För att BankID säkerhetsapp i iOS ska kunna återstarta FP-app efter
legitimering/underskrift måste FP:
3. registrera ett unikt URL-schema i FP-app, samt
4. hantera fallet då FP-app startas med URL-schema-förfarandet.
I exemplen används URL-schemat fp_app_x. FP ska ändra fp_app_x till det URLschema FP vill använda.
7.2.1 Registrera schema
Öppna
App anifest.xml med en text-editor
Lägg till ett "Tokens lägger du till följande:
Hantera anrop / återstart
I VisualStudio:
Lägg till klassen AssociationUri apper enligt följande:
<Extensions>
<Protocol Name="fp-app-x"
NavUriFragment="encodedLaunchUri=%s"
TaskID="_default" />
</Extensions>
7.2.2 Hantera anrop
I VisualStudio:
Lägg till klassen AssociationUri apper enligt följande:
<Extensions>
Finansiell ID teknik BID AB
Riktlinjer för Mobilt BankID till förlitande part
Version 1.0.7
Sida 15(29)
Datum:2013-06-03
<Protocol Name="fp-app-x"
NavUriFragment="encodedLaunchUri=%s"
TaskID="_default" />
</Extensions>
/// <summary>
/// The association uri mapper.
/// </summary>
internal class AssociationUriMapper : UriMapperBase
{
/// <summary>
/// When overridden in a derived class, converts a
requested uniform
resource identifier (URI) to a new URI.
/// </summary>
/// <returns>
/// A URI to use for the request instead of the value in
the <paramref
name="uri"/> parameter.
/// </returns>
/// <param name="uri">The original URI value to be mapped
to a new
URI.</param>
public override Uri MapUri(Uri uri)
{
var tempUri =
System.Net.HttpUtility.UrlDecode(uri.ToString());
// URI association launch.
don't
if (tempUri.StartsWith("/Protocol"))
{
// Here we can redirect to the correct page, but for now
we
return new Uri("/MainPage.xaml", UriKind.Relative);
}
}
// Otherwise perform normal launch.
return uri;
}
1. I App.xaml.cs, lägg till AssociationUri apper som Uri apper genom att i
metoden Initiali e honeApplication lägga till följande rad:
// Assign the URI-mapper class to the application frame.
RootFrame.UriMapper = new AssociationUriMapper();
8
RP Interface
Finansiell ID teknik BID AB
Riktlinjer för Mobilt BankID till förlitande part
Sida 16(29)
Datum:2013-06-03
Version 1.0.7
8.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.
8.1.1 Legitimering
1.
2.
Anropa BankID med funktionen Authenticate.
SOAP-ramverket indikerar om anropet gick bra, legitimeringen behandlas nu
av BankID-systemet.
8.1.2 Underskrift
1.
2.
Anropa BankID med funktionen Sign. Texten i parametern userVisibleData
kommer att visas för användaren vid underskriftstillfället. För att formatera
texten kan CR, LF och CRLF användas och alla resulterar i en (1) radbrytning.
Inga andra formateringsmöjligheter finns.
SOAP-ramverket indikerar om anropet gick bra, underskriften behandlas nu av
BankID-systemet.
8.1.3 Gemensam fortsättning för legitimering/underskrift
3.
4.
5.
Anropa BankID med funktionen Collect för att få slutlig status på
legitimering/underskrift. Anropet görs upprepade gånger tills statuskoden
COMPLETE returneras, i avsnittet
Statuskoder beskrivs samtliga statuskoder i detalj. Om Collect returnerar en
felkod avbryts legitimeringen/underskriften 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.
8.1.4 Statuskoder
I tabellen nedan beskrivs samtliga statuskoder i detalj.
Statuskod
Var har hänt?
OUTSTANDIN
G_TRANSACT
ION
USER_SIGN
BankID säkerhetsapp är inte
startad.
Meddelande
som FP bör
använda
RFA1
BankID säkerhetsapp har tagit emot RFA9
ordern.
Visas i BankID
säkerhetsapp
Legitimeringen
eller underskriften.
Finansiell ID teknik BID AB
Riktlinjer för Mobilt BankID till förlitande part
COMPLETE
Sida 17(29)
Datum:2013-06-03
Version 1.0.7
Användaren har skrivit in sin
säkerhetskod och slutfört
legitimeringen eller underskriften.
Om BankID
säkerhetsapp
startades av FP
avslutas nu BankID
säkerhetsapp och
FP återstartas.
8.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?
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.
ACCESS_DENI FP är inte behörig. FP ska inte
ED_RP
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.
SIGN_VALIDA Internt tekniskt fel. FP bör inte
TION_FAILED försöka automatiskt igen. Ska inte
kommuniceras till användaren som
ett BankID-fel.
RETRY
Tillfälligt tekniskt fel i systemet.
INTERNAL_ER Internt tekniskt fel i systemet. FP
ROR
bör inte försöka automatiskt igen.
UNKNOWN_U 1) Användaren finns inte i systemet
SER
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.
Meddelande
som FP bör
använda
INVALID_PAR
AMETERS
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.
Visas i BankID
säkerhetsapp
Inget
Inget
RFA5
Inget
RFA5
RFA5
Inget
Inget
RFA4
1) Inget
2) ”Din
säkerhetskod ä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) Giltighetstiden
på ditt BankID har
gått ut, du måste
hämta ett nytt hos
din internetbank”
Finansiell ID teknik BID AB
Riktlinjer för Mobilt BankID till förlitande part
Felkod
Sida 18(29)
Datum:2013-06-03
Version 1.0.7
Var har hänt?
FP har fortsatt att anropa Collect
efter att COMPLETE har
returnerats. Internt tekniskt fel hos
FP som inte ska försöka igen. Ska
inte kommuniceras till användaren
som ett BankID-fel.
EXPIRED_TRA Legitimeringen har passerat bästNSACTION
fö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.
INVALID_DEV Fel på BankID säkerhetsapp,
ICESW
äkthetsverifieringen misslyckades.
ALREADY_IN Användaren har redan en pågående
_PROGRESS
legitimering eller underskrift. FP
ska inte automatiskt försöka igen.
USER_CANCE Användaren har valt att avbryta
L
legitimeringen eller underskriften i
BankID säkerhetsapp.
Meddelande
som FP bör
använda
ALREADY_CO
LLECTED
TIME_BLOCK
ED
CANCELLED
Användarens säkerhetskod är
tillfälligt låst p.g.a. användaren har
skrivit in fel säkerhetskod
upprepade gånger.
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.
En ny begäran om legitimering
eller underskrift har inkommit för
samma användare.
8.2 Krav på teknisk lösning
Riktlinjer
Visas i BankID
säkerhetsapp
Inget
RFA8
”Legitimeringen
avbruten p.g.a.
inaktivitet”
RFA12
”Icke-godkänd
användare”
Inget
RFA3
RFA6
RFA11
RFA6
Om BankID
säkerhetsapp
startades av FP
avslutas nu BankID
säkerhetsapp och
FP återstartas.
”Din säkerhetskod
är tillfälligt låst”
”Åtgärden
avbruten”
Finansiell ID teknik BID AB
Riktlinjer för Mobilt BankID till förlitande part
Version 1.0.7
Sida 19(29)
Datum:2013-06-03
RFT1
När BankID säkerhetsapp anropas med hjälp av en URL skall query-delen av
URL:en vara kodad med URL UTF-8-formatet.
RFT2 BankID säkerhetsapp anropas med hjälp av en URL skall request-parametern
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, 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/v2/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.
8.3 Riktlinjer för meddelanden
RFA1
RFA2
RFA3
RFA4
RFA5
RFA6
RFA7
RFA8
RFA9
MEDDELANDE_STARTA_BANKID_APP: Starta din BankID säkerhetsapp.
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.
MEDDELANDE_PÅGÅENDE_OPERATION: En inloggning eller underskrift för
det här personnumret är redan påbörjad, tryck avbryt i BankID säkerhetsapp och
försök igen.
MEDDELANDE_USER_DENIED: Det angivna personnumret saknar ett
fungerande Mobilt BankID. Ange ett annat personnummer eller kontakta din bank
för att beställa ett Mobilt BankID.
MEDDELANDE_PERMANENT_FEL: Det har inträffat ett internt tekniskt fel i
systemet. Försök igen.
MEDDELANDE_USER_CANCEL: Åtgärden avbruten.
Avsiktligt tom, används ej längre.
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.
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.7
Sida 20(29)
Datum:2013-06-03
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.
8.1 Speciella noteringar om Webbservicen
8.1.1 Versioner
Om webbservicen ändras på så sätt att nya parametrar kan användas eller returneras, att befintliga
parametrar försvinner, att nya svarskoder returneras, nya metoder tillkommer eller befintliga
försvinner kommer detta att betraktas som en ny version som publiceras på en ny url, till exempel
publiceras version 2 av tjänsten på https://appapi.bankid.com/RpServiceEjb/RpService/v2/RpService.
Förlitande part skall alltid använda den senaste versionen av webbservicen.
Vi förbehåller oss rätten att stänga av äldre versioner av tjänsten när vi vill men kommer först att, i den
mån det är möjligt och korrekta kontaktuppgifter finns tillgängliga, informera förlitande parter i god
tid innan så att de hinner ändra i sina tjänster.
8.1.2 Testmiljön
Nya versioner och releaser körs i testmiljön innan de produktionssätts. Därför kan innehåll och
funktionalitet i testmiljön tillfälligt skilja sig från innehållet i produktionsmiljön.
8.1.3 Ingen soapAction
Tjänsten använder url för att specificera vilken action som ska tas. soapAction i headern skall vara ””
eller utelämnas helt.
Finansiell ID teknik BID AB
Riktlinjer för Mobilt BankID till förlitande part
9
Version 1.0.7
Sida 21(29)
Datum:2013-06-03
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/v2/RpServi
ce
https://appapi.bankid.com/RpServiceEjb/RpService/v2/RpServi
ce?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-----
Brandväggsinformation
BankID säkerhetsapp för produktion kontaktar BankID-servern
på adressen 194.242.109.204 och portarna TCP / 4711, 4710,
443, 80.
Finansiell ID teknik BID AB
Riktlinjer för Mobilt BankID till förlitande part
Version 1.0.7
Sida 22(29)
Datum:2013-06-03
10 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/v2/RpS
ervice
https://appapi.test.bankid.com/RpServiceEjb/RpService/v2/RpS
ervice?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
http://bankid.com/RP/Info
http://bankid.com/RP/Info
Finansiell ID teknik BID AB
Riktlinjer för Mobilt BankID till förlitande part
Testversion BankID
Säkerhetsapp för iOS
Version 1.0.7
Sida 23(29)
Datum:2013-06-03
Installera BankID säkerhetsapp från App Store. Gå in i
Inställningar  BankID  Utvecklare  Server. Skriv in
businternal.test.bankid.com. 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.
Testversion BankID
Installera BankID säkerhetsapp från Windows Phone Store.
Säkerhetsapp för Windows Starta BankID säkerhetsapp, gå in i inställningar 
Phone 8
Utvecklare Server. Skriv in businternal.test.bankid.com.
Spara, stäng BankID säkerhetsapp och starta appen igen. 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
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.
Brandväggsinformation
BankID säkerhetsapp för test kontaktar BankID-servern på
adressen 194.242.109.185 och portarna TCP / 4711, 4710, 443,
80.
Finansiell ID teknik BID AB
Riktlinjer för Mobilt BankID till förlitande part
Version 1.0.7
Sida 24(29)
Datum:2013-06-03
11 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].
Finansiell ID teknik BID AB
Riktlinjer för Mobilt BankID till förlitande part
Version 1.0.7
Sida 25(29)
Datum:2013-06-03
12 BankID säkerhetsapp RP Interface Description
12.1 Introduction
This document describes the RP Web Service interface for the BUS Server. The interface is used by a
Relying Party, RP to request authentication and signature from a mobile device client. The resulting
XML signature is validated before it is returned to the RP.
The web service contains the methods described below and is defined by the WSDL 0 and XSD 0 for
the latest version 2. There is also an older version defined by the WSDL 0 and XSD 0 that will
eventually be deprecated.
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 (“köparcertifikat”).
12.2 Version
As the RP Web Service interface evolve over time new parameters and methods will be added. The
changes will be in a new version of the interface leaving the existing version unchanged for a while
but the old version will eventually be deprecated and removed. As new functionality is introduced to
the system then the behaviour of an existing version of the interface may change, e.g. existing faults
may also be used in new situations. New RPs should use version 2 and existing RPs should upgrade to
version 2.
This document is written for the latest version 2 of the interface and details of the older version are
found in an older version of this document.
The first version was released during 2011 with the formal version 1.0.0. This version will be
deprecated in the future and RPs should start using version 2.
Version 2 with formal version 2.0.0 adds some new types and parameters to existing methods. There is
also a new fault to handle the new RP cancel functionality.
12.3 URL
Each version of the interface has a unique URL.
Version 2: https://server:port/RpServiceEjb/RpService/v2/RpService
Version 1: https://server:port/RpServiceEjb/RpService/RpService
12.4 References
Reference
[1]
Document title
RpService.wsdl
Version
1.0.0
[2]
RpService.xsd
1.0.0
[3]
RpService_v2.wsdl
2.0.0
[4]
RpService_v2.xsd
2.0.0
[5]
Signature Profile for BankID
1.5
[6]
OCSP, RFC 2560, http://www.ietf.org/rfc/rfc2560.txt
12.5 Authenticate
Request an authentication order. This is an asynchronous operation and the output is used later in the
Collect method to query the status of the order and to get the final XML signature.
New from version 2 is that if an Authenticate or Sign order is already in progress for a
personalNumber when Authenticate is issued then the attempt fails as before but now the existing
order is also cancelled. No order is in progress for personalNumber after that.
12.5.1 Input
A new optional parameter endUserInfo was introduced in version 2. The input parameters are also
wrapped in the new element AuthenticateRequest, which includes the single parameter in version 1.
The input parameters to Authenticate are the following:
Parameter
personalNumber
Description
The Personal Number
(i.e “personnummer”) of the End User to enroll.
Required
Yes
Finansiell ID teknik BID AB
Riktlinjer för Mobilt BankID till förlitande part
Version 1.0.7
Sida 26(29)
Datum:2013-06-03
Format is 12 digits.
endUserInfo
Additional information about the end user that is known by the RP.
This is a list of elements of type EndUserInfoType,. The number of
items in the list is in the range 0 to 20. There can be no duplicates for
the type element in .EndUserInfoType.
This is a new parameter from version 2.
No
12.5.2 Output
Output parameter from Authenticate is the following:
Parameter
orderRef
Description
An identifier that uniquely identifies the order. 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.
12.5.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.
12.6 Sign
Request a signature order. This is an asynchronous operation and the output is used later in the Collect
method to query the status of the order and to get the final XML signature.
New from version 2 is that if an Authenticate or Sign order is already in progress for a
personalNumber when Sign is issued then the attempt fails as before but now the existing order is also
cancelled. No order is in progress for personalNumber after that.
12.6.1 Input
A new optional parameter endUserInfo was introduced in version 2. The input to Sign is wrapped in
the element 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 base 64-encoded. Max 40KB (after base 64-encoding).
Yes
userNonVisibleData
Data that is not displayed to the user at time of signature computation.
The value should be base 64-encoded. Max 5MB (after base 64encoding).
No
endUserInfo
Additional information about the end user that is known by the RP.
This is a list of elements of type EndUserInfoType. The number of
items in the list is in the range 0 to 20. There can be no duplicates for
the type element in .EndUserInfoType.
This is a new parameter from version 2.
No
12.6.2 Output
Output parameter from Sign is the following:
Parameter
orderRef
Description
An identifier that uniquely identifies the order. Used later in the Collect method to
collect the Sign 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.
Finansiell ID teknik BID AB
Riktlinjer för Mobilt BankID till förlitande part
Version 1.0.7
Sida 27(29)
Datum:2013-06-03
12.6.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.
12.7 Collect
This method is used to query the status of an Authenticate or a Sign order. The return value is only
progress status until the end user is finished and the order is complete. Once the order is complete the
return values are also the resulting XML signature, the OCSP response when validating the end user
BankID and some information about the end user. Some new elements for information about the end
user was introduced in version 2.
12.7.1 Input
The input parameter to Collect is the following:
Parameter
orderRef
Description
An identifier that uniquely identifies an order. Returned by
Authenticate or Sign method.
Required
Yes
12.7.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 12.7.5 below
Required
Yes
signature
A validated Signature encoded as base 64.
The XML format is according to 0.
This is only present if progressStatus is COMPLETE.
No
userInfo
An element of type UserInfoType with information about the end
user, see 12.7.4.
This is only present if progressStatus is COMPLETE.
No
ocspResponse
Status of the BankID certificate when the signature was validated,
OCSP response encoded as base 64, see 12.7.3.
This is only present if progressStatus is COMPLETE.
No
12.7.3 OCSP Response
The OCSP 0 response is signed by a certificate that has the same issuer as the certificate being verified
(i.e. the BankId).
The OSCP response has an extension for Nonce. The nonce is calculated as:

SHA-1 hash over the base 64 XML signature encoded as UTF-8. This is the value in the signature
element in Collect output.

12 random bytes is added after the hash
The nonce is 32 bytes (20 + 12).
12.7.4 UserInfo type
UserInfoType holds information about the end user that is returned to the RP. It has been updated for
version 2 with two new elements.
Parameter
name
Description
Name of the end user.
Required
Yes
personalNumber
Yes
notBefore
The Personal Number (i.e “personnummer”) of the end user.
Format is 12 digits.
Validity time for the BankId.
notAfter
Validity time for the BankId.
Yes
givenName
Given name of the end user.
This is a new element from version 2.
Yes
Yes
Finansiell ID teknik BID AB
Riktlinjer för Mobilt BankID till förlitande part
surname
Version 1.0.7
Surname of the end user.
This is a new element from version 2.
Sida 28(29)
Datum:2013-06-03
Yes
12.7.5 Status
The progressStatus element in the Collect response message is of the type ProgressStatusType that is
an enumeration with 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.
12.8 EndUserInfo Type
The type EndUserInfoType was introduced in version 2 and holds information about the end user that
is known by the RP. It is a parameter in the Authenticate and Sign method.
Parameter
type
Description
Required
The type of information about the end user. There are two allowed
Yes
types (string, 1 - 20 characters):
IP_ADDR_WEB - End user web IP address. This should be the remote
address and not a HTTP header value.
IP_ADDR_APP – End user App IP address. This should be the remote
address and not a HTTP header value.
More types may be added in the future. This will not affect the RP
Web Service interface version.
value
The value for the type, string 1 - 1024 characters.
Yes
12.9 Fault
All Services methods return RpFault if an error occurs. It has the following sub-elements:
Parameter
faultStatus
Description
A fault status enumeration of type FaultStatusType described below, see 12.9.1.
detailedDescription
Additional information describing the error.
12.9.1 Fault status
All faults are of the FaultStatusType enumeration type. One new fault was introduced in version 2.
One existing fault in version 1 is also used in a new situation. 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.
Could be caused by the mobile client not encrypting correctly.
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
Finansiell ID teknik BID AB
Riktlinjer för Mobilt BankID till förlitande part
Sida 29(29)
Datum:2013-06-03
Version 1.0.7
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. This is due to not following the protocol
correctly in the Genuine Software Verification.
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.
This fault also has a new behaviour for version 1. RPs using version 1 of
the interface will get this fault for the new RP cancel order handling. The
new fault CANCELLED is sent to RPs using version 2, see below.
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.
CANCELLED
The order has been cancelled.
If an Authenticate or Sign order is already present for a personalNumber
when a new one is ordered then the RP that first created the order receives
this fault and the order is cancelled.
The RP that sends the second order receives ALREADY_IN_PROGRESS
fault. There is no order active for personalNumber after that.
If the first RP is using version 1 of the interface then the existing fault
USER_CANCEL is used.
This is a new fault from version 2.
13 Rekommenderade termer
Beskrivning
Rekommenderad term på
svenska
Rekommenderad term på
engelska
Mobilt BankID
Mobilt BankID
Mobile BankID
BankID säkerhetsapp
BankID säkerhetsapp
BankID Security App
Säkerhetskod/lösenord/PIN-kod
Säkerhetskod
Security code
Underteckna/signera
Underteckna
Sign
Underskrift/Signatur
Underskrift
Signature
Identifiera/autentisera/legitimera
sig
Legitimera sig
Identify
Identifiering/autentisering/legitime
ring
Legitimering
Identification