High Level Overview

Version: 1.2 updated on 2023-06-20

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 - 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.

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.

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

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

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

Scopes used in Profile API

Scope	Claims included
profile.name	given_name, family_name, middle_name
profile.titles	title_prefix and title_suffix
profile.gender	gender
profile.birthdate	birthdate, age and date_of_death
profile.birthnumber	birthnumber
profile.birthplaceNationality	birthplace, primary_nationality and nationalities
profile.maritalstatus	maritalstatus
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.paymentAccounts	paymentAccounts, paymentAccountsDetails
profile.email	email
profile.phonenumber	phone_number
profile.updatedat	updated_at
profile.legalstatus	majority, pep, limited_legal_capacity
profile.verification	verified_claims.verification
notification.claims_updated	Request for sending notifications on the update of listed claims

Scopes used in UserInfo API

Scope	Claims included
profile.name	name, given_name, family_name, middle_name, nickname and preferred_username
profile.gender	gender
profile.email	email and email_verified
profile.phonenumber	phone_number and phone_number_verified
profile.birthdate	birthdate
profile.zoneinfo	zoneinfo
profile.locale	locale
profile.updatedat	updated_at
profile.verification	verified_claims.verification
notification.claims_updated	Request for sending notifications on the update of listed claims

Claims

Legend for Source: I - IdP internal systems, S - Government registers, C - Combined data from internal systems and government registers

Scope	Claim	Source	Description
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
email	email	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	I	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

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.

There are several types of addresses, in order to fill it out correctly here are some examples:

#	city	cityarea	street	buildingapartment	streetnumber	evidencenumber
1	yes	yes	no	yes	no	no
2	yes	yes	yes	yes	no	no
3	yes	yes	no	no	no	yes
4	yes	yes	yes	yes	yes	no
5	yes	yes	yes	no	no	yes
6	yes	yes	yes	no	yes	yes

Example 1

{
  "type": "PERMANENT_RESIDENCE",
  "buildingapartment": "10",
  "city": "Libníkovice",
  "cityarea": "Borovice",
  "zipcode": "50346",
  "country": "CZ",
  "ruian_reference": "15761673"
}
Copy to clipboard

Example 2

{
  "type": "PERMANENT_RESIDENCE",
  "buildingapartment": "722",
  "city": "Rapotín",
  "street": "Zámecká",
  "cityarea": "Rapotín",
  "zipcode": "78814",
  "country": "CZ",
  "ruian_reference": "27885798"
}
Copy to clipboard

Example 3

{
  "type": "PERMANENT_RESIDENCE",
  "evidencenumber": "845",
  "city": "Brno",
  "cityarea": "Jundrov",
  "zipcode": "63700",
  "country": "CZ",
  "ruian_reference": "31179711"
}
Copy to clipboard

Example 4

{
  "type": "PERMANENT_RESIDENCE",
  "buildingapartment": "1491",
  "streetnumber": "13",
  "street": "Berlínská",
  "city": "Praha",
  "cityarea": "Hostivař",
  "zipcode": "10200",
  "country": "CZ",
  "ruian_reference": "26682826"
}
Copy to clipboard

Example 5

{
  "type": "PERMANENT_RESIDENCE",
  "evidencenumber": "194",
  "street": "Hulická",
  "city": "Praha",
  "cityarea": "Újezd nad Lesy",
  "zipcode": "19016",
  "country": "CZ",
  "ruian_reference": "22534288"
}
Copy to clipboard

Example 6

{
  "type": "PERMANENT_RESIDENCE",
  "evidencenumber": "2894",
  "streetnumber": "78",
  "street": "Červnová",
  "city": "Plzeň",
  "cityarea": "Litice",
  "zipcode": "32100",
  "country": "CZ",
  "ruian_reference": "28054717"
}
Copy to clipboard

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.