Implementing BankID Web-client in a merchant application


This section discusses the context and the environment in which the BankID components are to be used.

Implementation overview

When implementing BankID in a merchant application the developer needs to integrate her merchant application, the BankID Web-client interface and the BankID Server interface. The figure below illustrates how the merchant BankID implementation units relate to each other.

The code needed for this integration is illustrated as the BankID integration implementation in the figure below and is described in subsequent chapters in this document. 

Implementation document overview

Figure 3 – BankID Web-client implementation documents overview 

The use of BankID can be broken down into different steps. The next chapter illustrates the different steps/tasks the merchant application needs to perform.

Banklagret BankID using BankID Web-client

Overview of BankID Web-client

The BankID Web-client is a single-page AJAX web application. It consists of both HTML/CSS and JavaScript. In order to execute correctly the Web-client is dependent on a set of web features, including CORS and XDM. For a detailed overview the reader is referenced to [BIOA]
The Web-client is designed to support initialization by three different modes:

  • iframe – injected into the DOM-tree of the current Merchant document.
  • window – creates a separate window for the client.
  • redirect – takes over the current browsing context by redirecting to a landing page with the Web-client. When the session is completed, whether with success or error, the browsing context is redirected back to the merchant via nextURL.


The initialization mode is defined by the parameter frameMode during the initialization of the Helper, see 3.2.6.


Note that BankID 2.1 supports all three frameModes. 
Note further that BankID 2.1 also supports all three docDisplayModes as described in detail in Table 11 – BankID Web-client parameters and values.


The Web-client is however also designed to also work with WebViews in native apps. Note that when using WebView the merchant should allow for persistent storage by the BankID Web-client (cookies) used for fraud detection purposes. If implementing BankID Web-client in WebViews in native apps, the merchant also needs to ensure that:

  • PDF Documents To Be Signed are displayed properly
  • control is returned to the native application upon termination, if necessary.


For more details, see [IMMC]
Also note that the Web-client includes an option to activate the HTML5 geolocation-API for fraud detection purposes. In order for this to work properly any native apps should specifically enable support in the WebView. For more details regarding the use of WebViews see [IMMC].

Configuration and initialization of BankID Server

Figure 4 is a list of the tasks with a reference to the applicable chapters that describe how to do the actual implementation of BankID Server. 

Overview of main activities for configuration an initialisation
Figure 4 – Overview of main activities for configuration and initialization 
 Step 1: Configure the BankID Server
Please refer to:

  • this document, BankID Server Features.
  • [ICSRV], 4. Configuration of BankID C server
  • [IJSRV], 3.1 Configuration of BankID J Server


 Step 2: Initialize the BankID Server
Please refer to:

  • [ICSRV], 5.1 Application start-up code
  • [IJSRV], 4.1 Application start-up code 

Configuration of Cross-Origin Resource Sharing (CORS)

CORS1 allows XMLHttpRequest requests across domains, which traditionally wouldn't be allowed under the browser's Same origin policy (SOP)2. CORS works by adding a special header to responses from a server to the client. If a response contains the Access-Control-Allow-Origin header, and if the browser supports CORS3,4, it is possible to access resources from a different domain. In order to achieve this the merchant site must allow CORS access from scripts provided from *https://csfe.bankid.no* by setting the Access-Control-Allow-Origin directive. This is true also for signing with BankID 2.1 due to the fact that the Web-client will send handleError() directly to the merchantURL in case of communication errors towards the Client proxy. See also section 
Client proxy.

See Code example 1 for CORS settings below.

If the merchant makes use of http-cookies for session handling, the directive Access-Control-Allow-Credentials must be set to true. This fact has the implication that Access-Control-Allow-Origin cannot be set to '*'. Any request with Access-Control-Allow-Credentials set to true will then fail at the client. If the merchant does not use cookies, the Access-Control-Allow-Credentials directive can safely be omitted.

See Code example 1 below:

Access-Control-Allow-Origin: https://csfe.bankid.no
Access-Control-Allow-Credentials: true

Code example 1 – Configuration of CORS 

The merchant can make sure that the Web-client sends requests with credentials by specifying this in the initSession() request, see Table 11 for more details.

IE version 9 uses the XDomainRequest object instead of the standard CORS XMLHttpRequest5. When receiving XDomainRequests from IE9, the requests are sent with Content-type: text/plain. This is something the merchant application might need to handle differently from requests that are received as Content-type: application/x-www-form-urlencoded. See Appendix E for more details.

For more information about CORS, we recommend this blog post at html5rocks.

Configuration of any merchant Content Security Policy (CSP)

Note that CSP is optional for the merchants. For merchants already using content security policy1, special requirements apply. If set, CSP could prevent both the loading of the Helper script and the BankID Web-client itself, in addition to the pre check-script (bid-browser-test.js) [BSID]. To allow the merchant document to load both of these components, any CSP must allow for *https://csfe.bankid.no* in all of the script-src, frame-src and style-src directives.

In order to source the Feature- and UA-detection script, merchants that use CSP must allow for *https://services.bankid.no* in the script-src directive.

See Code example 2 below for a recommended CSP-header in order to source the BankID components successfully using CSP:

Content-Security-Policy: 
default-src 'self'; 
script-src 'self' https://csfe.bankid.nohttps://services.bankid.no;
child-src 'self' https://csfe.bankid.no;

Code example 2 – CSP header 
The configuration of script-src has two possible outcomes:

  • If successful the script loads and runs as intended.
  • In case of an error the Helper will not be sourced, and an error message should be available in the browser's console:
    Refused to load the script 'https://<Helper URL>' because it violates the following Content Security Policy directive: "script-src 'self' https://csfe.bankid.no."
    (Note that if 'script-src' is not explicitly set, 'default-src' will be used as a fallback). 

The configuration of child-src also has two possible outcomes:

  • If successful the iframe is initialized and the client download process will continue.
  • In case of an error the iframe appears, but has no content. An error message should be available in the browser's console:
    Refused to frame 'https://<Frame URL>' because it violates the following Content Security Policy directive: "frame-src 'self' https://csfe.bankid.no".

Any form of CSP violation reporting is up to the merchant.

Note that the BankID Web-client has its own CSP policy, which is transparent to the merchant. Details are beyond the scope of this document.

Authentication and Signing

Figure 5 below shows the tasks with a reference to the applicable chapters that describe how to do the actual implementation. 
Overview of main activities for authentication and signing netcentric

Figure 5 – Overview of main activities for authentication and signing 
Steps  and  in Figure 5 are shown in more detail in Figure 6. Below Figure 6 follows a textual explanation of some of the aspects that show the initialization and load process. Look for the numbered items in the diagram.

Steps  ,  and  are shown in more detail in Figure 7.

 Denotes the setting of client features, which is done at three different points in the process: initSession(), bankidhelper.init() and initTransaction(). 

Merchant BankID integration application Flow Chart
Figure 6 – Overview – Merchant BankID integration application – Flow chart
Continues in Figure 7 .  See 3.2.8 Error handling. 

 If the merchant application collects the userID it is advised that the keystroke data for the userID form are collected by using a BehavioWeb JavaScript. A tailored script to collect keyboard biometrics for the SSN1,2 is provided in the release package . See [BIDG] for a code sample. These keystroke data are subsequently sent to the client in the initTransaction() response, see Table 4.

 In order to get the HelperURI, and later the correct BankID Web-client, a set of parameters need to be determined by the Merchant and provided in the initSession() request. See the list of the required parameters in Table 2 – BankID Web-client initSession() parameters below:

Key

Description

Values

merchantURL

This is the URL which the client uses to communicate with the merchant application during authentication and signing. The URL must use SSL.

Any URL that uses SSL.

useragent

The client application connecting the web server, typically a web browser, but it can also be other programs that access web pages.

In this case a text string in a common pattern identifying the browser's make and model, among other things.

action

The action you would like to perform.

Use "auth" for Authentication, "sign" for Signing, "netPay" for BankAxess and "changepassword" for user initiated change of password via merchant.

localeId

The language to use in the client.

"nb" = Norwegian, "en" = English.

sid

The session id the merchant generates and uses to identify the session. Optional.

A unique sid as a string.

merchantFEDomain

Set to be able to verify origin on later messages across via XDM.

Any domain as a valid URL, must use SSL: "https://www.merchant.com". Must be the same domain that hosts the Helper.

Table 2 – BankID Web-client initSession() parameters
The table above only lists the required parameters. Chapter 3.4 gives a broader description of all the parameters from Table 2, and also lists and describes the parameters that are optional for the initSession() from the Merchant's point of view.

Note that BankID Server also will set a number of parameters in the initSession() call which is sent to BankID COI. This is done transparently to the Merchant, see 3.4. After invoking BankID Server, the merchant application will receive the HelperURI, a client id (CID) and a random trace id (TID). The Helper URI is used to retrieve the Helper JavaScript from COI, the CID is used to retrieve the correct BankID Web-client, and the TID must be used when creating the BIDSessionData object in BankID Server. This is described in more detail in the BankID Quick Start Guides [BIDG].

 BankID COI validates the Merchant signature, generates TID and CID, retrieves a reference to a Helper instance and returns them to the Merchant. BankID COI also starts the generation of the JS Client which will subsequently be fetched after the Helper has been initialized inside the browser later on.

 When the Merchant gets the Helper URL it embeds the URL into an appropriate script tag to source the Helper. When the Helper is loaded and the browsing context is initialized and the client.html is fetched, the Bootloader will start loading. See [BIDG] for details.

 The Helper is responsible for creating the browsing context of the BankID Web-client based on the frame mode parameter as described below. The Helper initializer (bankidhelper) provides one public init() method that will be called by the Merchant frontend, and accepts the following parameters:

  • frameMode
  • Client ID (cid) received from BankID Server.
  • ContainerID – a CSS-selector determining where in the DOM-tree the client is to be inserted.
  • Height and Width for the client, see 3.2.9 and 3.2.10.
  • Callback function.
  • sessionCookie.

See 3.2.6 Helper for more details.

The Bootloader script secures the loading of the client. When it starts running it will do the key exchange with COI, and an encrypted and uniquely built client will be fetched from the BankID COI. The Bootloader script will verify the integrity of the package, and decrypt the client. The BankID Web-client will start running at this point. Note that details of the Bootloader is beyond the scope of this document.

The following text provides more detail to what is shown in Figure 7 below.

 The BankID Web-client sends an initTransaction() message with either an initAuth() or initSign() request depending on the operation, to the merchant as shown below.

initAuth request

initSign request

Parameter

Value

Value

Main

Decrypted

Inner

operation

initAuth

initSign

encKey

The base 64 encoded baseKey received from the client to derive the sessionKey

encData

The base 64 encoded encrypted data received from the client

clientChallenge

Client generated challenge.
Used by the client to authenticate the merchant.

carrier

"NC_BID20"

traceId

The traceId from this transaction in COI

encAuth

A base64 encoded message authentication code over the rest of the main parameters

sid

Merchant specific session id

For further details see 3.6.

Table 3 – InitTransaction() request – BankID Web-client
The contents of the three parameter columns are as follows:

  • Main: These are the key-value pairs sent as HTTP parameters in communication with the merchant website. The values should be extracted and used as input in function calls to the BankID Server API
  • Decrypted: Relevant parameters contained in the end-to-end3 encryption packets. These parameters are decrypted by BankID Server from the encKey/encData/encAuth triples, and are made accessible as session values after processing.
  • Inner: Relevant parameters passed through the inner encryption channel(s) between the BankID Server and the BankID COI. Some of these values can be manipulated through configuration and settings, but not accessed directly by the merchant implementation. The list of parameters is non-exhaustive.


The merchant application needs to perform the following actions:

  • Read the request parameters from the request object.
  • Create a session object.
  • If sign operation: Once the data to be signed has been chosen4, it is added to the session object.
  • Call the BankID Server function InitTransaction(), and add the session object.
  • Store the session object received from the function call.
  • Send the response from InitTransaction() to the BankID Web-client.


Table 4 below outlines the InitTransaction responses used for BankID 2.0. See Table 5 for details regarding BankID 2.1.

initAuth response

initSign response

Parameter

Value

Value

Main

Decrypted

Inner

encData

The base 64 encoded encrypted data returned to the client

serverChallenge

BankID Server generated challenge. Used by the merchant to authenticate the client.

data

Data to be signed. Used during signing by both the client and merchant.

pkcs7

Merchant signature over the clientChallenge

Merchant signature over the data to be signed

bssChannel

Data to be forwared to COI.

bssChannelSignature

Merchant signature over the bssChannel

dataDescription

Used to identify the document in the client.

mimeType

The mimeType of the data to be signed.

extPDFURL

URL to the document to be signed. Note: Must be within the same domain as extPDFDomain, see Table 11 for more details.

nextURL

Optional. The URL the client may redirect to after completion. Use of callback function will have precedence over this URL. This parameter will overwrite any previous nextURL. Note: The URL must be HTTPS.

userId

Returned if Merchant has collected userId

userIDKeyStrokeData

If userId is set in response, behaviour metrics should be returned.

ocspFormat Data to be forwarded to the COI. Will allways be default BankID format in initAuthData to be forwarded to the COI. The format is can be chosen by the merchant. Otherwise it will be the default BankID format
cmsFormat Data to be forwarded to the COI. Will allways be default PKCS7 format in initAuthData to be forwarded to the COI. The format is can be chosen by the merchant. Otherwise it will be the default PKCS7 format

encAuth

A base64 encoded message authentication code over the encData parameter.

For further details see 3.6.

Table 4 – InitTransaction() response – BankID Web-client 2.0 

initAuth response

initSign response

Parameter

Value

Value

Main

Decrypted

encData

The base 64 encoded encrypted data returned to the client

serverChallenge

BankID Server generated challenge. Used by the merchant to authenticate the client.

documents

Used during signing by both the client and merchant. A JSON array of JSON objects.

Per document5

data

Data to be signed. May include merchant visual seal.

mimeType

The mimeType of the data to be signed

dataDescription

Used to identify the document in the client.

encoding

coiData

Data to be forwarded to COI.

coiData Content

pkcs7s

List of merchant signatures over the data to be signed

bssChannel

The BankID Server secure Channel. This will contain the list of hashes of PKCS#7. This information will be used in the OTP token.

bssChannelSignature

Merchant signature over the bssChannel

pkcs7

Merchant signature over the clientChallenge

nextURL

Optional. The URL the client may redirect to after completion. Use of callback function will have precedence over this URL. This parameter will overwrite any previous nextURL. Note: The URL must be HTTPS.

userId

Returned if Merchant has collected userID

userIDKeyStrokeData

If userID is set in response, behavior metrics should be returned.

otpService

If userID is set in response

ocspFormatData to be forwarded to the COI. Will allways be default BankID format in initAuthData to be forwarded to the COI. The format is can be chosen by the merchant. Otherwise it will be the default BankID format
cmsFormatData to be forwarded to the COI. Will allways be default PKCS7 format in initAuthData to be forwarded to the COI. The format is can be chosen by the merchant. Otherwise it will be the default PKCS7 format

encAuth

A base64 encoded message authentication code over the encData parameter.

For further details see 3.6.

Table 5 – InitTransaction() response – BankID Web-client 2.1 
The client passes the server's signature to the BankID COI for validation, and then the appropriate dialogues are shown to the end-user.


Continued from Figure 6.  See 3.2.8 Error handling.
Merchant BankID Integration application flow chart pt.2
Figure 7 – Overview – Merchant BankID integration application – Flow chart
 The resulting client signature is returned to the merchant application in a request object along with in case of a signing operation, a merchant certificate status instance (OCSP response).

verifyAuth request

verifySign request

Parameter

Value

Value

Main

Unencrypted

Inner

operation

verifyAuth

verifySign

encKey

The base 64 encoded baseKey received from the client to derive the sessionKey

encData

The base 64 encoded encrypted data received from the client

pkcs7

End-user signature over the serverChallenge

End-user signature over the data to be signed

ocsp

A merchant certificate status instance (OCSP response)

carrier

"NC_BID20"

traceId

The traceId from this transaction in COI

encAuth

A base64 encoded message authentication code over the rest of the main parameters

sid

Merchant specific session id

For further details see 3.6.

Table 6 – VerifyTransactionRequest() – BankID Web-client 2.0

verifyAuth request

verifySign request

Parameter

Value

Value

Main

Unencrypted

Inner

operation

verifyAuth

verifySign

encKey

The base 64 encoded baseKey received from the client to derive the sessionKey

encData

The base 64 encoded encrypted data received from the client

pkcs7

End-user signature over the serverChallenge

ocsp

Last ocsp after CS check of Merchant sign certificate for each merchant pkcs7

clientpkcs7s

Comma separated list of PKCS7s (client signatures).

rtReport

Blob lob of comma separated name=value pairs. Used to send information from client to merchant. See Appendix G

carrier

"NC_BID20"

traceId

The traceId from this transaction in COI

encAuth

A base64 encoded message authentication code over the rest of the main parameters

sid

Merchant specific session id

For further details see 3.6.

Table 7 – VerifyTransactionRequest() – BankID Web-client 2.1
Please note that in BankID 2.1 the verifySign() request will contain the signatures of all documents that were signed. 
The merchant application then needs to:

  • Read the request parameters from the request object.
  • Get the stored session object.
  • Call the BankID Server function verifyTransactionRequest(), adding the stored sessionObject.


 The merchant application then needs to continue with the following actions to authenticate the client:

  • Merchant application specific business logic to update internal state as needed.
  • Merchant application specific business logic updates e.g. associate the end-user with the customer database.


If an SDO is to be created as part of the signing operation, the merchant application needs to

  • Call the BankID Server function Create SDO.
  • Add the SDO to the session object.


Finally the merchant application must:

  • Call the function verifyTransactionResponse(), adding the session object.
  • Update the business logics.
  • Return the data from verifyTransactionResponse() back to the BankID client.


Note that the concept of rtReport is introduced in the verifyTransaction()-request. The rtReport contains information about the current transaction, and is possible to fetch using a new function in BankID Server. See section Raw Transaction report in [BIDG] for BankID Java and C server for the contents of the rtReport.

See Appendix G for a full example of an rtReport.

For signing, one of the elements of the rtReport is the cpReport, which is the unformatted result from the pdf validation tool at the Client proxy. This can be used by Merchants to correct any errors in their pdf documents in order to become compliant with the pdf version(s) which the tool validated against. Merchants may retrieve this version by providing the key pdfValidationVersion in the getRawTransactionInfoItem(..)/getReport(..) request.

The pdf version which is validated against is discussed in section 2.2.4.

verifyAuth response

verifySign response

Parameter

Value

Value

Main

Unencrypted

Inner

encData

The base 64 encoded encrypted data returned to the client

nextURL

Optional. The URL the client may redirect to after completion. Use of callback function will have precedence over this URL. This parameter will overwrite any previous nextURL. Note: The URL must be HTTPS.

SDO

SDO XML object. Enables the end-user to save signed data. See text below the table. NB: Not supported in BankID 2.0/2.1.

vaPerf

The time, in milliseconds, the BankID Server used to retrieve the certificate status from VA.

errCode

If something fails

encAuth

A base64 encoded message authentication code over the encData parameter

For further details see 3.6.

Table 8 – VerifyTransactionResponse() – BankID Web-client 2.0 and 2.1
An option for the end-user to save the SDO, if received, to disk or to a centrally located archive is currently not supported by the Web-client but may be available in future versions. 
For further details regarding authentication, please refer to:

  • [ICSRV], 5.4 Authentication process.
  • [IJSRV], 4.2.1 Authentication process.


For further details regarding signing, please refer to:

  • [ICSRV], 5.5 Signing process without SEID SDO & 5.6 Signing process with SEID SDO
  • [IJSRV], 4.2.2 Signing process without creating of SEID SDO& 4.2.3 Signing process and creation of SEID SDO

1 Located in \Utils\UserProfile\ - see also readme.txt

2 The latest version is always available for download here: http://www.behaviosec.com/downloads/behavioweb-js.zip

3 Note that for signing with a Client proxy it is technically a MITM that decrypts and encrypts the contents between the Web-client and Merchant.

4 This is done without usage of BankID components. The transaction to be signed could be for instance a contract, a purchase order or a form. The format of the data must be PDF, plain text or BankID XML.

5 Note that documents may contain 1 to n document elements. All data to be signed is returned in the initSign() response

Helper initialization

The Helper is responsible for creating the browsing context based on the frameMode parameter. The most common case will be the Helper injecting an iframe into the DOM-tree of the merchant web document.

Table 9 below lists all the parameters that are part of the init() call to the Helper (bankidhelper.init()):

helperParams

Comment

Caption

Used in scenario

Mandatory

frameMode

"iframe" (default), "window"1, "redirect". Governs the browsing context of the client.

Governs the browsing context of the client.

All.

Yes

cid

Received previously in initSession() response, pka kid.

A unique clientID received previously in initSession() response.

All

Yes

callback

Function that Helper will call upon client termination. This is the preferred way of returning control to the Merchant application. See Table 10 for details.

A function that Helper will call upon client termination. If not provided the last received nextURL over a secure channel will be used to return control instead.

All

Optional

containerID

A reference to an element id in DOM where the client will be injected, see [BIDG].

A reference to an element id in DOM where the client will be injected.

If frameMode == "iframe"

Yes

height

Default set to 100%, which is the recommended height.

The height of the iframe provided to the client.

If frameMode == "iframe"

Optional

windowHeight

The desired window height in pixels. Default set to 500.

The height of the window provided to the client.

If frameMode == "window"

Optional

width

Default set to 100%, which is the recommended width.

The width of the iframe provided to the client.

If frameMode == "iframe"

Optional

windowWidth

The desired window width in pixels. Default set to 350.

The width of the window provided to the client.

If frameMode == "window"

Optional

positionX

Integer representing the left position of the window on the screen.

Integer representing the left position of the window on the screen.

If frameMode == "window"

Optional

positionY

Integer representing the top position of the window on the screen.

Integer representing the top position of the window on the screen.

If frameMode == "window"

Optional

errorRedirectUrl

Location to redirect to in case of an initialization error.

Location to redirect to in case of an initialization error if frame mode is "redirect".

If frameMode == "redirect". Note that return using callback function is not supported in this instance.

Yes

sessionCookie

New 2.1 parameter. Specifies whether a session cookie is used. Object must have a name attribute, and optionally a value attribute. Is not used during frameMode redirect, see [BIDG], and text about withCredentials below Table 11. The cookie is sent inside encData from the Web-client to the Client proxy.

Specifies whether a session cookie is used. Object must have a name attribute, and optionally a value attribute.

Signing transactions in 2.1, not applicable for auth or 2.0.

Optional

Table 9 – Helper parameters set by Merchant
For captions in supported languages besides English, see Appendix D.

A very simple code sample on how to source the Helper is found below. For a more extensive one, with complete Helper-initialization for all frameMode scenarios, see [BIDG], which also provides more information on how to implement the Web-client using a single page application with a re-entrant Helper.

<script type="text/javascript" src="<helperURI from initSession()>"></script> 
<--
// Merchant javascript to call init() and define callback() goes here
--> 

Code example 3 – Helper initialization

1 Note that frameMode="window" must be initiated by a user click/tap in order to avoid conflicts with any pop-up blockers.

Client termination

As the Client completes the business logic of the transaction in progress (either with success or no success), the control is returned to the Merchant application, either by a callback-function or by providing the client with a redirect-URL (nextURL). Hence, each of the following return alternatives will be supported:

  • If a callback-function was provided to the Helper in the init() request, this function is used by the Web-client to return the control to the Merchant as it completes. This is the recommended way of returning the control to the Merchant application, and the Client will ignore any redirects to nextURLs that may have been defined.
  • If no callback was provided, and a nextURL is provided during Client execution, the end-user will be redirected to the nextURL upon termination regardless of any fallback URL.
  • If no callback was provided, and no nextURL is provided during Client execution, the end-user will be redirected to any fallback nextURL that is provided.
  • If neither a callback-function nor a nextURL was provided, the Web-client terminates silently as it completes.

It is up to the Merchant to choose which of the return alternatives listed above to be implemented in the Merchant application. The callback function allows for a more fine grained error description and error handling than the nextURL options. Note that if the merchant application is triggered by a native app on iOS, Android or Windows Phone/RT the callback is the only return option to return the result to the native app.

Table 10 below shows the contents of the result objects which are returned from the client through the Helper in the callback function:

Object name

statusParams

Comment

Example value

error

errorId

An error code, see [BEMEC].

2904

error

A textual description of the result.

"Some error text"

detail

Added if available.

[ "Cross Origin Resource Sharing (CORS) is not supported!" ]

status

statusText

A textual description of the result.

"Success"

status

Status code. See below for more details.

1

Table 10 – The result objects of the callback function in BankID 2.1
The Initialiser´s callback function expects an error and a status parameter, and if this return alternative is used, the callback-function will be called with these two objects. The value of the error object contains an error code and an error description of any errors occurring during the startup phase (before the client has been in touch with either merchant or COI), see Code example 4. Otherwise it will be null.

{ 
        errorId: 2904, 
        error: "Your browser does not support BankID",
        detail: [ "Cross Origin Resource Sharing (CORS) is not supported!" ]
}

Code example 4 – Error object in Helper callback function 
The value of the result object will contain a status code and a description (if the error object is null). The status code can be one of the following:

  • -1 = aborted (The user has closed the BankID client without completing the operation)
  • 0 = failure (Some error occurred during the BankID operation)
  • 1 = success (The BankID operation was completed successfully)


Any errors during the BankID operation process (after the Web-client has been initialized) will return with either -1 or 0. For a thorough code sample, see [BIDG]. For how the callback works with BankID 2.0, see previous versions of this document.

Merchants should first check the error object in their callback function and handle any errors accordingly. If no error (error object is null) proceed with the status object.

If an exception is caught during the Helper initialization due to lack of mandatory features or because of timeouts, the result parameter passed to the callback-function will contain a populated error object that includes an error id and an error description, and possibly a detailed description, as described in Table 10. Depending on what type of exception is thrown, the Web-client will inform the end-user accordingly.

Error handling

Errors occurring during client start-up stages

Since the BankID Web-client has new triggering and termination mechanisms compared to the legacy clients, some new possible error scenarios arise. The Helper, the Client and the XDM-interface are all involved in front-end error handling. 
If sourcing of the Helper fails, a CSS used to display an error message is sourced from the COI.

The Helper alone handles any errors during loading and initialization of the client. In case of an error inside the Bootloader a callback function provided at Bootloader initialization will be used to relay the error information to the Helper that in turn will display it to the end-user. Error conditions can be delivered to the merchant via a callback as explained in 3.2.7.

Note that an incorrectly configured CSP by Merchant will prevent the Helper from loading. An incorrect CORS setting will also effectively prevent the XHR communication. The Helper will be able to identify such an CORS-error. Note that when the XDM communication does not work, the Helper will not be able to retrieve the nextURL from the Web-client, thus the callback should be used.

In order to prevent sub optimal user experiences, merchants are encouraged to download and execute the Feature- and UA-detection script hosted on *https://services.bankid.no* as described in detail in [BIDG]. The Helper will also perform the same feature and UA-detection. This process may result in an error being reported over the callback-function. Any blacklist error will cause the client to terminate according to 3.2.7.

Note that the corresponding blacklist check performed in the initSession() step with BankID 2.0 is replaced by the abovementioned UA-detection in the Helper for BankID 2.1.

Errors during normal execution

Should an error occur on the Web-client, it will, like for the other legacy BankID clients, send an encrypted error message to the merchant. The web application should then perform verifyTransactionRequest() on the request to get the errCode and then set the desired nextUrl and errorCode for the BankID client and call the verifyTransactionResponse() method. The result should then be sent to the BankID client. The errorCode, and the control will then be returned to the merchant application through the Helper interface, preferably by using the provided callback function from bankidhelper.init(). If no callback function is defined, the nextURL (if valid) is also returned to the merchant application.

When signing with a Client proxy, the handleError() request and –response go through the Client proxy, unless, as mentioned in section 3.2.3, there is a communication problem with the Client proxy. Then the handleError() will be sent directly from the Web-client to the Merchant. 

Gliffy Macro Error

Cannot find a diagram with these parameters:

  • Name: Error handling in client


Diagrams with the same name were found on the following pages:


Figure 8 – Error handling in client
Note that with BankID 2.1 encData in handleError() is extended with rtReport as described for verifyTransaction() request in Table 7. The request will not contain any signatures even if one or more documents were successfully signed during the process. If an handleError() is returned in the midst of a multi-document signing process, the end-user will have to start the entire process all over again.

In most cases when an error occurs on the server side, it is still possible to send an encrypted response. To send an error message to the client, the web application has to set the errCode and nextUrl, and call the verifyTransactionResponse() method, see [BIDG] for a complete code sample.

If an error occurs that prevents the merchant from calling verifyTransactionRequest() / verifyTransactionResponse(), an unencrypted response may be sent to the client (through the Client proxy in case of signing with BankID 2.1). This response should be on the form "errCode=<errorCode>". 

Gliffy Macro Error

Cannot find a diagram with these parameters:

  • Name: Error handling in the server component


Diagrams with the same name were found on the following pages:

Figure 9 – Error handling in the server component 
It is possible to specify nextUrl in the unencrypted handle error message, but it will be ignored by the BankID Web-client.

Client appearance

The BankID Web-client is based on responsive design and adapts to the space made available for the iframe. For further details see [IMMC].

Size restrictions and recommendations

As mentioned in 3.2.1 the BankID Web-client is designed to work well across a broad range of devices. There are still some recommendations regarding the minimum size of client. For further details, see [IMMC].

In case of document signing, it may be appropriate to consider the docDisplayMode=overlay, depending on the size and nature of the document to be signed. See 3.2.1 for more information.

Features

This chapter describes the features available to the merchant. By using these features the client behavior can be tailored to suit the application in question.

 Client features

Essentially the client features are set at three different stages: initSession(), bankidhelper.init() and initTransaction().

See Table 2 for features set by initSession() and chapter 3.2.6 features set by bankidhelper.init().

The merchant may set the userID in the sessionInfo object before the initTransaction() call. The merchant may also suggest a OTPService to be used. If this service is supported for the userID in BankID COI only this OTP-service will be presented to the user. If userID is provided, any keystroke data should also be sent in the initTransaction() call. See userProfile in [BIDG] for more information. 

Keystroke data of the userID may also be collected from the merchant site using a tailored JavaScript which is provided in the BankID release package. See also [BIDG] for code samples and extended documentation. 

BankID Server features

A merchant application may specify the types of BankIDs that it accepts. A company specific application may only accept Employee certificates and a public government site may only accept Person certificate. This is done using the concept of Policy OIDs. The merchant can achieve this control and filtering by specifying a single or a list of Policy OIDs that are compatible with the application using features in the BankID Server.

Note that the certType parameter is configured in BankID Server.

For further details please refer to:

Associating the end-user with the customer database

Each BankID end-user has a unique identifier in the certificates. This identifier is unique within BankID and uniquely identifies a physical person. Each person may however have more than one unique identifier, depending on whether it is a Personal BankID or Employee BankID.

The unique identifier cannot be transferred once associated to a person. The unique identifier (UniqueID) can be extracted from the end-user certificate using available BankID Server functionality.

Merchants that are authorized to retrieve SSN as additional information from the VA, may do so. Only the SSN or the UniqueID shall be used to identify the end-user.

For further details please refer to:

  • Section B.5 in this document.
  • [ICSRV], 6.1.7 BID_GetInfoItem (for retrieving the uniqueID from certificate)5.9 Retrieving additional information from VA (for retrieving SSN from VA)
  • [IJSRV], 5.2.12 getCertificateInfo (for retrieving the uniqueID from certificate)4.2.5 Retrieve additional information from VA

BankID Web-client parameters and values

Table 11 below lists all parameters that the Merchant may set in the initSession()-call which is initiated by the Merchant. The parameters are sent to BankID COI through BankID Server:

Key

Description

Caption

Values

Value set by

BankID 2.1

action

Tells BankID COI what kind of operation which will be initiated.

The type of BankID operation to be initiated.

"auth" (Default) for Authentication
"sign" for Signing
"netPay" for BankAxess
"changePassword" for changing end-user password (supports camel casing also).

Merchant

Cont'

localeId

Sets the language of the client that will be assembled by BankID COI.

The wanted language of the client.

"nb" = Norwegian (default)
"en" = English

Merchant

Cont'

nextURL

Optional. This is an error fallback URL used by the client if an error occurs and the client cannot obtain the proper nextURL from the merchant, or if the merchant did not provide a callback function. Note: The URL must use SSL.

An error fallback URL used by the client if any error occurs, must use SSL.

Example: "https://www.merchant.no/genericErrorPage"

Merchant

Cont'

merchantURL

This is the URL which the web-client uses to communicate with the merchant application during authentication and signing. The URL must use SSL.

The merchant endpoint of the merchant protocol, must use SSL.

Any https-URL. Note that the BankID client will verify that the hostname of the URL matches the webaddress in the configuration file.

Merchant

Cont'

timeout

Optional. The time, in milliseconds, the web-client will wait for a response from the merchant application. The minimum value is 1 ms.

The time, in milliseconds, the client will wait for a response from the merchant application, optional.

40000 (Default)

Merchant

Cont'

sid

SessionID. This is a parameter that can be set and used by merchant in order to keep track of sessions.

A sessionID set by merchant. Optional.

Any string.

Merchant

Cont'

certType

Optional, the default value comes from merchant config. Lists the BankID certificate types that the application accepts

Lists the BankID certificate types that the application accepts, Optional.

"ALL" or a comma separated list of PolicyOIDs

Merchant through BankID Server configuration

Cont'

showUnderstanding

Optional. During a signing process, the merchant can with this flag control whether the text "Jeg har lest og forstått innholdet" (including the checkbox) will be visible or not.

Determines if the text "Jeg har lest og forstått innholdet" (including the checkbox) will be visible or not. Optional.

"Y" (Default)
"N"

Merchant

Cont'

showConfirmation

Optional. During a signing process where an SDO receipt is received at the client, this flag controls whether a "confirmation of signing complete" message is to be presented.

During a signing process where an SDO receipt is received at the client, this flag controls whether a "confirmation of signing complete" message is to be presented. Optional.

"Y" (Default)
"N"

Merchant

Cont'

suppressBroadcast

Optional. Set if any message from COI to all users will be suppressed. If "N" and there is a broadcast msg from COI, the msg will be incorporated into the client, which will format and display it to the end-user.

Suppress any broadcast message from COI. Optional.

"N" (Default)
"Y"

Merchant

Cont'

extPDFDomain

Optional. Display of PDF by external application. Only mandatory if action = "sign". Is set in the CSP for the client to permit sourcing from extPDFURL.

Display of PDF by external application. Only mandatory if action = "sign".

"https://www.merchant.no/pdfs"

Merchant

2.0 only

docDisplayMode

Optional. Determines how external documents to be signed will be displayed. Only mandatory if action = "sign".

Determines how external documents to be signed will be displayed. Only mandatory if action = "sign".

"interior" (default)
"window"
"overlay"

Merchant

Cont'

merchantFEDomain

The expected domain of the Helper, as seen from the client. Must use HTTPS. Also used in X-Frame-Option1.

The expected domain of the Helper, as seen from the client.

"https://www.merchant.com"

Merchant

Cont'

merchantFEAncestors

Optional. A space separated list of domains. Merchants that use an iframe inside another iframe should set it in order to define the browsing contexts in which the Web-client is allowed to execute. Used to set the correct CSP-directive2.

The chain of domains used in an iframe in iframe-scenario. Optional.

"https://www.domain-1.com

https://www.domain-2.com
https://www.domain-N.com
"

Merchant

New

userAgent

Used to check against userAgent blacklist in COI.

The end user's UA-string.

Merchant

Cont'

withCredentials

Optional. Used to activate CORS-requests with credentials. Tells the Web-client to set Access-Control-Allow-Credentials = true, resulting in any cookies set in the context of the merchant application are forwarded by the client over the merchant protocol.

Sets CORS credentials to true in order to include any Merchant cookies. Optional.

"N" (Default)
"Y"

Merchant

Cont'

clientProxyURL

Optional. If not provided by Merchant, the centrally located Client proxy will be used as default.

The URL of the Client proxy used by the Merchant

URL of any BankID approved Client proxy, set by Merchant. Default:3

https://cp.bankid.no/clientproxy

Merchant/COI

New

clientProxyPublicKey

Optional. The hex encoded modulus of the Client proxy's public RSA key the client will use to encrypt requests to the Client proxy. Exponent is 65537. If not provided by Merchant, a centrally stored key will be used.

The public RSA key the client will use to encrypt requests to the Client proxy. Optional.

Hex encoded modulus, set by Merchant

Merchant/COI

New

clientSessionTimeout

Optional. Merchant may use this to align the valid session intervals on the merchant and COI sides. Merchants should consider if auth and sign should have different values. It has no performance impact on COI.
This parameter also sets the valid Client proxy session interval.

The time, in milliseconds, the client session will live according to the merchant application. Optional.

1800000 ms (Default)

Merchant

New

clientVersion

Optional. Lets the merchant decide to perform signing with BankID 2.0 or 2.1. Note that for authentication only the 2.1 client exists, i.e. the same client will be returned regardless of this parameter value.

The desired BankID version to be used for document signing. Optional. Default value: "2.0".

"2.0" (default) / "2.1"

Merchant

New

Table 11 – BankID Web-client parameters and values
For captions in supported languages besides English, see Appendix D.

Please note the following remarks regarding parameters used for multi-document signing:

  • showUnderstanding – This setting will apply for all documents to be signed within a list of documents.
  • showConfirmation – This setting only applies for signing of one document. Due to usability reasons it has been decided that the confirmation step will be shown for all multi-document signings to minimize any user confusion, meaning this flag has no relevance when performing a multi-document signing.
  • withCredentials – This setting has no relevance when signing in 2.1 because the Client proxy has been introduced as a component in between the Web-client and the Merchant. This means that cookies are transferred from the Web-client to the Merchant in a different manner. See section about Helper initialization with sessionCookie in [BIDG].

Also note that the clientSessionTimeout has a globally defined maximum value in COI. If the merchant provides a value which is greater, it will be overwritten with the COI maximum. At the time of writing, the maximum value is set to 3600000 ms (1 hour). The default value is described in Table 11.

Further note that to ensure full backwards compatibility with BankID 2.0, the new parameter clientVersion is introduced with BankID 2.1, as described in Table 11.

Encoding

The information passed to and from the client are URL-encoded1 key/value pairs separated with the character "&". The URL- encoding and decoding must be performed by the merchant web application, and is not part of the BankID API. As a rule of thumb, the character encoding used is "ISO-8859-1". Note that there are some exceptions, please refer to [IJSRV] and [ICSRV] for details.

The bulk of the data transmitted between the client and the server is encrypted. The parameters appear as encKey, encData and encAuth in packets originating from the client, and encData and encAuth in responses to the client.

The following example shows the information that is sent to and from the client during the initial phase of authentication:

Client sends:

operation=initAuth&encKey=<base64encoded string>&encData=<base64encoded string>&
encAuth=<base64encoded string>(&sid=<sid>)

The response will be:

encData=<base64encoded string>&encAuth=<base64encoded string>

or

errCode=<the error code>


See also Appendix F for information on BIDXML and encoding.

1 A method for converting a string into a MIME type called "x-www-form-urlencoded".

Communication Parameters

The following tables describe the keys that are defined as part of the Web-client to Merchant protocol. 
Note that all values must be URL encoded, see chapter 3.5.

Set by merchant per transaction

Key

Format

Description

Comment

operation

String

The parameter describes the operation to perform on the merchants application. Operation values are:

  • initAuth
  • initSign
  • verifyAuth
  • verifySign
  • handleError

documents

JSON

Array of data elements used in multi-document signing. Only used in BankID 2.1.

Per document:

  • data
  • mimeType
  • dataDescription
  • encoding (latin1)

data

Base64-encoded

Data to be signed.

Used during signing by both the client and merchant. Several methods to set these raw data exists, some needs raw data b64 encoded, other needs the data as is in Java Strings.

nextURL

String

Optional. The URL the client redirects to after completion.

Used together with 'status=OK' or together with 'errCode=theErrCode'. Note: The URL must be HTTPS. The callback function in Helper is preferred over this parameter.

mimeType

String

MIME type of the data to be signed.

Used during signing (text/plain, text/BIDXML application/pdf).

sid

String

Session identifier

If sid is present in the initSession() request, the Web-client will include the sid during the initial server communication. The server may change the sid at any time. The client always returns the last received sid.

sdo

Base64-encoded

SDO XML object

Enables the end-user to save signed data. Not supported in 2.1.

dataDescription

String

Short description of the content of the SDO data.

This info is shown during PDF-signing.

userID

(The merchant may set the user profile by either including just the userID, or the userID and the OTP Service name. See [ICSRV] or [IJSRV] for details.)

StringEnd-user's user ID.

Used when the merchant is using user profile.

OTPService

String

OTP service name.

Used when the merchant is using user profile.

extPDFURL

String

URL to pdf to be signed.

Any URL using https. Only BankID 2.0.

userIDKeystrokeData

String

Key biometrics for user name input field from Merchant application

See BehavioWeb.

ocspFormatStringOptional. Indicates what OCSP format should be produced during COI operationsWill allways default to the the original default BankID format. Is only intended to be used in signing transactions, and specifically for PDF signing with PAdES compatability
cmsFormatStringOptional. Indicates what CMS format should be produced during COI operationsWill allways default to the the original PKCS7 BankID format. Is only intended to be used in signing transactions, and specifically for PDF signing with PAdES compatability

Table 12 – Values set by merchant per transaction

Generated by BankID Server or client in either initTransaction() or verifyTransaction().

Key

Format

Description

Comment

operation

String

Request type / identifactor

tokenType

String

"roaming"

Used by the Banklagret client in the first communication with the server component.

clientChallenge

Base64-encoded

Client generated challenge.

Used by the client to authenticate the merchant.

serverChallenge

Base64-encoded

Server generated challenge.

Used by the BankID Server to authenticate the client.

pkcs7

Base64-encoded

End-user or merchant signature

Used during both authentication and signing in BankID 2.0. For authentication only in 2.1. See also clientpkcs7s below.

clientpkcs7s

Base64-encoded

Comma separated list of PKCS7s (client signatures).

Used in signing transactions in BankID 2.1.

ocsp

Base64-encoded

OCSP response

May be used by merchant when creating an SDO. The merchant then does not have to do a VA lookup on its own certificate. BankID 2.1: Last ocsp after CS check of Merchant sign certificate for each merchant pkcs7.

status

String

OK indicates SUCCESS; all other values will indicate FAILURE.

Result of the last operation performed on the server during an authentication or signing process.

errCode

String

Defines the error that has occurred.

Can be generated on both the server and the client.

bssChannel

String

hash of the merchant signature.

Security mechanism.

bssChannelSignature

String

Merchant signature over bssChannel

To verify that the content of bssChannel is not compromised.

rtReport

Blob of comma separated name=value pairs. Used to send information from client to merchant.

See Appendix G

Table 13 – Values generated by BankID Server or client