diff options
Diffstat (limited to 'libeufin/nexus-tutorial.rst')
| -rw-r--r-- | libeufin/nexus-tutorial.rst | 339 |
1 files changed, 298 insertions, 41 deletions
diff --git a/libeufin/nexus-tutorial.rst b/libeufin/nexus-tutorial.rst index 51e0cd28..482b0f96 100644 --- a/libeufin/nexus-tutorial.rst +++ b/libeufin/nexus-tutorial.rst @@ -134,6 +134,9 @@ 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 uses HTTP Basic auth, with username ``admin``. +Choose a password and set env var ``LIBEUFIN_SANDBOX_ADMIN_PASSWORD`` to it. + 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. @@ -141,6 +144,7 @@ If this variable is not set, ``libeufin-sandbox`` complains and exits: .. code-block:: console + $ export LIBEUFIN_SANDBOX_ADMIN_PASSWORD=secret $ 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: @@ -149,99 +153,336 @@ If this variable is not set, ``libeufin-sandbox`` complains and exits: 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: +Before being usable, a Sandbox needs to be configured. This is done +by creating the ``default`` demobank. A demobank is a set of configuration +values associated to one name; in the example below, we'll create one +named ``default``, that is mandatory to have. + +.. note:: + + By design, many demobanks can be hosted by one running Sandbox, + although at the time of writing only the ``default`` one is supported. + +A default demobank having the EUR currency is created with the following command: + +.. code-block:: console + + $ export LIBEUFIN_SANDBOX_DB_CONNECTION=jdbc:sqlite:/tmp/libeufintestdb + $ libeufin-sandbox config --currency EUR default + +In order to use Taler, a default exchange needs to be configured. + +.. code-block:: console + + $ export LIBEUFIN_SANDBOX_DB_CONNECTION=jdbc:sqlite:/tmp/libeufintestdb + $ libeufin-sandbox default-exchange --demobank default $exchange_base_url $exchange_payto_address + +The sandbox service can now be started with the following command: .. code-block:: console + $ export LIBEUFIN_SANDBOX_ADMIN_PASSWORD=secret $ export LIBEUFIN_SANDBOX_DB_CONNECTION=jdbc:sqlite:/tmp/libeufintestdb $ libeufin-sandbox serve --port 5016 +The instructions below hook Nginx to the Sandbox: + +.. code-block:: nginx + + redirect / to /demobanks/default; + rewrite ^/$ https://$host/demobanks/default; + location / { + proxy_set_header Host $host; + proxy_set_header X-Forwarded-Host $host; + proxy_set_header X-Forwarded-Proto "https"; + proxy_set_header X-Forwarded-Prefix "/"; + proxy_pass http://localhost: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: +the following environment variables must be set to the authentication +information, and the URL of the sandbox service: .. code-block:: console - $ export LIBEUFIN_SANDBOX_URL=http://localhost:5016/ + $ export LIBEUFIN_SANDBOX_USERNAME=admin + $ export LIBEUFIN_SANDBOX_PASSWORD=secret + $ export LIBEUFIN_SANDBOX_URL=http://localhost:5016 +Note that the password is the same as for ``LIBEUFIN_SANDBOX_ADMIN_PASSWORD``. Verify that the sandbox is running: .. code-block:: console $ libeufin-cli sandbox check - { - "name" : "libeufin-sandbox", - "version" : "0.0.0-dev.0" - } + Hello, this is the Sandbox Now an EBICS host can be created: .. code-block:: console $ libeufin-cli sandbox ebicshost create --host-id testhost + $ libeufin-cli sandbox ebicshost list + { + "ebicsHosts" : [ "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: +Next, register a user. For the ``libeufin-cli sandbox demobank register`` +command, the ``LIBEUFIN_SANDBOX_USERNAME`` and ``LIBEUFIN_SANDBOX_PASSWORD`` +are assumed to be ``jrluser`` and ``easy``, respectively. + +.. note:: + + All the following commands address the ``default`` demobank, see ``libeufin-cli sandbox demobank --help``. .. code-block:: console - $ libeufin-cli sandbox ebicssubscriber create \ - --host-id testhost --partner-id partner01 --user-id user01 + $ export LIBEUFIN_SANDBOX_USERNAME=jrluser + $ export LIBEUFIN_SANDBOX_PASSWORD=easy + $ libeufin-cli sandbox demobank register -Create a bank account for the subscriber and add a sample transaction: +Check the balance of the user just created: .. 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 + $ libeufin-cli sandbox \ + demobank info --bank-account jrluser + +With a user registered, we can now create an EBICS subscriber (identified by +the partner ID and user ID) for the host. This command requires admin +privileges, so ``LIBEUFIN_SANDBOX_USERNAME`` and ``LIBEUFIN_SANDBOX_PASSWORD`` +are reset back to ``admin`` and ``secret``, respectively. -The account name ``testacct01`` is the unique identifier of the account within +.. The plan is to replace the ‘sandbox ebicssubscriber list’ command + below with a ‘sandbox demobank show-ebicssubscriber’ command. + Need to implement it first! + +.. code-block:: console + + $ export LIBEUFIN_SANDBOX_USERNAME=admin + $ export LIBEUFIN_SANDBOX_PASSWORD=secret + $ libeufin-cli sandbox \ + demobank new-ebicssubscriber \ + --host-id testhost \ + --partner-id partner01 \ + --user-id user02 \ + --bank-account jrluser + $ libeufin-cli sandbox ebicssubscriber list + { + "subscribers" : [ { + "hostID" : "testhost", + "partnerID" : "partner01", + "userID" : "user02", + "systemID" : null, + "demobankAccountLabel" : "jrluser" + } ] + } + +The ``libeufin-cli sandbox demobank new-ebicssubscriber`` command +also creates an associated bank account. You can see it with command: + +.. code-block:: console + + $ libeufin-cli sandbox bankaccount list + [ { + "label" : "bank", + "name" : "Bank account owner's name", + "iban" : "DE895351", + "bic" : "SANDBOXX" + }, { + "label" : "jrluser", + "name" : "Bank account owner's name", + "iban" : "DE724881", + "bic" : "SANDBOXX" + } ] + +The account name ``jrluser`` 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): +The account already has one transaction, the "Sign-up bonus" from the bank. +Note that in the following examples we transition to using the ``bankaccount`` +subcommand, because there is no need to rely on EBICS: .. code-block:: console - $ libeufin-cli sandbox bankaccount generate-transactions testacct01 + $ libeufin-cli sandbox bankaccount transactions jrluser + { + "payments" : [ { + "accountLabel" : "jrluser", + "creditorIban" : "DE724881", + "creditorBic" : "SANDBOXX", + "creditorName" : "Unknown", + "debtorIban" : "DE895351", + "debtorBic" : "SANDBOXX", + "debtorName" : "The Bank", + "amount" : "100", + "currency" : "EUR", + "subject" : "Sign-up bonus", + "date" : "Tue, 22 Feb 2022 00:04:15 GMT", + "creditDebitIndicator" : "credit", + "accountServicerReference" : "2NG75I0O", + "paymentInformationId" : null + } ] + } + +To populate the account with some more transactions, run the following command: .. code-block:: console - $ libeufin-cli sandbox bankaccount simulate-incoming-transaction testacct01 \ + $ libeufin-cli sandbox bankaccount generate-transactions jrluser + +.. code-block:: console + + $ libeufin-cli sandbox bankaccount simulate-incoming-transaction jrluser \ --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: +Now the list of transactions has grown by several entries: + +.. code-block:: console + + $ libeufin-cli sandbox bankaccount transactions jrluser + { + "payments" : [ { + "accountLabel" : "jrluser", + "creditorIban" : "DE724881", + "creditorBic" : "SANDBOXX", + "creditorName" : "Unknown", + "debtorIban" : "DE895351", + "debtorBic" : "SANDBOXX", + "debtorName" : "The Bank", + "amount" : "100", + "currency" : "EUR", + "subject" : "Sign-up bonus", + "date" : "Tue, 22 Feb 2022 00:04:15 GMT", + "creditDebitIndicator" : "credit", + "accountServicerReference" : "2NG75I0O", + "paymentInformationId" : null + }, { + "accountLabel" : "jrluser", + "creditorIban" : "DE724881", + "creditorBic" : "SANDBOXX", + "creditorName" : "Creditor Name", + "debtorIban" : "DE64500105178797276788", + "debtorBic" : "DEUTDEBB101", + "debtorName" : "Max Mustermann", + "amount" : "22", + "currency" : "EUR", + "subject" : "sample transaction GSF7S5LC", + "date" : "Tue, 22 Feb 2022 01:26:18 GMT", + "creditDebitIndicator" : "credit", + "accountServicerReference" : "GSF7S5LC", + "paymentInformationId" : null + }, { + "accountLabel" : "jrluser", + "creditorIban" : "DE64500105178797276788", + "creditorBic" : "DEUTDEBB101", + "creditorName" : "Max Mustermann", + "debtorIban" : "DE724881", + "debtorBic" : "SANDBOXX", + "debtorName" : "Debitor Name", + "amount" : "10", + "currency" : "EUR", + "subject" : "sample transaction 1WUP303Q", + "date" : "Tue, 22 Feb 2022 01:26:18 GMT", + "creditDebitIndicator" : "debit", + "accountServicerReference" : "1WUP303Q", + "paymentInformationId" : null + }, { + "accountLabel" : "jrluser", + "creditorIban" : "DE724881", + "creditorBic" : "SANDBOXX", + "creditorName" : "Creditor Name", + "debtorIban" : "DE06500105174526623718", + "debtorBic" : "INGDDEFFXXX", + "debtorName" : "Joe Foo", + "amount" : "10.50", + "currency" : "EUR", + "subject" : "Hello World", + "date" : "Tue, 22 Feb 2022 01:26:41 GMT", + "creditDebitIndicator" : "credit", + "accountServicerReference" : "sandbox-ALQP8TXKJWRVKMAH", + "paymentInformationId" : null + } ] + } + +Lastly, you will want to schedule some tasks to run +periodically in the background. +This enables the Nexus to interact in (almost) real-time with the bank. .. code-block:: console - $ libeufin-cli sandbox bankaccount transactions testacct01 + $ libeufin-cli accounts task-schedule jrluser \ + --task-type submit \ + --task-name submit-payments-each-second \ + --task-cronspec "* * *" + $ libeufin-cli accounts task-schedule jrluser \ + --task-type fetch \ + --task-name fetch-reports-each-second \ + --task-cronspec "* * *" \ + --task-param-level report \ + --task-param-range-type latest + +The first task submits payments and the second fetches reports. +Both are specified to run every second (cronspec ``"* * *"``). +To reduce the frequency to every five seconds, use the cronspec ``"*/5 * *"`` +(remember to quote, to protect from shell filename expansion). .. note:: The sandbox is intended as a testing tool and thus not stable. +Disable registrations (experimental) +------------------------------------ + +Demobanks can disable/enable registrations for new users. +The responsible options are +``--with-registrations`` / ``--without-registrations``. + 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>`. +Register merchants for local currencies (experimental) +------------------------------------------------------ + +This feature allows to register merchants to participate +in a local currency circuit. After having installed the +Sandbox with the steps described above, the administrator +can now register new merchant accounts with the following +command. The main difference with ordinary registrations +is that this API offers to associate a `cash-out` address +to the account, so that merchants can convert the local +currency back to their fiat bank account. + +.. note:: + Disable ordinary registrations as described in the previous section, + to make sure that only the administrator can add new accounts. + +.. code-block:: console + + $ export LIBEUFIN_SANDBOX_USERNAME=admin + $ export LIBEUFIN_SANDBOX_PASSWORD=$password + $ export LIBEUFIN_NEW_CIRCUIT_ACCOUNT_PASSWORD=$circuit-account-password + $ libeufin-cli sandbox demobank circuit-register \ + --username=example-shop \ + --email=example-shop@example.com \ + --cashout-address=payto://iban/EXAMPLESHOP-FIAT-IBAN \ + --name="Example Shop" + + +If the command exited successfully, the new user should be +able to login with the ``$circuit-account-username`` and +``$circuit-account-password`` credentials. Run ``libeufin-cli sandbox demobank circuit-register --help``, for additional information about the other options. Connect Nexus with an EBICS account =================================== @@ -255,7 +496,12 @@ Only *SQLite* (e.g. ``jdbc:sqlite:/tmp/libeufintestdb``) and *PostgreSQL (via TC (e.g. ``jdbc:postgresql://localhost:$port/libeufintestdb?user=$username&password=$password``) are supported right now. -Use the following command to run the nexus service: +Use the following command to run the Nexus service: + + Neuxs defaults to *not* storing the messages that it downloads + from the bank. To revert this behaviour, export also the environment + variable ``LIBEUFIN_NEXUS_KEEP_BANK_MESSAGES`` to ``yes`` before + running the following command. .. code-block:: console @@ -264,8 +510,8 @@ Use the following command to run the nexus service: 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. +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. @@ -290,14 +536,22 @@ to be defined in the environment: ``LIBEUFIN_NEXUS_URL``, ``LIBEUFIN_NEXUS_USERN 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/``. +``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. +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``. + This is the value of environment variable + ``LIBEUFIN_SANDBOX_URL`` suffixed with ``/ebicsweb``, + since the sandbox will be providing EBICS services. + + Similarly, ``EBICS_HOST_ID`` should be ``testhost``, + and ``EBICS_PARTNER_ID`` should be ``partner01``. + For ``EBICS_USER_ID`` we will use ``user02`` (for account ``jrluser``), + and for ``CONNECTION_NAME``, we will use ``conn01``. .. code-block:: console @@ -310,7 +564,10 @@ Next, we create a EBICS *bank connection* that nexus can use to communicate with --ebics-user-id $EBICS_USER_ID \ $CONNECTION_NAME -If this step executes correctly, Nexus will have created all the cryptographic +If this step executes correctly +(use ``libeufin-cli connections list-connections`` +and ``libeufin-cli connections show-connection`` to check), +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. @@ -325,7 +582,7 @@ a backup copy* of such keys. $CONNECTION_NAME At this point, Nexus needs to both communicate its keys to the bank, and -download the bank's keys. This syncronization happens through the INI, HIA, 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 @@ -394,7 +651,7 @@ list of transactions, and making a payment. Request history of transactions =============================== -The LibEuFin nexus keeps a local copy of the bank account's transaction +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. @@ -449,18 +706,18 @@ in the next step, to **send the payment instructions to the bank**: .. code-block:: console - $ libeufin-cli accounts submit-payment \ + $ libeufin-cli accounts submit-payments \ --payment-uuid $UUID \ $LOCAL_ACCOUNT_NAME Automatic scheduling ==================== -With an EBICS bank connection, the LibEuFin nexus needs to regularly query for +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 +cron(8). However, the Nexus also has an internal task scheduling mechanism for accounts. |