The Open Bank Project API

The Open Bank Project is an open-source API for banks that enables account holders to interact with their bank using a wider range of applications and services.

The OBP API supports transparency options (enabling account holders to share configurable views of their transaction data with trusted individuals and even the public), data blurring (to preserve sensitive information) and data enrichment (enabling users to add tags, comments and images to transactions).

The OBP API abstracts away the peculiarities of each core banking system so that a wide range of apps can interact with multiple banks on behalf of the account holder. We want to raise the bar of financial transparency and enable a rich ecosystem of innovative financial applications and services.

Our tagline is: "Bank as a Platform. Transparency as an Asset".

The API supports OAuth 2, OpenID Connect OIDC, Direct Login, and other authentication methods.

Note: OAuth 1.0a support has been removed. Please use OAuth 2.0, OpenID Connect, or Direct Login for authentication.

The API documentation is best viewed using the OBP API Explorer or a third-party tool that has imported the OBP Swagger definitions.

If you want to run your own copy of API Explorer II, see here

OBP instances support multiple versions of the API simultaneously (unless they are deactivated in config) To see the status (DRAFT, STABLE or BLEEDING-EDGE) of an API version, look at the root endpoint. For example, /obp/v2.0.0/root or /obp/v3.0.0/root.

This project is dual licensed under the AGPL V3 (see NOTICE) and commercial licenses from TESOBE GmbH.

A good way to manage JDK versions and install the correct version for OBP is sdkman. If you have this installed then you can install the correct JDK easily using:

• OracleJDK: 1.8, 13
• OpenJdk: 11

OpenJDK 11 is available for download here: https://jdk.java.net/archive/.

The project uses Maven 3 as its build tool.

To run the API using the http4s server, use the obp-api module from the project root:

The http4s server binds to hostname / dev.port as configured in your props file (defaults are 127.0.0.1 and 8080).

For ZED IDE users, we provide a complete development environment with Scala language server support:

This sets up automated build tasks, code navigation, and real-time error checking. See zed/README.md for complete documentation.

In case the above command fails try the next one:

Note: depending on your Java version you might need to do this in the OBP-API directory. This creates a .mvn/jvm.config File

Then try the above command.

Or use this approach:

Note: How to run via IntelliJ IDEA

• In obp-api/src/main/resources/props create a test.default.props for tests. Set connector=mapped.

• Run a single test. For instance, right-click on obp-api/test/scala/code/branches/MappedBranchProviderTest and select "Run Mapp"...

• Run multiple tests: Right-click on obp-api/test/scala/code and select Run. If need be:

  Goto Run / Debug configurations Test Kind: Select All in Package Package: Select code Add the absolute /path-to-your-OBP-API in the "working directory" field You might need to assign more memory via VM Options. For example:

  -Xmx1512M -XX:MaxPermSize=512M


  or

  -Xmx2048m -Xms1024m -Xss2048k -XX:MaxPermSize=1024m


  Ensure your test.default.props has the minimum settings (see test.default.props.template).

  Right-click obp-api/test/scala/code and select the Scala Tests in the code to run them all.

  Note: You may want to disable some tests not relevant to your setup e.g.: set bank_account_creation_listener=false in test.default.props.

• See pom.xml for test configuration.
• See http://www.scalatest.org/user_guide.

Set memory options:

Run one test:

Run all tests and save the output to a file:

If you use Ubuntu (or a derivate) and encrypted home directories (e.g. you have ~/.Private), you might run into the following error when the project is built:

The current workaround is to move the project directory onto a different partition, e.g. under /opt/.

Docker images of OBP API can be found on Dockerhub: https://hub.docker.com/r/openbankproject/obp-api - pull with docker pull openbankproject/obp-api.

Props values can be set as environment variables. Props need to be prefixed with OBP_, . replaced with _, and all upper-case, e.g.:

openid_connect.enabled=true becomes OBP_OPENID_CONNECT_ENABLED=true.

The default database for testing etc is H2. PostgreSQL is used for the sandboxes (user accounts, metadata, transaction cache). The list of databases fully tested is: PostgreSQL, MS SQL and H2.

Set DB options in the props file:

Note: The H2 web console at /console was available when OBP-API ran on Jetty but is no longer served by the http4s server. To inspect the H2 database, connect directly using the H2 Shell or a database tool such as DBeaver.

Use the following connection values (make sure the JDBC URL matches your Props value):

Once Postgres is installed (On macOS, use brew):

1. psql postgres

2. Create database obpdb; (or any other name of your choosing).

3. Create user obp; (this is the user that OBP-API will use to create and access tables etc).

4. Alter user obp with password daniel.says; (put this password in the OBP-API Props).

5. Grant all on database obpdb to obp; (So OBP-API can create tables etc.)

-- Connect to the sandbox database \c sandbox;

-- Grant schema usage and creation privileges GRANT USAGE ON SCHEMA public TO obp; GRANT CREATE ON SCHEMA public TO obp;

-- Grant all privileges on existing tables (if any) GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO obp; GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO obp;

-- Grant privileges on future tables and sequences ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO obp; ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO obp;

1. Then, set the db.url in your Props:

   db.driver=org.postgresql.Driver
db.url=jdbc:postgresql://localhost:5432/obpdb?user=obp&password=daniel.says


2. Then, restart OBP-API.

Set the database connection properties in your props file. You can either embed credentials in the URL or use separate props:

Option 1: Credentials in the URL

Option 2: Separate props (recommended)

Option 2 is recommended because it keeps credentials out of the URL and avoids URL parsing issues. Note that db.user and db.password take priority over any credentials in the URL.

Postgres needs to be compiled with SSL support.

Use OpenSSL to create the files you need.

For the steps, see https://www.howtoforge.com/postgresql-ssl-certificates.

In short, edit postgresql.conf:

And restart Postgres.

Now, this should enable SSL (on the same port that Postgres normally listens on) - but it doesn't force it. To force SSL, edit pg_hba.conf replacing the host entries with hostssl.

Now in OBP-API Props, edit your db.url and add &ssl=true. For example:

Note: Your Java environment may need to be set up correctly to use SSL.

Restart OBP-API, if you get an error, check your Java environment can connect to the host over SSL.

Note: You can copy the following example files to prepare your own configurations:

• /obp-api/src/main/resources/logback.xml.example -> /obp-api/src/main/resources/logback.xml (try TRACE or DEBUG).
• /obp-api/src/main/resources/logback-test.xml.example -> /obp-api/src/main/resources/logback-test.xml (try TRACE or DEBUG).

There is a gist/tool which is useful for this. Search the web for SSLPoke. Note this is an external repository.

For example:

• https://gist.github.com/4ndrej/4547029

  or

• git clone https://github.com/MichalHecko/SSLPoke.git .
  
  gradle jar
  cd ./build/libs/
  
  java -jar SSLPoke-1.0.jar www.github.com 443

  Successfully connected

  java -jar SSLPoke-1.0.jar YOUR-POSTGRES-DATABASE-HOST PORT

You can add switches. For example, for debugging:

To import a certificate:

To get a certificate from the server / get further debug information:

The above section is work in progress.

In the API's props file, add the ID of your user account to super_admin_user_ids=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. User Id can be retrieved via the "Get User (Current)" endpoint (e.g. /obp/v4.0.0/users/current) after login or via API Explorer (https://github.com/OpenBankProject/API-Explorer) at /#OBPv3_0_0-getCurrentUser.

Super users can give themselves any entitlement, but it is recommended to use this props only for bootstrapping (creating the first admin user). Use this admin user to create further privileged users by granting them the "CanCreateEntitlementAtAnyBank" role. This, again, can be done via API Explorer (/#OBPv2_0_0-addEntitlement, leave bank_id empty) or, more conveniently, via API Manager (https://github.com/OpenBankProject/API-Manager).

To populate the OBP database with sandbox data:

1. In the API's props file, set allow_sandbox_data_import=true.
2. Grant your user the role CanCreateSandbox. See the previous section on how to do this.
3. Now, post the JSON data using the payload field at /#2_1_0-sandboxDataImport. An example of an import set of data (JSON) can be found here.
4. If successful you should see this result { "success": "Success" } and no error message.

OBP-API runs on http4s Ember. Standard security headers (Cache-Control, X-Frame-Options, Correlation-Id, etc.) are applied automatically by Http4sLiftWebBridge.withStandardHeaders to all responses. Cookie flags and other session-related settings can be configured via the props file.

IMPORTANT: The server_mode configuration property has been completely removed from OBP-API.

OBP-API now operates exclusively as a backend API server. There is no configuration needed - the application automatically runs in API-only mode.

• server_mode=portal - Removed (no longer supported)
• server_mode=apis - Removed (no longer needed, this is now the default and only mode)
• server_mode=apis,portal - Removed (no longer supported)

If your props file contains server_mode, you can safely remove it. The property is ignored.

Before:

After:

For portal/UI functionality: Deploy the separate OBP-Portal application.

For migration instructions, see .kiro/specs/remove-lift-portal-pages/MIGRATION_GUIDE.md

Most internal OBP model data access now occurs over Akka. This is so the machine that has JDBC access to the OBP database can be physically separated from the OBP API layer. In this configuration we run two instances of OBP-API on two different machines and they communicate over Akka. Please see README.Akka.md for instructions.

For SSL encryption we use JKS keystores. Note that both the keystore and the truststore (and all keys within) must have the same password for unlocking, for which the API will stop at boot up and ask for.

• Edit your props file(s) to contain:

  rabbitmq.use.ssl=true
keystore.path=/path/to/api.keystore.jks
keystore.password=123456
truststore.path=/path/to/api.truststore.jks


For SSL encryption we use jks keystores. Note that keystore (and all keys within) must have the same password for unlocking, for which the API will stop at boot up and ask for.

• Edit your props file(s) to contain:

  jwt.use.ssl=true
keystore.path=/path/to/api.keystore.jks
keystore.alias=SOME_KEYSTORE_ALIAS


A props key value, XXX, is considered encrypted if has an encryption property (XXX.is_encrypted) in addition to the regular props key name in the props file e.g:

• db.url.is_encrypted=true
• db.url=BASE64URL(SOME_ENCRYPTED_VALUE)

The Encrypt/Decrypt workflow is :

1. Encrypt: Array[Byte]
2. Helpers.base64Encode(encrypted)
3. Props file: String
4. Helpers.base64Decode(encryptedValue)
5. Decrypt: Array[Byte]

1st, 2nd and 3rd step can be done using an external tool

1. Export the public certificate from the keystone:

   keytool -export -keystore /PATH/TO/KEYSTORE.jks -alias CERTIFICATE_ALIAS -rfc -file apipub.cert

2. Extract the public key from the public certificate:

   openssl x509 -pubkey -noout -in apipub.cert > PUBKEY.pub`

3. Get the encrypted propsvalue like in the following bash script (usage ./scriptname.sh /PATH/TO/PUBKEY.pub propsvalue):

   #!/bin/bash
echo -n $2 |openssl pkeyutl -pkeyopt rsa_padding_mode:pkcs1 -encrypt -pubin -inkey $1 -out >(base64)


Please refer to the Code Generation for links.

DEPRECATED: Portal functionality has been removed from OBP-API.

For UI customization, please use the separate OBP-Portal project.

We support rate limiting i.e functionality to limit calls per consumer key (App). Only New Style Endpoins support it. The list of they can be found at this file: https://github.com/OpenBankProject/OBP-API/blob/develop/obp-api/src/main/scala/code/api/util/NewStyle.scala.

There are two supported modes:

• In-Memory
• Redis

It is assumed that you have some Redis instances if you want to use the functionality in multi-node architecture.

We apply Rate Limiting for two types of access:

• Authorized
• Anonymous

To set up Rate Limiting in case of anonymous access edit your props file in the following way: