summaryrefslogtreecommitdiff
path: root/libeufin
diff options
context:
space:
mode:
authorFlorian Dold <florian@dold.me>2021-01-20 21:07:47 +0100
committerFlorian Dold <florian@dold.me>2021-01-20 21:07:47 +0100
commita1869a5950c97042f7c2570c99a7d6a648758f80 (patch)
tree89f6b7ddc7392c6b8eaeab7884561e435f424b19 /libeufin
parent93a3b61d241b20e36f7303bbba90c82f609ce1f6 (diff)
downloaddocs-a1869a5950c97042f7c2570c99a7d6a648758f80.tar.gz
docs-a1869a5950c97042f7c2570c99a7d6a648758f80.tar.bz2
docs-a1869a5950c97042f7c2570c99a7d6a648758f80.zip
libeufin permissions and user management
Diffstat (limited to 'libeufin')
-rw-r--r--libeufin/api-nexus.rst75
-rw-r--r--libeufin/nexus-tutorial.rst44
2 files changed, 118 insertions, 1 deletions
diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst
index 96cdbef..ef1a3c0 100644
--- a/libeufin/api-nexus.rst
+++ b/libeufin/api-nexus.rst
@@ -102,11 +102,84 @@ User Management
Return list of users.
+.. _nexus-permissions-api:
+
+Permissions API
+---------------
+
+The permissions API manages authorization of access of subjects (usually users)
+to resources.
+
+Permissions are modeled a set of ``(subject, resource, permission)`` triples.
+Subjects and resources consist of a type and an identifier.
+
+Superusers are not subject to further permission checks, they are allowed
+to do any operation.
+
+The following subject types are currently supported:
+
+* ``user``: An authenticated user. The subject ID
+ is interpreted as the user ID.
+
+The following permissions are currently defined:
+
+* ``facade.talerWireGateway.history``: Allows querying the
+ transaction history through a Taler wire gateway facade.
+* ``facade.talerWireGateway.transfer``: Allows creating payment initiations
+ to transfer money via a Taler wire gateway facade.
+
+The following resource IDs are currently supported:
+
+* ``facade``: A LibEuFin facade. The resource ID is interpreted as the
+ facade name.
+
+.. http:get:: {nexusbase}/permissions
+
+ List all permissions.
+
+ **Response**
+
+ .. ts:def:: QueryPermissionsResponse
+
+ interface QueryPermissionsResponse {
+ permissions: {
+ subjectType: string;
+ subjectId: string;
+ resourceType: string;
+ resourceId: string;
+ permissionName: string
+ }[];
+ }
+
+.. http:post:: {nexusbase}/permissions
+
+ Modify permissions.
+
+ **Request**
+
+ .. ts:def:: QueryPermissionsResponse
+
+ interface QueryPermissionsResponse {
+ action: "grant" | "revoke";
+ permission: {
+ subjectType: string;
+ subjectId: string;
+ resourceType: string;
+ resourceId: string;
+ permissionName: string
+ };
+ }
+
+ **Response**
+
+ The response is an empty JSON object.
+
+
Test API
--------
-.. http:post:: {nexusBase}/bank-accounts/{acctid}/test-camt-ingestion/{type}
+.. http:post:: {nexusbase}/bank-accounts/{acctid}/test-camt-ingestion/{type}
This call allows tests to **directly** give Nexus a Camt document. After
the processing, all the payment(s) details should be ingested as if the
diff --git a/libeufin/nexus-tutorial.rst b/libeufin/nexus-tutorial.rst
index 8c0d941..6ef7882 100644
--- a/libeufin/nexus-tutorial.rst
+++ b/libeufin/nexus-tutorial.rst
@@ -446,3 +446,47 @@ existing bank account / connection pair.
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 to rely on Nexus to manage its bank account.
+
+
+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