commit 5370cdc8f37087dc82d4a71d4228563bcb90b95a
parent 5293c62b066d8106816d2f270876e21056363782
Author: Sebastian <sebasjm@gmail.com>
Date: Fri, 6 Aug 2021 10:54:23 -0300
issue #6945: refactoring docs for management api on merchant backend service
Diffstat:
4 files changed, 51 insertions(+), 36 deletions(-)
diff --git 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
@@ -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
@@ -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
@@ -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
