[taler-docs] branch master updated: update KYC documentation

[gnunet]

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

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 97709e52 update KYC documentation
97709e52 is described below

commit 97709e5251bc8c65d90142224e1f5a628415c128
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Sun Nov 12 16:32:35 2023 +0100

    update KYC documentation
---
 taler-exchange-manual.rst | 67 +++++++++++++++++++++++++++++++----------------
 1 file changed, 45 insertions(+), 22 deletions(-)

diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst
index df05fbfc..f87dc3e0 100644
--- a/taler-exchange-manual.rst
+++ b/taler-exchange-manual.rst
@@ -1443,11 +1443,15 @@ service.  The OAuth 2.0 configuration options are:
 
   # Mustach template that converts OAuth2.0 data about the user
   # into GNU Taler standardized attribute data.
-  #
-  KYC_OAUTH2_ATTRIBUTE_TEMPLATE = "{"fullname":"{{last_name}}, 
{{first_name}}","phone":"{{phone}}"}"
+  KYC_OAUTH2_CONVERTER_HELPER = taler-exchange-kyc-oauth2-challenger.sh
 
-The ``KYC_OAUTH2_ATTRIBUTE_TEMPLATE`` provides a generic way to convert data
-returned by an OAuth-provider into the internal format used by the exchange.
+The converter helper is expected to be customized to the selected OAuth2.0
+service: different services may return different details about the user or
+business, hence there cannot be a universal converter for all purposes. The
+default shell script uses the ``jq`` tool to convert the JSON returned by the
+service into the KYC attributes (also in JSON) expected by the exchange.  The
+script will need to be adjusted based on the attributes collected by the
+specific backend.
 
 The Challenger service for address validation supports OAuth2.0, but does not
 have a static AUTHORIZE_URL. Instead, the AUTHORIZE_URL must be enabled by the 
client
@@ -1481,9 +1485,14 @@ We use the hosted flow. The Persona endpoints return a 
``request-id``, which
 we log for diagnosis.
 
 Persona should be configured to use the ``/kyc-webhook/`` endpoint of the
-exchange to notify the exchange about the completion of KYC processes.
-The webhook is authenticated using a shared secret, which should
-be in the configuration.
+exchange to notify the exchange about the completion of KYC processes.  The
+webhook is authenticated using a shared secret, which should be in the
+configuration.  To use the Persona webhook, you must set the webhook URL in
+the Persona service to ``$EXCHANGE_BASE_URL/kyc-webhook/$SECTION_NAME/`` where
+``$SECTION_NAME`` is the name of the configuration section.  You should also
+extract the authentication token for the webhook and put it into the
+configuration as shown above.
+
 
 .. code-block:: ini
   :caption: /etc/taler/conf.d/exchange-persona.conf
@@ -1503,29 +1512,31 @@ be in the configuration.
   # Which subdomain is used for our API?
   KYC_PERSONA_SUBDOMAIN = taler
 
-  # Helper to convert JSON with KYC data returned by Persona into GNU Taler
-  # internal format. Should probably always be set to
-  # "taler-exchange-kyc-persona-converter.sh".
-  KYC_PERSONA_CONVERTER_HELPER = "taler-exchange-kyc-persona-converter.sh"
-
   # Authentication token to use.
-  KYC_PERSONA_AUTH_TOKEN = persona_sandbox_42
+  KYC_PERSONA_AUTH_TOKEN = persona_sandbox_42XXXX
 
   # Form to use.
   KYC_PERSONA_TEMPLATE_ID = itempl_Uj6Xxxxx
 
   # Where do we redirect to after KYC finished successfully.
-  KYC_PERSONA_POST_URL = "https://taler.net/";
+  KYC_PERSONA_POST_URL = "https://taler.net/kyc-done";
 
   # Salt to give to requests for idempotency.
   # Optional.
   # KYC_PERSONA_SALT = salt
 
-To use the Persona webhook, you must set the webhook URL in the
-Persona service to ``$EXCHANGE_BASE_URL/kyc-webhook/$SECTION_NAME/``
-where ``$SECTION_NAME`` is the name of the configuration section.
-You should also extract the authentication token for the webhook
-and put it into the configuration as shown above.
+  # Helper to convert JSON with KYC data returned by Persona into GNU Taler
+  # internal format. Should probably always be set to some variant of
+  # "taler-exchange-kyc-persona-converter.sh".
+  KYC_PERSONA_CONVERTER_HELPER = "taler-exchange-kyc-persona-converter.sh"
+
+The converter helper is expected to be customized to the
+selected template: different templates may return different details
+about the user or business, hence there cannot be a universal converter
+for all purposes. The default shell script uses the ``jq`` tool to
+convert the JSON returned by Persona into the KYC attributes (also
+in JSON) expected by the exchange.  The script will need to be adjusted
+based on the attributes collected by the specific template.
 
 
 KYC AID specifics
@@ -1533,8 +1544,8 @@ KYC AID specifics
 
 We use the hosted flow.
 
-KYCAID should be configured to use the ``/kyc-webhook/`` endpoint of the
-exchange to notify the exchange about the completion of KYC processes.
+KYCAID must be configured to use the ``/kyc-webhook/$SECTION_NAME/`` endpoint
+of the exchange to notify the exchange about the completion of KYC processes.
 
 .. code-block:: ini
   :caption: /etc/taler/conf.d/exchange-kycaid.conf
@@ -1553,7 +1564,19 @@ exchange to notify the exchange about the completion of 
KYC processes.
   KYC_KYCAID_FORM_ID = XXX
 
   # URL to go to after the process is complete.
-  KYC_KYCAID_POST_URL = "https://taler.net/";
+  KYC_KYCAID_POST_URL = "https://taler.net/kyc-done";
+
+  # Script to convert the KYCAID data into the Taler format.
+  KYC_KYCAID_CONVERTER_HELPER = taler-exchange-kyc-kycaid-converter.sh
+
+
+The converter helper is expected to be customized to the selected template:
+different templates may return different details about the user or business,
+hence there cannot be a universal converter for all purposes. The default
+shell script uses the ``jq`` tool to convert the JSON returned by Persona into
+the KYC attributes (also in JSON) expected by the exchange.  The script will
+need to be adjusted based on the attributes collected by the specific
+template.
 
 
 .. _Deployment:

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