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:

1. Animated QR code for BankID on the another device.

2. Autostart for BankID on the same device.

3. 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.

Changes

Below we will describe the changes.

Auth/Sign > Request

These are the changes to the request of a call to /auth or /sign.

• Removed: personalNumber is removed. Use Secure Start instead.

Auth/Sign > Request > Requirements

These are the changes to the requirements object of the response from a call to /auth or /sign.

• Removed: For certificatePolicies one of the valid values is removed. Specifically the one related to Nordea ("1.2.752.71.1.3" - Nordea e-id on file and on smart card) is removed.

• Removed: autoStartTokenRequired is removed.

• Removed: tokenStartRequired is removed.

• Removed: issuerCn is removed.

• Removed: allowFingerprint is removed. You can accomplish the same functionality using pinCode , see documentation below.

• Added: pinCode is 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 false.

• Added: personalNumber is 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.

• Changed: mrtdRequired is 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 /collect.

• Added: callInitiator is 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 /collect.

• Removed: cert is removed.

• Removed: notBefore (a subproperty of cert) is removed.

• Removed: notAfter (a subproperty of cert) is removed.

• Changed: hintCode has a new possible value called userMrtd with 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.".

• Added: uhi is a new subproperty of device. It is a "Unique hardware identifier" for the device where the user identified / signed.

• Added: bankIdIssueDate is 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".

• Added: stepUp is a new object.

• Added: mrtd is 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

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 tokenStartRequired is removed)

• RFA14(B) - Removed (As we understand it, RFA14 is never used anymore as tokenStartRequired is removed)

• 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

Summary

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.