How to get started with Bank iD
Version: 1.4 updated on 13.09.2022
Anyone can try banking identity services without restrictions. The Sandbox environment is used for the first experience and development support, which includes the same services as the production environment and is freely available.
Developer portal
The Bank iD developer portal is intended for the interaction of third-party application developers with the Banking Identity services. Access to the portal's individual functions is free through an account created by simple registration. The account created by registration allows the user to personalize their applications, consumed services, and organizations. At the same time, it serves for collaboration with colleagues when working with the Banking Identity services.
How to do it?
The developer's main path is described in a few steps, from logging in to the developer portal to putting the application into operation on a production environment.
Single steps:
- Create an account
- Creating an application
- Application settings
- Obtaining credentials
- Organization creation
- Product selection
- Production environment
1. Creating an account
To create an account, you can use the "Log in" link in the portal's upper right corner. If you do not have an account yet, click on the "Register" tab. After filling out the form, a confirmation message will be sent to your e-mail.
After registration, you will receive a confirmation e-mail. Follow the instructions in the e-mail.
It is important to use the correct e-mail address.
2. Creating an application
After logging in to the developer portal, the user is redirected to the application dashboard, where he has the option to create the first application. The user is redirected directly to this dashboard after each login.
Each application in Bank iD represents the definition of its own solution for connection to the Bank Identity. The application settings allow you to define specific parameters of the consumed services. If a developer needs to access the Banking Identity from two different solutions with different data range needs, he can configure multiple applications with different settings.
As a first step in creating a new application, you need to define its name and optionally its logo. The name of the application and its logo can be changed at any time later. The application name is displayed to the end-user during the login process (on the IDP login page).
It is important to use a meaningful name of the application. We strongly suggest NOT to use company name for application name.
The created application has automatic access to the Sandbox and cannot be used in production yet. The status is signaled by a semaphore for each environment.
Green - The environment is ready to use
Yellow - the environment needs to be configured
Red - Environment not available
To configure the environment, you need to click on its name. In our case, the new app, it's Sandbox. If the application does not even have a basic configuration, you need to go to Settings from the Credentials page.
3. Application settings
Setting up the application is the most important step. The settings include:
- The configuration of application characteristics (name, URL, logo).
- Users management (invitation of additional users, permissions).
- Selection of required data.
- Configuration of technical parameters of OIDC communication.
Most parameters are preset, and the user has the option to change the values. Identical parameters can be set for the application in the Sandbox environment and Production. Different values may be used in each environment.
App settings
In the App settings section, it is possible to change the logo and the application's name within the selected environment (Sandbox, for example). This information will be displayed to the application's end-user when logging in via the selected IDP (Bank).
Most of the data is mandatory, and it is possible to use pre-filled default values for the first steps on the Sandbox. It's different for production environment, where production data has to be used in order to pass validation process before allowing application for live operation.
Open ID Connect and OAuth2 settings
Setting OIDC parameters is important for the correct function of the application. The meaning of individual parameters can be found in the documentation https://developer.bankid.cz/docs. The only required parameters for this area is Redirect URIs. Their default values can be used only to verify the result of the authentication process via the service https://oidcdebugger.com/debug. For the real function of the application, it is necessary to change the values.
Scopes
The scopes area is used to set the required data. By default, most scopes are set to "optional". Each scope has a list of included claims (data). By selecting scope, all its defined claims are required and passed.
The setting allows you to select unwanted scopes, optional scopes, and required scopes. The end-user can deny the optional scope on the consent page during the IDP authentication process, if IDP allows it. The required scope is displayed on the consent page, and the end-user can refuse to pass it only by terminating/rejecting the entire authentication process.
It is recommended to set scopes as required only if the application absolutely needs them.
It is possible to set any scope in the Sandbox. Only the scope that is part of the selected product can be used in the application at production. See Product Selection and Production Environment.
Scopes and Claims overview
Legend: Y - Always sent by IdP, O - Only sent, if IdP has the value, N - Idp does not send.
| Scope | Claim | AB | CS | CSOB | FIO | KB | MMB | RB |
|---|---|---|---|---|---|---|---|---|
| name | given_name | Y | Y | Y | Y | Y | Y | Y |
| family_name | Y | Y | Y | Y | Y | Y | Y | |
| middle_name | N | N | O | N | N | O | N | |
| nickname | N | N | N | N | N | N | N | |
| preferred_username | N | N | N | N | N | N | N | |
| phonenumber | phone_number | Y | O | Y | O | Y | O | O |
| phone_number_verified | N | O | Y | N | N | N | N | |
| Y | O | Y | O | O | O | O | ||
| email_verified | N | O | Y | N | N | N | N | |
| addresses | type | Y | Y | Y | Y | Y | Y | Y |
| street | Y | O | O | O | O | O | O | |
| buildingapartment | Y | O | O | O | Y | O | O | |
| streetnumber | Y | O | O | O | O | O | O | |
| evidencenumber | O | O | O | O | O | O | O | |
| city | Y | Y | Y | Y | Y | Y | Y | |
| cityarea | O | O | O | O | O | O | O | |
| zipcode | Y | Y | Y | Y | Y | Y | Y | |
| country | Y | Y | Y | Y | Y | Y | Y | |
| ruian_reference | N | N | O | O | O | O | O | |
| birthdate | birthdate | Y | Y | Y | Y | Y | Y | Y |
| age | Y | Y | Y | Y | Y | Y | Y | |
| date_of_death | N | N | O | O | N | N | O | |
| titles | title_prefix | O | O | O | O | O | O | O |
| title_suffix | O | O | O | O | O | O | O | |
| gender | gender | Y | Y | Y | Y | Y | Y | Y |
| birthnumber | birthnumber | O | O | O | O | O | O | O |
| birthplaceNationality | birthplace | Y | Y | Y | Y | Y | Y | Y |
| primary_nationality | N | Y | O | N | N | O | Y | |
| nationalities | Y | Y | Y | Y | Y | Y | Y | |
| birthcountry | Y | Y | Y | Y | Y | Y | Y | |
| maritalstatus | maritalstatus | O | O | O | N | O | O | N |
| idcards | type | Y | Y | Y | Y | Y | Y | Y |
| description | N | Y | O | O | N | N | O | |
| country | Y | Y | Y | Y | Y | Y | Y | |
| number | Y | Y | Y | Y | Y | Y | Y | |
| valid_to | Y | Y | Y | Y | Y | Y | Y | |
| issuer | N | O | O | O | Y | O | Y | |
| issue_date | O | N | O | N | O | O | N | |
| legalstatus | majority | Y | Y | Y | Y | Y | Y | Y |
| pep | Y | Y | Y | Y | Y | Y | Y | |
| limited_legal_capacity | Y | Y | Y | Y | Y | Y | Y | |
| paymentAccounts | paymentAccounts | Y | O | O | O | O | O | O |
| paymentAccountsDetails | O | O | O | O | O | O | O | |
| verification | trust_framework | Y | Y | Y | Y | Y | Y | Y |
| time | Y | O | O | N | O | O | N | |
| verification_process | Y | Y | Y | Y | Y | Y | Y |
Technical notes:
- birthnumber - for Czech citizens always filled
- ruian_reference - only for Czech addresses
- birthcountry - there could exceptions like "N/A" or "ZZ"
- idcards - this scope could be empty if enduser doesn't have a valid idcard due to expiration, replacement or theft
- paymentAccounts - it's not mandatory for users to have payment account in order to have Bank iD account
Technical scopes:
| Scope | Description |
|---|---|
| openid | Because Bank iD primarily uses the OpenID Connect framework, the application MUST specify this scope with each authentication request. |
| offline_access | During authentication, the application MUST specify this scope if it requests the release of a refresh_token. |
| zoneinfo | End-user's timezone. |
| locale | End-user's preferred language. |
| updatedat | Date and time of last update. |
Advanced settings
Advanced application settings allow you to select the preferred method of token exchange authorization within the OIDC (OAuth2) flow.
It is recommended to choose the parameters according to the application's character and possibilities and the required level of communication security.
Save settings
All changes to the application settings need to be applied by button "Apply". At the bottom of the screen, the user has the option to review the changes and use the menu to confirm or reject (discard) the change.
After applying the changes, "credentials" are created for the new application and the user is redirected to their overview.
4. Obtaining credentials
The credentials page contains information important for integrating the application with the Banking Identity.
The information on the page includes client_id (unique to the application) and client_secret (unique to the application and environment), which the application uses to communicate with the Bank identity.
The OIDC Discovery drop-down area lists all the URLs needed for the environment.
The Authorization URI example contains an application-personalized link that can be used to verify application functionality.
5. Organization creation
The next required step is Organization creation. Currently, it is a matter of filling in the form with the request to establish the organization, which is available from the App Settings.
After sending the form, Bank iD will check the form data and prepare the contracts which needs to be signed by both parties. Issuance of an invoice and payment of the activation fee.
As soon as the organization is established, the user is informed by e-mail with an organization's invitation. At the same time, it is possible to connect a specific application to the created organization in the App Settings.
6. Product selection
In order for the application to function in production environment it is required to have a product selected. You can go to the product selection by choosing Products in the left panel of the application screen.
The product is selected by choosing the required data and at the bottom of the screen by selecting Payments for calls and Payments per user, where you can compare the prices of payment options.
The selected product limits available Scopes in the production environment. In the Sandbox environment, it will only appear as information about the restriction of data collection outside the selected product.
7. Production environment
Once all the previous steps are done, it is possible to configure the application for production environment. The Production Environment settings are similar to those in the Sandbox.When setting, it is necessary to carefully check all entered parameters' content so that the preset default values do not remain somewhere. Parameter settings can be changed at any time. It is necessary to keep in mind that every change will be reflected in the application's function.
Each application must be approved by Bank iD for access to the production environment, just fill out the form and after checking by Bank iD, access will be allowed.
The application's Credentials page then lists specific production values, including a list of URIs from the Bank iD OIDC.
The production value of client_secret needs to be well protected!