bankid

A npm module to simplify integration with the Swedish Bank ID service for user authentication and signing processes.

Installation

# If you prefer npm
npm install --save bankid
# If you prefer yarn
yarn install bankid

Usage V6

import { BankIdClientV6 } from "bankid";

const client = new BankIdClientV6({
  production: false,
});

const { autoStartToken, orderRef } = await client.authenticate({
  endUserIp: "127.0.0.1",
});

// Generate deep link from autoStarttoken and try to open BankID app
// See ./examples

client
  .awaitPendingCollect(orderRef)
  .then(res => {
    console.log(res.completionData)
  })

Acting on a session is done trough opening the app or trough scanning a QR Code, both examples are documented in detail in the examples directory

Usage V5

import { BankIdClient } from "bankid";

const client = new BankIdClient();
const pno = "YYYYMMDDXXXX";

client
  .authenticateAndCollect({
    personalNumber: pno,
    endUserIp: "127.0.0.1",
    userVisibleData: "Authentication request for my service",
  })
  .then(res => console.log(res.completionData))
  .catch(console.error);

As outlined in the relying party guidelines, there are four main methods (arguments marked with * are required)

• authenticate({endUserIp*, personalNumber, requirement, userVisibleData, userVisibleDataFormat, userNonVisibleData})
• sign({endUserIp*, personalNumber, requirement, userVisibleData*, userVisibleDataFormat, userNonVisibleData})
• collect({orderRef*})
• cancel({orderRef*})

Note that userVisibleData will be base64-encoded before sent to the BankID API.

Additionally, bankid provides convenience methods to combine auth / sign with periodic collection of the status until the process either failed or succeeded (as shown in the example code above):

• authenticateAndCollect(...)
• signAndCollect(...)

Full example not using the convenience methods:

import { BankIdClient } from "bankid";

const client = new BankIdClient();
const pno = "YYYYMMDDXXXX";
const message = "some message displayed to the user to sign";

client
  .sign({
    endUserIp: "127.0.0.1",
    personalNumber: pno,
    userVisibleData: message,
  })
  .then(res => {
    const timer = setInterval(() => {
      const done = () => clearInterval(timer);
      client
        .collect({ orderRef: res.orderRef })
        .then(res => {
          if (res.status === "complete") {
            console.log(res.completionData);
            done();
          } else if (res.status === "failed") {
            throw new Error(res.hintCode);
          }
        })
        .catch(err => {
          console.error(err);
          done();
        });
    }, 1000);
  })
  .catch(console.error);

Configuration

By default, bankid is instantiated with the following configuration pointing to the Bank ID Test Environment:

settings = {
  refreshInterval: 1000, // how often to poll status changes for authenticateAndCollect and signAndCollect
  production: false, // use test environment
  pfx: "PATH_TO_TEST_ENV_PFX", // test environment
  passphrase: "TEST_ENV_PASSPHRASE", // test environment
  ca: "CERTIFICATE", // dynamically set depending on the "production" setting unless explicitely provided
};

For production, you'll want to pass in your own pfx and passphrase instead:

import { BankIdClient } from "bankid";

const client = new BankIdClient({
  production: true,
  pfx: "PATH_TO_YOUR_PFX", // alternatively also accepts buffer
  passphrase: "YOUR_PASSPHRASE",
});

PFX path

When providing a pfx path, it is expected to be based on the current working directory from where the script is run:

.
├── certs
│   └── bankid.pfx
├── src
│   └── main.js

From the current directory you would run the script with node src/main.js and provide the pfx path:

import { BankIdClient } from "bankid";

const client = new BankIdClient({
  pfx: "certs/bankid.pfx",
});

Compatibility

In Node.js v17+, OpenSSL is upgraded from v1.1.1 to v3, introducing subtle breaking changes for this library that yield this error:

Error: unsupported
    at configSecureContext (node:internal/tls/secure-context:278:15)

This is due to the legacy algorithms used to generate BankID certificates - and to handle this (until BankID updates their default certificate formats) there are two solutions.

Manual certificate modernization (suggested)

First, ensure OpenSSL v3.x needs to be installed on your machine.

Then, you can run the following commands to get an updated certificate (new.pfx):

openssl pkcs12 -in old.pfx -nodes -legacy -out combined.pem
openssl pkcs12 -in combined.pem -export -out new.pfx

Enable legacy OpenSSL support

If for any reason you do not want to modify the certificates, you can also enable the legacy OpenSSL provider when running Node.js:

node --openssl-legacy-provider ...

Deploy/Publish

In order to deploy new versions, bump the version in package.json and create a new GitHub release.

GitHub Actions should automagically release it to npm. ✨

Ownership

Repo ownership: Jeff Trinidad - @jefftrinidad29
Last audit: 2023-04-27 by @jefftrinidad29

Audit Notes

27th April 2023 by @jefftrinidad29

• Upgraded all non-critical dependencies
• yarn audit fix