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.
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.
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 - 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.
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.
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
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#
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.
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.
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.
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.1Host: bankid.czContent-Type: application/x-www-form-urlencodedX-Sep-identifier: f8ba33de-4ca8-4a11-a251-867cd3e3b41bgrant_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-867cd3e3b41bHost: bankid.cz