Download Report

BankID
BankID Relying Party Guidelines
Version: 2.7
Page 1(27)
2014-11-13
BankID Relying Party Guidelines
Version: 2.7
2014-11-13
BankID
Page 2(27)
BankID Relying Party Guidelines
1
Version: 2.7
Introduction .................................................................................................................................. 4
1.1
Versions...............................................................................................................................................4
1.2
Terms and definition..........................................................................................................................5
1.3
How it Works......................................................................................................................................5
1.4
BankID on file and BankID on smart cards ....................................................................................5
1.5
Mobile BankID ...................................................................................................................................6
1.6
Client Platforms .................................................................................................................................6
2
Use Cases ...................................................................................................................................... 6
2.1
Basic Use cases....................................................................................................................................7
2.2
Flow of events .....................................................................................................................................7
2.3
Exceptions ...........................................................................................................................................7
3
Launching ..................................................................................................................................... 8
3.1
Launching the BankID app from a browser ...................................................................................8
3.2
How to Start........................................................................................................................................8
3.3
Behaviour in Different Browsers ......................................................................................................8
3.3.1
3.3.2
3.3.3
3.4
Chrome ....................................................................................................................................................... 8
Internet Explorer ......................................................................................................................................... 8
Parameters in the start URL ........................................................................................................................ 8
Launching the BankID app from Native App on Mobile Device.................................................10
3.4.1
3.4.2
3.4.3
Android ..................................................................................................................................................... 10
iOS ............................................................................................................................................................ 10
Windows Phone ........................................................................................................................................ 10
4
Technical Requirements ............................................................................................................. 11
5
Recommended User Messages ................................................................................................... 12
6
Production Environment ............................................................................................................ 14
7
Test Environment ....................................................................................................................... 14
8
Information regarding the Web Service API ............................................................................ 16
8.1
Versions.............................................................................................................................................16
8.2
Test Environment.............................................................................................................................17
8.3
No soapAction...................................................................................................................................17
9
Support ........................................................................................................................................ 17
10
Recommended Terminology ................................................................................................... 17
11
File Signing ............................................................................................................................. 18
12
Appendix: RP Interface Description ...................................................................................... 19
12.1
12.1.1
12.1.2
12.2
12.2.1
12.2.2
12.3
12.3.1
Method Auth .................................................................................................................................19
In parameters ............................................................................................................................................ 19
Return value.............................................................................................................................................. 19
Method Sign ..................................................................................................................................19
In Parameters ............................................................................................................................................ 19
Return value.............................................................................................................................................. 19
Method FileSign - Deprecated .....................................................................................................19
In Parameters ............................................................................................................................................ 20
BankID
Page 3(27)
BankID Relying Party Guidelines
12.3.2
Version: 2.7
Return value.............................................................................................................................................. 20
12.4
PersonalNumberType ..................................................................................................................20
12.5
EndUserInfoType .........................................................................................................................20
12.6
RequirementAlternativesType ....................................................................................................21
12.6.1
OrderResponseType ................................................................................................................................. 22
12.7
Error codes for Auth/Sign/FileSign ............................................................................................22
12.8
Method Collect..............................................................................................................................23
12.8.1
12.8.2
12.8.3
12.8.4
12.8.5
12.9
12.9.1
12.9.2
In Parameters ............................................................................................................................................ 23
Return Value ............................................................................................................................................. 23
ProgressStatusType .................................................................................................................................. 23
UserInfoType ............................................................................................................................................ 24
Error codes Collect ................................................................................................................................... 24
More information about requirement alternatives ...................................................................26
Syntax ....................................................................................................................................................... 26
Examples .................................................................................................................................................. 26
BankID
Page 4(27)
BankID Relying Party Guidelines
1
Version: 2.7
Introduction
This document contains guidelines for Relying Parties (RP, Förlitande Part in Swedish) when using BankID
in their own services.
Please check www.bankid.com/rp/info and verify that you have the latest version of this document.
1.1 Versions
Version
Date
Change
1.0
2013-09-11
First English version
1.0.1
2013-09-30
Removed the iframe tip in the Mobile Web App use case since it doesn’t work in
Chrome for Android version 25 and later.
1.0.2
2013-10-21
Added Android, iOS and Windows Phone sections in the Mobile Web App use case.
2.0
2013-11-29
Possible to use the interface to access BankID on file, BankID on smart cards as well
as Mobile BankID
New name of document
New version of RP-Interface
2.1
2013-12-20
Changes in the instructions for launching the iOS and Windows Phone BankID app.
Changes in the user message requirements.
Added information in the Test Environment chapter regarding how the BankID
Security Application should be configured for test.
2.2
2014-01-23
Details on how to configure the PC-client for test.
We recommend the autostarttoken to be used.
The redirect parameter must be used together with autostarttoken on PC:s.
Minor change in the recommended text RFA15.
2.3
2014-03-25
How to start: The parameters must be in lower case.
How to start: Error message if client started multiple times
User message RFA17: updated with link to install.bankid.com
Test environment: You need to remove the config file if the selector file is changed.
Web Service: Validity time for previous versions of the web service API.
Appendix RP Interface: max file size is 5 Mb
Added REQ_BLOCKED (Not used) and ALREADY_COLLECTED (Not Used) as
error codes for collect.
2.4
2014-05-13
Parameters in the start URL: Removed the note for redirect in iOS, it was not reliable.
The general recommendation is to use redirect=null when it is possible. A
clarification in the note for Windows and Mac OS X.
Technical Requirements: New requirement RFT11 describing which cert to be
configured as trusted.
User Message Requirements: Changed RFA14 and RFA15 to two different texts
depending on if the user access the service using a PC or a mobile device.
Test Environment: Updated how to configure the PC-client for test.
Error Codes Collect: RFA3 should be used for CANCELLED
2.5
2014-06-03
Method fileSign is deprecated.
Changed the examples of requirementAlternatives to include Nordea E-leg.
2.6
2014-09-17
Launching from browser: The start URL for mobile devices shall include three
backslash (bankid:///).
Launching from native app (Android): intent.addCategory and intent.setType not
needed to launch in Android. Three backslash in the URI.
Launching from native app (iOS): Three backslash in the URL.
Launching from native app (WP): Three backslash in the URI.
More information about requirement alternatives: Added one more example.
Commented the examples.
BankID
Page 5(27)
BankID Relying Party Guidelines
2.7
2014-11-05
Version: 2.7
Parameters in the start URL: It is possible to use a new parameter rpref.
Production Environment: The client also uses IP address 194.242.109.208 and
159.72.128.183.
Test Environment: The client also uses IP address 194.242.109.169 and
159.72.128.183.
Use Cases: RP:s should consider to offer manual start of BankID app if the automatic
start fails.
RequirementAlternativesType: typing error; “type” changed to “key”.
1.2 Terms and definition
Term
BankID Security Application
BankID app
Description
The client software that needs to be installed in the end users mobile
device or personal computer (PC). The same term is used for PCs and
mobile platforms. BankID app is the short form used in this document.
In Swedish the client software installed on PCs is called “BankID
säkerhetsprogram”.
In Swedish the client software installed on mobile platforms is called
“BankID säkerhetsapp”
RP
Relying Party that uses the BankID web service to provide login and
signing functionality to the end user.
1.3 How it Works
To be able to use BankID’s identification and signature features users must install BankID Security
Application (the BankID app) in a mobile device or PC. They also need to order a BankID from their
bank.An RP uses the identification or signature service of BankID via a web service API provided by BankID
(see Appendix: RP Interface Description). The web service API can only be accessed by an RP that has a
valid SSL client certificate (an RP certificate). The RP certificate is obtained from the bank that the RP has
purchased the BankID service from.
If the BankID app is installed in the same device as the RP service executes in, the BankID app can be
launched automatically by the RP service. In this case the users do not need to enter their ID number in the
RP service. If, on the other hand, the RP service is used in a web browser on a PC and the users want to use a
Mobile BankID the users will have to manually launch the BankID app in their mobile device. In this case the
users need to provide their ID number in the RP service.
1.4 BankID on file and BankID on smart cards
This section includes general information for RP’s that have used BankID on file and BankID on smart cards
via the old BankID browser plugin solution. Some of the simplifications and changes are:







Installation and version control of the BankID app does not need to be done by the RP. The version
control is performed within the BankID system. If the user has not installed the BankID app a
special status will be returned via the RP-interface.
BankID Control Server is no longer needed. The signature and all other controls are done within the
BankID system.
There is no need to have different code for different browsers to start the BankID app.
Instead of using the plugins or activeX controls in the BankID app to authenticate the user and let
the user sign, the RP uses web services provided by BankID.
The RP interface has support for all different types of BankID (BankID on file, BankID on smart
cards and Mobile BankID). If an RP only wants to support BankID on file or BankID on smart cards
or Mobile BankID they need to use the requirementalternatives parameter to specify this (the
certificatePolicies should be set to 1.2.752.78.1.1 and/or 1.2.752.78.1.2 and/or 1.2.752.78.1.5).
Support for Nordea e-legitimation is included in the system.
The filter parameter is replaced with requirementalternatives. See RequirementAlternativesType for
more information.
BankID
Page 6(27)
BankID Relying Party Guidelines
Version: 2.7
1.5 Mobile BankID
This section includes a description for RPs’ that have used previous versions of the RP interface (which
supported Mobile BankID only). Some of the changes are:

The new RP interface has support for all different types of BankID (BankID on file, BankID on
smart cards and Mobile BankID). If RP only wants to support Mobile BankID they need to use the
requirementalternatives parameter to specify this (the certificatePolicies should be set to
1.2.752.78.1.5).
The sign and authenticate methods returns an orderResponse which contains the orderReference.
Users do not need to enter their ID number to sign or login. For this to work the BankID app must be
started using the autoStartToken which is returned in the orderResponse.
The following status and error codes are changed:
o “SIGN_VALIDATION_FAILED” and “INVALID_DEVICESW” is replaced with
“CLIENT_ERR”.
o “CLIENT_ERR” is a new error indicating various problems with the client.
o “UNKNOWN_USER” is deprecated.
o “ALREADY_COLLECTED” is replaced with “INVALID_PARAMETERS”.
o “TIME_BLOCKED” was not used in previous version and is now deprecated.
o “START_FAILED” is a new error used if auto start with autostarttoken fails.
o “CERTIFICATE_ERR” is a new error indicating that the BankID is expired or revoked.



1.6 Client Platforms
BankID is supported in PCs running Windows, Mac OS X, mobile phones and tablet computers running
Android and iOS and mobile phones running Windows Phone 8. Up to date information on platform support
can be found at http://support.bankid.com.
BankID Security Application for mobile
devices
BankID Security Application for
PCs
-
NOTE
Login
Sign
fileSign
Support for multiple
users
Support for smart cards
-
User does not need to
enter ID number at login
NOTE: fileSign is deprecated and will not be included in future versions of the RP Service API. We strongly
recommend RP not to use fileSign. See chapter 11 - File Signing for more information.
2
Use Cases
There are a number of use cases that can be implemented using the new BankID solution. In this document
we describe the most common use cases to keep it simple and to give the reader a basic understanding of the
solution.



If the BankID app is installed on the same device the user uses to access the service the RP should help
the user to start the BankID app automatically. A description is found in Launching. In this case the
users do not need to provide their ID number.
If the BankID app is installed on another device the users must provide their ID number and manually
start the BankID app.
If the BankID app is installed on the same device the user uses to access the service, but the BankID
app cannot be automatically started, the user must provide their ID number and manually start the
BankID app on the same device. RP:s should consider this use case as a fallback in case the automatic
start fails.
BankID
Page 7(27)
BankID Relying Party Guidelines
Version: 2.7
To make the user experience consistent the RP must use the recommended messages and error messages in
Recommended User Messages.
The possibilities to restrict the types of BankID that can be used and how to define other requirements are
described in RequirementAlternativesType.
2.1 Basic Use cases
The following basic use cases exist:
A. The user access the service using a browser on a personal computer. Users should be asked if they want
to login or sign using “BankID on this computer” or “Mobile BankID”. Message RFA19 should be used.
a. Users that select to use BankID on this computer does not need to enter their ID number and the
RP must start the BankID app on the computer.
b. Users that select Mobile BankID must enter their ID number and the RP must give the
instruction to manually start the BankID app on their mobile device.
B. The user access the service using a browser on a mobile device. Users should be asked if they want to
login or sign using “Mobile BankID on this device” or “Mobile BankID on another device”. Message
RFA20 should be used.
a. Users that select to use this device do not need to enter their ID number and the RP must start
the BankID app on the mobile device.
b. Users that select to use another device must enter their ID number and the RP must give the
instruction to manually start the BankID app on the other device.
C. The user access the service using a native app on a mobile device. In this case the user most likely wants
to use a BankID on the same device. The RP may however provide possibilities to use another device in
this case as well.
a. The users do not need to enter their ID number and the RP app launches BankID App
programmatically (see Native App on Mobile Device).
b. Users that select to use another device must enter their ID number and the RP App must give the
instruction to manually start the BankID app on the other device.
In some cases it may be impossible to automatically start the BankID app. The reason could be browsers
blocking it or that the RP app does not have the capabilities to launch external URL:s. In this case the users
always can start the BankID app manually. In this case the users need to enter their ID number.
2.2 Flow of events
1.
2.
3.
4.
5.
6.
7.
8.
Users that select “another device” are asked to enter their ID number if it’s not already saved or
known by the RP.
The RP uses the Authenticate or Sign call of the web service API. The web service returns an
autoStartToken and an orderReference.
If the user selected “another device” RP should set condition “certificatePolicies” to
“1.2.752.78.1.5” to restrict the transaction to mobile devices only.
If the user selected “same device” the RP tries to start the BankID app. The autoStartToken must be
used in the start command if the ID number is not provided in the web service call, see Launching.
Once the BankID app has finished execution, focus will be returned to the browser/app.
If the user selected “another device” the RP informs the user to start the BankID app manually.
The RP service displays a progress indicator.
The login or sign transaction is displayed in the BankID app. The RP name (as stated in the RP
certificate) is displayed. The user enters personal security code or cancels.
The RP periodically uses the Collect call of the web service API, until a final response is received
and continuously updates the message displayed to the user. See Recommended User Messages.
RP removes the progress indicator.
2.3 Exceptions
1.
2.
3.
The web service call in step 2 fails. The use case is cancelled and the RP shall instruct the user
according to Recommended User Messages. The RP must not try to start the BankID app.
The Collect call in 7 fails. The use case is cancelled and RP shall instruct the user according to
Recommended User Messages.
The automatic start in 3 fails due to different reasons:
o The user has not installed the BankID app
o Erroneous start command
o User did not allow the browser to launch the URL
BankID
Page 8(27)
BankID Relying Party Guidelines
4.
5.
3
Version: 2.7
The web browser will inform the user that the URL cannot be opened. Status “START_FAILED”
will be delivered to the RP as response to the Collect call in 7 if the automatic start of the BankID
app has not been completed within a certain time limit. The RP shall instruct the user according to
Recommended User Messages.
The automatic start in 3 is successful but the user has no BankID of correct type. The BankID app
will display an error message. Status “STARTED” will be delivered to the RP as response to the
Collect call in 7. RP shall instruct the user according to Recommended User Messages.
In step 4, the user fails to manually start the BankID app or no BankID of correct type exists in the
started client. Different status codes will be delivered to RP as response to the Collect call in 7. The
RP shall instruct the user according to Recommended User Messages.
Launching
3.1 Launching the BankID app from a browser
When the BankID app is installed the schema “bankid” is registered in the operating system. When the
bankid schema is requested from the browser the operating system launches the BankID app. The URL works
in Android, iOS and Windows Phone 8 when the built-in web browser is used. The URL works in PCs with
all commonly used browsers. Some differences exist on different platforms.
The URL syntax is:
bankid:///?autostarttoken=[TOKEN]&redirect=[RETURNURL]
Note that the redirect parameter must be last in the parameter list. The autostarttoken, filehash and rpref
parameters are optional.
Note that the parameter names must be lower case.
3.2 How to Start
We recommend using the following technique to start the BankID app from a browser.
1. Make the call to the web service, check the result.
2. Try to start the Bankid app in a frame with zero size.
<iframe src="bankid:///?autostarttoken=[TOKEN]&redirect=[RETURNURL]" height=0 width=0></iframe>"
3.
If the BankID app is not installed the error presented by the browser will be in the zero size window
and not visible for the user.
After 5 seconds display a link or button with the BankID URL. Use text RFA18.
<a href="bankid:///?autostarttoken=[TOKEN]&redirect=[RETURNURL]”>[RFA18]
Using a href this way is the most reliable method to start the BankID app.
If the start in 2 is successful, the link in 3 will be hidden by the BankID app. If the start in 2 is unsuccessful,
the user will have a second chance to start. If the BankID app is started but no matching call to Authenticate
or Sign has been done, an error message will be displayed in the app. To avoid this, we recommend that the
link or button is inactivated immediately after the user presses it.
3.3 Behaviour in Different Browsers
3.3.1 Chrome
In current version of Chrome (version 31) a known problem blocks BankID from being started from a frame.
Using the recommended method above solves the problem, see
https://code.google.com/p/chromium/issues/detail?id=318788.
3.3.2 Internet Explorer
Internet Explorer manipulates the URL in the redirect parameter. In this specification we state that the
RETURNURL must be URL-encoded. However, Internet Explorer decodes the content prior passing it to the
BankID app. This is why it must be last in the list of parameters. In the same way, Internet Explorer may
decode the content of the RETURNURL when the BankID app passes the return URL back to the browser. If
the RP includes session information that is affected by URL-encoders/decoders problems may occur. It is
recommended to use only URL-encoding safe characters in the parameters.
3.3.3 Parameters in the start URL
Parameter
autostarttoken
Description
Optional.
BankID
BankID Relying Party Guidelines
Page 9(27)
Version: 2.7
Holds the autoStartToken that was returned from the web service call. If the user ID
number was not included in the web service call the autostarttoken must be provided.
We strongly recommend to always use the autostarttoken when the URL is used to start
the client. If it is not included and the user reloads the page or if the page erroneously
repeats the start command the user may get an error claiming that the BankID is
missing. The likelihood of this to happen is reduced if autostarttoken is used.
filehash
redirect
rpref
Deprecated. Optional. Not supported in mobile devices.
Holds a filehash. When a file is signed the RP may provide the SHA256 computed over
the binary file content of the file being signed. The filehash will be compared with the
SHA2 computed over the file content in the file sent to the BankID Server. If the
hashsums differ an error will be returned when collecting the result. If filehash is used,
autostarttoken must be used as well. Hexadecimal number. Note that the fileSign
method is deprecated.
Mandatory.
The BankID app uses the request parameter redirect to launch the RP web app after
completed (including cancelled) authenticate or sign. The redirect URL must be UTF-8
and URL encoded and should match the web address the user is visiting when RP web
app launches the BankID app. It may include parameters to be passed to the browser.
For iOS and Windows Phone the redirect must have a value, but for all other platforms
it may be empty (“redirect=”), or set to “null” (“redirect=null”). If it is empty or null
the BankID app will terminate without launching any URL and the calling application
will be in focus. The general recommendation is to use redirect=null when it is
possible.
Note for Windows and Mac OS X
If redirect has a value the redirect parameter must be used together with autostarttoken.
If autostarttoken is excluded, the content of redirect will be ignored and the behavior
will be as if redirect=null.
Note for Android
If the user has several browsers installed on an Android device the user is sometimes
presented with a question asking what browser to use. BankID recommends that
redirect=null is used on Android. This ensures the user will return to the browser
previously used.
Note for Windows Phone
When the browser on Windows Phone is started from an app it is considered a new
session by the browser, hence any previous transient (session) cookies are unavailable.
RP can use a persistent cookie or the RETURNURL to control the session.
Relying Party Reference. Optional. Not supported in mobile devices.
Any reference the RP wants to use. The value will be included in the resulting
signature. A typical use case is to protect a file when it is transported from a client to a
server (compute hashsum of the file content in the client, include the hashsum as rpref,
compare it (server side) with a hashsum of the file content computed in the server). The
value must be base64 encoded and URL encoded and 8 – 255 bytes (after encoding).
rpref must be used together with autostarttoken. If autostarttoken is excluded, the
content of rpref will be ignored. If the client software version is too old the parameter is
not supported. An error will be displayed in the client.
3.3.3.1 Examples
The RP wants the BankID app to open a browser with the following URL after finishing execution:
https://demo.bankid.com/nyademobanken/CavaClientRedirReceiver.aspx?orderRef=bedea56d-7b46-47b1890b-f787c650bc93&returnUrl=./CavaClientAuth.aspx&Environment=Kundtest. The autostarttoken is
included. The start URL is:
bankid:///?autostarttoken=a4904c4c-3bb4-4e3f-8ac3-0e950e529e5f&
redirect=https%3a%2f%2fdemo.bankid.com%2fnyademobanken%2fCavaClientRedirReceiver.aspx%3forder
Ref%3dbedea56d-7b46-47b1-890bf787c650bc93%26returnUrl%3d.%2fCavaClientAuth.aspx%26Environment%3dKundtest
BankID
BankID Relying Party Guidelines
Page 10(27)
Version: 2.7
3.4 Launching the BankID app from Native App on Mobile Device
3.4.1 Android
Intent intent = new Intent();
intent.setPackage("com.bankid.bus");
intent.setAction(Intent.ACTION_VIEW);
intent.setData(Uri.parse("bankid:///?autostarttoken=<INSERT
AUTOSTARTTOKEN HERE>&redirect=null ")) ;
startActivityForResult(intent, 0);
In Android, the RP app does not need to register a URL scheme to be successfully re-launched by the BankID
app. onResume() will be called when RP app is re-launched.
If the BankID app is not present on the device an
android.content.ActivityNotFoundException is thrown. RP must inform the user. Message
RFA2 should be used.
3.4.2 iOS
openURL:[NSURL URLWithString: @”bankid:///?
autostarttoken=<INSERT AUTOSTARTTOKEN HERE>&redirect=fp_app_x://”]
If the BankID app is not present on the device NO is returned. RP must inform the user. Message RFA2
should be used.
The RP app must register a unique URL scheme to make it possible for the BankID app to re-launch RP app.
In Xcode select the project and in the Info tab expand URL Types and add the URL scheme rp_app_x.
Note: rp_app_x is an example. The RP should use its own unique URL scheme.
The RP must implement the following function that will be called when the RP app is re-launched.
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url
sourceApplication:(NSString *)sourceApplication
annotation:(id)annotation
3.4.3 Windows Phone
// Create the URI string
var uriToLaunch = string.Format(
"bankid:///www.bankid.com/autostarttoken={0}&redirect={1}",
<INSERT AUTOSTARTTOKEN HERE>,
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);
If the BankID app is not present on the device the operating system presents a dialogue asking to open
Windows Phone store. RP must inform the user. Message RFA2 should be used.
The RP app must register a unique URL scheme to make it possible for the BankID app to re-launch RP app.
In Visual Studio:
BankID
Page 11(27)
BankID Relying Party Guidelines
1.
2.
3.
4.
Version: 2.7
Open Package.appxmanifest
Open the tab Declarations.
Add a "Protocol". Under name enter ”rp_app_x”.
Enter a logo and a "Display name".
Note: rp_app_x is an example, RP should use its own unique URL scheme.
RP must also implement the following to be successfully re-launched by BankID Security App. In Visual
Studio add the class AssociationUriMapper:
/// <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.
if (tempUri.StartsWith("/Protocol"))
{
// Here we can redirect to the correct page, but
for now we don't
return new Uri("/MainPage.xaml",
UriKind.Relative);
}
// Otherwise perform normal launch.
return uri;
}
}
In App.xaml.cs, add AssociationUriMapper as UriMapper by adding the following line to the method
InitializePhoneApplication:
// Assign the URI-mapper class to the application frame.
RootFrame.UriMapper = new AssociationUriMapper();
4
Technical Requirements
Short Name
Requirement
BankID
Page 12(27)
BankID Relying Party Guidelines
Version: 2.7
RFT1
When the BankID app is launched with a URL the content of the request parameter redirect must be
UTF-8 and URL encoded.
RFT2
When the BankID app is launched with a URL the URL must not exceed 2000 characters.
RFT3
When the BankID app is launched with a URL the redirect URL should use HTTPS.
RFT4
The ID number in the RP web service API must be 12 characters (YYYYMMDDNNNN).
RFT5
When Collect returns COMPLETE RP shall read and store the parameters signature, userInfo and
ocspResponse. RP does not need to verify the signature. BankID verifies the signature.
RFT6
Collect should be called every two seconds and must not be called more frequent than once per
second.
RFT7
RP should display a progress indicator in its web app when waiting for the final response from
Collect.
RFT8
RP must contact BankID’s web service API from RP’s backend server. RP must NOT contact
BankID’s web service API from RP’s client app.
RFT9
RP should always use the latest version of the web service API, see Information regarding the Web
Service API.
RFT10
If the user selects to use Mobile BankID only, the certificatePolicies condition must be set to
1.2.752.78.1.5
RFT11
RP must use the issuer of the server cert as trusted root. If the server cert is used as trusted, the RP
service will not be able to access the BankID server when the server cert is changed.
5
Recommended User Messages
Short
Name
Swedish Text
English Text
Event or API
Code Mapping
RFA1
Starta BankID-programmet.
Start your BankID App.
OUTSTANDING_
TRANSACTION
RFA2
Du har inte BankID-appen
installerad. Kontakta din bank.
The BankID app is not installed. Please
contact your bank.
The BankID app is
not installed in the
mobile device.
RFA3
Åtgärden avbruten. Försök igen.
Action cancelled. Please try again.
ALREADY_IN_P
ROGRESS,
CANCELLED
RFA5
Internt tekniskt fel. Försök igen.
Internal error. Please try again.
RETRY,
INTERNAL_ERR
OR, CLIENT_ERR
RFA6
Åtgärden avbruten.
Action cancelled.
USER_CANCEL
RFA8
BankID-programmet svarar inte.
Kontrollera att det är startat och att
du har internetanslutning. Försök
sedan igen.
The BankID App is not responding. Please
check that the program is started and that
you have internet access, then try again.
EXPIRED_TRAN
SACTION
RFA9
Skriv in din säkerhetskod i BankIDprogrammet och välj Legitimera
eller Skriv under.
Enter your security code in the BankID App
and select Identify or Sign.
USER_SIGN
RFA12
Internt tekniskt fel. Uppdatera
BankID-programmet och försök
igen.
Internal error. Update your BankID App and
try again.
CLIENT_ERR
RFA13
Försöker starta BankIDprogrammet.
Trying to start your BankID App.
OUTSTANDING_
TRANSACTION
BankID
Page 13(27)
BankID Relying Party Guidelines
Version: 2.7
RFA14
(A)
Du har inget BankID som går att
använda för den här
inloggningen/underskriften på den
här datorn. Om du har ett BankIDkort, sätt in det i läsaren. Om du
inte har något BankID kan du
hämta ett hos din Bank. Om du har
ett BankID på en annan enhet kan
du starta ditt BankID-program där.
You do not have a BankID which can be
used for this login/signature on this
computer. If you have a BankID card, please
insert it into your card reader. If you don’t
have a BankID you can order one from your
bank. If you have a BankID on another
device you can start the BankID App on that
device.
STARTED
The RP provided
the ID number in
the web service
call.
The user accesses
the service using a
personal computer.
RFA14
(B)
Du har inget BankID som går att
använda för den här
inloggningen/underskriften på den
här enheten. Om du inte har något
BankID kan du hämta ett hos din
Bank. Om du har ett BankID på en
annan enhet kan du starta ditt
BankID-program där.
You do not have a BankID which can be
used for this login/signature on this device.
If you don’t have a BankID you can order
one from your bank. If you have a BankID
on another device you can start the BankID
App on that device.
STARTED
The RP provided
the ID number in
the web service
call.
The user accesses
the service using a
mobile device.
RFA15
(A)
Du har inget BankID som går att
använda för den här
inloggningen/underskriften på den
här datorn. Om du har ett BankIDkort, sätt in det i läsaren. Om du
inte har något BankID kan du
hämta ett hos din Bank.
You do not have a BankID which can be
used for this login/signature on this
computer. If you have a BankID card, please
insert it into your card reader. If you don’t
have a BankID you can order one from your
bank.
STARTED
The RP did not
provide the ID
number in the web
service call.
The user accesses
the service using a
personal computer.
RFA15
(B)
Du har inget BankID som går att
använda för den här
inloggningen/underskriften på den
här enheten. Om du inte har något
BankID kan du hämta ett hos din
Bank.
You do not have a BankID which can be
used for this login/signature on this device.
If you don’t have a BankID you can order
one from your bank.
STARTED
The RP did not
provide the ID
number in the web
service call.
The user accesses
the service using a
mobile device.
RFA16
Det BankID du försöker använda är
för gammalt eller spärrat. Använd
ett annat BankID eller hämta ett
nytt hos din bank.
The BankID you are trying to use is revoked
or too old. Please use another BankID or
order a new one from your bank.
CERTIFICATE_E
RR
RFA17
BankID-programmet verkar inte
finnas i din dator eller telefon.
Installera det och hämta ett BankID
hos din bank. Installera programmet
från install.bankid.com.
The BankID App couldn’t be found on your
computer or mobile device. Please install it
and order a BankID from your bank. Install
the app from install.bankid.com.
START_FAILED
RFA18
Starta BankID-programmet
Start the BankID App
The name of link or
button used to start
the BankID App
RFA19
Vill du logga in eller skriva under
med BankID på den här datorn eller
med ett Mobilt BankID?
Would you like to login or sign with a
BankID on this computer or with a Mobile
BankID?
The user access the
service using a
browser on a
personal computer.
RFA20
Vill du logga in eller skriva under
med ett BankID på den här enheten
eller med ett BankID på en annan
enhet?
Would you like to login or sign with a
BankID on this computer or with a BankID
on another device?
The user access the
service using a
browser on a
mobile device.
NB: RFA4, RFA7, RFA10 and RFA11 are deprecated and intentionally removed.
BankID
Page 14(27)
BankID Relying Party Guidelines
6
Version: 2.7
Production Environment
Description
SSL certificate (RP certificate)
Information
Provided by the bank that RP purchases the Mobile BankID service.
Web service URL
https://appapi.bankid.com/rp/v4
Web service API specification
https://appapi.bankid.com/rp/v4?wsdl
Server certificate
The server certificate is issued by the following CA:
CN = BankID SSL Root Certification Authority
OU = Infrastructure CA
O = Finansiell ID-Teknik BID AB
Certificate:
-----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-----
Network information
7
The BankID app for mobile devices in production connects to the BankID
server on the IP address 194.242.109.204 using the ports 4710, 443, 80, in
the order mentioned.
The BankID Security Application for personal computers in production
connects to the BankID server on the IP address 194.242.109.207 using
port 443 and address 194.242.109.208 using port 80.
The BankID Security Application for personal computers also connects to
a version control system on the address 159.72.128.183 using port 80.
Test Environment
BankID provides a test environment for an RP to use when developing and testing its service. To be able to
use the test environment the RP will need:
1. An SSL certificate (RP certificate) for authorisation with the BankID web service API.
2. The URL for BankID’s web service API.
3. Trust the issuer of the SSL certificate.
4. A test version of BankID Security App and/or BankID Security Program
5. A BankID for test.
Description
SSL certificate (RP certificate
for test)
Information
http://www.bankid.com/rp/info
Passphrase for above certificate
qwerty123
BankID
Page 15(27)
BankID Relying Party Guidelines
Version: 2.7
Web service URL
https://appapi.test.bankid.com/ rp/v4
Web service API specification
https://appapi.test.bankid.com/rp/v4?wsdl
Server certificate
CN = BankID SSL Root Certification Authority TEST
OU = Infrastructure CA
O = Finansiell ID-Teknik BID AB
Certificate:
-----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-----
Test version of BankID
Security App for Android
http://www.bankid.com/rp/info
Installation instructions for
Android
http://www.bankid.com/rp/info
Test version of BankID
Security App for iOS
Uninstall any existing version of BankID Security App. Install BankID
Security App from App Store. In Settings  BankID  Developer 
Server enter businternal.test.bankid.com. BankID Security App will now
connect to the test server. Please note that the app must be uninstalled to
undo the change.
Test version of BankID
Security App for Windows
Phone 8
Uninstall any existing version of BankID Security App. Install BankID
Security App from Windows Phone Store. Start BankID Security App,
select Settings  Developer  Server and enter
businternal.test.bankid.com. Save, exit BankID Security App and launch
again. BankID Security App will now connect to the test server. Please
note that the app must be uninstalled to undo the change.
Test version of BankID
Security Application for PCs
(Windows and OS X)
To be able to use the client for test you must configure it for test. If you
change configuration your existing BankID:s may be blocked. Follow the
backup-restore procedure to avoid that.
Start by backing up the configuration for production:
1. Stop BankID Security Application (BISP).
2. Open BISP configuration folder (see below).
3. Copy all files in the folder to a separate location to be able to
restore the production configuration later on.
Create a set-up for test:
1. Stop BISP.
2. Open configuration folder.
3. Delete all files in the folder.
BankID
Page 16(27)
BankID Relying Party Guidelines
Version: 2.7
4.
Create a plain text file in the folder named
”CavaServerSelector.txt”, containing the text ”kundtest”. The
content must be plain text. The file may be created using notepad
or the Terminal.app.
Switch between production and test later on:
1. Stop BISP.
2. Replace files in the configuration folder with the earlier copied
files for the desired environment.
Location of BISP configuration folder


Windows: %appdata%\BankID\Config
OS X: /Users/<användare>/Library/Application
Support/BankID/Config
IMPORTANT: Only a BankID that is enrolled in the present environment
can be used or administered in the present environment. Trying to use or
administer a BankID from the other environment will block it.
BankID for test
Perform step 1-4 above and verify that your web service client can
successfully communicate with the RP Interface.
Verify that you have BankID Security App configured for test (iOS, WP8,
Windows, OS X) or that you use a test version of BankID Security app
(Android).
Use a production or test BankID and log in to
https://demo.bankid.com/nyademobanken. Note that if you configured the
client for test, you cannot use a production BankID and vice versa.
Select “Hämta BankID för test” and click the “Hämta BankID” button
below the name in order to request a BankID for test. In the next step you
can enter the ID (“personnummer”) and name (“Namn”) for the test
BankID and request a Mobile BankID or a BankID on file.
This will open a pop-up window. Your browser must not block pop-up
windows. Follow the instructions in the pop-up window.
If you are unable to follow the instructions above, please contact
teknikinfo@bankid.com.
Network information
The BankID app for mobile devices for test connects to the BankID server
on the IP address 194.242.109.185 using the ports 4710, 443, 80, in the
order mentioned.
The BankID Security Application for personal computers for test connects
to the BankID server on the IP address 194.242.109.177 using port 443
and address 194.242.109.169 using port 80.
The BankID Security Application for personal computers also connects to
a version control system on the address 159.72.128.183 using port 80.
8
Information regarding the Web Service API
8.1 Versions
A new version of the web service API will be published on a new URL every time there is a change in the
API. RP should always use the latest version of the API. The general rule is that old versions will shut down 2
years after the release of the successor. As new functionality is introduced to the system the behavior of an
existing version of the interface may change, e.g. existing faults may also be used in new situations. This
document is written for version 4 of the interface.
V
URL
1
https://appapi.bankid.com/RpServi
ceEjb/RpService/RpService
Changes
The first version
Release
date
September
2011
End of life
January
20161
BankID
Page 17(27)
BankID Relying Party Guidelines
Version: 2.7
2
https://appapi.bankid.com
/RpServiceEjb/RpService/v2/RpSer
vice
3
Not for public use
4
https://appapi.bankid.com/rp/v4
Mobile BankID, BankID on file,
BankID on Card and Nordea e-leg
merged to one solution.
January
2014
4
Method fileSign in
https://appapi.bankid.com/rp/v4
Decision to deprecate method
fileSign
June 2014
1)
Added new types and parameters to
existing methods. Added new fault to
handle the new RP cancel
functionality
May 2012
Janaury
2016
October
2012
January
2016
June 2016
Extended
8.2 Test Environment
New versions and release candidates are used in the test environment prior to being taken into use in the
production environment. Due to this the content and functionality in the test environment and production
environment may temporarily differ.
8.3 No soapAction
The service uses URLs to specify the action to use. The soapAction header must be ”” or excluded all
together.
9
Support
In technical matters please contact teknikinfo@bankid.com. In any other business, please contact the bank
through which you have purchased the BankID service.
Requirement
RFS1
RP should inform the user what to do in case of lost or forgotten security code (contact the
issuer).
RFS2
RP must provide support for its own service.
RFS3
When the user is having problems the RP should redirect the user to test.bankid.com.
Users that cannot successfully use their BankID at test.bankid.com should be redirected to the
issuing bank in case of a BankID related problem and in case of network error to mobile phone
carrier or the internet service provider.
If the user can successfully identify and sign at test.bankid.com the user should be redirected to
the RP support.
10 Recommended Terminology
Description
Recommended terminology
in Swedish
Recommended terminology in
English
Mobile BankID
Mobilt BankID
Mobile BankID
BankID Security Application for
mobile devices
BankID säkerhetsapp
BankID Security Application
BankID Security Application for
PCs
BankID säkerhetsprogram
BankID Security Application
Security code, password, PIN
Säkerhetskod
Security code
Sign
Underteckna
Sign
Signature
Underskrift
Signature
Identify
Legitimera sig
Identify
BankID
Page 18(27)
BankID Relying Party Guidelines
Identification/authentication
Version: 2.7
Legitimering
Identification
11 File Signing
The method fileSign is deprecated and we strongly recommend RP not to use it. It will not be included in
future versions of the RP Service API. The main reasons are:
 It is impossible to support fileSign in a proper manner for Mobile devices
 Only pdf supported
 Size restrictions
Our recommendation is to use the sign method with the following notes:
1. Present the document to be signed to the user using your own application/website.
2. Compute a message digest of the binary representation of the document.
3. Compile an abstract of the content of the document.
4. Use method sign with userVisibleData set to abstract and userNonVisibleData set to the message
digest.
The benefits of using this method are that it is available for PC:s and mobile devices, that there is no sizelimitation and that all types of documents can be signed. A not yet planned and future fileSigning method will
be in line with this recommendation.
BankID
Page 19(27)
BankID Relying Party Guidelines
Version: 2.7
12 Appendix: RP Interface Description
12.1 Method Auth
Request an authentication order. The Collect method is used to query the status of the order.
12.1.1 In parameters
Name
Value
personalNumber
PersonalNumberType - The ID number of the user trying to be authenticated (optional).
If the ID number is omitted the user must use the same device and the client must be
started with the autoStartToken returned in orderResponse.
endUserInfo
List of EndUserInfoType (optional). Used to provide information related to the user and
the user’s computer/device to the BankID-server.
requirementAlternatives
RequirementAlternativesType (optional). Used by RP to set requirements how the
authentication or sign operation must be performed. Default rules are applied if omitted.
12.1.2 Return value
Returns an orderResponse of type OrderResponseType or error.
12.2 Method Sign
Request a signing order. The Collect method is used to query the status of the order.
12.2.1 In Parameters
Name
Value
personalNumber
PersonalNumberType - The ID number of the user trying to sign (optional). If the ID
number is omitted the user must use the same device and the client must be started with
the autoStartToken returned inorderResponse.
endUserInfo
List of EndUserInfoType (optional). Used to provide information related to the user and
the user’s computer/device to the BankID-server.
requirementAlternatives
RequirementAlternativesType (optional). Used by RP to set requirements how the login
or sign operation must be performed. Default rules are applied if omitted.
userVisibleData
The text to be displayed and signed. Must be UTF-8 encoded. The value must be base
64-encoded. 1-40 000 characters (after base 64-encoding). The text can be formatted
using CR = new line, LF = new line and CRLF = new line
userNonVisibleData
Data not displayed to the user (optional). The value must be base 64-encoded. 0 - 200
000 characters (after base 64-encoding).
12.2.2 Return value
Returns an orderResponse of type OrderResponseType or error.
12.3 Method FileSign - Deprecated
Request a file signing order. The Collect method is used to query the status of the order.
BankID
Page 20(27)
BankID Relying Party Guidelines
Version: 2.7
12.3.1 In Parameters
Name
Value
personalNumber
PersonalNumberType - The ID number of the user trying to sign (optional). If the ID number is
omitted the user must use the same device and the client must be started with the
autoStartToken returned inorderResponse.
endUserInfo
List of EndUserInfoType (optional). Used to provide information related to the user and the
user’s computer/device to the BankID-server.
requirementAlternati
ves
RequirementAlternativesType (optional). Used by RP to set requirements how the login or sign
operation must be performed. Default rules are applied if omitted.
userVisibleData
The text to be displayed and signed. Must be UTF-8 encoded. The value must be base 64encoded. 1-40 000 characters (after base 64-encoding). The text can be formatted using CR =
new line, LF = new line and CRLF = new line
userNonVisibleData
Data not displayed to the user (optional). The value must be base 64-encoded. 0 - 200 000
characters (after base 64-encoding).
fileName
String. Base 64-encoded. 5-340 characters. Printable ASCII-characters (32-127), and åäöÅÄÖ.
Characters not allowed in filenames are not allowed. The name must end with dot (".") and a
suffix that describes the type of file. Example: Agreement130821.pdf. Allowed file types are
.pdf and .txt
fileContent
MTOM/XOP-binary data. Must not be inline. Max 5Mb.
The filecontent is sent as binary attachment outside the SOAP-envelope using XML-binary
Optimized Packaging (XOP). The file is not base 64-encoded (even though the type is called
base64binary).
In some cases the support needs to be activated in the SOAP-client. The server will response
with an error if XOP is not used. The support is activated differently depending on used
framework. Note that MTOM only is required for fileSign and is not needed for other methods.
In JAX-WS the support can be activated using the following (where port is the SOAP port)
BindingProvider bindingProvider = (BindingProvider) port;
SOAPBinding binding = (SoapBinding) bindingProvider.getBinding();
binding.setMTOMEnabled(true);
In .Net you may need to set BasicHttpBinding.MessageEncoding to "Mtom".
12.3.2 Return value
Returns an orderResponse of type OrderResponseType or error.
12.4 PersonalNumberType
Example with personal number (“personnummer”)


<personalNumber>198103091234</personalNumber>
12.5 EndUserInfoType
Used to pass information related to the user and the user’s computer/device to the BankID server.
A list of types and values. Allowed types are:

IP_ADDR. used to include the users IP-address as seen by RP. It is recommended to use
this parameter to enable future controls of the IP-address (no controls are done in the
current solution).
BankID
Page 21(27)
BankID Relying Party Guidelines
Version: 2.7
Example with ip address
<endUserInfo>
<type>IP_ADDR</type>
<value>192.168.0.1</value>
</endUserInfo>
12.6 RequirementAlternativesType
A list of alternative requirements. Used by RP to put one or more requirement on how the order
must be created and verified. A requirement consists of one or more conditions. Every condition
has a type/key and can have one or more values. If no requirement is included a set of default
conditions is applied. The order of the requirement is significant. The first requirement where all
conditions are true will be used. The used requirement is included in the resulting signature.
<requirementAlternatives>
<requirement>
<condition>
<key>TYPE OF CONDITION</key>
<value>VALUE FOR THE CONDITION</value>
</condition>
</requirement>
</requirementAlternatives>
Type of conditions and values
Type of condition
CardReader




CertificatePolicies
Values
Default
"class1" - (default). The transaction must be
performed using a card reader where the PIN-code
is entered on the computers keyboard, or a card
reader of higher class.
"class2" - The transaction must be performed using
a card reader where the PIN-code is entered on the
reader, or a reader of higher class.
<no value> - defaults to "class1".
This condition should be combined with a
CertificatePolicies for a smart card to avoid
undefined behavior.
No special type of card reader
required.
The oid in certificatePolicies in the user certificate.
One wildcard ”*” is allowed from position 5 and
forward ie. 1.2.752.78.*
If no certificatePolicies is set
the following are default in the
production system:
The values for production BankIDs are:
1.2.752.78.1.1, 1.2.752.78.1.2,
1.2.752.78.1.5, 1.2.752.71.1.3
"1.2.752.78.1.1" - BankID on file
"1.2.752.78.1.2" - BankID on smart card
"1.2.752.78.1.5" - Mobile BankID
"1.2.752.71.1.3" - Nordea e-id on file and on smart
card.
The values for test BankIDs are:
"1.2.3.4.5" - BankID on file
"1.2.3.4.10" - BankID on smart card
"1.2.3.4.25" - Mobile BankID
The following are default in the
test system:
1.2.3.4.5, 1.2.3.4.10, 1.2.3.4.25,
1.2.752.60.1.6, 1.2.752.71.1.3
If one certificatePolicy is set all
the default policies are
dismissed.
BankID
Page 22(27)
BankID Relying Party Guidelines
Type of condition
Version: 2.7
Values
Default
"1.2.752.71.1.3" - Nordea e-id on file and on smart
card.
“1.2.752.60.1.6” - Test BankID for some BankID
Banks
IssuerCn
The cn (common name) of the issuer. Wildcards
are not allowed. Nordea values for production:
If issuer is not defined all
relevant BankID and Nordea
issuers are allowed.
"Nordea CA for Smartcard users 12" - E-id on
smart card issued by Nordea CA.
"Nordea CA for Softcert users 13" - E-id on file
issued by Nordea CA
Example Nordea values for test:
"Nordea Test CA for Smartcard users 12" - E-id on
smart card issued by Nordea CA.
"Nordea Test CA for Softcert users 13" - E-id on
file issued by Nordea CA
AutoStartTokenRequired
If set to Yes, the client must have been started
using the autoStartToken. To be used if it is
important that the BankID App is on the same
device as the RP service.
Default: No
Additional information related to RequirementAlternatives is given in More information about
requirement alternatives.
12.6.1 OrderResponseType
Return value from auth/sign/filesign
OrderRef must be used by RP when using the collect method. UUID-string: 36-50 characters.
AutoStartToken must be used when the user ID is not provided. UUID-string: 36-50 characters.
Example, response from Auth
<AuthResponse>
<orderRef>8e4dd041-e38f-463b-b286-a6c5e35d462d</orderRef>
<autoStartToken>a5312da3-0c71-4a74-a14d-28bc11d6ed3a</autoStartToken>
</AuthResponse>
12.7 Error codes for Auth/Sign/FileSign
Code
Reason
Action by RP
INVALID_PARAMETERS
Invalid parameter. Invalid use
of method
RP must not try the same request again. This is
an internal error within RP's system and must
not be communicated to the user as a BankIDerror.
ALREADY_IN_PROGRESS
An order for this user is
already in progress. The order
is aborted. No order is
created.
RP must inform the user that a login or signing
operation is already initiated for this user.
Message RFA3 should be used.
BankID
Page 23(27)
BankID Relying Party Guidelines
Version: 2.7
Code
Reason
Action by RP
INTERNAL_ERROR
Internal technical error in the
BankID system.
RP must not automatically try again. RP must
inform the user that a technical error has
occurred. Message RFA5 should be used.
RETRY
Internal technical error in the
BankID system.
RP must not automatically try again. RP must
inform the user that a technical error has
occurred. Message RFA5 should be used.
ACCESS_DENIED_RP
RP does not have access to
the service or requested
operation.
RP must not try the same request again. This is
an internal error within RP's system and must
not be communicated to the user as a BankIDerror.
12.8 Method Collect
12.8.1 In Parameters
Name
Value
orderRef
The orderReference in the orderResponse received from Auth, Sign or SignFile. (UUID-string)
12.8.2 Return Value
Name
Type
progressStatus
ProgressStatusType
signature
String (b64). XML-signature. (If the order is COMPLETE). The content of the signature is
described in BankID Signature Profile specification.
userInfo
UserInfoType (If the order is COMPLETE)
ocspResponse
String (b64). OCSP-response (If the order is COMPLETE). The OCSP 0 response is signed by a
certificate that has the same issuer as the certificate being verified. 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.8.3 ProgressStatusType
Status
Reason
Action by RP
OUTSTANDING_T
RANSACTION
The order is being processed. The
client has not yet received the
order. The status will later change
to NO_CLIENT, STARTED or
USER_SIGN.
If RP tried to start the client automatically, the RP should
inform the user that the app is starting. Message RFA13
should be used.
If RP did not try to start the client automatically, the RP
should inform the user that she needs to start the app.
Message RFA1 should be used.
BankID
Page 24(27)
BankID Relying Party Guidelines
Version: 2.7
Status
Reason
Action by RP
NO_CLIENT
The order is being processed. The
client has not yet received the
order.
If RP tried to start the client automatically: This status
indicates that the start failed or the users BankID was not
available in the started client. RP should inform the user.
Message RFA1 should be used.
If the user did not provide her ID
number the error
START_FAILED will be returned
in this situation.
If RP did not try to start the client automatically: This
status indicates that the user not yet has started her client.
RP should inform the user. Message RFA1 should be
used.
STARTED
A client has been started with the
autoStartToken but no usable ID
exists in the started client.
If RP does not require the autoStartToken to be used and
the user provided her ID number the RP should inform
the user of possible solutions. Message RFA14 should be
used.
If RP require the autostarttoken to be used or the user did
not provide her ID number the RP should inform the user
of possible solutions. Message RFA15 should be used.
USER_SIGN
The client has received the order.
The RP should inform the user. Message RFA9 should
be used.
USER_REQ
Not used
COMPLETE
The user has provided the security
code and completed the order.
Collect response includes the
signature, user information and the
ocsp response.
RP should control the user information returned in
userInfo and continue their process.
12.8.4 UserInfoType
Name
Value
personalNumber
PersonalNumberType - ID number (swe personnummer)
givenName
The given name of the user
surname
The surname of the user
name
The given name and surname of the user
notBefore
Start of validity of the users BankID
notAfter
End of validity of the Users BankID
ipAddress
The IP-address of the user agent as the BankID server discovers it
12.8.5 Error codes Collect
Error code
Reason
Action by RP
INVALID_PARAM
ETERS
Invalid parameter. Invalid use of method.
RP must not try the same request again. This
is an internal error within RP's system and
must not be communicated to the user as a
BankID-error.
Using an orderRef that previously resulted in
COMPLETE. The order cannot be collected
twice.
BankID
Page 25(27)
BankID Relying Party Guidelines
Version: 2.7
Error code
Reason
Action by RP
REQ_PRECOND
Not used.
REQ_ERROR
Not used.
REQ_BLOCKED
Not used.
INTERNAL_ERRO
R
Internal technical error in the BankID system.
RP must not automatically try again. RP must
inform the user. Message RFA5.
RETRY
Internal technical error in the BankID system.
RP must not automatically try again. RP must
inform the user. Message RFA5.
ACCESS_DENIED
_RP
RP does not have access to the service or
requested operation.
RP must not try the same request again. This
is an internal error within RP's system and
must not be communicated to the user as a
BankID-error.
CLIENT_ERR
Internal technical error. It was not possible to
create or verify the transaction.
RP must not automatically try again. RP must
inform the user. Message RFA12.
EXPIRED_TRANS
ACTION
The order has expired. The BankID security
app/program did not start, the user did not
finalize the signing or the RP called collect
too late.
RP must inform the user. Message RFA8.
CERTIFICATE_ER
R
This error is returned if:
RP must inform the user. Message RFA16.
1) The user has entered wrong security code
too many times in her mobile device. The
Mobile BankID cannot be used.
2) The users BankID is revoked.
3) The users BankID is invalid.
USER_CANCEL
The user decided to cancel the order.
RP must inform the user. Message RFA6.
CANCELLED
The order was cancelled. The system
received a new order for the user.
RP must inform the user. Message RFA3.
START_FAILED
The user did not provide her ID, or the RP
requires autostarttoken to be used, but the
client did not start within a certain time limit.
The reason may be::
1) The RP must use autoStartToken when
starting the client
1) RP did not use autoStartToken when
starting BankID security program/app.
2) The client software was not installed or
other problem with the user’s computer.
ALREADY_COLL
ECTED
Not used.
2) The RP must inform the user. Message
RFA17.
BankID
Page 26(27)
BankID Relying Party Guidelines
Version: 2.7
12.9 More information about requirement alternatives
12.9.1 Syntax
It is possible to use several alternative requirements. Each requirement has one or more
condition(s). Each condition in a requirement must be fulfilled. A condition can have one or more
alternative values of which one must be fulfilled.
requirement(s) (OR)
condition(s) (AND)
key
value(s) (OR)
12.9.2 Examples
12.9.2.1 Mobile BankID
<requirementAlternatives>
<requirement>
// The first requirement, all following
<condition>
<key>CertificatePolicies</key>
// conditions must be fulfilled
// The certificate policy must be
<value>1.2.752.78.1.5</value>
</condition>
// 1.2.752.1.5 (Mobile BankID)
</requirement>
</requirementAlternatives>
12.9.2.2 Mobile BankID OR Nordea E-leg OR BankID on Card
<requirementAlternatives>
<requirement>
<condition>
<Key>CertificatePolicies</key>
<value>1.2.752.78.1.5</value>
// The certificate policy must be
// Mobile BankID OR
<value>1.2.752.71.1.3</value>
// Nordea E-leg OR
<value>1.2.752.78.1.2</value>
// BankID on Card
</condition>
</requirement>
</requirementAlternatives>
12.9.2.3 BankID on Card in a Class2 Reader or Nordea E-leg on Card in a Class2 Reader
Different types of Nordea e-id cannot be separated using certificatePolicy only. Their smart card
issuer needs to be included as a condition as well.
<requirementAlternatives>
<requirement>
<condition>
<key>CertificatePolicies</key>
<value>1.2.752.78.1.2</value>
</condition>
<condition>
<key>CardReader</key>
// The first requirement
// The certificate policy must be
// BankID on Card
// AND cardreader class2 must be used
<value>class2</value>
</condition>
</requirement>
<requirement>
<condition>
<key>CertificatePolicies</key>
<value>1.2.752.71.1.3</value>
</condition>
<condition>
<key>IssuerCn</key>
// OR The second requirement
// The certificate policy must be
// Nordea e-leg
// AND The issuer must be Nordea 12
<value>Nordea CA for Smartcard users 12</value>
BankID
Page 27(27)
BankID Relying Party Guidelines
Version: 2.7
<condition>
<condition>
<key>CardReader</key>
<value>class2</value>
</condition>
</requirement>
</requirementAlternatives>
// AND
cardreader class2 must be used