High Level Overview for Service Providers
Version: 1.2 updated on 14.06.2022
This document provides a bird's-eye overview of the Bank iD 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 Bank iD technical specification.
Glossary
- 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.
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.
Bank iD system actors
- Bank - An entity which provides authentication and KYC services.
- End-User - A person 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 credentials 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.
Identity Providers supported by Bank iD
The list is continuously updated.
Legend: Y - Supports, N - Not currently supported.
| AB | ČS | ČSOB | KB | MMB | RB | FIO | CRD | |
|---|---|---|---|---|---|---|---|---|
| From what age is a bank identity issued | 15 | 7 | 18 | 15 | 15 | 15 | 15 | 15 |
| Service CONNECT | Y | Y | Y | Y | Y | Y | Y | Y |
| Service IDENTIFY (PLUS and AML) | Y | Y | Y | Y | Y | Y | Y | Y |
| Service SIGN (sign one PDF) | Y | Y | Y | Y | Y | Y | Y | N |
| Service SIGN (sign multiple PDF) | N | Y | Y | Y | Y | Y | Y | N |
| Service SIGN (sign object) | Y | Y | Y | Y | Y | Y | Y | N |
| Notifications | N | Y | Y | Y | Y | Y | N | N |
| Ability to use Bank iD by disponents | N | Y | Y | Y | Y | Y | Y | Y |
| Ability to use Bank iD for foreigners with idcards with MRZ issued in CZ | Y | Y | Y | Y | Y | Y | Y | Y |
| Ability to use Bank iD for foreigners with idcards without MRZ issued in CZ | N | N | N | N | Y | Y | Y | N |
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:
- Bank iD APIs for APIs exposed by Bank iD to be consumed by SeP
- SeP RP front/back-channel APIs for APIs exposed by a SeP to be consumed by Bank iD
- Bank iD Authorization APIs for APIs exposed by Bank iD for SeP to ensure the start of document signing
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.
List of scopes and claims offered through Bank iD
Scopes used in KYC - 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, city, zipcode, country and ruian_reference |
| profile.idcards | type, description, country, number, valid_to, issuer and issue_date |
| profile.paymentAccounts | paymentAccounts |
| profile.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.email | email and verified_email |
| 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 |
Security considerations
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.
UX considerations
To use the buttons and texts associated with Bank iD, it is necessary to follow the style guide and UX guide lines. Bank iD allows customization of the IdP selection page in the SeP environment. All documents are in our UX manual.
End-user identification
Unique end-user identification
The system for unique identifier is not currently running.
Sector Identifier URI usage
Bank iD uses pairwise subject identifiers, therefore each end user will have a unique sub (subject) identifier for each Service Provider, based on a Sector Identifier. The Sector Identifier is the host component (domain) of the Sector Identifier URI. If no Sector Identifier URI is provided, the Sector Identifier is the host component (domain) of the registered Redirect URI. If there are multiple hostnames in Redirect URIs, you are required to provide a Sector Identifier URI.
If you wish to have consistent sub identifiers across multiple apps with distinct hostnames in Redirect URIs, you can use a common Sector Identifier URI to unify the Sector Identifier of the apps. This Sector Identifier URI must point to an endpoint returning a JSON array of all Redirect URIs used in all apps which use this Sector Identifier URI. This URI along with JSON file has to be accessible from our portal.
Example: I want to have matching sub identifiers in App1 (Redirect URI https://app1.123.com/callback) and App2 (Redirect URI https://app2.123.com/callback). I will set Sector Identifier URI to https://example.com/sector.json in both apps. sector.json will contain the following JSON:
[
"https://app1.123.com/callback",
"https://app2.456.com/callback"
]Front and back channel logout
Both logout modes are supported as specified in the OpenID.FrontChannel and OpenID.BackChannel documents.
SLA service
Implementation guide for marking requests with a unique identifier and levering SLA offer.
Unique identifier for organization
If your company has requested SLA offering and business matters were settled, in your organization and linked applications will have in configuration special field for unique organization identifier. If this is present in http headers of your request or if that's not possible as request param in URL. This identifier must not be shared with other organizations and in case of infringements, Bank iD will suspend SLA offering until issue is resolved.
We assume that this identifier will be reused in future for other services if needed.
Technical details for implementation
For API endpoints (/ros, /token, /.well-known/*, /profile, /userinfo, ...) following header MUST be included in HTTP headers under header X-Sep-identifier. Example:
POST /token HTTP/1.1
Host: bankid.cz
Content-Type: application/x-www-form-urlencoded
X-Sep-identifier: f8ba33de-4ca8-4a11-a251-867cd3e3b41b
grant_type=authorization_code
&code=8BFAC1DA-3F94-4BBD-A743-473080FB6073
&redirect_uri=https://serviceprovider.cz/callback
&client_secret=368b8099c14c0964a4a9f958c8b5786c46845ec1
For redirected endpoints (/auth) identifier MUST be included as another parameter in URL Example:
GET /auth?
redirect_uri=https://serviceprovider.cz/callback
&client_id=589b7c53-c0bf-4f6d-8fee-c6972c5d88bf
&response_type=code
&scope=openid%20profile.name%20profile.gender
&state=main002
&sep_id=f8ba33de-4ca8-4a11-a251-867cd3e3b41b
Host: bankid.cz