commit 97709e5251bc8c65d90142224e1f5a628415c128
parent ccc9e40c21915920e9d678ff0fa999302ccd1de4
Author: Christian Grothoff <christian@grothoff.org>
Date: Sun, 12 Nov 2023 16:32:35 +0100
update KYC documentation
Diffstat:
1 file changed, 45 insertions(+), 22 deletions(-)
diff --git 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:
