The CAPITALIZED words throughout these guidelines have a special meaning as defined in RFC2119:
The keywords "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.
Request object - Object representing action which requires end-users consent.
Authorization - If not explicitly stated otherwise, in context of this document Authorization is defined as voluntary and conscious consent with action represented by object
IDP - Identity Provider - A component on the side of the Bank which handles authorization (in OpenID Connect sense) and consent and issues tokens
Authorization server - A component on the side of the Bank with handles request objects, and their authorization by end user
OIDC - OpenID Connect - An authentication framework, it is a superset of the OAuth2 authorization framework
RP - Relying Party - An OpenID Connect a middleman and orchestrator which sits between Service Providers and Banks - Bank iD
JWT - JSON Web Token - A Base64 encoded, signed and possibly encrypted JSON document
JWK - JSON Web Key - A JSON describing keys for JWT encryption, description, signing and verification
The following endpoints are to be implemented by the Bank to be compliant with the Bank iD system.
Each of these endpoints only contains illustratory examples. Please see the referenced OpenAPI documents for a full authoritative description of these resources.
Exposed by the Bank. Authoritatively described in idp_for_bankid.yaml. Not authenticated.
This endpoint provides information about OpenID Connect configuration.
The values given in the configuration response should strictly correspond to reality. According to the declared values, Bank iD registers applications to IDP (parameter values) and calls individual endpoints.
Exposed by the Bank. Authoritatively described in idp_for_bankid.yaml. Not authenticated.
This endpoint returns the current Bank liveness and outage information.
HealthCheck MUST describe the current system availability (OK|ERROR). This information is required for:
This information is presented to the End-User, possibly in a derived form, or form that is aggregated from multiple Banks at once
This information is needed to prevent unnecessary failing calls to the Bank APIs, this lightens the load of failing Bank APIs (which may be failing due to high load) and minimizes chance of data loss and corruption
Outage
In the context of Bank iD specification, an outage is a state of the system which is unavailable due to a planned or unplanned maintenance. The Bank SHOULD communicate outage end-time, when available, through the outage_planned_until property.
Design of this API is intended to allow automatic propagation of the outage information from internal Bank systems into the Bank iD RP.
Sub-system outages
It is possible that a only part of the system is experiencing an outage, however the rest remains fully operational. For this reason the HealthCheck Endpoint SHOULD implement the details property whenever possible.
Sub-system health information allows the Bank iD and SeP to only stop processes which are dependent on the failing services keep the rest operational if possible.
Differences between Bank iD HealthCheck and COBS RuleBook HealthCheck
outage_description has been added. The Bank SHOULD use this property to communicate the reason for the current outage
details property has been updated to reflect Bank iD sub-systems
poll_interval has changed from free-form string into a number specified in milliseconds to prevent ambiguity
CRUD over registered clients. Protected by mTLS and HTTP Bearer authentication where bearer token is a JWT
signed with a key from /.well-known/jwks.json of the Bank iD. This JWT contains claims defined in the RegistrationAuthJWT schema.
Example of RegistrationAuthJWT payload. This token is sent in signed form as the value of the client_assertion request header parameter:
For dynamic registration, the aud parameter in the RegistrationAuthJWT payload always contains the URL of the POST endpoint of the called registration API (ie, also in the case of the PUT, GET and DELETE methods).
Exposed by the Bank. Authoritatively described in idp_for_bankid.yaml. Uses HTTP Bearer authentication using a JWT token signed on the Bank iD side. See the RegistrationAuthJWT specification..
POST (create) /register
GET (read), PUT (update), DELETE (remove) /register/{client_id}
POST /register HTTP/1.1Host: idp.somebank.czContent-Type: application/jsonclient_assertion: eyJraWQiOiJycC1zaWduIiw......7xpA26QF5_Oung7E4y2n6client_assertion_type: urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearerAuthorization: Bearer 44010DFF-F77F-461A-8F3D-1466B24C5CC1
Please note that the authorization_access_token value obtained in the POST call must be here sent as a Bearer token
in the Authorization header parameter.
For Service providers, Bank iD supports various Authentication flow types of grants for the authentication process and obtaining access_token and id_token.
Flow type
Description
authorization_code refresh_token
Code grant is the most common authentication flow. It allows applications to securely exchange tokens and obtain a refresh_token in case of offline access.
implicit
No matter what type of grant the Service Provider has chosen for its application, all calls to the IDP are made by Bank iD within the code grant flow!
The sequence diagram shows the course of the authentication flow with the exchange of
code for tokens. In the case of offline access, the chart is supplemented by an example of exchanging a refresh token for an access token.
The authentication GET endpoint is a starting point for OAuth2 and OpenID Connect authorization code flows. This request authenticates the user and returns tokens to the client application as a part of the callback response.
Exposed by the Bank. Authoritatively described in idp_for_bankid.yaml. Not authenticated.
GET /auth? redirect_uri=https://bankid.cz/callback &client_id=D40D25DB-C330 &response_type=code &state=1234 &scope=openid%20profile.name%20profile.gender%20offline_accessHost: somebank.cz
Scope openid is required! In the context of its use, it is specified that the authorization flow control will be a
process established by the OpenID standard (e.g., including the issuing of id_token).
The scope offline_access should be specified whenever the application, based on the authentication flow, requires the
release of not only access_token but also refresh_token. For such a case, the application must have registered
code grant flow and refresh_token grant (during dynamic registration to the IDP).
Token representing offline (long-term) access. Refresh_token is used to release a new short-term access_token.
1 year
id_token
This token was identifying the end-user within the current context and session.
At least as long as access_token (3600 seconds)
Basic assumptions:
The issuance of these tokens MUST be independent of the context of previous and future authentications.
The authentication process MUST not affect the validity of previously issued tokens. Except in specific
cases where the authentication process will be evaluated as a security risk and, for example, if the authentication
device will be temporarily or permanently blocked.
The authentication process MUST do not affect the context (scopes) of previously issued tokens.
Any token CAN be invalidated with immediate effect using the mechanisms provided for this purpose (revoke, logout services).
Whether an application has a scope registered as optional or required has no effect on the scopes' final composition
in the token. Suppose the application does not require any of the required registered scopes in a specific
authentication. In that case, this scope will not appear either on the consent screen or during successful
authentication at the token. The scope obligation only affects the GUI controls on the consent screen.
The access_token is the main result of the authentication process. This token is used to call user-centric
APIs (primarily /userinfo and /profile). In the case of Bank iD, it may be a signed stateless token.
The access_token hash can be specified as one of the id_token claims (specifically at_hash claim), which is issued
simultaneously with the access_token to ensure integrity.
This token's validity can be found directly at issue in response (authorization_code and refresh_token grant flow)
to the API /token or call the API /token-info. The response to the call /token MUST also include a list of
scopes for the issued token.
Refresh_token is used to issue a new access_token, for example, if the access_token expires. Refresh_token is issued
if the application requesting its release has a refresh_token grant registered with the IDP and
the application asked for an offline_access scope in the authentication request.
The scope of this token's context corresponds to the result of the authentication at which it was issued. When
exchanging refresh_token for access_token, the application can request the same or smaller range of scopes.
The id_token represents the identification of the end-user and is issued together with the access_token. The id_token
is always signed and contains information about the time of issue and validity of the token. In the case of Bank iD,
it always contains the end-user identifier as a claim sub.
The id_token is issued signed by the issuer's key, and the application must verify this signature in each case.
The id_token can be issued in encrypted form if this IDP declares in its configuration. Encryption is performed using
one of the application's public encryption keys (listed on the registered JWKs URI). Bank iD does not directly require
this feature (because the required id_token does not contain any sensitive data).
The token endpoint is used by the client to obtain an access token by
presenting its authorization grant or refresh token.
To clarify the usage of token exchange API here are a few scenarios which could take place one after another:
Scenario 1 code exchange
SeP requires these scopes "openid profile.name profile.idcards offline_access" in /auth
IdP shows consent screen
SeP exchanges code for access_token
SeP calls /profile with access_token and receives data from IdP
Scenario 2 code exchange with less scopes
SeP requires these scopes "openid profile.name profile.idcards" in /auth
IdP may not show consent screen
SeP exchanges code for access_token
SeP calls /profile with access_token and receives data from IdP
Scenario 3 code exchange with more scopes
SeP requires these scopes "openid profile.name profile.idcards profile.address offline_access" in /auth
IdP shows consent screen, because consent for profile.address was not given by enduser
SeP exchanges code for access_token
SeP calls /profile with access_token and receives data from IdP
Scenario 4 code exchange
SeP requires only "openid" in /auth
IdP may not show consent, if for all registered scopes via /register endpoint has been given consent by enduser, otherwise it has to show consent screen
SeP exchanges code for access_token and IdP assigns for this access_token all scopes registered via /register endpoint eg. "openid profile.name profile.idcards profile.address offline_access"
SeP calls /profile with access_token and receives data from IdP
Scenario 5 refresh_token exchange
SeP exchanges refresh_token for access_token with scopes "openid profile.name profile.idcards profile.address profile.email"
IdP returns error, because profile.email is not assigned with current refresh_token
Scenario 6 refresh_token exchange
SeP exchanges refresh_token for access_token and doesn't specify any scope
IdP returns access_token with assigned scopes from previous refresh_token, IdP may include new refresh_token with the same expiration as previous refresh_token in which case previous refresh_token has to be discarded
Scenario 7 refresh_token exchange
SeP exhanges refresh_token with scope "openid"
IdP returns access_token with assigned only "sub"
SeP calls /profile a gets only "sub" and txn will have only "openid"
Scenario 8 refresh_token exchange
SeP exhanges refresh_token with scope "openid profile.name profile.idcards"
IdP returns access_token with assigned scopes which are subset of scopes assigned to the refresh_token
SeP calls /profile with access_token and receives data from IdP
Exposed by the Bank. Authoritatively described in idp_for_bankid.yaml. Uses client credentials for authentication.
POST /token HTTP/1.1Host: idp.somebank.czContent-Type: application/x-www-form-urlencodedgrant_type=authorization_code&client_id=2a54acba-f5d8-48cb-9c28-a06583724adb&code=8BFAC1DA-3F94-4BBD-A743-473080FB6073&redirect_uri=https://bankid.cz/callback&client_assertion=eyJraWQiOiJycC1zaWduIiw......7xpA26QF5_Oung7E4y2n6&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
Client assertion JWT payload for /token endpoint example:#
POST /token HTTP/1.1Host: idp.somebank.czContent-Type: application/x-www-form-urlencodedgrant_type=refresh_token&scope=openid%20profile.name%20profile.addresses&code=A9B54609-FF9E-42F0-B089-89E1E73E224F&redirect_uri=https://bankid.cz/callback&client_assertion=eyJraWQiOiJycC1zaWduIiw......7xpA26QF5_Oung7E4y2n6&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
Client assertion JWT payload for /token endpoint example:#
The introspection endpoint is an OAuth 2.0 endpoint that takes a parameter representing an OAuth 2.0 token and returns a JSON representing the meta information surrounding the token, including whether this token is currently active.
Exposed by the Bank. Authoritatively described in idp_for_bankid.yaml. Uses client credentials or a client access token for authentication.
POST /token-info HTTP/1.1Host: idp.somebank.czContent-Type: application/x-www-form-urlencodedclient_id=0f8837d4-77e0-47cc-9789-c53d8ca27928&client_secret=368b8099c14c0964a4a9f958c8b5786c46845ec1&token=WwVEraxkI7KbtP31wD3XSpZKqGpsLiXg&token_type_hin=refresh_token&client_assertion=eyJraWQiOiJycC1zaWduIiw......7xpA26QF5_Oung7E4y2n6&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
Client assertion JWT payload for /token-info endpoint example:#
POST /revoke HTTP/1.1Host: idp.somebank.czContent-Type: application/x-www-form-urlencodedtoken=WwVEraxkI7KbtP31wD3XSpZKqGpsLiXg&token_type_hin=refresh_token&client_assertion=eyJraWQiOiJycC1zaWduIiw......7xpA26QF5_Oung7E4y2n6&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
Client assertion JWT payload for /revoke endpoint example:#
The UserInfo and Profile API are the basic interfaces for retrieving authenticated
user data. The range of user-approved scopes strictly controls the range of data.
A detailed list of scopes and their associated claims is available in the API
technical documentation idp-for-bankid.yaml.
UserInfo endpoint is intended primarily for frequently performed identification and authentication, such as repeated
login processes to the system/application. This endpoint's data range corresponds to the data ranges for logins using
social network identities (Google, LinkedIn).
Access is authorized using a valid end-user access_token that was obtained from a completed login flow.
Unlike UserInfo, the Profile API is designed primarily to perform KYC or AML client authentication. This corresponds to
a much more extensive range of data provided. A complete overview of claims and scopes is in the
detailed API documentation idp-for-bankid.yaml.
Access is authorized using a valid end-user access_token that was obtained from a completed login flow.
The SeP wishes to request explicit consent from the End-User for some action, for example to obtain consent from end-user or sign document with end-user.
Bank iD has a universal system for request object authorization based on OpenID Financial-grade API.
Prior to start of authorization on end user side client MAY obtain end-user access token with grated scope "authorization".
Authorization API is secured by using mutual TLS and use of signed and encrypted JWTs on endpoints. See more in Security Considerations.
Authorization flow is composed of 3 endpoints - /ros , /authorize and /token.
Endpoint /ros MUST be called first for registration of request object on authorization server.
Request object must be passed directly in request body.
Endpoint returns request_uri that is used in other endpoints.
Notes on interface: - Authorization Bearer is not required for this resource. If it is not present, Bank iD will redirect end user to standard authentication process and after that will perform authorization. - If end user is not authenticated use of id_token_hint field is highly recommended, since Bank SHOULD allow skipping initial identification. - if end user is not authenticated additional scopes openid and authorization MUST be present - If you require to sign document, LoA 3 MUST be sent as acr_value, otherwise Bank MUST return error - If field scope is present and not empty, IdP MUST request consent for new scopes added by SeP prior or after authorization, if end user doesn't consent or authorize IdP SHOULD return error to SeP - max_age fields defines how long SeP will wait for authorization process to finish, IdP SHOULD take this value into consideration in setting exp value in response, since SeP could require out-of-bound authorization and such objects SHALL have longer life span than objects that are authorized in single session by end user. Out-of-bound authorization can be recognized by missing access_token
Endpoint /authorize is called next for initiating authorization on object by end-user.
Returns redirect for end-user to authorize the object on Authorization Server.
After a client's consent Authorization server redirects end-user on redirect URL provided in request.
In case of anonymous ROS, authentication flow is initiated on Bank iD side to authenticate end-user.
Interface is straightforward.
Standard OIDC endpoint /token is used to get final result of authorization on Authorization server.
Returns encrypted and signed JWT with the authorized object in an id_token and subject who had made authorization.
Bank iD can initiate authorization flow for anonymous user.
Bank can also require for anonymous user to use remote authorization -
meaning authorization flow is started without end-user's input and end-user authentication and authorization is executed asynchronously i.e. document signature with insurance agents or with utilities.
For purposes of remote authorization Bank iD MAY also provide an id_token (even old and expired) in /ros resource to prevent authentication of client and directly initiate authorization flow.
If Bank iD initiates authorization flow for authenticated user i.e. provide access token with granted scope, this end-user will be REQUIRED to use same bank to provide consent with adequate identity method.
Sequence diagrams of each flow can be found in documentation for Service Providers.
Structured scope is object that represents action or statement for which end user gives consent by using identity proofing with substantial assurance level if required.
Bank iD currently provides 3 types of object:
SignObject
DocumentObject
DocumentObjects
SignObject is general structure consisting of key-value fields and SHOULD be used for simple text consents, confirming of advertisements or similar tasks. Since SignObject is very general structure IdP SHOULD evaluate ui_locale in request thoroughly for correct language settings. SeP SHOULD also follow this guide as stated in Bank iD API description and fill labels and values in correct language. IdP SHOULD support minimum of Czech and English mutations. Other languages MAY NOT be supported and these languages SHOULD be converted to Czech or English following rules that Czech and Slovak ui_locales SHOULD be converted as Czech, other languages as English. IdP SHOULD also respect priority given by SeP in request.
DocumentObject in specialized structure for enabling document signature by Bank iD. Both objects requires authorization page by Bank and end user consent for Bank iD to allow it to get user data. See sequence diagram.
Appropriate scopes MUST be granted by a bank's IdP to Bank iD. Following are required:
These scopes are required for full identification for purposes of correct issue of certificates. Some of these data will be used for creation of certificate itself and some are for auditing purposes of proofing signatory identity.
DocumentObjects is a specialized structure for enabling up to 10 documents signature by Bank iD in bulk. Requirements for authorization page by Bank and end user consent is similar to DocumentObject. On top of single document signature the documents are encapsulated in an envelope, thus following is required:
envelope_nameenvelope_hash
Please note that set of these objects can grow. Also, it's possible to combine more objects together in one request henceforth end user can authorize more actions in one bulk.
For purposes of legal disputes bank must keep logs of processed authorization by their users. Bank MUST keep mainly log of successful authorizations with basic user
identification, authorization data and result. These logs should be kept as long as possible with adherence to GDPR and legal requirements.
Bank iD does not prescribe exact log structure but Bank MUST be able to prove or disprove that that exact transaction was or was not authorize by its end user.
Following guidelines must be followed by a bank to ensure security.
shall authenticate the confidential client at the token endpoint using by mutual TLS for OAuth Client Authentication as specified in section 2 of [MTLS] and private_key_jwt as specified in section 9 of [OIDC];
shall require a key of size 256 bits or larger for elliptic curve algorithms used for the client authentication;
shall require the redirect URIs to be pre-registered;
shall require the redirect_uri parameter in the authorization request;
shall require the value of redirect_uri to exactly match one of the pre-registered redirect URIs;
shall require user authentication at LoA 3 as defined in [X.1254] or more; LoA2 CAN be used in case of general objects authorization.
shall provide opaque non-guessable access tokens with a minimum of 128 bits of entropy where the probability of an attacker guessing the generated token is less than or equal to 2^(-160) as per [RFC6749] section 10.10;
shall support [MTLS] as a holder of key mechanism;
shall require the response_type values code id_token or code id_token token;
may support the request object endpoint as described in section 7;
The following endpoints are to be made available to the Bank by the Bank iD.
Each of these endpoints only contains illustratory examples. Please see the referenced OpenAPI documents for a full authoritative description of these resources.
API to enable banks get user statistics data, where it is possible to specify either idpSub or sepSub in request and get the data on the user across all banks.
Security is handled through sending the Authorization: Bearer in the header, it is important that in “sub” and “iss” client_assertion was the "id" of the banking environment issued by Bank iD. This can be obtained by entering a ticket in the Bank iD Developer Portal in the Helpdesk section. As the name of the ticket, fill in "Request for issuance of the "idp_id" of the banking environment for FDS".
The idp parameter in request allows users to isolate data related exclusively to banking applications. By setting this value to true, the system filters records where the bank acts as both the Identity Provider and the Service Provider. This logic is based on the validation of the bank's txnumber. Use this flag when you need to report on internal bank-to-bank transactions or specific banking app usage, excluding third-party service providers.
{ "sub": "00000000-0000-0000-0000-000000000000", //idp_id of the banking environment "aud": "https://api.bankid.cz/core-fds", "iss": "00000000-0000-0000-0000-000000000000", // idp_id of the banking environment "exp": 1695286736, "iat": 1695283136, "jti": "82662517-eafa-4de2-b071-9311fa714d35"}
client_assertion is generated according to the OAuth2/Open ID specification as well as e.g. when using PRIVATE_KEY_JWT authentication for token exchange.
Exposed by Bank iD. Authoritatively described in bankid_for_idp.yaml. Authenticated.
POST/user-stat-data
POST /token HTTP/1.1Content-Type: application/jsonAuthorization: Bearer eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwi