commit 7197802eadf70ddb064ff034651571baeffb65e2
parent ff4939564da4a4c52face5738d5182c6e8af887e
Author: Christian Grothoff <christian@grothoff.org>
Date: Sat, 13 May 2023 17:06:59 +0200
documentation for #7835, plus renaming
Diffstat:
2 files changed, 24 insertions(+), 12 deletions(-)
diff --git 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
@@ -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
-----------------
