BankID

The BankID consentor provides the ability for the users to sign the consent attributes using the Swedish BankID. It is possible to configure the consentor to use a test or a production version of BankID.

Integrating with BankID

The consentor has to integrate with the BankID in order for the user to use it and sign the consent attributes. Curity Identity Server uses the BankID API to integrate directly and for that reason a client certificate is needed. The certificate can be obtained from any authorized bank or reseller when the consentor is used in production. For testing purposes, you may use a test key available from BankID.

../../_images/bankid_consentor.png

Fig. 157 BankID integration overview

QR Code

As mentioned above, if the BankID application is not installed on the current device, the user can scan the code using their BankID application on the device where it is installed, and carry on the signing from there, without entering personal number to the Curity Identity Server.

Asking user for personal number

By configuring personal-number-attribute-path, the consentor can tie the QR code to a specific personal number. The attribute path corresponds to an attribute path inside the subject attributes from authentication, so configuring subject would give you the authenticated subject. Configuring attributes.personalNumber would expect the subject attributes to contain an object attributes, with an entry of personalNumber.

The consentor will throw an exception if it can’t find a personal number, or if it finds an invalid personal number. If using a username authenticator to prompt the user for a personal number, it is recommended to add a request validation procedure to make sure the personal number is valid before passing on to the consentor.

A typical configuration would be:

  • Username authenticator
  • Request validation, enforcing the format to be YYYMMDDXXXX
  • personal-number-attribute-path configured to subject

Signing cancellation

There is an option to cancel the signing of the consent data. That is feasible either via clicking on the cancellation button or cancel via the BankID application. That option will cancel signing and return an error message to the client indicating that the user cancelled the signing process.

Configuration settings

The configuration for the BankID consentor is described in the section Profile configuration. This section describes the configuration parameters that are available for the BankID consentor.

Important

Consentor base is /profiles/profile{id type}/settings/authorization-server/consentors

List Entry: <consentor_base>/consentor/ (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, this command can be executed:

$ openssl s_client -showcerts -connect appapi2.bankid.com:443 </dev/null

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

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

type enumeration

default production

The BankID consentor uses the token-issuer and text-to-display parameters which are described in Consentors section. The former is used to generate the JWT containing the consent attributes and the text-to-display. The latter is a human readable representation of the content that user is about to sign.

Being more specific, the request to the BankID will contain the JWT as the userNonVisibleData, thus it will not be rendered in the BankID application. That request field is the actual value that will get signed and returned from the BankID application. The text-to-display is the content that will be shown on the BankID application while the user is signing. Thus, the request sent to BankID servers will contain the text-to-display as the userVisibleData.

use-markdown-format: BankID API also supports the Markdown format for presenting the text-to-display content within the BankID application. The format instructions could be find from BankID Developer Guides section Formatting.

Listing 143 Example configuration.
<consentor>
    <id>bankidConsentor</id>
    <description>consentor1</description>
    <signing-consentor>
        <token-issuer>ConsentorTokenIssuer</token-issuer>
        <text-to-display-procedure>ZnVuY3Rpb24gcmVzdWx0KGNvbnRleHQpIHsKICByZXR1cm4gInRleHQtdG8tZGlzcGxheSI7Cn0=</text-to-display-procedure>
        <bankid-signing-consentor xmlns="https://curity.se/ns/ext-conf/bankid-signing-consentor">
            <mode>test</mode>
            <http-client>
                <id>bankid-client</id>
            </http-client>
        </bankid-signing-consentor>
    </signing-consentor>
</consentor>

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 Consentor Response

The outcome of the BankID signing consentor is persisted in the form of Attributes (as described in the SDK documentation). The response is persisted along with the delegation and contains several fields returned from BankID.

These Attributes consist of:

  • OCSP - Online Certificate Status Protocol (OCSP).
  • Name - the signing person’s name.
  • User - the signing person’s details.
    • personalNumber - the Swedish personal number of the person signing.
    • name - the signing person’s full name.
    • givenName - the signing person’s first name.
    • surname - the signing person’s surname.
  • device - details about the signing device.
    • ipAddress - the IP address of the signing device.
  • Personal Number - the Swedish personal number of the person signing.
  • Signature - XML signature of the JWT previously referred also as userNonVisibleData.

For more information on the values returned from BankID, please consult the corresponding documentation BankID developer guide.

Testing the Integration and Configuration

To test the integration with BankID using the test service provided by BankID, the mode configuration setting must be set 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, an HTTP client that refers to one that uses client authentication should be configured. 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

A test BankID and a production BankID cannot be used on the same device. If a test BankID is installed on a device, the regular one that is used for personal reasons will be cleared. Therefore, it is recommended that testing occurs on 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.

    The appender described above is also valid and can be created for the authenticators running on the the Curity Identity Server. That said, if an appender has already been created for an authenticator, that can be reused for the consentor as well. In that case, a new AsyncLogger can be created using the same appender as any already existing authenticator.

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

    <AsyncLogger name="io.curity.identityserver.plugin.bankid.BankidSigningConsentor" 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 BankidSigningConsentor logger are not also handled by any other loggers. The level must be TRACE or the BankID Web 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 the impact of the change should be verified before deploying it.