Test your BankID is a tool that comes in two versions and enables end users to try out authentication and signing of documents in their browser with no respect to any particular merchant site.

1. An HTML-version described in the section below.
2. A JavaScript-API-version in the form of bid-client-test.js described further below.

The HTML-version of Test your BankID can easily be used if there is no need for customisation beyond language, width, and height.

Should that not be the case however, a JavaScript-framework is also provided to allow for further customisation. It allows you to start a BankID session in the same manner as the HTML-version, but simply provides a URL to the helper script instead so that you may make your own version of Test your BankID. The framework is used by the HTML-version itself to assure the same experience across merchant sites except for any parameters you may provide.

HTML-version

The HTML-version of the tool is available at tools.bankid.no and merchants may embed this page as part of their web site through the use of an iframe or by linking directly to it.

The tool lets you authenticate, sign, and change password. Additionally, the tool allows you to sign the three main document types: plain text, PDF, and XML.

<-- Test authentication: --> <iframe src="https://tools.bankid.no/bankid-test/auth"></iframe> <-- Test signing of plain text, PDF, or XML: --> <iframe src="https://tools.bankid.no/bankid-test/sign/txt"></iframe> <iframe src="https://tools.bankid.no/bankid-test/sign/pdf"></iframe> <iframe src="https://tools.bankid.no/bankid-test/sign/xml"></iframe> <-- Test change of password: --> <iframe src="https://tools.bankid.no/bankid-test/changepassword"></iframe> 

The HTML-version is configurable through parameters passed in the URL and enables the merchant to tailor the tool to their needs, such as language, width, and height.

Below is an overview of all the URL-parameters:

JavaScript-API (bid-client-test.js)

The framework comes in the form of bid-client-test.js which exposes an API for Test your BankID through the bidClientTest-object. This section describes how this can be used for programmatically starting a BankID session so that you may implement your own version of the tool.

Note that for it to work properly bid-client-test.js must always be sourced from the path below, and must never be downloaded and hosted on the merchant's own site.

<script src="https://tools.bankid.no/js/bid-client-test.js"><script> 

The framework in bid-client-test.js is exposed as window.bidClientTools if sourced in a script tag as above, but also supports inclusion with AMD and RequireJS if so desired.

initAuth, initSign, and initChangePassword

Starting the BankID Web-client is a two-step process. First, the init methods in the framework allow you to initialise a BankID-session to either authenticate the user, sign documents, or change the personal password of the user, respectively. Second, once a session has been started the framework will provide you with a URL to the helper script that may then be used to start the BankID Web-client in the user's browser. The latter part is up to you, but we have included an example further below for reference.

The simplest possible use of one of these methods could look like this:

bidClientTools.initAuth({ success: startBankIdClient, error: startupError, errorURL: "https://example.com/test-your-bankid/error", frontEndDomain: "https://example.com" }); function startBankIdClient(startupObject) { // A session has been started! // Use startupObject.helperURL to load the helper script (see below). } function startupError(response) { // Failed to start a session! This might be because the tool is not working, but this should usually not happen. } 

In the example above the initAuth method starts a BankID authentication session with the given parameters. If a session was successfully created the success callback is called with a startupObject containing the URL to a unique helper script.

Below is an overview of the possible parameters to the init-methods:

Below is an overview of the startupObject given to the success-callback:

Once the helper URL has been retrieved, it can be injected into the DOM-tree using a script-tag. Once done loading, the global variable bankidhelper may be used to initialise the BankID Web-client and start the authentication or signing process.

Expanding on the example above:

function startBankIdClient(startupObject) { // Create a script element for the helper script. var helperScript = document.createElement("script"); helperScript.setAttribute("src", startupObject.helperURL); // Set the helper script source. // Once the helper script has loaded, the BankID Web-client may be initialised using bankidhelper. helperScript.onload = function () { bankidhelper.init({ containerID: "bankid-client", // Where in the DOM-tree to start the client, such as the ID of a div tag. cid: startupObject.clientID, // The client ID from earlier. callback: function (response) { if (response.status === 1) { console.info("Authentication successful!"); } else { console.error("Received status " + response.status + ": " + response.statusText); } } }); }; // Finally, load the helper script. document.getElementsByTagName("head")[0].appendChild(helperScript); } 

For detailed information regarding the helper script and how to use it, see the BankID Web-client Implementation Guide provided in the partner web at bankid.no.

Below is an overview of the response object given to the error-callback:

Example:

function startupError(response) { if (response.status === 2) { alert("Your browser is blocked for use with the BankID Web-client. Please upgrade your browser."); } else { alert("Something went wrong: " + response.statusText); } } 

withLocale

withLocale lets you specify the desired language used in the BankID Web-client. The method returns the framework itself, so that it may be used with chaining.

Example:

bidClientTools.withLocale("en").initAuth(); 

Currently, only Norwegian bokmål (nb) and English (en) are supported.