BankID

The BankID authenticator provides the ability for users to be authenticated using Swedish BankID. It allows for the use of a test and production versions of BankID. It can be configured to allow any type of BankID, including not only Mobile BankID but other forms as well. Restrictions can also be placed on the issuer of the BankID, to ensure that users authenticate using a credential from only certain banks.

Integrating with BankID

There are various ways of integrating BankID with an application. Some use SAML-based federation which is provided by a third-party, but the Curity Identity Server uses the BankID API to integrate directly. This is advantageous because no middleman is necessary to begin authenticating users with a BankID. All that is needed is a client certificate which can be obtained from any authorized bank or reseller; for testing purposes, even this is not needed. The overall integration is depicted in the following figure:

BankID integration overview

Fig. 47 BankID integration overview

To call the BankID API like this, a client certificate must be obtained from BankID and configured separately. For testing purposes, you may use a test key available from BankID. See below for more information on testing the integration.

Kinds of BankIDs

There are various kinds of BankIDs, including Mobile BankID that works on various devices, BankID on file, and BankID on smartcards. The authenticator works with all of these. It also allows an administrator to restrict the kind of BankID that an end user is able to authenticate with. This is done by configuring the list of allowed BankID types (allowed-bankid-types). This enumeration allows the following options to be set:

  • BankID on file (bankid-on-file)
  • BankID on smartcards (bankid-on-smartcard)
  • Mobile BankID (mobile-bankid)
  • Nordea E-ID on file or smartcard (nordea-e-id-on-file-and-on-smartcard)
  • Any (any)

By default, any kind of BankID is allowed.

Type of Card Reader Allowed

When the kind of allowed BankID includes any, nordea-e-id-on-file-and-on-smartcard, or bankid-on-smartcard, it is possible to restrict the type of smartcard reader to be one that has a keypad. This can be done by setting the type-of-card-reader configuration option to one of the following values:

  • Any (any) which is what the BankID documentation refers to as a “class 1” card reader
  • One with a keypad (with-keypad) which is what the BankID documentation refers to as a “class 2” card reader

Warning

If this option is set, and an allowed BankID type is configured other than the ones listed above, this option will be unset.

Trusted BankID Provider

There are various banks that provide BankIDs to their customers. If you want to allow users to authenticate with a BankID from any bank, nothing extra needs to be configured; however, if you would like to restrict which bank you will accept authentication from, you need to configure the CN of the bank’s Certificate Authority (CA) that is used to sign BankID client certificates. You can do this by setting the CN in the bankid-issuer-cn setting. If you wish to trust Nordea’s CA for smartcard or soft certificates, there are predefined values that can be used, namely nordea-ca-for-smartcard-users and nordea-ca-for-softcert-users respectively. Refer to your provider’s documentation for the exact CN of their CA.

Authentication flows

In BankID, there are three types of user flows available. The default is to allow the users to select where their app is installed, on the current device, or on another device.

Same device

If current device is selected, the Curity Identity Server will try to launch the BankID app automatically on the same device. The user authenticates in the app, and will be authenticated without entering their personal number to the Curity Identity Server.

Note

Some browsers have limitations on the handling of external protocols, which may prevent automatically launching the BankID app. This is true for Chrome and Firefox on Android, but it may also be true for other platforms In any case, users are presented with an option to manually launch the app.

Other device

If other device is selected the user will have to enter a personal number, and then manually start the app where it’s installed.

QR code

The QR code is similar to the Same device flow. If enabled, the user won’t have to select which flow to use, and instead the Curity Identity Server tries to launch the app on the same device. At the same time, a QR code is shown. So if the BankID app is not installed on the current device, the user can scan the code using their BankID app on the where it is installed, and carry on the authentication from there without entering personal number to the Curity Identity Server.

Binding message or User Message

When a BankID authenticator has configured a user message or when the request includes a binding message, then the BankID authenticator will include this in the BankID authentication request. A binding message in the (signed or pushed) request will take precedence over a configured user message.

Configuration settings

The general authenticator configuration is described under Authenticator Base Configuration. This section describes the additional parameters that are available for the BankID authenticator.

Important

Authenticator base is /profiles/profile{id type}/settings/authentication-service/authenticators/

List Entry: <authenticator_base>/authenticator/ (key id)

http-client: A reference to the HTTP client that presents the client SSL certificate in calls to the BankID API.

type http-client-ref

mandatory

It is important that this client trusts the CA used to sign BankID’s SSL certificate. This can be obtained using the SSL Server Trustore dialog, or if the admin UI is not available, openssl can be used. To obtain the CA certificate of BankID’s production SSL certificate, you can run this command:

$ openssl s_client -showcerts -connect appapi2.bankid.com:443 </dev/null
allowed-bankid-types: The allowed forms of BankID that may be used to authenticate
type string[]
bankid-issuer-cn: The Common Name (CN) of the certificate used by the BankID provider
type union of string and enumeration
type-of-card-reader: The type of smartcard reader that must be used when authenticating with a form of BankID that supports smartcards
type enumeration
generate-autostart-qr-code: Enable the QR code flow

type boolean

default: false

add-extended-bankid-attributes: Add extended information to the context attributes. When enabling this option, the BankID response signature will be parsed, to add issuer and device information into the context attributes. This will make the SSO session quite large, storing the SSO session in database is advised.

type boolean

default: false

mode: The method by which to connect to the BankID – either test or production

type enumeration

default production

api-version: The version of the BankID API to use.

type enumeration

default version-5

enforce-ip-address-match-on-same-device: Enforce that the IP address reported by BankID must match the IP address used by the client interacting with the Curity Identity Server. If enabled, then authentication will fail if these addresses are different.

type boolean

default false

Example:

<authenticator>
    <id>bankid1</id>
    <bankid xmlns="https://curity.se/ns/conf/authenticators/bankid">
        <http-client>test-bankid-client</http-client>
        <allowed-bankid-types>bankid-on-smartcard</allowed-bankid-types>
        <mode>test</mode>
    </bankid>
</authenticator>

A bankid authenticator can also be used as a back-channel authenticator.

Example:

<authenticators>
  <backchannel-authenticator>
    <id>bankid-backchannel-test-authenticator</id>
    <bankid-backchannel xmlns="https://curity.se/ns/ext-conf/bankid-backchannel">
      <frontchannel-authenticator>bankid1</frontchannel-authenticator>
    </bankid-backchannel>
  </backchannel-authenticator>
</authenticators>

After configuring the Curity Identity Server for production mode, it can be used with any production BankID. For test, a test BankID credential needs to be setup on a device. How to do this is described below.

BankID Version 6 API

Configuring the use of version 6 of the API removes some settings from the configuration model. generate-autostart-qr-code and bankid-issuer-cn are obsolete on this version. Version 6 of the BankID API makes “Secure Start” mandatory, which means that it is no longer possible to start a BankID transaction by entering a personal number. Instead the available options are to start on the same device, or scan a QR code to start the authentication on a different device. Chaining the BankID authenticator with an authenticator that collects the personal number is still possible. When there is a valid personal number in the subject field from a previous authenticator when starting the BankID transaction, no other person will be able to authenticate that transaction.

Upgrading to version 6 API

Enabling the version 6 API will remove the page to select between “same device” or “other device”. Instead the user will be presented with a QR code to authenticate using another device or the option to launch on same device. If already using the QR code, the functionality will be the same. No action needed, other than enabling version 6 in the configuration.

Risk Assessment

Using the version 6 API enables the possibility to configure the risk assessment feature. Setting risk-assessment/send-device-data to true will cause the Curity Identity Server to send the web or the app field in the BankID authentication and sign requests. Configuring risk-assessment/accepted-risk-level will cause the BankID to block transactions whose associated risk is higher than the configured one.

Regardless of the risk-assessment settings, the returnRisk parameter is always sent when using the version 6 API. This makes the BankID service return the risk parameter, which is then inserted into the authentication attributes.

IP address check on same device

When an authentication flow uses an autostart token, it is possible to add an extra check, verifying that the client IP address reported by BankID is the same as the IP address of the client interacting with the Curity Identity Server. This ensures that the autostart token was indeed used in the same device and increases the security of the authentication process. However, this verification is prone to false negatives, where the IP addresses do not match, even when the end-user is using the same device. Causes for this mismatch can be:

  • Misconfigured reverse-proxy not properly forwarding client IP address information.
  • Different networks being used by the user’s browser and by the user’s BankID application in the same device (e.g. when using VPNs).

Due to this, this additional check is not enabled by default and needs to be explicitly enabled via the enforce-ip-address-match-on-same-device configuration setting. When disabled, IP address mismatches on same-device flows do not fail the authentication, however the additional bankid_address_mismatch_on_auto_start_token is added to the resulting authentication context attributes. This information can be used downstream to make access control decisions.

When the authentication fails due to an IP address mismatch the Curity Identity Server uses the BankID failed/index.vm common template and the specific BankID service.error.ip-address-mismatch error message (present in service.properties). Customizing this template or error message can provide additional information for users experiencing this failure due to false negatives presented before.

BankID on the Phone

BankID version 6 has functionality for authenticating users you are in a phone call with. Using this functionality allows you to start an authentication transaction with a personal number, which the user can fulfill using their BankID app. In the app, the authentication screen will be enriched with information that they are supposed to be in a call with the operator, as well as a way to report if the authentication started without them actually being in a call with an operator. In Curity this is implemented using a Back-channel Authenticators, to be used with OpenID Connect CIBA Flow.

Backchannel Authenticator Configuration Options

This authenticator is a standalone authenticator, and does not require you to pair it with a regular authenticator.

http-client: A reference to the HTTP client that presents the client SSL certificate in calls to the BankID API.

type http-client-ref

mandatory

It is important that this client trusts the CA used to sign BankID’s SSL certificate. This can be obtained using the SSL Server Trustore dialog, or if the admin UI is not available, openssl can be used. To obtain the CA certificate of BankID’s production SSL certificate, you can run this command:

$ openssl s_client -showcerts -connect appapi2.bankid.com:443 </dev/null
allowed-bankid-types: The allowed forms of BankID that may be used to authenticate
type string[]
type-of-card-reader: The type of smartcard reader that must be used when authenticating with a form of BankID that supports smartcards
type enumeration
add-extended-bankid-attributes: Add extended information to the context attributes. When enabling this option, the BankID response signature will be parsed, to add issuer and device information into the context attributes. This will make the SSO session quite large, storing the SSO session in database is advised.

type boolean

default: false

mode: The method by which to connect to the BankID – either test or production

type enumeration

default production

call-initiator: The entity who initiated the call that now needs to be authenticated. This will impact what the user sees while authenticating using the BankID app. When it is configured to user, the user will get a question asking “Did you call Demobank AB”. If its configured to rp, the question will instead be “Did Demobank AB call you?”. – either user``or ``rp.

type enumeration

default user

user-message: A message to show in the BankID App for the user while authenticating. This allows the use of simple markdown, supported syntax is available in the BankID guidelines. The value of the user-message can also be a message key that is localized by Curity.
type string

BankID Backchannel Authenticator

BankID authenticator supports Back-channel Authentication out of the box. BankID Backchannel authenticator enables secure start by returning the following additional parameters in the authentication request response :

autostarttoken: Relying party can use the autostarttoken to launch the BankID app on the same device.

qr_image: Relying party can utilize the data URI to display a QR code, enabling users to authenticate via BankID on a separate device.

To enhance security, the relying party can periodically query the token endpoint for updated QR images. This leverages BankID’s animated QR feature, mitigating scam attempts by thwarting the use of static QR codes.

Configuration

BankID Backchannel Authenticator supports following configuration options:

Front-channel Authenticator: Allows the backchannel authenticator to fetch config from the linked front-channel BankID Authenticator.

Sign Binding Message: This is only applicable when the front-channel BankID authenticator is using version-6 API and cannot be turned off for version-5. When turned on, ensures that the binding message is signed using the BankID sign api. When using version-6 this can be turned off to instead use the authentication API, i.e. “My Intent”

type boolean

default: true

Testing the Integration and Configuration

To test the integration with BankID using the test service provided by BankID, you must set the mode configuration setting to test. Otherwise, the Curity Identity Server will attempt to contact the production BankID servers. It will not be able to authenticate to this service using a test certificate, and authentication will fail. With the mode set correctly, you should be able to configure an HTTP client that refers to one that uses client authentication. If this key is the test certificate provided by BankID, integration should work as expected and user authentication should succeed.

For more information about testing BankID, refer to the BankID developer portal. That web site has information about obtaining a test BankID, installing BankID on Android, iOS, and other details.

Warning

You cannot use a test BankID and a production BankID on the same device. If you install a test BankID on a device, your regular one that you use for personal reasons will be cleared. Therefore, it is recommended that you test with a separate device.

Persisting the BankID Responses

If required, it is possible to configure Curity to save the BankID responses. This can be helpful for audit or regulatory purposes. If this is needed, make the following changes to the $IDSVR_HOME/etc/log4j2.xml file which controls how logging is performed:

  1. Add a new appender to the <Appenders> section, like this:

    <RollingFile name="bankid-log" fileName="${env:IDSVR_HOME}/var/log/bankid.log"
             filePattern="${env:IDSVR_HOME}/var/log/bankid.log.%i.gz">
    <RegexFilter regex=".*COMPLETE.*" onMatch="ACCEPT" onMismatch="DENY"/>
    <Policies>
        <SizeBasedTriggeringPolicy size="1GB"/>
    </Policies>

    <PatternLayout pattern="&lt;message time=&quot;%date{yyyy-MM-dd'T'HH:mm:ss:SSSZ}&quot;&gt;%msg&lt;/message&gt;%n"/>
</RollingFile>

    This will cause a new file to be created in the $IDSVR_HOME/var/log directory named bankid.log. This will be rolled after the file grows beyond one GB. If preferred, a different kind of Log4j appender can be used instead. By using the RegexFilter, the only BankID-related messages that will be logged are those that contain the word COMPLETE. These are the final responses from BankID after a user successfully logs in.

  2. In the Loggers section of the same file, add a new logger like this:

    <AsyncLogger name="io.curity.identityserver.plugin.authenticators.bankid.client.BankIdClient" additivity="false" level="TRACE">
    <AppenderRef ref="bankid-log"/>
</AsyncLogger>

    The key here is the name of the logger. Be aware that the name of the logger is subject to change, and should be verified to continue working in future versions. The additivity attribute value ensures that the messages from the BankIdClient logger are not also handled by any other loggers. The level must be TRACE or the BankID service messages will not be logged.

Important

This will cause sensitive, personally identifiable information (e.g., personal number, IP address, name, etc.) to be logged. Also, this additional logging could negatively impact performance; the use of an asynchronous logger will help mitigate this, but you should verify the impact of the change before deploying it.

Launch behavior

Since 8.7, there is a new behavior in the authenticator templates to better handle polling and the browser differences. This new behaviour has to be enabled by setting a parameter in the settings.vm template. In addition, the new behavior is only present when BankID v6 API is enabled. To enable, override the settings.vm, and add #set($bankidLaunchVersion2 = true).

Change specific browser behavior

The new templates will load known browser behaviors dynamically from templates. To be able to change the behavior of a problematic browser, follow these steps.

  1. Add a template problematic-browser.js.vm in overrides/authenticator/bankid/launch/browsers

  2. Add the following contents. (see authenticator/bankid/browser-strategy.js.vm for available parameters)

    browsers.push(new BrowserStrategy({
    browserName: 'default-android',
    platform: PLATFORM_ANDROID,
    neverAutoLaunch: true,
    detectCurrentBrowser: () => /android/i.test(navigator.userAgent)
}));

3. Add your new browser strategy by overriding the authenticator/bankid/browsers/available-browser-detections.vm template and adding this directive: #parse(“authenticator/bankid/launch/browsers/problematic-browser.js”)

Note

The list of browsers in available-browser-detections.vm will be processed top down, and the first instance with a detectCurrentBrowser function that returns true will be deemed the current browser.

Disable autostart

With the new launch behavior it is possible to disable autostart of the BankID app for all devices. Enabling this will allow the user to manually start the app by clicking a launch button, or scan the QR code. To enable, update the settings.vm template to have this: #set($bankidNeverAutoStart = true)

Debugging the templates

An additional parameter is available in the settings.vm to enable client side debug logs. This is a product wide setting, and will enable debug logs for the templates that use it. For BankID authenticator, using the new launch behavior will use the logging. To enable, set $enableClientSideDebugLog in the settings.vm.