Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/anyfin/bankid
npm module to simplify integration with the Swedish Bank ID service for user authentication and signing processes.
https://github.com/anyfin/bankid
bankid javascript sweden
Last synced: 29 days ago
JSON representation
npm module to simplify integration with the Swedish Bank ID service for user authentication and signing processes.
- Host: GitHub
- URL: https://github.com/anyfin/bankid
- Owner: anyfin
- License: mit
- Created: 2016-12-18T21:08:05.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2024-10-21T11:45:57.000Z (about 2 months ago)
- Last Synced: 2024-10-23T13:34:33.786Z (about 2 months ago)
- Topics: bankid, javascript, sweden
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/bankid
- Size: 220 KB
- Stars: 66
- Watchers: 25
- Forks: 26
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-sweden - JavaScript
README
# bankid
A npm module to simplify integration with the Swedish [Bank ID](https://www.bankid.com/en/) service for user authentication and signing processes.
## Installation
```sh
# If you prefer npm
npm install --save bankid
# If you prefer yarn
yarn install bankid
```
## Usage V6
```javascript
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](./examples)
## Usage V5
```javascript
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](https://www.bankid.com/assets/bankid/rp/bankid-relying-party-guidelines-v3.5.pdf),
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:
```javascript
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:
```javascript
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:
```javascript
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:
```javascript
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`):
```sh
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:
```sh
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](https://github.com/jefftrinidad29) \
Last audit: 2023-04-27 by [@jefftrinidad29](https://github.com/jefftrinidad29)
# Audit Notes
> 27th April 2023 by @jefftrinidad29
- Upgraded all non-critical dependencies
- yarn audit fix