Integrating with BankID v6

BankID's version 6 web service API was released in May 2023 and supports a number of security improvements. Starting in version 8.5 of the Curity Identity Server, the v6 behavior is supported in BankID front-channel and back-channel authenticators. Version 8.6 of the Curity Identity Server adds some finishing touches. This tutorial describes the updated security behavior, and how to get integrated.

BankID Logins

Applications that integrate with BankID can enable users to login with BankID installed on the same device, such as the BankID desktop app. Alternatively, users can login on a different device, using the BankID mobile app and selecting the Scan QR Code option. To see how this works, run the BankID online login test, which presents the following options:

If required, first follow the instructions to install the BankID app on your mobile or desktop device, and to point it to the BankID test environment. Also create a BankID test account, to receive a personal code, personal number and security code. You will then be able to sign in with this account.

Secure Start Changes

In the v6 APIs, all applications that integrate with BankID must implement the Secure Start behaviors. These are briefly summarized in this section, and you can read more about the details in the frequently asked questions.

Firstly, the application must use an auto-start token for same device logins, which binds the application instance to a BankID session. Secondly, when logging in to BankID from another device, a more secure animated QR code, which is more difficult to fake than a static image, is presented to the BankID mobile app. Finally, BankID no longer allows flows that ask the user to enter a personal number, to prevent potential exploits if a malicious app runs such a flow.

The BankID Front-channel Authenticator

BankID can be used during an OpenID Connect code flow, as an authentication method. To configure BankID authentication, run the Admin UI and navigate to Profiles → Authentication Service → Authenticators →. Then add a BankID authenticator, selecting the version-6 API, so that the new security behaviors are activated. Read more about the configuration settings in the Authentication Service Admin Guide.

The BankID Back-channel Authenticator

Using a Client Initiated Backchannel Authentication (CIBA) flow requires a license with the financial-grade package. A common use case is when a customer service operative runs an app that needs to ask a user to authenticate remotely, e.g., as part of a phone call. Configure a back-channel authenticator with BankID to enable users to authenticate remotely using BankID.

The CIBA tutorial explains how to run a CIBA flow. To set up authentication for a CIBA flow that uses the BankID v6 API, run the Admin UI and navigate to Profiles → Authentication Service → Authenticators → Back-channel Authenticators. When using the v6 API, select the bankid-phone authenticator:

The customer service application can trigger remote authentication. To enable this, add the Back-channel Authentication capability to the corresponding OAuth client, then select the authenticator as shown here. The back-channel authenticator interacts directly with the BankID v6 API, so there is no need to configure a BankID front-channel authenticator.

My Intention

BankID has added a new My intention behavior during user authentication. This provides explanatory text that a company can provide to its customers. From version 8.6 of the Curity Identity Server, a static value can be entered in the User Message field of the BankID front-channel authenticator. Alternatively, a runtime value can be provided in authentication flows that support a binding_message parameter, such as a CIBA flow.

BankID Technical Setup

The connection from the Curity Identity Server to BankID APIs uses mutual TLS. The BankID integration guide provides resources needed to get connected.

For test environments, follow the guide to download the client certificate and key, in a file such as FPTestcert4_20230629.p12. In the Admin UI, import this as an asymmetric key under Facilities → Keys and Cryptography → TLS → Client SSL Keys, and enter the certificate passphrase. Next, copy the issuer of server certificate text and import it under Facilities → Keys and Cryptography → Trust Anchors → Server Trust Stores.

Next, create a new entry under Facilities → HTTP Clients, and configure it to use the client keystore. Also select the Use Truststore option so that the issuer of the test client certificate is trusted by the Curity Identity Server.

Overriding Browser Launch Settings

Starting in version 8.7 of the Curity Identity Server, you can take closer control over the launch behavior of BankID, if you run into reliability problems launching BankID on particular platforms. This is managed by using the template system to activate newer BankID templates. See Launch Behavior in the Admin Guide for further details.

Testing BankID Logins

Once the setup is complete, integrate BankID authentication into either a web or mobile client by simply running a code flow. By default, the code flow opens the system browser, which can feel unnatural in a mobile client. The App2App Logins using BankID and the Hypermedia Authentication API tutorial shows how to integrate BankID authentication using a purely native flow, without the system browser.

BankID Signing Consentor

The Curity Identity Server provides a BankID Consentor, which can be used to digitally sign the attributes of an OAuth user consent. From version 8.6 of the Curity Identity Server, the BankID Consentor uses the BankID v6 Signng API. Use of consentors enables custom solutions to be built, as demonstrated in the following video.

Conclusion

BankID provides secure, user-friendly authentication. Users should not need to enter their personal number, with risks of fraudulent authentication. Instead, the user is prompted with an animated QR code or the option to start the BankID app on the same device. Applications that have been using BankID for authentication for same and cross device flows can easily upgrade by enabling version 6 for their BankID authenticator, to enforce secure authentication. For customers who use BankID in phone calls there is the bankid-phone back-channel authenticator, which provides a BankID native and secure implementation for remote authentication.