High Level Overview
Version: 1.1 updated on 2022-05-05
This document provides a bird's-eye overview of the BankID system, its technical goals, decisions and related motivations. This document SHOULD also provide a starting point for Bank implementors wishing to achieve compliance with the BankID technical specification.
- SeP - Service Provider - A third party which is registered in the BankID system and intends to consume Bank APIs
- PII - Personally Identifiable Information - End-User information like name, email address or state-issued IDs
- AML - Anti-Money Laundering - A set of laws and regulations intended to prevent money laundering
- KYC - Know Your Customer - A Bank API which allows SePs to gather information about End-Users
- IDP - Identity Provider - A component on the side of the Bank which handles authorization and consent and issues tokens
- RP - Relying Party - RP is a party using the provider's identity services. From the bank's point of view, the Relying Party is BankID, and for BankID, it is the Service Provider.
How to read this document
The CAPITALIZED words throughout these guidelines have a special meaning as defined in RFC2119:
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.
BankID system actors
- Bank - An entity which provides authentication and KYC services.
- End-User - A person (or legal entity) that has an account in the Bank and wants to use it for authentication.
- Service Provider (SeP) - A Third party which provides service to the End-User. Uses BankID to get additional Bank-verified information about the End-User.
- BankID - A service that sits between the SeP and the Bank.
What is BankID?
BankID acts as a middleman, between the Service Provider (SeP) and the End-User's Bank. BankID gives the user an option to authenticate against the SeP using their Bank account and later allows the SeP to acquire Bank verified data and Personally Identifiable Information (PII) of the End-User.
The main goals of the BankID system are:
- To streamline authentication experience for the End-User during initial registration into the SeP with the End-User's pre-existing Bank account.
- To allow Service Providers access to Bank-verified personal data for
- Authorization - for example: Is the End-User over 18 years of age? Can I sell them alcohol?
- PII verification - Is this End-User who they claim they are?
- Compliance with Anti-Money Laundering (AML) laws and regulations through the use of Know Your Customer (KYC) API.
- To give Banks an additional revenue stream using easily interoperable and monetized APIs, which will decrease SeP's barrier for entry and thus increase usage of the monetized KYC (or other) APIs exposed by the Banks.
What is BankID on a technical level?
BankID exposes two sets of REST interfaces - one for Banks and one for Service Providers. These are based on the OpenID Connect and OAuth2 specifications. The specification is followed as closely as possible to allow for easy interoperability with existing solutions and code - which SHOULD decrease overall development and maintenance costs.
The APIs are described using a set of OpenAPI specifications, namely:
- IDP Authentication APIs for APIs exposed by Bank to be consumed by BankID
- IDP Authorization APIs for APIs exposed by Bank IDP to ensure transaction authorization
- BankID back-channel APIs for APIs exposed by BankID to be consumed by Bank
High level technical decisions
Why use standards instead of making a custom-tailored solution?
- Use of open standards such as OpenID Connect and OAuth2 allows all parties to decrease integration costs by reusing existing code and solutions.
- Use of well defined standards removes most ambiguity and simplifies technical communication.
- Technical communication is easier as all parties can reference the open standard and use language and technical terms defined in the standard.
Why is it important to aim for maximal standard compliance?
- Full standard compliance allows for existing solutions and code to be used with minimal modification.
- It reduces the quantity of bugs caused by misunderstood specification and wrong assumptions.
- Low standard compliance may result in nasty surprising bugs that stem from code and solutions assuming standard compliance when that is not the case. These can be costly.
Why were OpenID Connect and OAuth2 selected as the standards to follow?
- OAuth2 is a very well established authorization framework that is used by most high profile players in the IT vertical. These companies include Google, Microsoft, Facebook, Twitter, LinkedIn and many others. This implies a vast quantity of available tooling, code and solutions - Open Source or otherwise.
- OpenID Connect is an identity layer on top of OAuth2 which improves on security and provides additional features such as discovery and session management. OpenID Connect is a relatively newer protocol; it is, however, well thought out and already in use by most of the companies above.
Why is dynamic registration required?
One of the APIs that Banks need to implement is dynamic registration. The purpose of this API is to dynamically register the SeP into the Bank's systems. This is required because:
- This gives the Bank intelligence as to which Third Parties it does business with
- It allows the Bank to properly display the consent screen to the End-User, including SeP specific branding, logo and TOS link.
- It gives control over the consent screen into the hands of the Bank, rather than to the RP.
- It allows the Bank to be standard-compliant.
- It gives the Bank the possibility to use an already existing OpenID Connect or OAuth2 middleware in front of its IDP; this way, the Bank can just slightly modify an existing solution, rather than implement a custom one.
Which hypothetical alternatives to dynamic registration would there be?
All of the following solutions are not standard-compliant and thus incur costs mentioned above.
- The BankID MAY expose additional back-channel APIs which would provide branding information for the consent screen.
- This would force the Bank to make additional calls and thus slow down the authentication process
- The Bank would need to fully implement this new non-standard protocol
- It would only increase development costs for the Bank, since the Bank would still need to keep all the branding information, but now there would be an additional step to reacquire it during each authorization
- The Bank would not be directly notified of branding changes
- The BankID MAY stream branding updates over some other non-standard back channel like a Kafka queue
- This would be exactly the same as the standard-compliant solution in the sense that the Bank would keep all the branding information
- It would introduce another moving part, the queue server, which would need to be managed and maintained
- In conclusion, it would break the standard for no additional benefit
- The Bank MAY handle the authentication only and let the Bank handle the consent screen
- This gives control over the consent screen to the Bank
- It is less secure since now the BankID decides for the Bank what the SeP can do with End-User's data
- The BankID would have to propagate this authorization information into the Bank, which would need to validate it
What does your Bank need to implement to be compliant?
Broadly speaking, as a Bank you will need to implement an OpenID Connect wrapper around your Identity Provider (IDP). This wrapper will need to conform to the BankID specification. It will therefore provide:
- A Dynamic registration API - this API will allow SePs to register into your identity system
- A Discovery API - this is a set of well-known endpoints which are there for auto configuration and URL discovery. It allows you flexibility regarding endpoint locations, encryption algorithms and more. It also allows you to easily rotate encryption keys.
- Authorization and token exchange APIs - These are well specified OAuth2/OpenID Connect APIs which serve the core authentication
- A Token revocation API - For RP originated logouts
- A HealthCheck API - For liveness and outage information
Your solution will also need to have the following capabilities:
- Call RP Logout API - The Bank will call this API when the End-User has removed their consent for a SeP in the Bank's Internet Banking
- Download RP encryption keys; URL of these is delivered during dynamic registration
- Encrypt and validate JSON Web Tokens (JWTs) - These enhance security and are prescribed in the OpenID Connect specification
- Setup Mutual TLS channel to the RP
- Properly use and verify Public Key Infrastructure (PKI) certificates
List of scopes and claims offered through BankID
Scopes used in KYC - Profile API
|profile.name||given_name, family_name, middle_name|
|profile.titles||title_prefix and title_suffix|
|profile.birthdate||birthdate, age and date_of_death|
|profile.birthplaceNationality||birthplace, primary_nationality and nationalities|
|profile.addresses||type, street, buildingapartment, streetnumber, city, zipcode, country and ruian_reference|
|profile.idcards||type, description, country, number, valid_to, issuer and issue_date|
|profile.legalstatus||majority, pep, limited_legal_capacity|
|notification.claims_updated||Request for sending notifications on the update of listed claims|
Scopes used in UserInfo API
|profile.name||name, given_name, family_name, middle_name, nickname and preferred_username|
|profile.email||email and email_verified|
|profile.phonenumber||phone_number and phone_number_verified|
|notification.claims_updated||Request for sending notifications on the update of listed claims|
Filling amr values
In order to fill correct amr values according to RFC8176, here is a guideline on how to fill them:
|Type of authentization||amr values|
|Login, Password, SMS||mfa, pwd, sms|
|Login, Password, Software Key||mfa, pwd, swk + pin or face or fpt|
|Login or QR code, Software Key||mfa, swk + pin or face or fpt|
|Certificate, PIN||mfa, sc, pin|
Software Key is either dedicated app for authorization or combined app for authorization and mobile banking. If you cannot identify which type of biometrics is used in your Software Key, use fpt.
Due to the nature of the information provided by BankID, a high level of security is required.
See the Security guideline for recommended security practices when implementing the BankID solution.