diff options
Diffstat (limited to 'libeufin/nexus-tutorial.rst')
| -rw-r--r-- | libeufin/nexus-tutorial.rst | 631 |
1 files changed, 0 insertions, 631 deletions
diff --git a/libeufin/nexus-tutorial.rst b/libeufin/nexus-tutorial.rst deleted file mode 100644 index 5ce357b5..00000000 --- a/libeufin/nexus-tutorial.rst +++ /dev/null @@ -1,631 +0,0 @@ -.. target audience: operator, developer - -LibEuFin How-To -############### - -.. contents:: Table of Contents - -The LibEuFin Nexus is a Web service that provides a JSON abstraction layer to -access bank accounts. It does **not** itself offer banking services, but is a -translator between JSON requests and other banking protocols (such as EBICS), -that are offered by banks. - -This document explains how to set up Nexus to access a bank account -via the EBICS protocol. - -In order to follow all the steps below, the reader should either -have access to a bank account with EBICS support or follow the -steps in :ref:`Configuring the Sandbox <configuring-the-sandbox>`. - - -Installing LibEuFin -=================== - -Installation on Debian ----------------------- - -.. include:: ../frags/installing-debian.rst - -To install LibEuFin, you can now simply run: - -.. code-block:: console - - # apt install libeufin - -Administration via SystemD --------------------------- - -After the Debian installation, the installed unit files -should be listed by the following command: - -.. code-block:: console - - # systemctl list-unit-files | egrep '(nexus|sandbox)' - -Both ``nexus.service`` and ``sandbox.service`` should appear. - -At this point, the services can be started on boot: - -.. code-block:: console - - # systemctl enable libeufin-nexus # use 'disable' to rollback - # systemctl enable libeufin-sandbox # only if you want the sandbox - -Or just manually: - -.. code-block:: console - - # systemctl start libeufin-nexus # use 'stop' to terminate. - # systemctl start libeufin-sandbox # only if you want the sandbox - -The following command should inform the user about the status -of the running / terminated service: - -.. code-block:: console - - # systemctl status libeufin-nexus - -For more diagnostics, use: - -.. code-block:: console - - # journalctl -u libeufin-nexus - -Run-time dependencies ---------------------- - -LibEuFin has the following run-time dependencies: - -* OpenJDK 11 -* Python 3.8 -* python3-click (can be installed via ``pip3 install click``) -* python3-requests (can be installed via ``pip3 install requests``) - -These dependencies only need to be installed manually when building from source -or using the prebuilt binaries. - -Downloading prebuilt binaries ------------------------------ - -Pre-built packages can be obtained from the `taler.net website -<https://taler.net/files/libeufin>`__. - -Unpack the ``libeufin-$version.zip`` file to -your desired location (typically ``/opt`` or ``~/opt``) and make sure that your ``PATH`` -environment variable contains the ``bin/`` directory of the unpacked archive. - -Building from source --------------------- - -Nexus belongs to the LibEuFin project, and can be downloaded via Git: - -.. code-block:: console - - $ git clone git://git.taler.net/libeufin - -Note that Kotlin and Gradle should already work on the host system. - -Navigate into the *libeufin* local repository, and from top-level run: - -.. code-block:: console - - $ ./bootstrap - $ ./configure --prefix=$PREFIX - $ make install - -Verifying your installation ---------------------------- - -In case of success, the three following commands should be found: - -.. code-block:: console - - $ which libeufin-nexus - $ which libeufin-sandbox - $ which libeufin-cli - - -.. _configuring-the-sandbox: - -Configuring the Sandbox (Optional) -================================== - -If you don't have access to a real bank account with an EBICS API, you can set -up the sandbox. The sandbox is a simplistic and incomplete implementation of a -core banking system with EBICS access to bank accounts. - -The sandbox relies on a database, which you must specify using a JDBC -connection URI with the ``LIBEUFIN_SANDBOX_DB_CONNECTION`` environment -variable, before invoking any commands. -If this variable is not set, ``libeufin-sandbox`` complains and exits: - -.. code-block:: console - - $ libeufin-sandbox serve - DB connection string not found/valid in the env variable LIBEUFIN_SANDBOX_DB_CONNECTION. - The following two examples are valid connection strings: - jdbc:sqlite:/tmp/libeufindb.sqlite3 - jdbc:postgresql://localhost:5432/libeufindb?user=Foo&password=secret - -Only *SQLite* and *PostgreSQL (via TCP)* are supported right now. - -For the following commands, the sandbox service must be running. -The sandbox service is started with the following command: - -.. code-block:: console - - $ export LIBEUFIN_SANDBOX_DB_CONNECTION=jdbc:sqlite:/tmp/libeufintestdb - $ libeufin-sandbox serve --port 5016 - -To reset the state of the sandbox, delete the database. - -For invocations of the LibEuFin command-line interface tool (``libeufin-cli``), -the following environment variable must be set to the URL of the sandbox -service: - -.. code-block:: console - - $ export LIBEUFIN_SANDBOX_URL=http://localhost:5016/ - -Verify that the sandbox is running: - -.. code-block:: console - - $ libeufin-cli sandbox check - { - "name" : "libeufin-sandbox", - "version" : "0.0.0-dev.0" - } - -Now an EBICS host can be created: - -.. code-block:: console - - $ libeufin-cli sandbox ebicshost create --host-id testhost - -Note that most ``libeufin-cli`` subcommands will ask for input interactively if -the respective value is not specified on the command line. - -Next, create an EBICS subscriber (identified by the partner ID and user ID) for the host: - -.. code-block:: console - - $ libeufin-cli sandbox ebicssubscriber create \ - --host-id testhost --partner-id partner01 --user-id user01 - -Create a bank account for the subscriber and add a sample transaction: - -.. code-block:: console - - $ libeufin-cli sandbox ebicsbankaccount create \ - --currency EUR \ - --iban DE18500105172929531888 \ - --bic INGDDEFFXXX \ - --person-name "Jane Normal" \ - --account-name "testacct01" \ - --ebics-host-id testhost \ - --ebics-user-id user01 \ - --ebics-partner-id partner01 - -The account name ``testacct01`` is the unique identifier of the account within -the sandbox. The EBICS parameters identify the subscriber that should have -access to the bank account via EBICS. - -To populate the account with some test transactions, run the following command -(note that we use the ``bankaccount`` subcommand, because there is no need to rely -on EBICS): - -.. code-block:: console - - $ libeufin-cli sandbox bankaccount generate-transactions testacct01 - -.. code-block:: console - - $ libeufin-cli sandbox bankaccount simulate-incoming-transaction testacct01 \ - --debtor-iban DE06500105174526623718 \ - --debtor-bic INGDDEFFXXX \ - --debtor-name "Joe Foo" \ - --subject "Hello World" \ - --amount 10.50 - -Payments to a sandbox bank account can be listed as follows: - -.. code-block:: console - - $ libeufin-cli sandbox bankaccount transactions testacct01 - -.. note:: - - The sandbox is intended as a testing tool and thus not stable. - -For more information on the available commands, use the built-in ``--help`` flag. -The full functionality of the sandbox is available via -the :ref:`Sandbox API <sandbox-api>`. - - -Connect Nexus with an EBICS account -=================================== - -Nexus relies on a database, which you must specify using a JDBC -connection URI with the ``LIBEUFIN_NEXUS_DB_CONNECTION`` environment -variable, before invoking any commands. -(If this variable is not set, ``libeufin-nexus`` complains and exits.) - -Only *SQLite* (e.g. ``jdbc:sqlite:/tmp/libeufintestdb``) and *PostgreSQL (via TCP)* -(e.g. ``jdbc:postgresql://localhost:$port/libeufintestdb?user=$username&password=$password``) -are supported right now. - -Use the following command to run the nexus service: - -.. code-block:: console - - $ export LIBEUFIN_NEXUS_DB_CONNECTION=jdbc:postgresql://localhost:5433/libeufindb?user=foo&password=secret - $ libeufin-nexus serve --port 5017 - -This assumes that the PostgreSQL service with a database -called ``libeufindb`` listens on port 5433 -for requests from the nexus service. -The nexus service itself listens on port 5017. -Note that you must have the ``LIBEUFIN_NEXUS_DB_CONNECTION`` -environment variable set for most uses of the libeufin-nexus -command. - -At this point a superuser account needs to be created: - -.. code-block:: console - - $ libeufin-nexus superuser foo --password secret - -If you omit ``--password secret``, you will interactively be asked for a password. -For simplicity, a superuser can as well act as a normal user, but an API -to create less privileged users is offered. - -.. note:: - - User and permissions management in LibEuFin is still under development. - In particular, permissions for non-superusers are very limited at the moment. - -The command line interface needs the following three values -to be defined in the environment: ``LIBEUFIN_NEXUS_URL``, ``LIBEUFIN_NEXUS_USERNAME``, -and ``LIBEUFIN_NEXUS_PASSWORD``. In this example, ``LIBEUFIN_NEXUS_USERNAME`` should be -set to ``foo``, and ``LIBEUFIN_NEXUS_PASSWORD`` to the value given for its password -in the previous step (with the ``libeufin-nexus superuser`` command). The -``LIBEUFIN_NEXUS_URL`` could be given as ``http://localhost:5017/``. - -Next, we create a EBICS *bank connection* that nexus can use to communicate with the bank. - -.. note:: - - For the sandbox setup in this guide, the ``EBICS_BASE_URL`` - should be ``http://localhost:5016/ebicsweb``. - -.. code-block:: console - - $ libeufin-cli \ - connections \ - new-ebics-connection \ - --ebics-url $EBICS_BASE_URL \ - --host-id $EBICS_HOST_ID \ - --partner-id $EBICS_PARTNER_ID \ - --ebics-user-id $EBICS_USER_ID \ - $CONNECTION_NAME - -If this step executes correctly, Nexus will have created all the cryptographic -material that is needed on the client side; in this EBICS example, it created -the signature and identification keys. It is therefore advisable to *make -a backup copy* of such keys. - -.. code-block:: console - - $ libeufin-cli \ - connections \ - export-backup \ - --passphrase $SECRET \ - --output-file $BACKUP_FILE \ - $CONNECTION_NAME - -At this point, Nexus needs to both communicate its keys to the bank, and -download the bank's keys. This synchronization happens through the INI, HIA, and -finally, HPB message types. - -After the electronic synchronization, the subscriber must confirm their keys -by sending a physical mail to the bank. The following command helps generating -such letter: - -.. code-block:: console - - $ libeufin-cli connections get-key-letter $CONNECTION_NAME out.pdf - -.. note:: - - When using the LibEuFin sandbox, subscribers are automatically - activated after keys are received electronically. - -.. code-block:: console - - $ libeufin-cli \ - connections \ - connect \ - $CONNECTION_NAME - -Once the connection is synchronized, Nexus needs to import locally the data -corresponding to the bank accounts offered by the bank connection just made. -The command below downloads the list of the bank accounts offered by ``$CONNECTION_NAME``. - -.. code-block:: console - - $ libeufin-cli \ - connections \ - download-bank-accounts \ - $CONNECTION_NAME - -It is now possible to list the accounts offered by the connection. - -.. code-block:: console - - $ libeufin-cli \ - connections \ - list-offered-bank-accounts \ - $CONNECTION_NAME - -.. note:: - - The ``nexusBankAccountId`` field should at this step be ``null``, - as we have not yet imported the bank account and thus the account - does not yet have a local name. - -Nexus now needs an explicit import of the accounts it should manage. This -step is needed to let the user pick a custom name for such accounts. - -.. code-block:: console - - $ libeufin-cli \ - connections \ - import-bank-account \ - --offered-account-id testacct01 \ - --nexus-bank-account-id $LOCAL_ACCOUNT_NAME \ - $CONNECTION_NAME - -Once a Nexus user imported a bank account (``$LOCAL_ACCOUNT_NAME``) -under a certain connection (``$CONNECTION_NAME``), it is possible -to accomplish the usual operations for any bank account: asking for the -list of transactions, and making a payment. - -Request history of transactions -=============================== - -The LibEuFin nexus keeps a local copy of the bank account's transaction -history. Before querying transactions locally, it is necessary -to request transactions for the bank account via the bank connection. - -This command asks Nexus to download the latest transaction reports/statements -through the bank connection: - -.. code-block:: console - - $ libeufin-cli accounts fetch-transactions $LOCAL_ACCOUNT_NAME - -.. note:: - - By default, the latest available transactions are fetched. It is also - possible to specify a custom date range (or even all available transactions) - and the type of transactions to fetch (inter-day statements or intra-day - reports). - -Once Nexus has stored all the information in the database, the -client can ask to actually see the transactions: - -.. code-block:: console - - $ libeufin-cli accounts transactions $LOCAL_ACCOUNT_NAME - -Make a payment -============== - -Payments pass through two phases: preparation and submission. The preparation -phase assigns the payment initiation a unique ID, which prevents accidental -double submissions of payments in case of network failures or other -disruptions. - - -The following command prepares a payment: - -.. code-block:: console - - $ libeufin-cli accounts prepare-payment \ - --creditor-iban=$IBAN_TO_SEND_MONEY_TO \ - --creditor-bic=$BIC_TO_SEND_MONEY_TO \ - --creditor-name=$CREDITOR_NAME \ - --payment-amount=$AMOUNT \ - --payment-subject=$SUBJECT \ - $LOCAL_ACCOUNT_NAME - -Note: the ``$AMOUNT`` value needs the format ``CURRENCY:X.Y``; for example -``EUR:10``, or ``EUR:1.01``. - -The previous command should return a value (``$UUID``) that uniquely -identifies the prepared payment in the Nexus system. That is needed -in the next step, to **send the payment instructions to the bank**: - -.. code-block:: console - - $ libeufin-cli accounts submit-payment \ - --payment-uuid $UUID \ - $LOCAL_ACCOUNT_NAME - -Automatic scheduling -==================== - -With an EBICS bank connection, the LibEuFin nexus needs to regularly query for -new transactions and (re-)submit prepared payments. - -It is possible to schedule these tasks via an external task scheduler such as -cron(8). However, the nexus also has an internal task scheduling mechanism for -accounts. - - -The following three commands create a schedule for submitting payments hourly, -fetching transactions (intra-day reports) every 5 minutes, and (inter-day statements) -once at 11pm every day : - -.. code-block:: console - - $ libeufin-cli accounts task-schedule myacct \ - --task-type="submit" \ - --task-name='submit-payments-hourly' \ - --task-cronspec='0 0 *' - - $ libeufin-cli accounts task-schedule myacct \ - --task-type="fetch" \ - --task-name='fetch-5min' \ - --task-cronspec='0 */5 *' \ - --task-param-level=report \ - --task-param-range-type=latest - - $ libeufin-cli accounts task-schedule myacct \ - --task-type="fetch" \ - --task-name='fetch-daily' \ - --task-cronspec='0 0 23' \ - --task-param-level=statement \ - --task-param-range-type=latest - -The cronspec has the following format, which is slightly non-standard due to -the ``SECONDS`` field - -.. code-block:: none - - SECONDS MINUTES HOURS DAY-OF-MONTH[optional] MONTH[optional] DAY-OF-WEEK[optional] - - -Restore the backup -================== - -The following command restores all the details associated with -one bank connection subscription. For EBICS, this means that the -INI and HIA secret keys will be restored for the requesting user. - -.. code-block:: console - - $ libeufin-cli connections \ - restore-backup \ - --passphrase=$SECRET \ - --backup-file=$BACKUP_FILE \ - $CONNECTION_NAME - -.. - FIXME: - On a bad password given, Nexus responds - "bad backup given" instead of "authentication failed". - - -Creating a Taler facade -======================= - -Facades are additional abstraction layers that can serve -specific purposes. For example, one application might need -a filtered version of the transaction history, or it might -want to refuse payments that do not conform to certain rules. - -At this moment, only the *Taler facade type* is implemented -in the Nexus, and the command below instantiates one under a -existing bank account / connection pair. You can freely -assign an identifier for the ``$FACADE_NAME`` below: - -.. code-block:: console - - $ libeufin-cli facades new-taler-wire-gateway-facade \ - --currency EUR \ - --facade-name $FACADE_NAME \ - $CONNECTION_NAME \ - $LOCAL_ACCOUNT_NAME - -At this point, the additional *taler-wire-gateway* (FIXME: link -here to API here) API becomes offered by the Nexus. The purpose -is to let a Taler exchange rely on Nexus to manage its bank account. - -The base URL of the facade that can be used by the Taler exchange -as the Taler Wire Gateway base URL located when listing the facades: - -.. code-block:: console - - $ libeufin-cli facades list - -Creating a Anastasis facade -=========================== - -The following command creates a Anastasis facade. At this point, *only* -the superuser is able to create facades; please set the environment variables -``LIBEUFIN_NEXUS_USERNAME`` and ``LIBEUFIN_NEXUS_PASSWORD`` accordingly. - -.. code-block:: console - - $ libeufin-cli facades new-anastasis-facade \ - --currency EUR \ - --facade-name $FACADE_NAME \ - $CONNECTION_NAME \ - $LOCAL_ACCOUNT_NAME - -If the previous command succeeded, it is possible to see the -facade's base URL with: - -.. code-block:: console - - $ libeufin-cli facades list - -At this point, to allow a non superuser to use the facade, a history -permission needs to be set: - -.. code-block:: console - - $ libeufin-cli permissions grant \ - user $USERNAME \ - facade $FACADENAME \ - facade.anastasis.history - -.. note:: - - There is no need to set/unset a transfer permission on the facade - since this one does not offer any endpoint to issue wire transfers. - -Managing Permissions and Users -============================== - -This guide has so far assumed that a superuser is accessing the LibEuFin Nexus. -However, it is advisable that the Nexus is accessed with users that only have a -minimal set of permissions. - -The Nexus currently only has support for giving non-superusers access to Taler -wire gateway facades. - -To create a new user, use the ``users`` subcommand of the CLI: - -.. code-block:: console - - $ libeufin-cli users list - # [ ... shows available users ... ] - - $ libeufin-cli users create $USERNAME - # [ ... will prompt for password ... ] - -Permissions are managed with the ``permissions`` subcommand. -The following commands grant permissions to view the transaction history -and create payment initiations with a Taler wire gateway facade: - - -.. code-block:: console - - $ libeufin-cli permissions grant \ - user $USERNAME \ - facade $FACADENAME \ - facade.talerWireGateway.history - - $ libeufin-cli permissions grant \ - user $USERNAME \ - facade $FACADENAME \ - facade.talerWireGateway.transfer - -The list of all granted permissions can be reviewed: - -.. code-block:: console - - $ libeufin-cli permissions list |