High Level Overview for Service Providers

Version: 1.0

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.

Glossary

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

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:

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 BankID

Scopes used in KYC - Profile API

ScopeClaims included
profile.namegiven_name, family_name, middle_name
profile.titlestitle_prefix and title_suffix
profile.gendergender
profile.birthdatebirthdate, age and date_of_death
profile.birthnumberbirthnumber
profile.birthplaceNationalitybirthplace, primary_nationality and nationalities
profile.maritalstatusmaritalstatus
profile.addressesaddresses.type, addresses.street, addresses.buildingapartment, addresses.streetnumber, addresses.city, addresses.zipcode, addresses.country and ruian_reference
profile.idcardsidcards.type, idcards.description, idcards.country, idcards.number, idcards.valid_to, issuer and issue_date
profile.paymentAccountspaymentAccounts
profile.emailemail
profile.phonenumberphone_number
profile.updatedatupdated_at
profile.legalstatusmajority, pep, limited_legal_capacity
profile.verificationverified_claims.verification
notification.claims_updatedRequest for sending notifications on the update of listed claims

Scopes used in UserInfo API

ScopeClaims included
profile.namename, given_name, family_name, middle_name, nickname and preferred_username
profile.gendergender
profile.emailemail and verified_email
profile.phonenumberphone_number and phone_number_verified
profile.birthdatebirthdate
profile.zoneinfozoneinfo
profile.localelocale
profile.updatedatupdated_at
profile.verificationverified_claims.verification
notification.claims_updatedRequest for sending notifications on the update of listed claims

Security considerations

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.

Front and back channel logout

Both logout modes are supported as specified in the OpenID.FrontChannel and OpenID.BackChannel documents.

Cookies are bad for your teeth but good for BankID • Cookie policy