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:

../../_images/bankid_arch.png

Fig. 58 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.

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.

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 configured client that configures the client SSL certificate that should be used

type http-client-ref

mandatory

It is important that this client trust 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

See below for information about how to configure this certificate to be trusted.

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

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

type enumeration

default production

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>

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.

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="se.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.