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.
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:
Fig. 43 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.
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:
allowed-bankid-types
bankid-on-file
bankid-on-smartcard
mobile-bankid
nordea-e-id-on-file-and-on-smartcard
any
By default, any kind of BankID is 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:
type-of-card-reader
with-keypad
Warning
If this option is set, and an allowed BankID type is configured other than the ones listed above, this option will be unset.
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.
bankid-issuer-cn
nordea-ca-for-smartcard-users
nordea-ca-for-softcert-users
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.
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.
If other device is selected the user will have to enter a personal number, and then manually start the app where it’s installed.
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.
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.
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)
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:
SSL Server Trustore
$ openssl s_client -showcerts -connect appapi2.bankid.com:443 </dev/null
type boolean
default: false
false
test
production
type enumeration
default production
default version-5
version-5
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.
<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.
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.
generate-autostart-qr-code
subject
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.
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.
This authenticator is a standalone authenticator, and does not require you to pair it with a regular authenticator.
user
rp
user``or ``rp
default user
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.
mode
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.
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.
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:
$IDSVR_HOME/etc/log4j2.xml
Add a new appender to the <Appenders> section, like this:
<Appenders>
<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="<message time="%date{yyyy-MM-dd'T'HH:mm:ss:SSSZ}">%msg</message>%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.
<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="<message time="%date{yyyy-MM-dd'T'HH:mm:ss:SSSZ}">%msg</message>%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.
$IDSVR_HOME/var/log
bankid.log
RegexFilter
COMPLETE
In the Loggers section of the same file, add a new logger like this:
Loggers
<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.
<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.
additivity
BankIdClient
TRACE
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.
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).
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.
Add a template problematic-browser.js.vm in overrides/authenticator/bankid/launch/browsers
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”)
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.
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)
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.