About this document

The purpose of this document is to provide the basics for implementing the BankID Web-client at merchant websites. This is a practically oriented document which aims to guide the merchants on how to implement the BankID Web-client, independently of the BankID Server implementations. References to other documents are provided where necessary.

The detailed information about the server APIs are contained in separate interface descriptions ([IJSRV] and [ICSRV]). They are vital when performing an actual implementation of the new BankID Server version and the BankID Web-client.

For a more hands-on approach to implementing the BankID Web-client, see [BIDG] and [BIDGS]¹. Merchants are recommended to also read [IMMC].

Organization of this document

This document is an adaptation of the original BankID Implementation Guide [IMPL], which covers the legacy Banklagret BankID clients and the BankID on Mobile client, but this document solely focuses on how to implement the BankID Web-client. If you need a copy of [IMPL] please send an email to support@bankid.no. 
 Please note that this version of the document describes the 2.1 version of the Web-client and is a continuation of the corresponding 2.0 version. Important changes from 2.0 to 2.1 are clearly identified by 
 The most important changes that come with release 2.1.0 of BankID are:

• Support for multi-document signing, see section 2.2.5.
• Dual support for BankID 2.0 after upgrade of BankID Server to support 2.1, see 2.1 related information in section 3.4.
• The introduction of a new intermediate component, the Client proxy, used for (multi) document signing.
• Support for internal display of documents in the Web-client (with support from Client proxy).
• Support for frameModes window and redirect.
• Support for docDisplayModes window and overlay.
• A dynamic progress status in the Web-client UI when downloading documents to be signed.
• The signing flow when signing one document will be continued from 2.0. See section 2.2.4.
• rtReport in verifyAuth(), verifySign() and handleError()-requests, available through BankID Server, see section 3.2.5.
• The parameter clientSessionTimeout will also set the valid session interval on Client proxy (requires BankID Server in 2.1-mode).

 The most important changes that come with the PAdES/serial release are identified by the  symbol.

• new CMS and OCSP formats compatible with PAdES.
• PAdES B-B serial signing with turnkey generation of visualSeal for merchant and enduser.
• PAdES B-B serial signing allowing merchant to generate visualSeal for merchant and enduser.
• PAdES B-B serial signing with optional generation of visualSeal for merchant both turnkey and self assembling merchant.
• Download of PAdES and unsigned PDF from Web-client.
• PAdES signing requires BankID 2.1

Merchants that are going to use features specific for PAdES/serial or BankID 2.1 must upgrade BankID Server. Merchants who are not going to use BankID 2.1 specific features may continue to use their current version of BankID Server.

The current version of BankID Server may be installed without having to change the existing implementation in order to continue to use BankID 2.0 or BankID 2.1.

The internal upgrade to Java 1.8 and newer Bouncy Castle versions may cause some incompatibilities.

Where appropriate it will be stated what Merchants need to take into consideration regarding 2.1 or PAdES/serial signing. See also [IMMC]. 
The document is organized as follows:

• Section 2 presents the principal architecture of BankID and gives an overview of the SDK components.
• Section 3 gives an overview of the task of implementing the BankID Web-client at a merchant site.
• Section 4 discusses migration between test and production environments.
• Section 5 lists helpful hints on troubleshooting.
• Section 6 addresses some security issues that the merchant must consider.
• Appendix A contains some key concepts for further understanding of BankID.
• Appendix B contains an overview of services offered by the BankID Server.
• Appendix C contains an overview of the web features used by the Web-client.
• Appendix D lists captions of all bankidhelper.Init() and initSession() parameters in all supported languages.
• Appendix E addresses some known browser specific issues with regard to the Web-client.
• Appendix F shows the BIDXML format.
• Appendix G outlines the format of the rtReport introduced with BankID 2.1.

See the change history of this document in Table 23 – Document change history.

Target audience

The target audience of this document is project teams in banks, merchants and partners, and technical personnel designing and coding the integration with BankID Web-client and BankID Server.

Any support inquiries regarding the production versions of the BankID clients shall be forwarded to the following e-mail address:

• support@bankid.no

Limitations

This document focuses primarily on how application developers should integrate the BankID Server applications. It does not describe the process of applying for BankID certificates, key generation, test and activation of certificates and certificate suspending and revocation. Neither does it describe the overall BankID infrastructure. The server APIs are covered in separate documents. The client type BankID on Mobile is outside the scope of this document. The reader is kindly asked to refer to [IMPL] for further detail.

Preconditions

It is important that the reader has an understanding of the basic functionality within BankID. The reader should have read and be familiar with the white paper [WP] before reading this document. It is also recommended that the reader has read the BankID 2.0 Overall architecture document [BIOA]. The technical background required by the reader should include C or Java programming, some knowledge of PKI and in particular the use of digital certificates and signatures. An understanding of common web technologies is strongly recommended.

Acronyms

Referenced documents

• Restricted documents 
  See release notes for the exact location of all of the referenced documents.