[taler-docs] branch master updated: issue #6945: refactoring docs for management api on merchant backend service

[gnunet]

This is an automated email from the git hooks/post-receive script.

sebasjm pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 5370cdc  issue #6945: refactoring docs for management api on merchant 
backend service
5370cdc is described below

commit 5370cdc8f37087dc82d4a71d4228563bcb90b95a
Author: Sebastian <sebasjm@gmail.com>
AuthorDate: Fri Aug 6 10:54:23 2021 -0300

    issue #6945: refactoring docs for management api on merchant backend service
---
 core/api-merchant.rst                              | 30 +++++++--------
 .../015-merchant-backoffice-routing.rst            |  2 +-
 taler-mcig.rst                                     | 10 ++---
 taler-merchant-manual.rst                          | 45 ++++++++++++++--------
 4 files changed, 51 insertions(+), 36 deletions(-)

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 8b9d44b..5395fe1 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -48,9 +48,9 @@ this base URL are divided into to categories:
 * Private endpoints (under ``/private/*``) that are only supposed to be exposed
   to the merchant internally, and must not be exposed on the
   Internet.
-
-To manage instances, private endpoints only available to the ``default``
-instance must be used.
+* Management endpoints (under ``/management/*``) are also private and dedicated
+  to CRUD operation over instances and reset authentication settings over all 
+  instances. Only accessible with the default instance authentication token
 
 Examples:
 
@@ -62,14 +62,14 @@ Examples:
    A private endpoint (default instance):
    https://merchant-backend.example.com/private/orders
 
-   A public endpoint (default instance):
-   https://merchant-backend.example.com/orders
+   A public endpoint (default instance and order id "ABCD"):
+   https://merchant-backend.example.com/orders/ABCD
 
    A private endpoint ("myinst" instance):
    https://merchant-backend.example.com/instances/myinst/private/orders
 
-   A public endpoint ("myinst" instance):
-   https://merchant-backend.example.com/instances/myinst/orders
+   A public endpoint ("myinst" instance and order id "ABCD"):
+   https://merchant-backend.example.com/instances/myinst/orders/ABCD
 
    A private endpoint (explicit "default" instance):
    https://merchant-backend.example.com/instances/default/private/orders
@@ -78,8 +78,8 @@ Examples:
    https://merchant-backend.example.com/instances/default/orders
 
    Endpoints to manage other instances (ONLY for implicit "default" instance):
-   https://merchant-backend.example.com/private/instances
-   https://merchant-backend.example.com/private/instances/$ID
+   https://merchant-backend.example.com/management/instances
+   https://merchant-backend.example.com/management/instances/$ID
 
    Endpoints to manage own instance:
    https://merchant-backend.example.com/private
@@ -855,7 +855,7 @@ instance setup before it can be used to manage inventory or 
process payments.
 Setting up instances
 --------------------
 
-.. http:post:: [/instances/$INSTANCE]/private/instances
+.. http:post:: [/instances/$INSTANCE]/management/instances
 
   This request will be used to create a new merchant instance in the backend.
   It is only available for the implicit ``default`` instance.
@@ -929,7 +929,7 @@ Setting up instances
     }
 
 
-.. http:post:: /private/instances/$INSTANCE/auth
+.. http:post:: /management/instances/$INSTANCE/auth
 .. http:post:: [/instances/$INSTANCE]/private/auth
 
    Update the authentication settings for an instance.  POST operations against
@@ -965,7 +965,7 @@ Setting up instances
     }
 
 
-.. http:patch:: /private/instances/$INSTANCE
+.. http:patch:: /management/instances/$INSTANCE
 .. http:patch:: [/instances/$INSTANCE]/private
 
   Update the configuration of a merchant instance.  PATCH operations against
@@ -1034,7 +1034,7 @@ Inspecting instances
 --------------------
 
 .. _instances:
-.. http:get:: /private/instances
+.. http:get:: /management/instances
 
   This is used to return the list of all the merchant instances.
   It is only available for the implicit ``default`` instance.
@@ -1079,7 +1079,7 @@ Inspecting instances
    }
 
 
-.. http:get:: /private/instances/$INSTANCE
+.. http:get:: /management/instances/$INSTANCE
 .. http:get:: [/instances/$INSTANCE]/private
 
   This is used to query a specific merchant instance.  GET operations against
@@ -1165,7 +1165,7 @@ Inspecting instances
 Deleting instances
 ------------------
 
-.. http:delete:: /private/instances/$INSTANCE
+.. http:delete:: /management/instances/$INSTANCE
 .. http:delete:: [/instances/$INSTANCE]/private
 
   This request will be used to delete (permanently disable)
diff --git a/design-documents/015-merchant-backoffice-routing.rst 
b/design-documents/015-merchant-backoffice-routing.rst
index 07aee23..f6372dc 100644
--- a/design-documents/015-merchant-backoffice-routing.rst
+++ b/design-documents/015-merchant-backoffice-routing.rst
@@ -55,7 +55,7 @@ There are 2 type of routing: instance and internal
   doest not need to care about matching all applications URL
 
 Knowing that the $BACKEND_URL points to a correct merchant backend the SPA will
-check for ``$BACKEND_URL/private/instances``:
+check for ``$BACKEND_URL/management/instances``:
 
 * if Unauthorized ask for credentials
  
diff --git a/taler-mcig.rst b/taler-mcig.rst
index f93d3d1..e7c89a6 100644
--- a/taler-mcig.rst
+++ b/taler-mcig.rst
@@ -151,24 +151,24 @@ are demonstrated in the next section.
   which you may choose to pay or to pass on to the customer.
   This can be configured to a maximum amount, per order.
 
-  You can set ``default_max_deposit_fee`` in :http:post:`/private/instances`,
+  You can set ``default_max_deposit_fee`` in 
:http:post:`/management/instances`,
   or override the default by setting ``max_fee`` when creating an order.
 
   There is also the *wire fee* (see step 6, above),
   which you may choose to pay or to pass on to the customer.
 
-  You can set ``default_max_wire_fee`` in :http:post:`/private/instances`,
+  You can set ``default_max_wire_fee`` in :http:post:`/management/instances`,
   and ``max_wire_fee`` in the contract.
   If unspecified, the default value is zero (meaning you bear the entire fee).
 
   You can *amortize* the wire fee across a number of customers
-  by setting ``default_wire_fee_amortization`` in 
:http:post:`/private/instances`,
+  by setting ``default_wire_fee_amortization`` in 
:http:post:`/management/instances`,
   and ``wire_fee_amortization`` in the contract.
   This is the number of customer transactions over which you expect to
   amortize wire fees on average.
   If unspecified, the default value is one.
 
-  .. Note:: :http:post:`/private/instances` must be done at
+  .. Note:: :http:post:`/management/instances` must be done at
      instance-setup time (prior to any purchase).
 
 **forgettable customer details**
@@ -287,7 +287,7 @@ above => refer to other guide, but of course specify how we 
can
 override defaults from instance setup per-order.)
 
 
-M: :http:post:`/private/instances`
+M: :http:post:`/management/instances`
 
 .. code-block:: javascript
 
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index f6b2e1a..c8f3e53 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -110,10 +110,10 @@ merchant’s signing keys and bank account information are 
encapsulated within
 the Taler backend.
 
 A typical deployment will additionally include a full-blown Web server (like
-Apache or Nginx). Such a Web server would be responsible for TLS termination
-and access control to the ``/private/`` API endpoints of the merchant backend.
-Please carefully review the section on :ref:`Secure setup <Secure-setup>` 
before
-deploying a Taler merchant backend to production.
+Apache or Nginx). Such a Web server would be responsible for TLS termination 
and
+access control to the ``/private/`` and ``/management/`` API endpoints of the
+merchant backend. Please carefully review the section on :ref:`Secure setup
+<Secure-setup>` before deploying a Taler merchant backend to production.
 
 
 Terminology
@@ -806,7 +806,7 @@ Setup
 ------
 
 With the knowledge of the ``payto://``-URI, instances can be configured by 
POSTing
-a request to :http:post:`/private/instances`.  To create a first instance,
+a request to :http:post:`/management/instances`.  To create a first instance,
 create a file ``instance.json`` with an `InstanceConfigurationMessage`
 
 .. code-block:: json
@@ -839,7 +839,7 @@ You can then create the instance using:
 
 .. code-block:: console
 
-   $ wget --post-file=instance.json http://localhost:8888/private/instances
+   $ wget --post-file=instance.json http://localhost:8888/management/instances
 
 The base URL for the instance will then be
 ``http://localhost:8888/instances/default``.  You can create additional
@@ -939,19 +939,20 @@ setup access control!
 Access control
 --------------
 
-All endpoints with ``/private/`` in the URL must be restricted to authorized 
users
-of the respective instance.  Specifically, the HTTP server must be configured
-to only allow access to ``$BASE_URL/private/`` to the authorized users of the
-default instance, and to ``$BASE_URL/instances/$ID/private/`` to the
-authorized users of the instance ``$ID``.
+All endpoints with ``/private/`` in the URL must be restricted to authorized
+users of the respective instance.  Specifically, the HTTP server must be
+configured to only allow access to ``$BASE_URL/private/`` and
+``$BASE_URL/management/`` to the authorized users of the default instance, and
+to ``$BASE_URL/instances/$ID/private/`` to the authorized users of the instance
+``$ID``.
 
 How access control is done (TLS client authentication, HTTP basic or digest
 authentication, etc.) is completely up to the merchant and does not matter to
 the Taler merchant backend.
 
-Note that all of the other endpoints (without ``/private/``) are expected to be
-fully exposed to the Internet, and wallets may have to interact with those
-endpoints directly without client authentication.
+Note that all of the other endpoints (without ``/private/`` or 
``/management/``)
+are expected to be fully exposed to the Internet, and wallets may have to
+interact with those endpoints directly without client authentication.
 
 Nginx
 ^^^^^
@@ -967,6 +968,12 @@ follows:
           }
           proxy_pass ...; // as above
       }
+      location /management/ {
+          if ($http_authorization !~ "(?i)ApiKey SECURITYTOKEN") {
+             return 401;
+          }
+          proxy_pass ...; // as above
+      }
 
 Here, ``SECURITYTOKEN`` should be replaced with the actual shared secret.  Note
 that the ``~`` ensures that the above matches all endpoints that include the
@@ -998,6 +1005,12 @@ each instance:
           }
           proxy_pass ...; # as above
       }
+      location /management/ {
+          if ($http_authorization !~ "(?i)ApiKey MASTERTOKEN") {
+             return 401;
+          }
+          proxy_pass ...; # as above
+      }
       location ~ /private/ {
           return 401; # access to instances not explicitly configured is 
forbidden
       }
@@ -1019,6 +1032,7 @@ Then, you can restrict to an access control token using:
        RewriteEngine On
        RewriteCond "%{HTTP:AUTHORIZATION}" "!=SECURITYTOKEN"
        RewriteRule "(.+)/private/" "-" [F]
+       RewriteRule "/management/" "-" [F]
 
        ProxyPass "unix:/some/path/here.sock|http://example.com/";
        </Location>
@@ -1026,7 +1040,7 @@ Then, you can restrict to an access control token using:
 Here, ``SECURITYTOKEN`` should be replaced with the actual shared secret.  Note
 that the ``(.+)`` ensures that the above matches all endpoints that include the
 string ``/private/``.  If you only run a single instance, you could simply
-specify ``/private/`` without the ``~`` to only configure the access policy for
+specify ``/private/`` without the ``(.+)`` to only configure the access policy 
for
 the default instance.
 
 If you are running different instances on the same backend, you
@@ -1055,6 +1069,7 @@ each instance:
        RewriteEngine On
        RewriteCond "%{HTTP:AUTHORIZATION}" "!=MASTERTOKEN"
        RewriteRule "/private/" "-" [F]
+       RewriteRule "/management/" "-" [F]
        RewriteRule "(.+)/private/" "-" [F] # reject all others
 
        ProxyPass ... # as above

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.