diff options
Diffstat (limited to 'libeufin/nexus-tutorial.rst')
-rw-r--r-- | libeufin/nexus-tutorial.rst | 864 |
1 files changed, 0 insertions, 864 deletions
diff --git a/libeufin/nexus-tutorial.rst b/libeufin/nexus-tutorial.rst deleted file mode 100644 index 4b99e308..00000000 --- a/libeufin/nexus-tutorial.rst +++ /dev/null @@ -1,864 +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 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. -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: - jdbc:sqlite:/tmp/libeufindb.sqlite3 - jdbc:postgresql://localhost:5432/libeufindb?user=Foo&password=secret - -Only *SQLite* and *PostgreSQL (via TCP)* are supported right now. - -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 variables must be set to the authentication -information, and the URL of the sandbox service: - -.. code-block:: console - - $ 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 - 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, 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. -Also, the URL for all ``libeufin-cli sandbox demobank`` commands -must include the name of a bank, as follows: - -.. code-block:: console - - $ export LIBEUFIN_SANDBOX_USERNAME=jrluser - $ export LIBEUFIN_SANDBOX_PASSWORD=easy - $ libeufin-cli sandbox \ - --sandbox-url http://localhost:5016/demobanks/default \ - demobank register - -In this example, the bank name is ``default``. In these examples, we use the -``--sandbox-url`` option for the ``demobank`` commands, so that we don't need -to change the environment variable ``LIBEUFIN_SANDBOX_URL`` for the -non-``demobank`` commands. - -Check the balance of the user just created: - -.. code-block:: console - - $ libeufin-cli sandbox \ - --sandbox-url http://localhost:5016/demobanks/default \ - 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 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 \ - --sandbox-url http://localhost:5016/demobanks/default \ - 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. - -.. note:: - - Currently, the person (given human) name is not maintained by - the sandbox. It displays "Bank account owner's name" instead. - -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 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 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 - -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 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>`. - - -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``. - 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 - - $ 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 -(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. - -.. 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-payments \ - --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 |