From 2b1526d7e6499246e1d7188b65346003c893f9ff Mon Sep 17 00:00:00 2001 From: "`{3rd: \"Beedell\", 1st: \"Roke\"}`{.JSON5}" Date: Mon, 29 Jul 2024 00:39:57 +0100 Subject: [PATCH 1/2] Updated `README.md`. Massive improvements to formatting: 1. All code blocks now use fences, instead of a combination of inconsistent (and sometimes invalid) indentation and fences without syntax declarations. 1. Fixed approximately 30 misspellings and English syntactic errors. 1. Ensured that no lines would accidentally conjoin due to Markdown processing - all are separated by one line, instead of being inconsistent. --- README.md | 510 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 302 insertions(+), 208 deletions(-) diff --git a/README.md b/README.md index 126d4336b4..c055e7accb 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,31 @@ -# README +# ReadMe The Open Bank Project API -## ABOUT +## About -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 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 tag line is: Bank as a Platform. Transparency as an Asset. +Our tagline is: "Bank as a Platform. Transparency as an Asset". The API supports [OAuth 1.0a](https://apiexplorer-ii-sandbox.openbankproject.com/glossary#OAuth%201.0a), [OAuth 2](https://apiexplorer-ii-sandbox.openbankproject.com/glossary#OAuth%202), [OpenID Connect OIDC](https://apiexplorer-ii-sandbox.openbankproject.com/glossary#OAuth%202%20with%20Google) and other authentication methods including [Direct Login](https://apiexplorer-ii-sandbox.openbankproject.com/glossary#Direct%20Login). -## DOCUMENTATION +## Documentation -The API documentation is best viewed using the [OBP API Explorer](https://apiexplorer-ii-sandbox.openbankproject.com) or a third party tool that has imported the OBP Swagger definitions. +The API documentation is best viewed using the [OBP API Explorer](https://apiexplorer-ii-sandbox.openbankproject.com) 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](https://github.com/OpenBankProject/API-Explorer-II) -## STATUS of API Versions +## Status of API Versions -OBP instances support multiple versions of the API simultaniously (unless they are deactivated in config) -To see the status (DRAFT, STABLE or BLEEDING-EDGE) of an API version, look at the root endpoint e.g. /obp/v2.0.0/root or /obp/v3.0.0/root -``` +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`. + +```log 24.01.2017, [V1.2.1](https://apisandbox.openbankproject.com/obp/v1.2.1/root) was marked as stable. 24.01.2017, [V1.3.0](https://apisandbox.openbankproject.com/obp/v1.3.0/root) was marked as stable. 08.06.2017, [V2.0.0](https://apisandbox.openbankproject.com/obp/v2.0.0/root) was marked as stable. @@ -37,195 +38,239 @@ To see the status (DRAFT, STABLE or BLEEDING-EDGE) of an API version, look at th ``` -## LICENSE +## License . This project is dual licensed under the AGPL V3 (see NOTICE) and commercial licenses from TESOBE GmbH. -## SETUP +## Setup The project uses Maven 3 as its build tool. -To compile and run jetty, install Maven 3, create your configuration in obp-api/src/main/resources/props/default.props and execute: +To compile and run Jetty, install Maven 3, create your configuration in `obp-api/src/main/resources/props/default.props` and execute: - mvn install -pl .,obp-commons && mvn jetty:run -pl obp-api +```sh +mvn install -pl .,obp-commons && mvn jetty:run -pl obp-api +``` -In case that the above command fails try next one: +In case the above command fails try the next one: - export MAVEN_OPTS="-Xss128m" && mvn install -pl .,obp-commons && mvn jetty:run -pl obp-api +```sh +export MAVEN_OPTS="-Xss128m" && mvn install -pl .,obp-commons && mvn jetty:run -pl obp-api +``` [Note: How to run via IntelliJ IDEA](obp-api/src/main/docs/glossary/Run_via_IntelliJ_IDEA.md) -## Run some tests. +## Run some tests -* In obp-api/src/main/resources/props create a test.default.props for tests. Set connector=mapped +* 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 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: -* 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: e.g. -Xmx1512M -XX:MaxPermSize=512M + You might need to assign more memory via VM Options. For example: + + ``` + -Xmx1512M -XX:MaxPermSize=512M + ``` or + ``` -Xmx2048m -Xms1024m -Xss2048k -XX:MaxPermSize=1024m + ``` - Make sure your test.default.props has the minimum settings (see test.default.props.template) + 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 code to run them all. + 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 + set `bank_account_creation_listener=false` in `test.default.props`. ## Other ways to run tests -* See pom.xml for test configuration -* See http://www.scalatest.org/user_guide +* See `pom.xml` for test configuration. +* See http://www.scalatest.org/user_guide. ## From the command line -Set memory options +Set memory options: - export MAVEN_OPTS="-Xmx3000m -Xss2m" +```sh +export MAVEN_OPTS="-Xmx3000m -Xss2m" +``` -Run one test +Run one test: - mvn -DwildcardSuites=code.api.directloginTest test +```sh +mvn -DwildcardSuites=code.api.directloginTest test +``` -Run all test and save output to a file +Run all tests and save the output to a file: - export MAVEN_OPTS="-Xss128m" && mvn clean test | tee obp-api-test-results.txt +```sh +export MAVEN_OPTS="-Xss128m" && mvn clean test | tee obp-api-test-results.txt +``` ## Ubuntu 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: - uncaught exception during compilation: java.io.IOException - [ERROR] File name too long - [ERROR] two errors found - [DEBUG] Compilation failed (CompilerInterface) +```log +uncaught exception during compilation: java.io.IOException +[ERROR] File name too long +[ERROR] two errors found +[DEBUG] Compilation failed (CompilerInterface) +``` -The current workaround is to move the project directory onto a different partition, e.g. under /opt/ . +The current workaround is to move the project directory onto a different partition, e.g. under `/opt/`. ## Running the docker image -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` +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` +`openid_connect.enabled=true` becomes `OBP_OPENID_CONNECT_ENABLED=true`. -## Databases: +## Databases -The default database for testing etc is H2. PostgreSQL is used for the sandboxes (user accounts, metadata, transaction cache). List of databases fully tested is: PostgreSQL, MS SQL and H2. +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. ### Notes on using H2 web console in Dev and Test mode: -Set DB options in props file: +Set DB options in the props file: - db.driver=org.h2.Driver - db.url=jdbc:h2:./obp_api.db;DB_CLOSE_ON_EXIT=FALSE +``` +db.driver=org.h2.Driver +db.url=jdbc:h2:./obp_api.db;DB_CLOSE_ON_EXIT=FALSE +``` -In order to start H2 web console go to http://127.0.0.1:8080/console and you will see a login screen. +In order to start H2 web console go to [http://127.0.0.1:8080/console](http://127.0.0.1:8080/console) and you will see a login screen. Please use the following values: Note: make sure the JDBC URL used matches your Props value! - Driver Class: org.h2.Driver - JDBC URL: jdbc:h2:./obp_api.db;AUTO_SERVER=FALSE - User Name: - Password: - - -### Notes on the basic ussage of Postgres: -Once postgres is installed: (On Mac use brew) - -psql postgres - -create database obpdb; (or any other name of your choosing) - -create user obp; (this is the user that OBP-API will use to create and access tables etc) - -alter user obp with password 'daniel.says'; (put this password in the OBP-API Props) - -grant all on database obpdb to obp; (So OBP-API can create tables etc.) - -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 - -The restart OBP-API +``` +Driver Class: org.h2.Driver +JDBC URL: jdbc:h2:./obp_api.db;AUTO_SERVER=FALSE +User Name: +Password: +``` -### Notes on using Postgres with SSL: +### Notes on the basic usage of Postgres + +Once Postgres is installed (On macOS, use `brew`): + +1. ```sh + psql postgres + ``` + +1. Create database `obpdb`; (or any other name of your choosing). + +1. Create user `obp`; (this is the user that OBP-API will use to create and access tables etc). + +1. Alter user obp with password `daniel.says`; (put this password in the OBP-API Props). + +1. Grant all on database `obpdb` to `obp`; (So OBP-API can create tables etc.) + +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 + ``` + +1. Then, restart OBP-API. + +### Notes on using Postgres with SSL Postgres needs to be compiled with SSL support. -Use openssl to create the files you need. +Use OpenSSL to create the files you need. -For the steps, see: https://www.howtoforge.com/postgresql-ssl-certificates +For the steps, see [https://www.howtoforge.com/postgresql-ssl-certificates](https://www.howtoforge.com/postgresql-ssl-certificates). -In short, edit postgresql.conf +In short, edit `postgresql.conf`: +``` ssl = on +``` +``` ssl_cert_file = '/etc/YOUR-DIR/server.crt' +``` +``` ssl_key_file = '/etc/YOUR-DIR/server.key' +``` -And restart postgres. +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 +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 +Now in OBP-API Props, edit your `db.url` and add `&ssl=true`. For example: - e.g. - - db.url=jdbc:postgresql://localhost:5432/my_obp_database?user=my_obp_user&password=the_password&ssl=true +``` +db.url=jdbc:postgresql://localhost:5432/my_obp_database?user=my_obp_user&password=the_password&ssl=true +``` -Note: Your Java environment may need to be setup correctly to use SSL +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) +Note: You can copy the following example files to prepare your own configurations: -There is a gist / tool which is useful for this. Search the web for SSLPoke. Note this is an external repository. + - `/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). -e.g. https://gist.github.com/4ndrej/4547029 +There is a gist/tool which is useful for this. Search the web for SSLPoke. Note this is an external repository. -or +For example: -git clone https://github.com/MichalHecko/SSLPoke.git . +* [https://gist.github.com/4ndrej/4547029](https://gist.github.com/4ndrej/4547029/84d3bff7bba262b3f77baa32a43873ea95993e45#file-sslpoke-java-L1-L40) -gradle jar -cd ./build/libs/ + or -java -jar SSLPoke-1.0.jar www.github.com 443 +* ```sh + git clone https://github.com/MichalHecko/SSLPoke.git . -Successfully connected + gradle jar + cd ./build/libs/ -java -jar SSLPoke-1.0.jar YOUR-POSTGRES-DATABASE-HOST PORT + java -jar SSLPoke-1.0.jar www.github.com 443 + ``` + + > Successfully connected -You can add switches e.g. for debugging. + ```sh + java -jar SSLPoke-1.0.jar YOUR-POSTGRES-DATABASE-HOST PORT + ``` -java -jar -Dhttps.protocols=TLSv1.1,TLSv1.2 -Djavax.net.debug=all SSLPoke-1.0.jar localhost 5432 +You can add switches. For example, for debugging: +```sh +java -jar -Dhttps.protocols=TLSv1.1,TLSv1.2 -Djavax.net.debug=all SSLPoke-1.0.jar localhost 5432 +``` To import a certificate: +```sh keytool -import -storepass changeit -noprompt -alias localhost_postgres_cert -keystore /Library/Java/JavaVirtualMachines/jdk1.8.0_73.jdk/Contents/Home/jre/lib/security/cacerts -trustcacerts -file /etc/postgres_ssl_certs/server/server.crt +``` +To get a certificate from the server / get further debug information: -To get certificate from the server / get further debug information: - +```sh openssl s_client -connect ip:port +``` The above section is work in progress. @@ -233,87 +278,98 @@ 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 priviledged 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). +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). ## Sandbox data 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 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](https://raw.githubusercontent.com/OpenBankProject/OBP-API/develop/obp-api/src/main/scala/code/api/sandbox/example_data/2016-04-28/example_import.json) -4) If successful you should see this result `{ "success": "Success" }` and no error message - - +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](https://raw.githubusercontent.com/OpenBankProject/OBP-API/develop/obp-api/src/main/scala/code/api/sandbox/example_data/2016-04-28/example_import.json). +4. If successful you should see this result `{ "success": "Success" }` and no error message. -## Production Options. +## Production Options -* set the status of HttpOnly and Secure cookie flags for production, uncomment the following lines of "webapp/WEB-INF/web.xml" : +* set the status of HttpOnly and Secure cookie flags for production, uncomment the following lines of `webapp/WEB-INF/web.xml`: - - - true - true - - +```XML + + + true + true + + +``` ## Running the API in Production Mode We use 9 to run the API in production mode. -1) Install java and jetty9 +1. Install java and jetty9. -2) jetty configuration +2. jetty configuration -* Edit the /etc/default/jetty9 file so that it contains the following settings: +* Edit the `/etc/default/jetty9` file so that it contains the following settings: - NO_START=0 - JETTY_HOST=127.0.0.1 #If you want your application to be accessed from other hosts, change this to your IP address - JAVA_OPTIONS="-Drun.mode=production -XX:PermSize=256M -XX:MaxPermSize=512M -Xmx768m -verbose -Dobp.resource.dir=$JETTY_HOME/resources -Dprops.resource.dir=$JETTY_HOME/resources" + ``` + NO_START=0 + JETTY_HOST=127.0.0.1 #If you want your application to be accessed from other hosts, change this to your IP address + JAVA_OPTIONS="-Drun.mode=production -XX:PermSize=256M -XX:MaxPermSize=512M -Xmx768m -verbose -Dobp.resource.dir=$JETTY_HOME/resources -Dprops.resource.dir=$JETTY_HOME/resources" + ``` -* In obp-api/src/main/resources/props create a test.default.props file for tests. Set connector=mapped +* In obp-api/src/main/resources/props create a `test.default.props` file for tests. Set `connector=mapped`. -* In obp-api/src/main/resources/props create a default.props file for development. Set connector=mapped +* In obp-api/src/main/resources/props create a `default.props file` for development. Set `connector=mapped`. -* In obp-api/src/main/resources/props create a production.default.props file for production. Set connector=mapped. +* In obp-api/src/main/resources/props create a `production.default.props` file for production. Set `connector=mapped`. -* This file could be similar to the default.props file created above, or it could include production settings, such as information about Postgresql server, if you are using one. For example, it could have the following line for postgresql configuration. +* This file could be similar to the `default.props` file created above, or it could include production settings, such as information about the Postgresql server if you are using one. For example, it could have the following line for Postgresql configuration. - db.driver=org.postgresql.Driver - db.url=jdbc:postgresql://localhost:5432/yourdbname?user=yourdbusername&password=yourpassword + ``` + db.driver=org.postgresql.Driver + db.url=jdbc:postgresql://localhost:5432/yourdbname?user=yourdbusername&password=yourpassword + ``` -* Now, build the application to generate .war file which will be deployed on jetty server: +* Now, build the application to generate `.war` file which will be deployed on the jetty server: - cd OBP-API/ - mvn package + ```sh + cd OBP-API/ + mvn package + ``` -* This will generate OBP-API-1.0.war under OBP-API/target/ +* This will generate OBP-API-1.0.war under `OBP-API/target/`. -* Copy OBP-API-1.0.war to /usr/share/jetty9/webapps/ directory and rename it to root.war +* Copy OBP-API-1.0.war to `/usr/share/jetty9/webapps/` directory and rename it to root.war -* Edit the /etc/jetty9/jetty.conf file and comment out the lines: +* Edit the `/etc/jetty9/jetty.conf` file and comment out the lines: - etc/jetty-logging.xml - etc/jetty-started.xml + ``` + etc/jetty-logging.xml + etc/jetty-started.xml + ``` * Now restart jetty9: - sudo service jetty9 restart + ```sh + sudo service jetty9 restart + ``` -* You should now be able to browse to localhost:8080 (or yourIPaddress:8080) +* You should now be able to browse to `localhost:8080` (or `yourIPaddress:8080`). ## Using OBP-API in different app modes -1) `portal` => OBP-API as a portal i.e. without REST API -2) `apis` => OBP-API as a apis app i.e. only REST APIs -3) `apis,portal`=> OBP-API as portal and apis i.e. REST APIs and web portal +1) `portal` => OBP-API as a portal i.e. without REST API. +2) `apis` => OBP-API as an *APIs* app i.e. only REST APIs. +3) `apis,portal`=> OBP-API as portal and apis i.e. REST APIs and web portal. * Edit your props file(s) to contain one of the next cases: - - 1) server_mode=portal - 2) server_mode=apis - 3) server_mode=apis,portal - In case is not defined default case is the 3rd one i.e. server_mode=apis,portal + + 1. `server_mode=portal` + 2. `server_mode=apis` + 3. `server_mode=apis,portal` + + In case it is not defined, the default case is the 3rd one. For example, `server_mode=apis,portal`. ## Using Akka remote storage @@ -321,26 +377,28 @@ Most internal OBP model data access now occurs over Akka. This is so the machine ## Using SSL Encryption with kafka -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. +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: - - kafka.use.ssl=true - keystore.path=/path/to/api.keystore.jks - truststore.path=/path/to/api.truststore.jks + + ``` + kafka.use.ssl=true + keystore.path=/path/to/api.keystore.jks + truststore.path=/path/to/api.truststore.jks + ``` ## Using SSL Encryption with props file 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. +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 + + ``` + 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: @@ -356,43 +414,51 @@ The Encrypt/Decrypt workflow is : 1st, 2nd and 3rd step can be done using an external tool -### Encrypting props values with openssl on the commandline +### Encrypting props values with OpenSSL on the command line -1. Export the public certificate from the keystore: +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 + ```sh + keytool -export -keystore /PATH/TO/KEYSTORE.jks -alias CERTIFICATE_ALIAS -rfc -file apipub.cert + ``` + +3. 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) + ```sh + openssl x509 -pubkey -noout -in apipub.cert > PUBKEY.pub` + ``` + +4. 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) -``` + ``` + #!/bin/bash + echo -n $2 |openssl pkeyutl -pkeyopt rsa_padding_mode:pkcs1 -encrypt -pubin -inkey $1 -out >(base64) + ``` ## Using jetty password obfuscation with props file You can obfuscate passwords in the props file the same way as for jetty: -1. Create the obfuscated value as described here: https://www.eclipse.org/jetty/documentation/9.3.x/configuring-security-secure-passwords.html +1. Create the obfuscated value as described here: [https://www.eclipse.org/jetty/documentation/9.3.x/configuring-security-secure-passwords.html](https://www.eclipse.org/jetty/documentation/9.3.x/configuring-security-secure-passwords.html). -2. A props key value, XXX, is considered obfuscated if has an obfuscation property (XXX.is_obfuscated) in addition to the regular props key name in the props file e.g: +2. A props key value, XXX, is considered obfuscated if has an obfuscation property (`XXX.is_obfuscated`) in addition to the regular props key name in the props file e.g: - * db.url.is_obfuscated=true - * db.url=OBF:fdsafdsakwaetcetcetc + * `db.url.is_obfuscated=true` + * `db.url=OBF:fdsafdsakwaetcetcetc` ## Code Generation -Please refer to the [Code Generation](https://github.com/OpenBankProject/OBP-API/blob/develop/CONTRIBUTING.md##code-generation) for links + +Please refer to the [Code Generation](https://github.com/OpenBankProject/OBP-API/blob/develop/CONTRIBUTING.md##code-generation) for links. ## Customize Portal WebPage -Please refer to the [Custom Webapp](obp-api/src/main/resources/custom_webapp/README.md) for links + +Please refer to the [Custom Webapp](obp-api/src/main/resources/custom_webapp/README.md) for links. ## Using jetty password obfuscation with props file You can obfuscate passwords in the props file the same way as for jetty: -1. Create the obfuscated value as described here: https://www.eclipse.org/jetty/documentation/9.3.x/configuring-security-secure-passwords.html +1. Create the obfuscated value as described here: [https://www.eclipse.org/jetty/documentation/9.3.x/configuring-security-secure-passwords.html](https://www.eclipse.org/jetty/documentation/9.3.x/configuring-security-secure-passwords.html). 2. A props key value, XXX, is considered obfuscated if has an obfuscation property (XXX.is_obfuscated) in addition to the regular props key name in the props file e.g: @@ -400,28 +466,32 @@ You can obfuscate passwords in the props file the same way as for jetty: * db.url=OBF:fdsafdsakwaetcetcetc ## Rate Limiting -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. + +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](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 instance if you wan to use the functionality in multi node architecture. +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: -We apply Rate Limiting for two type of access: * Authorized * Anonymous -To set up Rate Limiting in case of the anonymous access edit your props file in next way: +To set up Rate Limiting in case of anonymous access edit your props file in the following way: + ``` user_consumer_limit_anonymous_access=100, In case isn't defined default value is 60 ``` -Te set up Rate Limiting in case of the authorized access use these endpoints +Te set up Rate Limiting in case of the authorized access use these endpoints: + 1. `GET ../management/consumers/CONSUMER_ID/consumer/call-limits` - Get Call Limits for a Consumer 2. `PUT ../management/consumers/CONSUMER_ID/consumer/call-limits` - Set Call Limits for a Consumer - In order to make it work edit your props file in next way: ``` @@ -430,37 +500,42 @@ redis_address=YOUR_REDIS_URL_ADDRESS, In case isn't defined default value is 127 redis_port=YOUR_REDIS_PORT, In case isn't defined default value is 6379 ``` +The next types are supported: -Next types are supported: -``` 1. per second 2. per minute 3. per hour 4. per day 5. per week 6. per month -``` -If you exceed rate limit per minute for instance you will get the response: -```json + +If you exceed the rate limit per minute for instance you will get the response: + +```JSON { "error": "OBP-10018: Too Many Requests.We only allow 3 requests per minute for this Consumer." } ``` + and response headers: + ``` X-Rate-Limit-Limit → 3 X-Rate-Limit-Remaining → 0 X-Rate-Limit-Reset → 22 ``` + Description of the headers above: -1. `X-Rate-Limit-Limit` - The number of allowed requests in the current period -2. `X-Rate-Limit-Remaining` - The number of remaining requests in the current period -3. `X-Rate-Limit-Reset` - The number of seconds left in the current period -Please note that first will be checked `per second` call limit then `per minute` etc. +1. `X-Rate-Limit-Limit` - The number of allowed requests in the current period. +2. `X-Rate-Limit-Remaining` - The number of remaining requests in the current period. +3. `X-Rate-Limit-Reset` - The number of seconds left in the current period. -Info about rate limiting availability at some instance can be found over next API endpoint: https://apisandbox.openbankproject.com/obp/v3.1.0/rate-limiting. Response we are interested in looks lke: -```json +Please note that first will be checked `per second` call limit then `per minute`, etc. + +Info about rate limiting availability at some instance can be found over next API endpoint: https://apisandbox.openbankproject.com/obp/v3.1.0/rate-limiting. The response we are interested in looks like this: + +```JSON { "enabled": false, "technology": "REDIS", @@ -470,19 +545,21 @@ Info about rate limiting availability at some instance can be found over next AP ``` ## Webhooks -Webhooks are used to call external URLs when certain events happen. -Account Webhooks focus on events around accounts. -For instance, a webhook could be used to notify an external service if a balance changes on an account. -This functionality is work in progress! -There are 3 API's endpoint related to webhooks: +Webhooks are used to call external URLs when certain events happen. Account Webhooks focus on events around accounts. For instance, a webhook could be used to notify an external service if a balance changes on an account. This functionality is a work in progress! + +There are 3 API endpoints related to webhooks: + 1. `POST ../banks/BANK_ID/account-web-hooks` - Create an Account Webhook 2. `PUT ../banks/BANK_ID/account-web-hooks` - Enable/Disable an Account Webhook 3. `GET ../management/banks/BANK_ID/account-web-hooks` - Get Account Webhooks + --- ## OpenID Connect -In order to enable an OIDC workflow at an instance of OBP-API portal app(login functionality) you need to set-up the following props: + +In order to enable an OIDC workflow at an instance of OBP-API portal app(login functionality) you need to set up the following props: + ```props ## Google as an identity provider # openid_connect_1.client_secret=OYdWujJl******_NXzPlDI4T @@ -506,10 +583,13 @@ In order to enable an OIDC workflow at an instance of OBP-API portal app(login f # openid_connect_2.access_type_offline=true # openid_connect_2.button_text = Yahoo ``` + Please note in the example above you MUST run OBP-API portal at the URL: http://127.0.0.1:8080 ## OAuth 2.0 Authentication -In order to enable an OAuth2 workflow at an instance of OBP-API backend app you need to set-up the following props: + +In order to enable an OAuth2 workflow at an instance of OBP-API backend app you need to set up the following props: + ``` # -- OAuth 2 --------------------------------------------------------------------------------- # Enable/Disable OAuth 2 workflow at a server instance @@ -524,9 +604,10 @@ In order to enable an OAuth2 workflow at an instance of OBP-API backend app you OpenID Connect is supported. Tested Identity providers: Google, MITREId. - ``` + ### Example for Google's OAuth 2.0 implementation for authentication, which conforms to the OpenID Connect specification + ``` allow_oauth2_login=true oauth2.jwk_set.url=https://www.googleapis.com/oauth2/v3/certs @@ -534,38 +615,50 @@ oauth2.jwk_set.url=https://www.googleapis.com/oauth2/v3/certs --- ## Frozen APIs + API versions may be marked as "STABLE", if changes are made to an API which has been marked as "STABLE", then unit test `FrozenClassTest` will fail. -### Changes to "STABLE" api cause the tests fail: -* modify request or response body structure of apis -* add or delete apis -* change the apis versionStatus from or to "STABLE" -If it is required for a "STABLE" api to be changed, then the class metadata must be regenerated using the FrozenClassUtil (see how to freeze an api) -### Steps to freeze an api +### Changes to "STABLE" API cause the tests to fail: + +* modify request or response body structure of APIs +* add or delete APIs +* change the APIS' `versionStatus` from or to "STABLE" + +If it is required for a "STABLE" api to be changed, then the class metadata must be regenerated using the FrozenClassUtil (see how to freeze an API) + +### Steps to freeze an API + * Run the FrozenClassUtil to regenerate persist file of frozen apis information, the file is `PROJECT_ROOT_PATH/obp-api/src/test/resources/frozen_type_meta_data` * push the file `frozen_type_meta_data` to github There is a video about the detail: [demonstrate the detail of the feature](https://www.youtube.com/watch?v=m9iYCSM0bKA) ## Frozen Connector InBound OutBound types -The same as `Frozen APIs`, if related unit test fail, make sure whether the modify is required, if yes, run frozen util to re-generate frozen types metadata file. take `RestConnector_vMar2019` as example, the corresponding util is `RestConnector_vMar2019_FrozenUtil`, the corresponding unit test is `RestConnector_vMar2019_FrozenTest` + +The same as `Frozen APIs`, if a related unit test fails, make sure whether the modification is required, if yes, run frozen util to re-generate frozen types metadata file. take `RestConnector_vMar2019` as an example, the corresponding util is `RestConnector_vMar2019_FrozenUtil`, the corresponding unit test is `RestConnector_vMar2019_FrozenTest` ## Scala / Lift -* We use scala and liftweb http://www.liftweb.net/ +* We use scala and liftweb: [http://www.liftweb.net/](http://www.liftweb.net/). -* Advanced architecture: http://exploring.liftweb.net/master/index-9.html +* Advanced architecture: [http://exploring.liftweb.net/master/index-9.html +](http://exploring.liftweb.net/master/index-9.html). * A good book on Lift: "Lift in Action" by Timothy Perrett published by Manning. ## Supported JDK Versions + * OracleJDK: 1.8, 13 * OpenJdk: 11 -OpenJDK 11 is available for download here: https://jdk.java.net/archive/ +OpenJDK 11 is available for download here: [https://jdk.java.net/archive/](https://jdk.java.net/archive/). ## Endpoint Request and Response Example - ResourceDoc#exampleRequestBody and ResourceDoc#successResponseBody can be the follow type + +```log +ResourceDoc#exampleRequestBody and ResourceDoc#successResponseBody can be the follow type +``` + * Any Case class * JObject * Wrapper JArray: JArrayBody(jArray) @@ -573,7 +666,8 @@ OpenJDK 11 is available for download here: https://jdk.java.net/archive/ * Wrapper primary type: IntBody(1), BooleanBody(true), FloatBody(1.2F)... * Empty: EmptyBody -example: +Example: + ``` resourceDocs += ResourceDoc( exampleRequestBody= EmptyBody, From d46e97d289a7b7d93a6baa9ba8ff8b3273f9ccae Mon Sep 17 00:00:00 2001 From: "`{3rd: \"Beedell\", 1st: \"Roke\"}`{.JSON5}" Date: Tue, 6 Aug 2024 15:55:49 +0100 Subject: [PATCH 2/2] Update README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit
```txt Harmony Individual Contributor Assignment Agreement Thank you for your interest in contributing to Open Bank Project ("We" or "Us"). This contributor agreement ("Agreement") documents the rights granted by contributors to Us. To make this document effective, please sign it and send it to Us by mail, email, fax, or electronic submission, following the instructions at [SUBMISSION_INSTRUCTIONS below]. This is a legally binding document, so please read it carefully before agreeing to it. The Agreement may cover more than one software project managed by Us. 1. Definitions "You" means the individual who Submits a Contribution to Us. "Contribution" means any work of authorship that is Submitted by You to Us in which You own or assert ownership of the Copyright. If You do not own the Copyright in the entire work of authorship, please follow the instructions in [NONOWNER_INSTRUCTIONS below]. "Copyright" means all rights protecting works of authorship owned or controlled by You, including copyright, moral and neighboring rights, as appropriate, for the full term of their existence including any extensions by You. "Material" means the work of authorship which is made available by Us to third parties. When this Agreement covers more than one software project, the Material means the work of authorship to which the Contribution was Submitted. After You Submit the Contribution, it may be included in the Material. "Submit" means any form of electronic, verbal, or written communication sent to Us or our representatives, including but not limited to electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, Us for the purpose of discussing and improving the Material, but excluding communication that is conspicuously marked or otherwise designated in writing by You as "Not a Contribution." "Submission Date" means the date on which You Submit a Contribution to Us. "Effective Date" means the date You execute this Agreement or the date You first Submit a Contribution to Us, whichever is earlier. "Media" means any portion of a Contribution which is not software. 2. Grant of Rights 2.1 Copyright Assignment (a) At the time the Contribution is Submitted, You assign to Us all right, title, and interest worldwide in all Copyright covering the Contribution; provided that this transfer is conditioned upon compliance with Section 2.3. (b) To the extent that any of the rights in Section 2.1(a) cannot be assigned by You to Us, You grant to Us a perpetual, worldwide, exclusive, royalty-free, transferable, irrevocable license under such non-assigned rights, with rights to sublicense through multiple tiers of sublicensees, to practice such non-assigned rights, including, but not limited to, the right to reproduce, modify, display, perform and distribute the Contribution; provided that this license is conditioned upon compliance with Section 2.3. (c) To the extent that any of the rights in Section 2.1(a) can neither be assigned nor licensed by You to Us, You irrevocably waive and agree never to assert such rights against Us, any of our successors in interest, or any of our licensees, either direct or indirect; provided that this agreement not to assert is conditioned upon compliance with Section 2.3. (d) Upon such transfer of rights to Us, to the maximum extent possible, We immediately grant to You a perpetual, worldwide, non-exclusive, royalty-free, transferable, irrevocable license under such rights covering the Contribution, with rights to sublicense through multiple tiers of sublicensees, to reproduce, modify, display, perform, and distribute the Contribution. The intention of the parties is that this license will be as broad as possible and to provide You with rights as similar as possible to the owner of the rights that You transferred. This license back is limited to the Contribution and does not provide any rights to the Material. 2.2 Patent License For patent claims including, without limitation, method, process, and apparatus claims which You [or Your Affiliates] own, control or have the right to grant, now or in the future, You grant to Us a perpetual, worldwide, non-exclusive, transferable, royalty-free, irrevocable patent license, with the right to sublicense these rights to multiple tiers of sublicensees, to make, have made, use, sell, offer for sale, import and otherwise transfer the Contribution and the Contribution in combination with the Material (and portions of such combination). This license is granted only to the extent that the exercise of the licensed rights infringes such patent claims; and provided that this license is conditioned upon compliance with Section 2.3. 2.3 Outbound License Based on the grant of rights in Sections 2.1 and 2.2, if We include Your Contribution in a Material, We may license the Contribution under any license(s), including copyleft, permissive, commercial, or proprietary licenses and we agree to license the Contribution under an AGPL V3 or later compatible license. 2.4 Moral Rights. If moral rights apply to the Contribution, to the maximum extent permitted by law, You waive and agree not to assert such moral rights against Us or our successors in interest, or any of our licensees, either direct or indirect. 2.5 Our Rights. You acknowledge that We are not obligated to use Your Contribution as part of the Material and may decide to include any Contribution We consider appropriate. 2.6 Reservation of Rights. Any rights not expressly assigned or licensed under this section are expressly reserved by You. 3. Agreement You confirm that: (a) You have the legal authority to enter into this Agreement. (b) You own the Copyright and patent claims covering the Contribution which are required to grant the rights under Section 2. (c) The grant of rights under Section 2 does not violate any grant of rights which You have made to third parties, including Your employer. If You are an employee, You have had Your employer approve this Agreement or sign the Entity version of this document. If You are less than eighteen years old, please have Your parents or guardian sign the Agreement. (d) You have followed the instructions in [NONOWNER_INSTRUCTIONS], if You do not own the Copyright in the entire work of authorship Submitted. 4. Disclaimer EXCEPT FOR THE EXPRESS WARRANTIES IN SECTION 3, THE CONTRIBUTION IS PROVIDED "AS IS". MORE PARTICULARLY, ALL EXPRESS OR IMPLIED WARRANTIES INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE EXPRESSLY DISCLAIMED BY YOU TO US AND BY US TO YOU. TO THE EXTENT THAT ANY SUCH WARRANTIES CANNOT BE DISCLAIMED, SUCH WARRANTY IS LIMITED IN DURATION TO THE MINIMUM PERIOD PERMITTED BY LAW. 5. Consequential Damage Waiver TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT WILL YOU OR US BE LIABLE FOR ANY LOSS OF PROFITS, LOSS OF ANTICIPATED SAVINGS, LOSS OF DATA, INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL AND EXEMPLARY DAMAGES ARISING OUT OF THIS AGREEMENT REGARDLESS OF THE LEGAL OR EQUITABLE THEORY (CONTRACT, TORT OR OTHERWISE) UPON WHICH THE CLAIM IS BASED. 6. Miscellaneous 6.1 This Agreement will be governed by and construed in accordance with the laws of Germany excluding its conflicts of law provisions. Under certain circumstances, the governing law in this section might be superseded by the United Nations Convention on Contracts for the International Sale of Goods ("UN Convention") and the parties intend to avoid the application of the UN Convention to this Agreement and, thus, exclude the application of the UN Convention in its entirety to this Agreement. 6.2 This Agreement sets out the entire agreement between You and Us for Your Contributions to Us and overrides all other agreements or understandings. 6.3 If You or We assign the rights or obligations received through this Agreement to a third party, as a condition of the assignment, that third party must agree in writing to abide by all the rights and obligations in the Agreement. 6.4 The failure of either party to require performance by the other party of any provision of this Agreement in one situation shall not affect the right of a party to require such performance at any time in the future. A waiver of performance under a provision in one situation shall not be considered a waiver of the performance of the provision in the future or a waiver of the provision in its entirety. 6.5 If any provision of this Agreement is found void and unenforceable, such provision will be replaced to the extent possible with a provision that comes closest to the meaning of the original provision and which is enforceable. The terms and conditions set forth in this Agreement shall apply notwithstanding any failure of essential purpose of this Agreement or any limited remedy to the maximum extent possible under law. ________________________ You: Name: Roke Julian Lockhart Beedell Address: The Homestead, The Common, Hanworth, NRW, NFK, ENG, GBR Github username: RokeJulianLockhart Email / Phone: 66an3p0y@rokejulianlockhart.addy.io / +44-7840-875616 ________________________ Us: Name: Simon Redfern Title: CEO, TESOBE GmbH Address: Osloerstrasse 16/17, Berlin 13359, Germany ________________________ [SUBMISSION_INSTRUCTIONS] – In person. [NONOWNER_INSTRUCTIONS] – Please tell us in person and in writing. This work is licensed under a Creative Commons Attribution 3.0 Unported License. ```
--- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index c055e7accb..d307640366 100644 --- a/README.md +++ b/README.md @@ -37,9 +37,8 @@ To see the status (DRAFT, STABLE or BLEEDING-EDGE) of an API version, look at th 16.12.2022, [V5.0.0](https://apisandbox.openbankproject.com/obp/v5.0.0/root) was marked as stable. ``` - ## License -. + This project is dual licensed under the AGPL V3 (see NOTICE) and commercial licenses from TESOBE GmbH. ## Setup