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. 

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. 

• 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)

CORS¹ allows XMLHttpRequest requests across domains, which traditionally wouldn't be allowed under the browser's Same origin policy (SOP)². 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 CORS^3,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 XMLHttpRequest⁵. 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 policy¹, 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. 

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(). 

 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:

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.

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-end³ 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 chosen⁴, 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.

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

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.

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

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.

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

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()):

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

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:

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. 

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

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:

• this document, BankID Web-client parameters and values
• [ICSRV], 4. Configuration of BankID C server
• [IJSRV], 3.1 Configuration of BankID J server

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:

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-encoded¹ 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.

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

Table 12 – Values set by merchant per transaction

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

Table 13 – Values generated by BankID Server or client