High Level Overview
Version: 1.1 updated on 2022-05-05
This document provides a bird's-eye overview of the Bank iD system, its technical goals, decisions and related motivations. This document should provide a starting point for Bank developers wishing to achieve compliance with the Bank iD technical specification.
- SeP - Service Provider - A third party which is registered in the Bank iD 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 Bank iD, and for Bank iD, it is the Service Provider.
Bank iD 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 Bank iD to get additional Bank-verified information about the End-User.
- Bank iD - A service that sits between the SeP and the Bank.
What is Bank iD?
Bank iD acts as a middleman, between the Service Provider (SeP) and the End-User's Bank. Bank iD 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 Bank iD 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 Bank iD on a technical level?
Bank iD 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 and Authorization APIs for APIs exposed by Bank to be consumed by Bank iD
- Bank iD back-channel APIs for APIs exposed by Bank iD 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 Bank iD 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 Bank iD 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 Bank iD decides for the Bank what the SeP can do with End-User's data
- The Bank iD 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?
Please see the Bank iD API endpoint overview for a detailed technical description.
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 Bank iD 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 Bank iD
Scopes used in 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, evidencenumber, city, cityarea, 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|
Legend for Source: I - IdP internal systems, S - Government registers, C - Combined data from internal systems and government registers
|name||given_name||S||Given name of a physical person, should always be present|
|family_name||S||Family name of a physical person, should always be present|
|middle_name||S||Middle name of a physical person, seldomly used|
|nickname||I||Nickname used by a physical person|
|preferred_username||I||Preferred username used by physical person|
|phonenumber||phone_number||I||Phone number of a physical person without spaces and with country prefix +420123456789, usually present|
|phone_number_verified||I||If the number has been verified by the IdP|
|I||E-mail of the a physical person, usually present|
|email_verified||I||If the e-mail has been verified by the IdP|
|addresses||type||I||If the address type is Permanent residence, it's from government registers. If it's contact address, it's from IdP internal systems|
|street||C||Street is usually present, for small villages unused|
|buildingapartment||C||Buildingapartment is usually present, for small houses unused|
|streetnumber||C||Streetnumber is usually present, for small villages unused|
|evidencenumber||C||Evidencenumber is rarely used in suburbs|
|city||C||City should always be present|
|cityarea||C||City area is usually present|
|zipcode||C||Zip code should always be present|
|country||C||Country should always be present|
|ruian_reference||C||RÚIAN reference is usually present for Czech addresses|
|birthdate||birthdate||S||Birth date of the physical person, should always be present|
|age||I||Age of a physical person derived from birthdate by IdP, should always be present|
|date_of_death||S||Date of death of the physical person|
|titles||title_prefix||I||Title prefix of the physical person, seldomly used|
|title_suffix||I||Title suffix of the physical person, seldomly used|
|gender||gender||I||Gender of the physical person, should always be present|
|birthnumber||birthnumber||S||Birthnumber given by Czech Government, should always be present for Czech Citizens|
|birthplaceNationality||birthplace||S||Birthplace of a physical person, should always be present|
|primary_nationality||I||Primary natinality of the physical person, seldomly used|
|nationalities||S||A list of nationalities of the physical person, should always be present|
|birthcountry||S||Birth country of the physical person, should always be present|
|maritalstatus||maritalstatus||I||Marital status of the physical person, optional|
|idcards||type||S||Type of the document corresponding to the government registers, should always be present|
|description||I||Description of the document used by IdP, optional|
|country||S||Issuing country of the document, should always be present|
|number||S||Number of the document, should always be present|
|valid_to||S||Expiration date of the document, should always be present|
|issuer||S||Issuing government body, optional|
|issue_date||S||Issue date of the document, optional|
|legalstatus||majority||S||Legal majorty status of the physical person, should always be present|
|pep||I||Politically exposed person status according to Anti-money laundering laws in Czech republic, should always be present|
|limited_legal_capacity||S||Status for people with limited legal capacity, should always be present|
|paymentAccounts||paymentAccounts||I||List of payment accounts physical person has in IdP as owner, optional|
|paymentAccountsDetails||I||List of payment accounts and currency physical person has in IdP as owner, optional|
|verification||trust_framework||I||Anti-money laundering framework used by IdP's "cz_aml", should always be present|
|time||I||Time stamp in ISO 8601:2004 [ISO8601-2004] YYYY-MM-DDThh:mm[:ss]TZD format representing the date and time when the physical identity verification process took place for audit purposes, optional|
|verification_process||I||Contains a company identification number of IdP, that completed the physical identity verification process, should always be present|
|updatedat||updated_at||I||Time when any of the scopes provided via Bank iD was last updated. Value in seconds from 1970-01-01T0:0:0Z, should always be present|
|locale||locale||I||Preferred language of the physical person for better presentation of interface like "cs_CZ", should always be present|
|zoneinfo||zoneinfo||I||Representation of a physical person's time zone like "Europe/Prague", should always be present|
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 Bank iD, a high level of security is required.
See the Security guideline for recommended security practices when implementing the Bank iD solution.