BankID Authorization API

Version: 1.0

The goal of this document is to describe the authorization feature of the BankID. It provides guidance on how to understand and use the authorization API.

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.

Glossary

  • 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
  • SeP - Service Provider - A third party which is registered in the BankID system and intends to consume Bank APIs
  • 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

Authorization use-case

  • You wish to request explicit consent from the End-User for some action, for example to obtain consent or sign document with end-user.

Authorization overview

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 SHOULD 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 usage

Authorization flow is composed of 3 endpoints - /ros , /authorize and /token. For additional validation of signed document SeP can use endpoint /verification.)

  • 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. In case of document signature resource return upload url for document upload. Document MUST be uploaded prior to call of /authorize endpoint.

      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 or document signature.
      - If end user is not authenticated use of id_token_hint field is highly recommended, since IdP 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 BankID will return error 
      - remote_authorization constitutes different behavior see remarks in general notes
      - If field scope is present and not empty, IdP will request consent for new scopes added by SeP prior or after authorization, if end user doesn't consent or authorize BankID returns error to SeP.
    
  • 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. A signed document can be downloaded on url found in the structured scope field in ID token.

  • Endpoint /verification may be used to get authenticity of signature in a document made by BankID. Document_id from PDF metadata must be used as parameter.

Notes on general structures

Structured scope

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 2 types of object:

  • SignObject
  • DocumentObject

SignObject SHOULD be used for simple text consents, confirming of advertisements or similar tasks. Since SignObject is very generic structure, SeP should send correct ui_locale of end user and fill labels and values in correct language. IdPs SHOULD support minimum of Czech and English mutations. Other langugages 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.

DocumentObject CAN be used for signing legally binding PDF with digital signatures with provable audit trails.

Document signature

You can request document signature by end user via BankID. Authorization flow differs in this case, since BankID actively process document and provides additional features.

On call of /ros resource only metadata of document are sent and BankID returns upload_url additionally. Document MUST be uploaded prior to call of /authorize resource.

If you fail to upload document prior to call, /authorize will send error response and request object will be deleted.

On call of /authorize resource BankID validates the document, makes hash and flow continues as normal.

On a redirect from end-users browser, you get authorization code and BankID adds digital signature by user's certificate to document and seals it with a qualified seal.

Call of /token resource with authorization code returns response with an id_token, which contains URL of signed document, which is stored in BankID.

Example of body of id_token in JWT

{
  "sub": "41f382d2-7cea-402f-97b4-afd864390b9c",
  "name": "John Doe",
  "exp": 1612258710,
  "iat": 1516239022,
  "iss": "https://idp.example.com",
  "sid": "41f382d2-7cea-402f-97b4-afd864390b9c",
  "aud": "https://rp.example.com/resource",
  "nonce": "gH4FFacc81",
  "acr": "loa3",
  "structured_scopes": {
    "documentObject": {
      "document_id": "'7159534b-3b88-4f29-866b-9e83489d3053",
      "document_hash": "a93e305306c7a52ac2ccc55b83f197ea8e02b0ce6b317f53ae8e038586f88197",
      "hash_alg": "2.16.840.1.101.3.4.2.3",
      "document_title": "Smlouva o smlouvě budoucí",
      "document_subject": "Smlouva s společností ACME",
      "document_language": "en.EN",
      "document_created": "2020-06-24T08:54:11+00:00",
      "document_author": "Orange SK",
      "document_size": "1250000",
      "document_uri": "https://rp.net/documents?document_id=7e766e94-eb62-11ea-adc1-0242ac120002",
      "sign_area": {
        "page": 1,
        "x-coordinate": 10,
        "y-coordinate": 100,
        "x-dist": 35,
        "y-dist": 25
      }
    }
  }
}

Please note that BankID doesn't and cannot verify that document was signed by the person that should sign this document. Personal data of signatory person can be found in the certificate. Structure of certificate is below.

We also add serial number, and we keep this in immutable record for future proofing for validity of signature.

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.

Requirements on documents

Following section describes requirements on documents which BanKID accepts for signatures

  • Document MUST be in PDF/A format, other formats are not accepted
  • Document CAN have signatures, document MUST NOT be locked in order to prevent changes. If document is locked BankID can't attach signature to document.
  • Document SHOULD have signature plane where BankID can place digital signature visualization. Specification of such area is manadatory.
  • Document MUST have same metadata as metadata sent through API

General notes on behavior of authorization

  • You can initiate authorization flow for anonymous user. If such flow is initiated BankID is initiating standard OIDC authentication flow.
  • You 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. See following sequence diagram:

  • For purposes of remote authorization or anonymous flow you MAY also provide an id_token (even old and expired) in /ros resource to prevent authentication of client and directly initiate authorization flow.
  • If you initiate 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.

Authorization server requirements

Following requirements must be met by you in general behavior and are enforced by BankID API

  • shall support only confidential clients;
  • shall require the request object to contain an exp claim; and
  • 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;

Security considerations

Usage of authorization flow is bounded by general security guidelines.

General

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;

Certificates and policies

BankID is for each usage generating new certificate for end user based on identity proofing with assurance level substantial. Details can be found in certification policy. Fo technical purposes of verification of identity, structure of certificate is following:

CN= title_prefix + " " +firstname +" "+last name
givenName= firstname
sn= last name
O= name of verifying bank 
C= country of residence
X509v3 Extensions:
SAN: sub - id of end user issued by BankID for you, MUST match sub in ID token
dateOfBirth = year of birth (19710101120000Z where 1971 is year of birth) in subjectDirectoryAttributes

We also add serial number, and we keep this as immutable record for future proofing of validity of signature.

Authorization server

Following guidelines must be followed by you to ensure security, and these are enforce by BankID APIs.

  • shall authenticate the confidential client at the token endpoint 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 require the response_type values code id_token or code id_token token;

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