IdP's Authorization API
The goal of this document is to describe the authorization feature of the Bank IdP. It provides guidance on how to understand and use the authorization API. It's manadatory guidelines togheter with Swagger for banks for implementation of thier authorization feature.
How to read the guideline
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
- 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 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.
BankID 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, BankID 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 BankID 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.
General notes on behavior of authorization
- BankID 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 BankID MAY also provide an id_token (even old and expired) in /ros resource to prevent authentication of client and directly initiate authorization flow.
- If BankID 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.
Authorization server requirements
- shall support only confidential clients;
- shall require the request object to contain a max_age claim;
- shall require explicit consent by the user to authorize the requested scope if it has not been previously authorized;
- shall return token responses that conform to section 4.1.4 of [RFC6749];
- shall return the list of granted scopes with the issued access token;
- shall require the redirect URIs to use the https scheme;
Notes on general structures
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. BankID currently provides 3 types of object:
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 BankID 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 BankID. Both objects requires authorization page by Bank and end user consent for BankID to allow it to get user data. See sequence diagram. Appropriate scopes MUST be granted by a bank's IdP to BankID. Following are required:
profile.name profile.titles profile.birthdate profile.address profile.email profile.legalstatus
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 BankID 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:
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. BankID 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.
Usage of authorization flow is bounded by general security guidelines which are extended in following way
Only following cipher suites are allowed for mTLS
TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
Following rules SHALL be followed for both client and authorization server JWS algorithms
SHALL use PS256 or ES256 algorithms; SHALL not use algorithms that use RSASSA-PKCS1-v1_5 (e.g. RS256); SHALL not use none;
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;