Overview

BankID 2.1 is a single-page AJAX-type web application. The Client consists of Client HTML/CSS (C) and Client JavaScript (E). The Client is loaded through a start-up phase involving a series of steps (1-9), most of them concerning communication between the browser front-end and BankID COI COI=Common Operational Infrastructure (I). In the browser front-end a JavaScript Helper (B) component provides the interface (4,12) to the front-end part of the Merchant application (A).

In its execution-phase the Client communicates (10, 11a, 11b, 11c) with both BankID COI (I) and the Merchant back-end (G). In the following the term Client interchangeably refers to either (C) or (E) or both(C) and (E) in combination. The term Merchant application refers to the Merchant front-end (A) and Merchant back-end (G) in combination.

Markup for the Client (C) is sourced from BankID COI (6) and consists mostly of CSS. Static HTML is kept to a minimum and limited to tags required to source a JavaScript Bootloader (D) Third-party product. The user-interface and business logic of the Client is implemented dynamically via JavaScript in the Client JS (E). The Client includes several checks to verify that the presentation layer I.e. the Client's legitimate dynamic changes to the DOM-tree. is not overridden and/or manipulated by rogue JavaScript that has bypassed security measures and found its way into the browsing context of the Client.

The Client (C) and a Bootloader (D) are sourced (6,7) from BankID COI (I) into a browsing context See http://www.w3.org/TR/2010/WD-html5-20100624/browsers.html#windows for a definition separate from the browsing context of the Merchant front-end (A) (merchant web document). The same-origin policy ensures separation of the two domains. The common case is when a browser is the User-Agent See http://www.w3schools.com/jsref/prop_nav_useragent.asp and an embedded iframe is used. The other options are to create a separate window, or to take over the current browsing context by performing a redirect to a centrally hosted and BankID-branded landing page. Note that Content Security Policy (CSP) is used to enhance the security of the browsing context of the Client. Details on CSP-configuration are beyond the scope of this document.

Note that the Merchant application (as seen from the BankID perspective) may itself run inside an iframe, thus resulting in nested iframes. This may typically be the case for intermediate services like eID-portals (e.g. Signicat, Trust) or payment-service providers (e.g. DIPS). This use-case is supported as long as the intermediate provider, playing the role of a BankID Merchant application, adapts its service to work with BankID Web-client.

The Bootloader (D) provides cryptographic protection on an outer layer as the JavaScript Client (E) is downloaded (8) from the infrastructure and inserted directly into the JavaScript environment of the containing browsing context. The dashed line-style of interface (8) signifies asynchronous HTTP requests (XHR). This is in contrast to the interfaces (3, 5, 6 and 7) using ordinary HTTP requests. The security of the Bootloader rests on the provision that its embedded key-generator mutates frequently enough to not allow an attacker enough time to automatically reverse engineer the Bootloader before it rotates. The Bootloader is obfuscated to make reverse engineering harder. Determination of a suitable rotation interval for the Bootloader is beyond the scope of this document.

As Client-code is delivered from BankID COI (I) it undergoes obfuscation also on an inner layer, before being inserted into the Bootloader. The system can be configured to bypass obfuscation and encryption (Bootloader), thus simplifying test and debugging. The Client-code is modularized and the source-code for a particular invocation is assembled only from modules that are actually needed (hence the Client-factory symbol). The Client-code is also personalized with unique values for each invocation. Personalization depends on client parameters. Note that each unique Client is equipped with a lifetime. A specific Client that is not retrieved via (8) within its lifetime becomes invalid.

Since the Merchant governs selection of language, COI can be informed about the selected language and all i18n handling can be placed in COI. Hence, the Client is prepared in the correct language before it is delivered.

The J Helper (B) is also sourced (5) from BankID COI (I), but resides in the domain of the Merchant application. The Merchant application must permit sourcing of the Helper from the BankID domain. Since the Helper and the Client are in different domains they communicate via cross document messaging (XDM) (9). Since the Client has an origin different from the merchant domain, the Merchant back-end (G) must support cross-origin resource sharing (CORS) to enable subsequent communication (11a) with the Client (C).

Note that the merchant protocol comes in three varieties with BankID 2.1 as suggested by (11a), (11b) and (11c) in the figure. Variety (11a) corresponds to the legacy protocol and is carried forward in BankID 2.1 but restricted to the purposes of authentication and password change. For the purpose of signing (and netPay) in BankID 2.1 an intermediate Client proxy component (L) is introduced, using protocol variety (11b) towards the merchant and variety (11c) towards the Client. Further details on these protocol varieties (11a, 11b, 11c) are beyond the scope of this document.

The Client proxy (L) is introduced in order to simplify deployment of new services required for signing in BankID 2.1. See section 8 for further details.

Any content-security policy (CSP) enforced by the Merchant application must be compatible with the implementation of the Helper component. For compatibility reason, and because the Helper is a less critical component, this component is not protected by a Bootloader. Note however that the Helper is obfuscated. Note also that the Helper, in contrast to the Client, is not made unique for each invocation.

The Helper (B) and Client (C) are instantiated as a result of the Merchant front-end (A) initiating a BankID session. There is a chain of events (1,2,3) via the Merchant back-end (G) and an associated BankID Server (H) to BankID COI. As control returns in the opposite direction, the BankID Server provides an URL for the Helper (B) and the Merchant application is responsible for embedding the URL in an appropriate script-tag. The Helper (B) will in turn inject the required markup for the iframe containing the Client (C). The Merchant application interfaces with the Helper (B) via a pair of JavaScript functions, init (4) and callback (12).

The interface (1) between the Merchant back-end (G) and the BankID Server (H) is changed to support the new startup (and return) mechanism of BankID Web-client. The same applies for the interface (2) between the BankID Server (H) and BankID COI (I).

The Merchant front-end may source (0) a pre-check component (M) from BankID COI and run this prior to actually initiating a transaction (1) via BankID Server. The pre-check component may be used to test if the browsing context is compatible with the requirements for BankID Web-client. The pre-check component consists of a feature-detection module (O) as well as a blacklist-check module based on UA-string comparison (P). The Helper (B) uses the same feature detection and blacklist-check modules as the pre-check component. The benefit of using the pre-check component is a better user-experience in case the BankID Web-client is not supported, since loading the Client should not be attempted in such a case. The Merchant should in this case ask the user to upgrade his User-Agent.

Once the Client (E) is securely loaded, the business logic of the Client takes control. During its lifetime the Client (E) communicates with the Merchant back-end (G) and the BankID infrastructure (I) over XHR using variants of the end-to-end encrypted BankID protocols (10, 11a, 11b, 11c) with some changes (see next section). Note that the Helper (B) does not communicate with the BankID COI (I).

As the Client completes the business logic of the session in progress (either with success or no success), control is returned to the Merchant application (12) via the Helper (B). Each of the following return alternatives are supported in prioritized order:

1. The Client communicates its completion via (9) to the Helper (B) from which the Merchant application (A) regains control through a callback (12). The Merchant front-end (A) can in turn communicate with the Merchant back-end (B) or redirect the Merchant application.
2. The Client does not communicate its completion via (9) to the Helper (B). The Merchant front-end (A) must in this case continuously poll the Merchant back-end (B) to determine when the on-going BankID session has completed. This corresponds to the solution that is today used for BankID on Mobile.

Return via a JavaScript callback (first alternative) is recommended if the Merchant application is already an AJAX-type application.