adorsys/open-banking-gateway

Provides RESTful API, tools, adapters, and connectors for transparent access to open banking API's (for banks that support PSD2 and XS2A as well as HBCI/FinTS)

Code coverage

• Backend:
• Frontend:
• Example code:

This is the try-out version of adorsys Open Banking Gateway: an open source (AGPL v3) solution to get acquainted with the adorsys-developed gateway and test its AIS and PIS flows and the respective connectivity to the largest retail banks in Germany (see our XS2A Adapter project).

If you are looking for a strong base framework to build up your own gateway capabilities, we would be thrilled to cooperate with you and share our know-how of the framework and overall open finance and development expertise.

If you are an organisation that would like to commercially use our solutions beyond AGPL v3 requirements, we are open to discuss alternative individual licensing options. If you are interested in working with us or have any other inquiries, please contact us under [email protected].

Open Banking Gateway

Provides tools, adapters and connectors for transparent access to open banking apis. The initial effort focuses on the connectivity to banks that implement the European PSD2 directive either through one of the common market initiatives like : The Berlin Group NextGenPSD2, The Open Banking UK, The Polish PSD2 API or even through proprietary bank api like the ING’s PSD2 API.

What this Project is about

Tackle the Key Challenge for Third Party Providers of Payment Services

The European PSD2 as the first regulator driven Open Banking initiative offers many opportunities for both banks, known as traditional provider of payment services (called ASPSPs in this context) and other Third Party Providers of payment services (TPPs). TPPs can use account information and payment services provided by banks to offer new innovative services to bank account holders. The more banks and TPPs can interact with each other, the more payment account holders can be provided with reacher banking solutions, which in turn simplifies and leverage commercial value chains.

Being able to interact with different banking APIs can be a time and cost consuming challenge. Even though the PSD2 requires European banks to provide APIs and despite the effort of market initiatives to provide common standard interfaces, there is still a multitude of divergent authorization schemes involved and a lot of space for implementation options. A bank can even decide not to join one of the known market initiatives and define it's own PSD2 compliant API.

The purpose of this open banking gateway is to provide the community with a common and simple interface for accessing major Open Banking APIs.

Introducing the FinTech as a Major Role

Being a regulator driven initiative, PSD2 mandates the regulation of TPPs. With this additional detail, the market is experiencing a distinction between regulated TPPs and non regulated FinTechs. This framework is therefore designed taking in consideration the existence of the category of payment service providers called FinTech that used APIs exposed by a regulated TPP to access payment services exposed by banks.

Address Security Issues associated with PSU Access to Multiple Interfaces

In the Open Banking Context, a payment service user (PSU or banking account holder) might have to deal with up to 3 different user interface to initiate, authorize and get the requested banking service executed. There being redirected back and forth from one UserAgent (resp. device) to another. This intensive use of redirection in Open Banking bearing a lot of risk of impersonating the PSU, we set a goal of this Framework to dissect the complexity involved with those redirection processes and open forums for discussion of possible solutions and sample implementations. Following papers are the first attempt to capture the problem (UserAgent Redirection, PSU Access Security Design).

Project Demo

• Demo deployment and guide

Big Picture

The following picture displays the overall architecture of this banking gateway:

Security concept

The following picture displays the overall security concept of this banking gateway:

Security concept has 2 kinds of flows:

• authenticated (for consent sharing)
• anonymous (for payments, but can be authenticated too).

Here are detailed diagrams of each flow:

• Authenticated security concept detailed flow
• Anonymous security concept detailed flow

Technical architecture

The following picture displays the overall technical architecture concept of this banking gateway:

Key components as shown on diagram:

APIs:

• Banking API and its implementation Banking API Impl
• Consent API and its implementation Consent API Impl

Facade:

• Banking protocol facade

Protocol:

• Banking protocol API
• XS2A compliant banking protocol Impl

Running the project locally

• docker-compose-dev.yml - docker-compose file in the project root for Development (requires building docker images)
• docker-compose.yml - docker-compose file in the project root for Demo (Images will be pulled from DockerHub)

Postman scripts to play with API

• postman-collections
• postman-environments (for playing use this Postman environment)

Postman collection details

• postman-ais-collection Xs2a-embedded or HBCI AIS (account information services) example - getting users' account and transactions list

Note: Postman requires disabled request signing functionality - for that use Spring-profile no-signature-filter. You can use our DEV environment (without signature check) if you import this Postman environment

Information for developers:

• Working with BPMN: As most protocols use BPMN, we have developed the plugin 'Flowable BPMN visualizer' that directly integrates into IntelliJ with code navigation, refactoring and other stuff for Flowable BPMN engine. It will make your work a lot easier as you don't need to leave IntelliJ to change diagram or to see what class is used at which step.

• Running local tests faster. To avoid Postgres TestContainer slow initialization one can use following environment variables: TESTCONTAINERS_REUSE_ENABLE=true;TESTCONTAINERS_RYUK_DISABLED=true;SPRING_DATASOURCE_URL=jdbc:tc:postgresql:12:////open_banking?TC_DAEMON=true&?TC_TMPFS=/testtmpfs:rw&TC_INITSCRIPT=init.sql&TC_REUSABLE=true this will keep Postgres TestContainer started and migrated after 1st run, significantly reducing next tests startup time. Note, that it will introduce shared state across tests, which is mostly OK but for some tests may cause failures.

• Starting with project: How to start with project

• Populating database with bank data: How to fill database with bank data

Documentation

Please take a look into our documentation to know more about:

Planned and released versions

• Versioning, Release and Support policy
• Release notes
• Roadmap for next features development

Architecture

• Dictionary
• Use Cases
• Banking Protoсol Design
• User Agent Redirection
• PSU Access Security Design
• JavaDoc

Third Parties Contribution

This project is designed to enable contribution from different sources, as the open banking challenge will start with a magnitude of discrepancies in individual bank implementations, even for banks implementing a common standards.

How to contribute

• Getting started
• Contribution Guidelines

Authors & Contact

• Francis Pouatcha - Initial work - adorsys

See also the list of contributors who participated in this project.

For commercial support please contact adorsys Team.

License

This project is licensed under Affero GNU General Public License v.3 (AGPL v.3) - see the LICENSE file for details.

For alternative individual licensing options please contact us at [email protected].

open-banking-gateway's Issues

Create CI/CD code quality checks

should include:

• Check style
• Spot bugs
• PMD
• coverage check (at least 60%)

Creating documentation framework/process

creating basic mavin configuration of project, travis pipeline

Monitoring UI

Implement the communication between the Fintech Data Center and the TppBankSeachAPI

Use cases:
Sending a request to the TppBanksearchAPI and receiving a response from it

Refine sequence diagram and doc to fit newly defined consent api.

Decide on whether to use runtime or compile time dependency injection

We will have to decide on wether to use

• runtime dependency injection like spring boot or
• compile time dependency injection like play, dagger-2, Micro?

Talking to valentine right now, we might also consider start with runtime DI, and move to compile time DI after the first MVP.

As a PSU, I want to see the list of my transactions for a given bank account with an existing consent

Acceptance criteria:

• The consent must be verified with the BankingProtocol provided by the bank profile.
• The consent must exist
• The consent must be valid.
• If FinTech already has an existing consent for this service, no consent will be given.
• The PSU receives its transaction list.

Style the bank selection component

Style the bank selection component as in the given example https://xd.adobe.com/view/a446b05b-5ee1-414b-5e00-6053783dc8af-d277/

see [#13]

As a PSU, I want to give my consent so that I can get my transaction list for a given account (Embedded Approach)

Acceptance criteria:

• The ASPSP - SCA approach is embedded
• The Psu's browser is redirected to the FinTech consent authorisation UI to give his consent using its online banking credentials
• After PSU has given its consent for this service, the psu's browser is redirected back to the FinTechUI
• The FinTech displays the psu's transaction list

Use Case description

Transform project opba-consent-rest-api to present api first

Create proof of concept for the banking Protocol

Banking Protocol should be able to retrieve user's transaction list using mock environment of XS2A-Adapter -> XS2A-Sandox. Under the hood application should retrieve consent necessary to get transaction list.

• Integrate XS2A adapter, so that it can talk to dynamic sandbox from our code
• Add and validate flowable BPMN engine into flow
• Implement consent creation BPMN flow
• Implement get transaction list using FinTech provided consent BPMN flow

Implement the Banking Protocol for the dynamic sandbox

For get accounts list, redirect approach and test it with the dynamic sandbox

--> see Banking Protocol's Proof of concept

Merge documentation from gh-pages to develop and delete gh-pages branch.

Flowable separate schema

We should move Flowable tables to separate schema.
In order to do this we need to apply its liquibase migrations and schema ourselves.
This code only says Flowable to look for tables in flowable schema, but liquibase and sql migrations of Flowable will ignore it.

@Bean
    EngineConfigurationConfigurer<SpringAppEngineConfiguration> engineConfigurationConfigurer() {
        return engineConfiguration -> {
            engineConfiguration.setDatabaseTablePrefix("flowable.");
            engineConfiguration.setTablePrefixIsSchema(true);
        };
    }

Trying already implemented components, reading documentation

This task includes KT sessions, tryings launch environment locally, investigation tools we want bring to the project, reading PSD2, XS2A documentation.

Implement the FinTechApi

Implement with the following:
a. Get bank account
b. get transaction list

This will be done in a separate module

Rename TppBankingApi to BankingAPI

As a PSU, I want to login to the FinTechUI interface, so I can display the bank search screen

Acceptance criteria:

• Psu must enter his username and password on the LoginUI. (FinTech Login)
• Psu is redirected to the bank search screen.

[Use Case Description] ( https://github.com/adorsys/open-banking-gateway/blob/develop/docs/architecture/1-loginWithFinTech.md)

Getting started documentation for FinTechUI

The purpose of this task is to document how to start the FinTechUI locally and in the environment

As a PSU, I want to select my bank, so that i can see the bankprofile showing the open banking service offered by my bank

Acceptance criteria:

• PSU selects one of the list entries
• The Bankprofile must be the result of this use case
• The Bankprofile have the list of Banking services provided by the BankingApi of the bank (("get transactions" in this case)

Use cases description

Define the FinTechAPi

Define with the following:
a. Get bank account
b. get transaction list

As a PSU, I want to search the bank by auto-completion by entering keywords so I can find my bank

Purpose: We need a uniform API to enable communication with FinTech Data Center.

Acceptance criteria:

• The search is done by automatic completion
• The keyword to be entered must consist of at least 3 characters
• A bank list is the result of this use case
• The list is displayed as return in the server

The Banking Gateway offers a bank search interface for this purpose

Use case description

Solution for test accounts

In need of real bank accounts for testing purpose (Banking Gateway and XS2A adapter)

• the accounts have to be valid customer accounts

Integrate the Bank search API with the FinTechSearchUI

Connect bank search service to bank search API in order to receive real data

As a PSU, I want to give my consent so that I can get my bank account.

Acceptance criteria:

• Inform PSU, that consent is being checked (Loading screen)
• PSU doesn't have a valid consent
• Inform PSU, that no consent covering this service is present
• Banking Gateway must initiate a consent with the bank using the BankingProtocol located in the BankProfile
• PSU is redirected to the ConsentAuthorisationApi to authorize the consent

Use Case Description

As a PSU, I want to retrieve transaction information from my bank account

Create docker file for FintechUI

Create docker file for FintechUI

Init FintechUI application

Init FintechUI application Angular Application

Encode BankingProtocol selection information into the redirectCode

The redirectCode is generally used to:

• Securely redirect the PSU UserAgent from the TppBankingApi (InitConsent-067) over the FinTechApi (InitConsent-069) to the ConsentAuthorizationApi (Redirect-010).
• Securely redirect the PSU UserAgent back from the ConsentAuthorizationApi to the TppBankingApi over the FinTechApi. See AuthEmbedded-094, AuthRedirect-081, Service-010, Service-030

This redirectCode is the only information available to the target of the redirection and thus, must contain information necessary to retrieve the banking protocol instance to use.

As the redirectCode is opaque to the BankingProtocol module, it might make sense to implement this as part of the BankingProtocolSelector. Like: BankingProtocolSelector.select(redirectCode):BankingProtocol thus hiding the encoding in the BankingProtocol subsystem.

Request Access to XS2A Adapter Gitlab and BG Gitlab repositories

To proceed with the Bank Search API, Maksym need access to the productive banks we currently have.

Denonce time on keyup event

Add Denounce time on keyup event when searching for a bank, so event is fired only after a user finished typing the keyword

Draft FintechUI Architecture

Draft FintechUI Architecture:

1. Application layers
2. Application Separation into modules
3. State management and api communication

Use productive data for the Bank Search API

we are currently using test data for the bank research API. Because of our plan to work with real banks, this fake data must change with productive data.

write Contribution Guidelines for the open banking project

For orientation you can use this link:

Contribution Guideline Example

As a PSU, I want to give my consent so that I can get my transaction list for a given account (Redirected Approach)

Acceptance Criteria:

• The ASPSP - SCA approach is redirected
• The Psu's browser is redirected to the TppConsentSessionApi
• The Psu's browser is redirected to the ASPSP SCA authorisation site (ASPSP online banking UI) to give its consent
• After the psu has given its consent, the psu's browser is redirected back to the FinTechUI.
• The FinTech displays the psu's transaction list

Use case description

Setup subproject for FinTechApi

Setup an opba-fintech-rest-api project in which we can define open api yml and all endpoints needed by the prototypical FinTech Server.

Shall be labeled: FinTechApi

Define the java application for the FinTechUI

Architectural draft

Initial MVP:
Tech setup

1. Spring Boot >= 2.2
2. Flowable BPMN 6.x
3. Postgres RDBMS 12.x
4. XS2A-flow

Least annoying API:
STATIC:

1. TPP creates user profile (name, surname,...) that provides information necessary to perform requests on his behalf
2. TPP provides setting which mode will be used STATIC or DIALOG to perform user requests
3. In STATIC mode TPP must fulfill all fields that are not provided by profile but are necessary to perform action (except SCA)
4. TPP calls i.e. /pay/IBAN-from/IBAN-to/CURRENCY/amount with parameters from step nr. 3. The only extra stuff to complete the call is SCA

Extra:

1. Tests without mock-qwac

Mock Bank Search Service

Mock data for Bank Search Service

Design concept for faster travis build

Travis build already taking 10 minutes and project hasn't started yet. Can we optimize it?
See: https://travis-ci.com/adorsys/open-banking-gateway/builds

Provide Environment for FE

Create helm config for fintech-ui

Decide on How to layout Tpp Data Center Components

In the Tpp Data Center, we have the following components:

• The TppBankingApi
• The TppBankSearchApi
• The ConsentAuthorisationApi
• The BankingProtocol

We might decide on Setting Up the banking protocol such as to make it an isolated component that can be reached by both the TppBankingApi and the ConsentAuthorisationApi.

Decision is to be taken by the architecture board.

• Do we run all components in the same server?
• Do we have each component in a proper server?

It might make sense to separate between TppBankingApi (B2B interface) and ConsentAuthorisationApi (B2C interface)

• Missing Label: Architecture

Setup a pipeline based on example from https://github.com/DG0lden/mkdocs-demo/

see : Example LINK

Introduce facade service

Introduce facade to manage state and api data from a single service

Testing framework setup

We need fast startup/shutdown of sandbox-* umbrella project that imitates ASPSP in order to be able to test application behavior locally.

Setting Up the Banking Gateway Project Environment

• Create GitLab project for storing the deployment configuration.

• OpenShift project open-banking-gateway-dev.

• Adapt helm configs of the existing banking-gateway: sandbox (release), adapter (first release, later perhaps develop), b2c?. (Estimation: 2d)

• Create new helm config for open-banking-gateway application. (Estimation: 1h)

• Create new helm config for open-banking-gateway postgres database. (Estimation: 1h)

Normalize name of some components in doc and diagrams

Affected file:

• /doc/architecutre/**/*.puml
• /doc/architecutre/**/*.md
• /doc/architecutre/**/*.draw.io

Affected Naming
AspspConsentSessionApi --> OnlineBankingApi
AspspConsentSessionUI --> OnlineBankingUI
Aspsp2TppRedirectionInfoPanel --> RedirectInfoPage
PsuTppConsentSession UI --> ConsentAuthorisationUI
TppConsentSessionAPI --> ConsentAuthorisationApi

Specify Endpoint: FinTechApi.listOfTransactions

Specify this endpoint based on following existing artifacts:

• Sample Workflow
• Define interface based on the endpoint defines in this yml file TppBankingApi #/v1/ais/accounts/{account-id}/transactions

MIssing Label: FinTechApi

write Project Roadmap in gh-pages (github)

aims to provide an overview of the major elements of this project.

This will include the following:

• Objectives
• Milestones

Fill database with test data

We need at least 30000 records to be able to test performance of bank search api

Setup postgres full text search

PostgreSQL RDBMS has ability of full text search.
This task includes

• creating index for full text search,
• writing queries for searching bank by substring(>=3 letters),
• testing performance of enpoints with and without full text search