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.

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)

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.

¹ http://en.wikipedia.org/wiki/Cross-origin_resource_sharing

² http://en.wikipedia.org/wiki/Same_origin_policy

³ http://www.caniuse.com/CORS

⁴ http://blogs.msdn.com/b/ieinternals/archive/2010/05/13/xdomainrequest-restrictions-limitations-and-workarounds.aspx

⁵ http://blogs.msdn.com/b/ieinternals/archive/2010/05/13/xdomainrequest-restrictions-limitations-and-workarounds.aspx?Redirected=true

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.

¹ http://en.wikipedia.org/wiki/Content_Security_Policy

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

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 SSN^1,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.

Parameter			Value	Value
			initAuth request	initSign request
Main	Decrypted	Inner	Value	Value
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-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.
if serial signing:
- set the SerialSigningProperties to select turnkey or self assembling merchant mode
- in self assembling mode:
  - add the sealbuilder callback functions to the SerialSigningProperties
  - handle the extra operation="initSignBuildEndUserSeal" request
  - set at least the sealposition pageno for the visual seals
- in turnkey mode:
  - set the sealPositions for the visual seals
  - handle the extra operation="initSignSignMerchantSeal" request
- in both modes
  - set signingKind for each document
  - set CMSFormat and OCSPFormat to PAdES compatible values
  - optionally add an LTVHandler callback to the SerialSingningProperties 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.

Parameter			Value	Value
			initAuth response	initSign response
Main	Decrypted	Inner	Value	Value
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.
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

Parameter			Value	Value
			initAuth response	initSign response
Main	Decrypted		Value	Value
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 document⁵	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

		signingKind		String: parallel/serial/serialEndUserOnly
		byteRange		JSON array of 4 integers: Describes layout of data, i.e. where is the merchant seal if some
		(opt) merchantSeal		JSON object: x,y and page for merchantSeal placement
		(opt) endUserSeal		JSON object: x,y and page for endUserSeal placement
	serialSessionInfo			JSON object: Only when signing serial
		noGraphic		true or false: Turnkey: no graphic in visual seals
		timeStampServiceUrl		url or empty: For overriding default
	serialPkcs7s			list of merchant signatures over the data to be signed (as in coidata), for serial documents only, NODATA else.
	nextMerchantOperation			initSignBuildEndUserSeal or initSignSignMerchantSeal: tells next action on merchant side, dependent on turnkey or self assembling mode
	merchantCert			JSON object: Description of the merchant, used for building merchant sear, turnkey.
	coiData			Data to be forwarded to COI. Only sent when all documents to be signed are signed by merchant
	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
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.

For serial signing, turnkey mode, the server's signature is not yet computed since that signature must be computed over the document after ClientProxy has added the visual seal for the merchant. In that case the "nextMerchantOperation" is "initSignSignMerchantSeal". The ClientProxy will for all serial signings add the merchant seal and return that to the merchant to sign with operation="initSignSignMerchantSeal".

Parameter			Value
			initSignSignMerchantSeal request
Main	Decrypted		Value
operation			initSignSignMerchantSeal
encKey			The base 64 encoded baseKey received from the client to derive the sessionKey
encData			The base 64 encoded encrypted data received from client
	merchantSeals		pdf increments containing a merchant seal, one per serial document
	For each seal	data	b64MerchantSeal
		byteRange	JSON array of 4 integers: Describes layout of data, i.e. where is the merchant seal.
		index	Index of document in the documentlist in sessionData
encAuth

For serial signing, self assembling merchant mode, the end users visual seal must be computed at merchant site. For each serial document, a description of the end Users selected BankID is sent to the merchant with operation="initSignBuildEndUserSeal". The merchant must compute the end user seal and return it.

Parameter			Value
			initSignBuildEndUserSeal request
Main	Decrypted		Value
operation			initSignBuildEndUserSeal
encKey			The base 64 encoded baseKey received from the client to derive the sessionKey
encData			The base 64 encoded encrypted data received from client
	endUserCert		Description of the certificate of the end user
		cn	Common Name (in general <Last name, Given name>)
		serialNumber	Sent as empty field for endUserCert
		o	Organisation name
		c	Country name
		dateOfBirth	End users DOB on the format "dd.MM.yyyy"
	index		Some value
encAuth

Parameter			Value
			initSignBuildEndUserSeal response
Main	Decrypted		Value
encData			The base 64 encoded encrypted data returned to the client
	endUserSeal		The pdf increment containing the seal of the end user
		byteRange	relative position of endUserSeal in respect to original received bytes
		data	base64EndUserVisualSeal

Continued from Figure 6. See 3.2.8 Error handling.

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

Parameter			Value	Value
			verifyAuth request	verifySign request
Main	Unencrypted	Inner	Value	Value
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

Parameter			Value	Value
			verifyAuth request	verifySign request
Main	Unencrypted	Inner	Value	Value
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
	endUserSeals			Used in turnkey mode only, holds the end user visual seals built by clientProxy. Will be added to session data to complete PAdES up to B-B profile.
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.

When using serial signing, the resulting PAdES'es are now complete B-B profile. After verifyTransactionRequest these PAdES'es are accessible from the sessionobject. If further action need to be taken, as T/LTV this must be (for now) done by the merchant. Upload of the resulting document to the client for later download by the end user is not supported

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.

Parameter			Value	Value
			verifyAuth response	verifySign response
Main	Unencrypted	Inner	Value	Value
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

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

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

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

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

⁵ 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"¹, "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

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

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

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:

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-Option¹.	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-directive².	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:³ 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.

¹ http://www.rfc-editor.org/rfc/rfc7034.txt

² http://www.w3.org/TR/CSP2/#directive-frame-ancestors

³ For pre-production: https://cp-preprod.bankid.no/clientproxy

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>

errCode=<the error code>

See also Appendix F for information on BIDXML and encoding.

¹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 initSignSignMerchantSeal initSignBuildEndUserSeal
documents	JSON	Array of data elements used in multi-document signing. Only used in BankID 2.1.	Per document: data mimeType dataDescription encoding (latin1) signingKind byteRange merchantSeal -position of seal endUserSeal - position of seal
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.
String	End-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.
serialSessionProperties	JSON	containing pr. signing session serial signing information	Sets pr. session serial signing parameters for example kind of merchant mode, only PAdES
serialPkcs7s	String	commasep list of enduser signatures (b64) for serial documents.	only together with coiData, only PAdES
merchantCert	JSON	description of merchant cetificate	used for building merchant visual seal, only PAdES turnkey mode
endUserCert	JSON	description of enduser certificate	used for building end user visual seal, only PAdES self assembling mode
nextMerchantOperation	String	signal to client what to do next in some serial signing flows	only PAdES
merchantSeals	JSON	clientProxy generated merchant seals	only PAdES turnkey mode
endUserSeals	JSON	clientProxy generated end user seals	only PAdES turnkey mode
cmsFormat	String	kind of format in pkcs7	ordinary bankID or PAdES compatible
ocspFormat	String	kind of format in ocsp responses	ordinary bankID or PAdES compatible

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

TODO: must be updated to reflect a) BankID 2.1 multidocument changes and SIGN2's PAdES support

Browser not supported