How to integrate with eID Hub - Swedish BankID
Overview
For a general overview of the integration process see How to integrate with eID Hub. It describes the steps that have to be done to integrate with any eID. This guide goes more into details specifically for the integration with Swedish BankID.
Authentication / Signing flow
Swedish BankID can be used in different ways:
- For the authentication or signature of an unknown user
- If performed on desktop the user can either scan a QR code or enter their personal number
- If performed on mobile the user is directly taken to the BankID app
- For the identity verification or signature of a known user
- If performed on desktop an additional security measure could be added, so that the user needs to scan a QR code (to avoid certain types of fraud)
For all of the above scenarios one can either use eID Hub frontend, which facilitates the display of QR code, the entering of the personal number and the transaction to the BankID mobile app, or by only using eID Hub API and then, depending on the scenario one might need to implement a custom frontend.
| eID Hub | eID Hub - API only | |
| Unknown user | Enter PN / Scan QR / Proceed to the app | Custom UI is needed |
| Known user | Optionally scan QR for better security | Custom UI is needed in case one wishes for better security |
A better security level is assured by setting requireAutoStartToken parameter. When set, mobile app cannot be started without the so-called autoStartToken, which means that either one is performing the process on the same device, or one has to scan a QR code.
The whole authentication or signing process is performed in three steps:
- Create a new transaction with parameters. BankID-specific parameters are the personal number,
requireAutoStartToken, user visible data (mandatory for signing) and user non-visible data. See API documentation for details.
| eID Hub | eID Hub - API only | |
| 2. | Redirect the end-user to accessUrl returned by the above call. |
Start the transaction, extract autoStartToken from the response, use it in custom UI for end user. More information could be found in BankID documentation. |
| 3. | Query transaction completion data once the user is redirected back to you to redirectUrl. |
Poll transaction status and completion data. |
UI customization
Each company needs to have a display name that equal to the company name or is associated with the company for users. Usually it’s ordered when signing a contract with us, however it can also be changed later if necessary.
Apart from the display name, some UI elements can be customized too, when using eID Hub frontend. The frontend page, accessible at accessUrl, looks like the following image. The background color, logo and page title are customizable.
Please contact our support if you want a customization.
Authentication / Signing response
The data returned by BankID is the same for both authentication and signing:
- Personal user data (names, personal number)
- Device IP where BankID application was used
- Signature (in XML-DSig format, Base64 encoded)
- OCSP response (Base64 encoded)