The principal architecture of the BankID COI and participating components supporting the BankID Web-client (see [WP] and [BIOA] for details):

Note from Figure 1 that the Web-client resides inside the merchant's browsing context (the client may also reside in the browsing context of a redirect page in case of frameMode = "redirect", see section 3.2.1). The Web-client is initialized by the Helper which is sourced from COI, see 3.2.6. The client communicates with the Merchant application over the merchant protocol.

Also note that beginning in version 2.1 the merchant protocol for signing transactions is extended through a new intermediate component called Client proxy, shown in red in Figure 1. See section 2.3.1 for more details. For a detailed description of the BankID startup process, see [BIOA].

The role of the BankID clients

The BankID clients offer different graphical interfaces to the end-user. These user interfaces make the end-user able to perform authentication and signing operations when communicating with the merchant application. The different BankID clients are presented below in Figure 2. As this document only concerns the Web-client the other BankID clients are just briefly mentioned in the subsequent chapters:

Figure 2 – The BankID clients

BankID Web-client

The BankID Web-client is a single page AJAX-type application that runs in a browsing context on the end-user's device.

This client and how merchants should implement it is described in more detail in chapter 3 and beyond

BankID on Mobile

BankID on Mobile is BankID stored in the SIM card on mobile phones. It is triggered from a web page and allows users to authenticate and sign short messages. For more details about the merchant implementation of the BankID on Mobile client, see [IMPL].

BankID client features

Below is a table showing the features available in the BankID Web-client and any differences from the other BankID client types:

Feature		Client Type
Feature		BankID Web	Mobile
User profile		🗸	🗙
Keyboard biometrics		🗸
PersonBankID		🗸	🗸
AnsattBankID		🗸	🗙

Authentication		🗸	🗸

Signing	Plain text	🗸	🗸
	BankID XML	🗸	🗙
	PDF*	🗸	🗙
	Multiple documents	🗸	🗙
PAdES	B-B profile turnkey	🗸	🗙
	Any profile self assembling merchant	🗸	🗙
	PAdES download to local storage	🗸	🗙

SDO	Local storage	🗙	🗙
SDO	External archive	🗙	🗙

OTP services	non Challenge-Response	🗸	🗙
	Challenge Response	🗸	🗙
	BankID on Mobile as OTP service	🗸	🗙

Change of password	User initiated	🗸	🗙
	Enforced	🗸	🗙
	User initiated via Merchant	🗸	🗙

Information to End-user	BankID last used	🗸	🗙
	Own certificate information	🗸	🗸
	Merchant certificate information	🗸	🗙

Table 1 – BankID Web-client features

When signing large PDF documents there may be an issue where the end-user's device run out of memory. This is particularly the case when signing PDF on Android, as there is a wide range of devices and available internal memory, see section 2.2.6 for more information.

The role of the merchant’s web application

It is important to understand the responsibilities of the merchant's own web application. The main point is that there is never any communication directly between the BankID Web-client and a BankID Server function. The responsibilities of the merchant application are listed in the following subchapters below:

How to select the appropriate BankID client

The BankID Web-client is dependent upon web features such as Cross-origin resource sharing (CORS), JSON parsing and Cross-document messaging (XDM) in order to work, and the merchants must make a choice on how to best select the BankID client type to present to the end user based on the support of these features. See [IMMC] for further details.

For a list of all the web features used by the BankID Web-client, see Appendix C . In order for merchants to optimize the user experience it is recommended that the merchant application, as a pre-check, downloads and executes a Feature- and UA-detection script that will check if the current user agent string is blacklisted and subsequently run a feature detection to determine if all required web features are supported by the user agent. See section 3.2.8.1 on how to handle any errors returned by the script. See [BIDG] on how to implement it in a merchant application.

See also section 2.2.6 for a discussion on how to handle large documents to be signed.

Client size and responsiveness

The BankID Web-client is based on responsive design and adapts to the space made available for the client. See chapters 3.2.9 and 3.2.10 for further details on how merchants should address this new feature.

Authentication

The responsibility of the merchant web application during authentication is as follows:

Determine the end-user environment.
Configure the user session.
Generate a web page to start the BankID Web-client.
Transfer the necessary data between the client and server throughout the authentication process, see [BIDG] for details.
Continue with the merchant's business logic using the acquired information about the authenticated end-user.

Signing

The responsibility of the merchant web application during signing is as follows:

Generate the data to be signed (the format must be PDF, plain text, or BankID XML¹)
Determine the end-user environment, see 2.2.6.
Configure the user session, hereby optionally provide the clientProxyURL and the clientProxyPublicKey (CPPK), see section 2.3.1.
Generate a web page to start the BankID Web-client.
Transfer the necessary data between the client and server throughout the signing process, see [BIDG] for details. Note that BankID 2.1 supports multi-document signing (MDS), see section 2.2.5.
Continue with the merchant's business logic.
The Merchant must make sure PDF-documents to be signed comply with the standards PDF/A-2b as a minimum. Support for PDF/UA is recommended, see section 2.2.10.
Provide a URL to the document to be signed (BankID 2.0 only).

Add incremental updates with visual seals for merchant and end user when self assembling merchant mode
Add seal position for visual seals, both turnkey and self assembling merchant modes
Optionally add LTV incremental update in self assembling merchant mode
Set correct CMS and OCSP format when serial signing
Handling new callbacks related to serial signing, both turnkey and self assembling merchant modes

Please note regarding the BankID 2.0 only bullet point above that the Web-client does not verify that any contents exist "behind" the supplied extPDFURL, nor does it validate that the supplied URL points to a valid PDF-file. Merchants should ensure that the provided URL works, and that the document supplied is valid PDF/UA. See also 2.2.10 below.

The Client proxy component performs sanity checks on the documents to be signed. The sanity checks consist of PDF standard compliance validation and checks for any active contents inside the document, among others.

Another point for merchants to pay attention to is that in the BankID 2.1 the signing flow on one document is similar to the signing flow of BankID 2.0. This has the implication that signing with one document will be caught by any pop-up blockers when docDisplayMode is set to window. To work around this problem the user will be presented with a list of one document when starting the signing process.

If docDisplayMode is set to internal or overlay the list of documents is skipped in 2.1.

¹ XML document and XSL document in a BankID XML structure. For details see [ICSRV]/[IJSRV].

Multi-document signing

One of the most important features introduced with BankID 2.1 is the support for multi-document signing. This means that the merchant in the initSign() response can provide a set of documents to be signed in one sequence. The documents will be sent to the Client proxy which subsequently will forward them to the Web-client. The end-user signs the documents one by one before all the signed documents are returned to the merchant in the verifySign() request. See section 2.3.1 for how the introduction of the Client proxy implicates merchants.

The documents are presented to the end-user in the same order as the Merchant added them to the sessionData object (J-server) or struct DocsToSign (C-server) but the end-user is free to sign the documents in any order. The signed documents are returned by the Web-client in the same order as added by Merchant.

Multiple documents may be a mix of pdf, text or xml when using parallel signing. When serial signing all documents must be pdf. It is not possible to mix text, xml and pdf when doing serial signing.

Serial signing - PAdES

Serial signing means that when a signatar signs a document, he will sign the original document including visual seals and signatures generated by all earlier signatars. The data to be signed will also include a visual seal for the signatar himself. When doing parallel signing, all signatars sign the same data and the sequence they do it does not matter. When doing serial signing all signatars sign different data and the sequence this is done is relevant. Serial signing support in BankID are for PDF format only. When parallel signing produces the SEID SDO, the serial signing produces a PAdES document. Standard PDF readers support showing this format, both the original PDF data and it's associated signatures and visual seals. A visual seal is a graphic included in the PDF representing the signatar and the signature over these data.

BankID supports serial signing in both a turnkey and self assembling mode. In the turnkey mode, the BankID clientProxy component creates and manages the visual seals for the merchant and the end user. In self assembling mode, the merchant code builds the signature directories and visual seals, the BankID server or BankID WebClient does the computation of the signature.

BankID supports PAdES B-B profile only, so if a Long Time Validation signature directory needs to be added to the PAdES, the merchant must do this. The merchant may either do this manually by assembling all needed values from the BankID session data or the merchant may register a callback function for adding this incremental update. In the latter case, BankID server will extract all needed values and use the callback function after the end user has performed the signing .

To support PAdES the BankID server had to support new PAdES compatible CMS and OCSP formats. The merchant must set these in the BankID session before any serial signing has started.

Serial signing may be used in a multidocument context. A new property, signingKind is added to the document structure.

Serial signing in turnkey and self assembling mode must be done in separate sessions.

Serial signing where only end user visual seal is added is supported.

Serial and parallel signing must be done in separate session. It is not legal to mix serial and parallel signing.

Recommended size of documents to be signed

As experience with BankID 2.0 has shown, large PDF documents to be signed could impose a performance issue affecting the end user experience. The definition of large in this context is hard to pinpoint as there are a number of factors involved, like CPU and memory of the end-user device, bandwidth etc. As a consequence it is not desirable to set a fixed limit on document sizes or the total size or length of a list of documents to be signed in case of multi-document signing.

Merchants should perform their own tests to gain experience and then be prepared to instruct their users not to carry out potentially large signing operations on devices with limited resources or bandwidth (i.e. a document of 1 MB on a 3G mobile connection will most likely be perceived as slow by an end-user).

Please note that PDF files with a large number of images yield more data to be processed and will result in a less than optimal user experience, especially on mobile devices with limited processing power.

Merchants should prepare documents for universal accessibility

The BankID Web-client supports Universal Accessibility (UA) in all dialogs using the WCAG 2.0 AA standard as the reference. Support for Universal Accessibility when displaying documents to be signed does on the other hand require efforts from the merchant in order to give good results.

Text documents

For text documents, the merchant should ensure that the text content to be signed is readable and understandable. This means:

Avoiding the use of words in an unusual or restricted way.
Avoiding the use of abbreviations where possible.
Avoid using the same word with different meaning in the same document.
Be careful with the use of whitespace as a means for layout as this may break depending on the available width the Web-client is given.

XML documents

XML documents to be signed in the BankID Web-client are sent to the client (BankID 2.0)/Client proxy (BankID 2.1) as an XML and an XSL file. These are transformed in the client/Client proxy, and the merchant should ensure that the resulting HTML markup is readable and understandable.

Because the actual content displayed to the user is HTML, the merchant should ensure that the meaning of the information to be signed is reinforced using Semantic HTML¹. Semantic elements describe their meaning or purpose to the browser, and improve the accessibility of web documents. For example, when a screen reader or audio browser can correctly ascertain the structure of a document, it will not waste the visually impaired user´s time reading out repeated or irrelevant information when it has been marked up correctly.

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

PDF documents

Note that all PDF documents to be signed with BankID 2.1 will be subject to a PDF validation in the Client proxy. It is decided that the PDF/A-2b format is currently the one which best meets the BankID requirements. Merchants will be provided with a full report from the validation process, see section 3.2.5. Any critical errors from the validation may result in the transaction being blocked by COI based on requirements put forward by BSK. Merchants will be notified in due course.

In order to provide proper support for Universal Accessibility when displaying PDF documents to be signed, the merchant should conform to the PDF/UA specification, in addition to the PDF/A-2b format.

PDF/UA (PDF/Universal Accessibility)¹ provides definitive terms and requirements for accessibility in PDF documents. For those equipped with appropriate software, conformance with PDF/UA ensures accessibility for people with disabilities who use assistive technology such as screen readers, screen magnifiers, joysticks and other technologies to navigate and read electronic content.

¹http://en.wikipedia.org/?title=PDF/UA

Interaction between BID Server and client

The Banklagret BankID Web-client interacts with the merchant application using HTTPS communication and an encrypted BankID-specific communication over this protocol.

Note that it is the web component of the merchant that is responsible for the communication with the client. The BankID Server does not perform any direct client communication.

Note that for signing in BankID 2.1 an intermediate Client proxy component between the BankID Web-client and BankID Server is introduced, see section 2.3.1.

Merchants choosing to stick with BankID 2.0 can upgrade the BankID Server without having to do any additional work, except for the BankID Java server, upgrading to Java 1.8 and other dependencies.

Interaction between BID server and Web-client through Client proxy

The Client proxy is a new component, as shown in Figure 1, which is introduced in BankID 2.1 as an intermediary between the Web-client and the merchant applications during sign and netPay-operations. The rationale is to simplify deployment of new services required for signing in BankID 2.1. These services include:

Validation of documents to be signed.
Sanitation of documents displayed by the Web-client.
Conversion of PDF documents to PNG displayed internally in the Web-client.
Conversion of BIDXML to HTML and CSS.
Generation of a download URL of the original PDF-document (using a GUID).

Generation and inserting visual seals for turnkey mode serial signing
Mediating the interplay with merchant when inserting seals for self assembling mode serial signing.

The Client proxy interacts the merchant application using HTTPS communication and an encrypted BankID-specific communication over this protocol.

The introduction of the Client proxy concept has some important implications on the merchants.

In order to reap the benefits of the Client proxy merchants must upgrade BankID Server in order to support BankID 2.1. BankID Server 2.1 includes dual support for 2.0 and 2.1, leaving it to the merchants to choose its preferred BankID version. Note that BankID 2.0 is set as default and that 2.1 behavior must be set explicitly by the Merchant in the initSession() request.
There is a 1:1 per-request relationship between a BankID Server instance and a Client proxy. This means that the merchant may provide the URL of the Client proxy (CPURL) in the initSession() request. If not provided, the Web-client will default to the centrally hosted Client proxy. See [CPINTG] for details on setting a Client proxy configuration which deviates from the default settings.
Merchants may decide to use a different and separate Client proxy instance. In such cases the merchant may either store the CPPK at the merchant side and provide this with each initSession() request, or let the COI store it. See document [CPINSG] for details on installing and hosting a Client proxy.
The verifySign() and handleError() requests contain the result of the document sanity check performed by the Client proxy, together with the PDF version(s) that the documents were validated against. The results are returned in two formats, as a BankID condensed format version and as the raw output from the PDF validation tool itself. These data will help merchants to comply to the PDF standard set by BankID, see sections 2.2.10 and 3.2.5.
The verifyAuth, verifySign() and handleError() requests also contain the results of a number of security checks performed by the Web-client and COI. Merchants may use and analyze these data at their own discretion, see [BIDG] for details. Note that these results are just in the form of raw data and has not been interpreted in any way, unlike the transaction data returned over [ISDS].
Merchants may decide for how long a BankID session will be valid. By setting the clientSessionTimeout value, it will tell COI to check incoming requests against this value, to determine that the session is still valid. Session data will reside at the Client proxy until either a completeTransaction() request is sent from the Web-client or the clientSessionTimeout has expired, see [CPINTG].

Note that there is no direct communication between the Client proxy and the COI.

Please note that the following conditions apply to a test merchant in order to communicate with the central Client proxy instance (pre-production)¹:

It must have a public IP address with a DNS-resolvable hostname.
It must be open for incoming connections from anywhere on port 443.
It must have an SSL-certificate issued under a root whose CA-certificate is pre-installed with the Java platform's cacert trust store.
The Client proxy uses the Java cacerts folder for trusted root CA-certificates. If the merchant has not configured its web-server to return the chain of certificates including the intermediate certificate or this intermediate certificate is not already imported into Client proxy's trust store, the merchant must ask support@bankid.no to add the intermediate certificate to said trust store².

¹ https://cp-preprod.bankid.no/clientproxy

² See bankid.no for more details.

The role of the BankID Server API

The BankID Server API is the interface through which PKI functions are made accessible to PKI aware web application software¹. The roles of BankID Server API are to abstract implementation details at the PKI algorithm level and expose them in a standard way that application software can easily access. In particular, this abstraction eliminates the need for the application developer to have extensive knowledge of PKI.

The integration of BankID Server API consists of extending the web application code. The main responsibility of the web application from the BankID Server API point of view is to transfer data used in authentication and signing processes between the BankID Server and Client and to prepare data to be signed.

The BankID Server API is stateless, and any state data that must be kept during the client session must be held by the application. The sid parameter² is added for merchants to keep track of a session. Thus it is recommended that merchant applications are implemented using sid rather than any cookies.

The web application is your custom made code, and is not part of BankID.

See BankID Web-client parameters and values

Browser not supported