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.
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.
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:
| Parameter | Explanation | Default | Example |
|---|---|---|---|
| locale | Specifies the language to be used throughout the tool and
the BankID Web-client. Currently, only Norwegian bokmål (nb) and English (en) are supported. |
Norwegian bokmål (nb) | https://tools.bankid.no/bankid-test?locale=nb |
| width | Specifies the width to be used in the BankID Web-client, in pixels. Minimum is 320 pixels. | None (Full width adjusted to the parent container.) |
https://tools.bankid.no/bankid-test?width=640 |
| height | Specifies the height to be used in the BankID Web-client, in pixels. Minimum is 200 pixels. | None (Full height adjusted to the parent container.) |
https://tools.bankid.no/bankid-test?height=480 |
| docDisplayMode | Determines the user-experience for document signing.
Options:
|
interior | https://tools.bankid.no/bankid-test?docDisplayMode=interior |
| merchantFEAncestors | A space separated list of ancestor domains where any iframes other than the iframe in merchantFEDomain itself, will be listed. | None | https://tools.bankid.no/bankid-test?merchantFEAncestors=http://www.bankid.no |
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.
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:
| Parameter | Explanation |
|---|---|
| success | Callback that is called once a BankID-session has been successfully established and a helper script is ready to be used. |
| error | Callback that is called if a BankID-session could not be established or if the user's browser is blacklisted. |
| errorURL | The errorURL-parameter is mostly a technicality required as a fallback redirect in case something went wrong during the whole authentication process, including after the BankID Web-client has been started. |
| frontEndDomain | The frontEndDomain-parameter must be set to the domain of
the merchant web site (you) as seen in the address bar of the
browser. This is used to secure cross-document messaging (XDM)
between the BankID Web-client and the helper script. Note that loop-back addresses such as localhost or 127.0.0.1 are not allowed, although the domain need not be visible over the Internet. Example: https://example.com |
| docType | Either pdf, txt, or xml. Lets you specify which type of example document that should be used in case initSign was called. The documents presented are simple dummy documents with little text. |
| frameMode | Determines the BankID client location.
Options:
|
| docDisplayMode | Determines the user-experience for document signing.
Options:
|
| merchantFEAncestors | A space separated list of ancestor domains where any iframes other than the iframe in merchantFEDomain itself, will be listed. |
Below is an overview of the startupObject given to the success-callback:
| Field | Explanation |
|---|---|
| helperURL | After a BankID-session has been established, a helper script for loading a unique instance of the BankID Web-client has been prepared by the BankID COI. The startupObject returned from the init-methods contains the URL to this helper script, which may in turn be loaded by the browser and used to start the BankID Web-client (see example below). |
| clientID | The unique client ID associated with the BankID Web-client. Must be passed to the init-method of the helper script. |
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:
| Field | Explanation |
|---|---|
| status | The status code of the error, which has only two possible
outcomes: 1 indicates an unexpected error such as server failure. 2 indicates that the user's browser is blacklisted for use with the BankID Web-client. |
| statusText | A descriptive hint as to what went wrong. |
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 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.