How to upgrade BankID API to V6
Swedish BankID are on a constant journey to make their service even more safe for the users.
One of the latest additions to this is what is called Secure Start (Säker Start). If you are a company/organization that offers your users to identify or sign through BankID you need to ensure that you implement Secure Start. This will be mandatory from May 1st 2024.
Secure start comes with three requirements:
- Animated QR code for BankID on the another device.
- Autostart for BankID on the same device.
- Upgrading to version 6 of our API.
Step 1 (Animated QR code) and 2 (autostart on same device) above have been available for some time (since v5.1 / April 2020), while step 3 (API V6) just was released (May 2023).
At Active Solution we have been working with BankdID-implementations for a long time, and we have gathered loads of knowledge in our Open Source-project Active Login Authentication (BankID wrapper for .NET). We just announced the release of Active Login Authentication 7.0.0, which supports the latest version of the BankID API. While upgrading our BankID-implementation we had to find all the deletions, changes and additions in the new version.
This blogpost aims to describe our findings on everything that changed between API version 5.1 (as described in BankID Relying Party Guidelines V3.8) and API 6.0 (as described in Relying Party Guidelines V6.0). Note that if you are using an older version of the BankID API, there are additional changes. At the BankID website, you will find the full devleoper documentation.
Below we will describe the changes.
Auth/Sign > Request
These are the changes to the request of a call to
personalNumberis removed. Use Secure Start instead.
Auth/Sign > Request > Requirements
These are the changes to the
requirements object of the response from a call to
- Removed: For
certificatePoliciesone of the valid values is removed. Specifically the one related to Nordea ("1.2.718.104.22.168" - Nordea e-id on file and on smart card) is removed.
allowFingerprintis removed. You can accomplish the same functionality using
pinCode, see documentation below.
pinCodeis a new property. If set to true it requires the usage of pin code from the end user (instead of biometric / fungerprint). This value will default to
personalNumberis a new property that can be used to ensure that the user that scanned the identified/signed through BankID has a specific swedish personal identity number. Note: This is not the same thing as starting a flow for a specific person, but rather for verification. Example: The user identifies through BankID, you then want the same user to identify and then you can pass this parameter as you know the personalNumber for that person.
mrtdRequiredis renamed into
mrtd. This feature/property wasn't described in Relaying Party Guidelines 3.8 but was an "undocumented" feature it seems. The description is: "If present, and set to "true", the client needs to provide MRTD (Machine readable travel document) information to complete the order. Only Swedish passports and national ID cards are supported.".
Collect > Response
These are the changes to the response from a call to
callInitiatoris a new property. The description is: "Indicates whether RP or user initiated a phone/auth, if phone authentication.".
Collect > Response > CompletionData
These are the changes to the
completionData object of a call to
notBefore(a subproperty of
cert) is removed.
notAfter(a subproperty of
cert) is removed.
hintCodehas a new possible value called
userMrtdwith the description "Order is pending. A client has launched and received the order but additional steps for providing MRTD information are required to proceed with the order. The RP should inform the user using message RFA23.".
uhiis a new subproperty of
device. It is a "Unique hardware identifier" for the device where the user identified / signed.
bankIdIssueDateis new property with the description: "The date the BankID was issued to the user. The issue date of the ID expressed using ISO 8601 date format YYYY-MM-DD with a UTC time zone offset".
stepUpis a new object.
mrtdis a new property of the object
stepUp. The description is: "true if the mrtd check was performed and passed, false if the mrtd check was performed and failed".
Phone is a new concept introduced in API V6.0. It allows to initiate an authentication order when the user is talking to the RP over the phone. See section 10.2 in the Relying Party Guidelines V6.0 for documentation.
Recommended user messages
Here is a list summarizing what texts have changed in Swedish / English.
- RFA2 - Swedish and English Updated
- RFA3 - English Updated
- RFA5 - Swedish and English Updated
- RFA6 - Swedish and English Updated
- RFA8 - Swedish and English Updated
- RFA14(A) - Removed (As we understand it, RFA14 is never used anymore as
- RFA14(B) - Removed (As we understand it, RFA14 is never used anymore as
- RFA15(A) - Swedish and English Updated
- RFA15(B) - Swedish and English Updated
- RFA16 - Swedish and English Updated
- RFA17(A) - Swedish and English Updated
- RFA17(B) - Swedish and English Updated
- RFA20 - Swedish and English Updated
- RFA23 - New
BankID have introduced a set of new features to even further strengthen the security of their platform. Most of these should be minor changes if you were using the latest version of BankID API and had implemented Secure start.
If you are using Active Login Authentication for your BankID-integration, make sure to update to the latest version to get support for the latest version of the BankID API.