Principal Architecture
The principal architecture of the BankID COI and participating components (see [WP] for details):
ERROR
Gliffy is unlicensed. Please install a license to draw diagrams in your wiki.
The following overview is oriented towards BankID merchant implementations using the Banklagret client. For details on implementing BankID on Mobile, see chapters 3.3 and 3.6.
The role of the BankID Clients
The BankID Clients offers different graphical interfaces to the end-user. This user interfaces makes the end-user able to perform authentication and signing operations when communicating with the merchant application. The different BankID Clients are presented below (note that the clients mentioned in sections Error! Reference source not found. and 2.1.2 are grouped under the common term legacy clients):
BankID on Mobile
BankID on Mobile is BankID stored in the SIM card on mobile phones. It is triggered from a web page and allows users to authenticate and sign short messages (mime-type plaintext only).
BankID Web-client
To increase readability and highlight the changes, details on how to implement the BankID Web-client, which introduces some fundamental changes compared to the legacy clients, are provided in a separate guide: BankID Web-client Implementation Guide [IMPLW]. Please refer to that document as this does not provide any further information regarding the Web-client. The Web-client was introduced as a part of the BankID 2.0-project.
BankID Client features
Below is a table showing the features available in the different legacy clients (see [IMPLW] for the features supported by the Web-client):
Feature | Client Type | |
|---|---|---|
Mobile | ||
User profile | 🗙 | |
PersonBankID | ✓ | |
AnsattBankID | 🗙 | |
Authentication | ✓ | |
Signing | Plain text | ✓ |
BankID XML | 🗙 | |
PDF* | 🗙 | |
SDO | Local storage | 🗙 |
External archive | 🗙 | |
OTP services | non Challenge-Response | 🗙 |
Challenge Response | 🗙 | |
BankID on Mobile as OTP service | 🗙 | |
Change of password | User initiated | 🗙 |
Enforced | 🗙 | |
Information to End-user | BankID last used | 🗙 |
Own certificate information | ✓ | |
Merchant certificate information | 🗙 | |
When signing large PDF document's there may be an issue where the end users device run out of memory. This is particularly the case when signing PDF on Android, as there is a wide range of devices and internal memory. As a thumb rule, try to keep the size of the PDF below 3Mb. Doing so, ensures fast loading and also enables all devices to load the PDF.
The role of the merchant’s web application
It is important to understand the responsibilities of the merchant's own web application. The main point is that there is never any communication directly between a BankID Client and a BankID server function.
All communication between a BankID Client and a merchant implementation must use HTTPS.
Authentication
The responsibility of the merchant web application during authentication is as follows:
- Determine the end-user environment.
- Configure the user session.
- Generate a web page to start the BankID Client.
- Transfer the necessary data between the client and server throughout the authentication process.
- Continue with the merchant's business logic using the acquired information about the authenticated end-user.
Signing
The responsibility of the merchant web application during signing is as follows:
- Generate the data to be signed (the format must be PDF, plain text Signing with BankID on Mobile only supports mime-type plaintext., or BankID XML XML document and XSL document in a BankID XML structure. For details see [ICSRV]/ [IJSRV].)
- In case of PDF signing and PAdES compatible PDF signature creation, the PDF data to be signed must include an empty Signature Dictionary.
- Determine the end-user environment.
- Configure the user session.
- Generate a web page to start the BankID Client.
- Transfer the necessary data between the client and server throughout the signing process.
- Continue with the merchant's business logic.
Interaction between server and client
The Banklagret client interacts with the merchant application using HTTPS communication and an encrypted BankID-specific communication over this protocol.
Note that it is the web component of the merchant that is responsible for the communication with the client. The BankID server does not perform any direct client communication.
The role of the Server API
The BankID server API is the interface through which PKI functions are made accessible to PKI aware web application software The web application is your custom made code, and is not part of BankID. The roles of BankID server API is to abstract implementation details at the PKI algorithm level and expose them in a standard way that application software can easily access. In particular, these details eliminate the need for the application developer to have extensive knowledge of PKI.
The integration of BankID server API consists of extending the web application code. The main responsibility of the web application from the BankID server API point of view is to transfer data used in authentication and signing processes between the BankID server and Client and to prepare data to be signed.
The BankID server API is stateless, and any state data that must be held during the client session must be held by the application. The sid parameter See 1.1.1Error! Reference source not found. is added for merchants to keep track of a session.