[taler-docs] branch master updated: documentation for #7835, plus renaming

[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 7197802e documentation for #7835, plus renaming
7197802e is described below

commit 7197802eadf70ddb064ff034651571baeffb65e2
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Sat May 13 17:06:59 2023 +0200

    documentation for #7835, plus renaming
---
 manpages/taler.conf.5.rst | 11 +++++++----
 taler-exchange-manual.rst | 25 +++++++++++++++++--------
 2 files changed, 24 insertions(+), 12 deletions(-)

diff --git a/manpages/taler.conf.5.rst b/manpages/taler.conf.5.rst
index 534c51bd..7e1ec2a2 100644
--- a/manpages/taler.conf.5.rst
+++ b/manpages/taler.conf.5.rst
@@ -182,11 +182,11 @@ The following options must be in the section 
"[kyc-provider-XXX]" sections with
 KYC_OAUTH2_VALIDITY
   Duration (e.g. "12 months") of the validity of the performed KYC check. Can 
be "forever".
 
-KYC_OAUTH2_AUTH_URL
-  URL of the OAuth2 endpoint to be used for KYC checks. This is where the 
server will ultimately send the authorization token from the client and obtain 
its access token (which currently must be a "bearer" token). Example: 
"http://localhost:8888/oauth/v2/auth"; (or "/token")
+KYC_OAUTH2_AUTHORIZE_URL
+  URL of the OAuth2 endpoint to be used for KYC checks. The authorize URL is 
where the exchange will redirect the client to begin the authorization process. 
 Example: "http://localhost:8888/oauth/v2/authorize";. To use the plugin in 
combination with the Challenger service's ``/setup`` step, append "#setup", 
thus "https://challenger.example.com/authorize#setup";.  Here, "#setup" is not a 
fragment but merely a hint to the logic to determine the full authorization URL 
via the ``/setup`` handler.
 
-KYC_OAUTH2_LOGIN_URL
-  URL of the OAuth2 endpoint to be used for KYC checks. The login URL will be 
encoded as part of the 'redirect_uri' argument of the request to the 
KYC_AUTH2_AUTH_URL. Typically, the user will then be redirected to this URL to 
log in. Example: "http://localhost:8888/oauth/v2/login";
+KYC_OAUTH2_TOKEN_URL
+  URL of the OAuth2 endpoint to be used for KYC checks. This is where the 
server will ultimately send the authorization token from the client and obtain 
its access token (which currently must be a "bearer" token). Example: 
"http://localhost:8888/oauth/v2/token"; (or just "/token")
 
 KYC_OAUTH2_INFO_URL
   URL of the OAuth2-protected resource endpoint, where the OAuth 2.0 token can 
be used to download information about the user that has undergone the KYC 
process. The exchange will use the access token obtained from the 
KYC_AUTH2_AUTH_URL to show that it is authorized to obtain the details. 
Example: "http://localhost:8888/api/user/me"; or 
"http://localhost:8888/oauth/v2/info";
@@ -238,6 +238,9 @@ KYC_PERSONA_SALT
 KYC_PERSONA_SUBDOMAIN
   Subdomain to use under Persona.
 
+KYC_PERSONA_CONVERTER_HELPER
+  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_POST_URL
   URL to which the exchange will redirect the client's browser after 
successful authorization/login for the KYC process.
 
diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst
index 15dc90ae..55bf6369 100644
--- a/taler-exchange-manual.rst
+++ b/taler-exchange-manual.rst
@@ -1493,11 +1493,9 @@ service.  The OAuth 2.0 configuration options are:
   KYC_OAUTH2_VALIDITY = forever
 
   # URL to which we redirect the user for the login process
-  # FIXME: we should rename this option to AUTHORIZATION_URL
-  KYC_OAUTH2_LOGIN_URL = "http://kyc.example.com/authorization";
+  KYC_OAUTH2_AUTHORIZE_URL = "http://kyc.example.com/authorize";
   # URL where we POST the user's authentication information
-  # FIXME: we should rename this option to TOKEN_URL
-  KYC_OAUTH2_AUTH_URL = "http://kyc.example.com/token";
+  KYC_OAUTH2_TOKEN_URL = "http://kyc.example.com/token";
   # URL of the user info access point.
   KYC_OAUTH2_INFO_URL = "http://kyc.example.com/info";
 
@@ -1517,9 +1515,9 @@ 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 Challenger service for address validation supports OAuth2.0, but does not
-have a static LOGIN_URL. Instead, the LOGIN_URL must be enabled by the client
+have a static AUTHORIZE_URL. Instead, the AUTHORIZE_URL must be enabled by the 
client
 using a special authenticated request to the Challenger's ``/setup`` endpoint.
-The exchange supports this by appending ``#setup`` to the LOGIN_URL (note
+The exchange supports this by appending ``#setup`` to the AUTHORIZE_URL (note
 that fragments are illegal in OAuth2.0 URLs).  Be careful to quote the URL,
 as ``#`` is otherwise interpreted as the beginning of a comment by the
 configuration file syntax.
@@ -1528,8 +1526,8 @@ configuration file syntax.
   :caption: /etc/taler/conf.d/exchange-challenger-oauth2.conf
   [kyc-provider-challenger-oauth2]
   LOGIC = oauth2
-  KYC_OAUTH2_LOGIN_URL = "http://challenger.example.com/authorize/#setup";
-  KYC_OAUTH2_AUTH_URL = "http://challenger.example.com/token";
+  KYC_OAUTH2_AUTHORIZE_URL = "http://challenger.example.com/authorize/#setup";
+  KYC_OAUTH2_TOKEN_URL = "http://challenger.example.com/token";
   KYC_OAUTH2_INFO_URL = "http://challenger.example.com/info";
 
 
@@ -1562,6 +1560,11 @@ 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
 
@@ -1575,6 +1578,12 @@ be in the configuration.
   # 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.
+
 
 KYC AID specifics
 -----------------

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