issue #6945: refactoring docs for management api on merchant backend service

1 files changed, 30 insertions, 15 deletions

diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index f6b2e1a0..c8f3e53c 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