diff options
Diffstat (limited to 'taler-challenger-manual.rst')
| -rw-r--r-- | taler-challenger-manual.rst | 201 |
1 files changed, 196 insertions, 5 deletions
diff --git a/taler-challenger-manual.rst b/taler-challenger-manual.rst index ae7eb047..a7a7169f 100644 --- a/taler-challenger-manual.rst +++ b/taler-challenger-manual.rst @@ -17,8 +17,13 @@ @author Christian Grothoff @author Florian Dold -GNU Taler Challenger Operator Manual -#################################### +Challenger Operator Manual +########################## + +.. contents:: Table of Contents + :depth: 2 + :local: + Introduction ============ @@ -45,7 +50,37 @@ or learn about known limitations, please check our Architecture overview --------------------- -TBC. +The following picture gives an overview of the Challenger +architecture and the main interactions: + +.. image:: images/challenger.png + +Here, the *resource owner* is a user that is in control +of some *address* at a messaging service. This could be +an e-mail account, a mobile phone number (for SMS), or +a physical mail address (using the post office as the +messaging service). + +The *resource owner* makes some request that requires +some *client* to be in need of address validation. The +*client* is registered with the Challenger OAuth 2.0 +service and first authorizes an address validation to +be initiated. The client then redirects the resource +owner to the Challenger service. In step (2), the resource +owner submits the address that they claim to own. + +The Challenger service then creates a TAN code and +submits it to the given address via a configurable +*helper script* that is specific to the type of address +being validated. When the resource owner submits the +correct TAN code in step (6), they are given a token +that they can provide to the client. Using this token +the client can then finally obtain the now validated +address in step (8). + +Address data, TAN codes and meta-data such as the number +of failed attempts to submit a TAN code are recorded +in a Postgres database by the Challenger service. .. _ChallengerInstallation: @@ -423,7 +458,7 @@ three options from the previous section, but also the authorization, token and info endpoints. For Challenger, these are ``/authorize``, ``/token`` and ``/info``. However, the ``/authorize`` endpoint is special, as it is actually ``/authorize/$NONCE`` where ``$NONCE`` is a nonce that must be first requested -by the client using the ``/setup`` endpoint! +by the client using the ``/setup/$CLIENT_ID`` endpoint! ..note:: @@ -433,7 +468,7 @@ by the client using the ``/setup`` endpoint! validation could be expensive. Thus, to generate the authorization URL, a client must first POST to -``/setup`` using their client secret in an ``Authorization: Bearer $SECRET`` +``/setup/$CLIENT_ID`` using their client secret in an ``Authorization: Bearer $SECRET`` HTTP header to obtain a fresh ``$NONCE``. In the GNU Taler exchange configuration, this is indicated by appending @@ -489,3 +524,159 @@ The Challenger database can be re-initialized using: However, running this command will result in all data in the database being lost. + + +.. _ChallengerCustomization: + +Template Customization +====================== + +The Challenger service comes with various HTML templates that are shown to +guide users through the process. Challenger uses `Mustach +<https://gitlab.com/jbol/mustach>`__ as the templating engine. This section +describes the various templates. In general, the templates must be installed +to the ``share/challenger/templates/`` directory. The file names must be of +the form ``$NAME.$LANG.must`` where ``$NAME`` is the name of the template and +``$LANG`` is the 2-letter language code of the template. English templates +must exist and will be used as a fallback. If the browser (user-agent) has +provided language preferences in the HTTP header and the respective language +exists, the correct language will be automatically served. + +The following subsections give details about each of the templates. The +subsection title is the ``$NAME`` of the respective template. + +enter-$ADDRESS_TYPE-form +------------------------ + +These templates are used to ask the user to enter the address that challenger +is expected to validate. Here, ``$ADDRESS_TYPE`` will be replaced by the +``ADDRESS_TYPE`` configuration option in the ``[challenger]`` section of the +configuration file. Typical values include ``address`` (for physical mailing +addresses), ``phone`` (for mobile phone numbers) and ``email`` (for email +addresses). For testing, ``file`` (where the TAN code is written into a local +file) is also supported. + +The template is instantiated using the following information: + + * fix_address: boolean; indicates if the given address cannot be changed + anymore, the form should be read-only if set to true. + + * nonce: String; unique value identifying the challenge, should be shown + to the user so that they can recognize it when they receive the TAN code + + * last_address: Object; form values from the previous submission if available, + details depend on the ``ADDRESS_TYPE``, should be used to pre-populate the form + + * changes_left: Integer; number of times the address can still be changed, + may or may not be shown to the user + +enter-tan-form +-------------- + +This page should generate the HTML form for the user to enter the TAN code +that they received at the respective address. + +The template is instantiated using the following information: + + * nonce: String; unique value identifying the challenge, should be shown + to the user so that they can match it to the TAN code they received + + * attempts_left: Integer; how many more attempts are allowed, might be + shown to the user, highlighting might be appropriate for low values + such as 1 or 2 (the form will never be used if the value is zero) + + * address: Object; the address that is being validated, might be shown + or not + + * transmitted: boolean; true if we just retransmitted the challenge, + false if we sent a challenge recently and thus refused to transmit it + again this time; might make a useful hint to the user + + * next_tx_time: String; timestamp explaining when we would re-transmit + the challenge the next time (at the earliest) if requested by the user + + +invalid-pin +----------- + +The user has provided an invalid TAN code (HTTP 403 Forbidden). + +The template is instantiated using the following information: + + * ec: Integer; numeric Taler error code, should be shown to indicate the + error compactly for reporting to developers + + * hint: String; human-readable Taler error code, should be shown for the + user to understand the error + + * addresses_left: Integer; how many times is the user still allowed to + change the address; if 0, the user should not be shown a link to jump + to the address entry form + + * pin_transmissions_left: Integer; how many times might the PIN still + be retransmitted + + * auth_attempts_left: Integer; how many times might the user still try + entering the PIN code + + * exhausted: Bool; if true, the PIN was not even evaluated as the user previously exhausted the number of attempts + + * no_challenge: Bool; if true, the PIN was not even evaluated as no challenge was ever issued (the user must have skipped the step of providing their address first!) + +If both *pin_transmissions_left* and *auth_attempts_left* are zero, the link +to re-enter the PIN should be hidden and the user should only be allowed to +specify a different address. The form will never be generated if all three +values are zero. (Thus there is always at least one valid choice when the form +is shown.) + + +validation-unknown +------------------ + +The user has tried to access a validation process that is not known to the +backend (HTTP 404 Not Found). + +The template is instantiated using the following information: + + * ec: Integer; numeric Taler error code, should be shown to indicate the + error compactly for reporting to developers + + * hint: String; human-readable Taler error code, should be shown for the + user to understand the error + + * detail: String; optional, extended human-readable text provided to elaborate + on the error, should be shown to provide additional context + + +invalid-request +--------------- + +The request of the client is invalid (HTTP 400 Bad Request). + +The template is instantiated using the following information: + + * ec: Integer; numeric Taler error code, should be shown to indicate the + error compactly for reporting to developers + + * hint: String; human-readable Taler error code, should be shown for the + user to understand the error + + * detail: String; optional, extended human-readable text provided to elaborate + on the error, should be shown to provide additional context + + +internal-error +-------------- + +The service experienced an internal error (HTTP 500 Internal Server Error). + +The template is instantiated using the following information: + + * ec: Integer; numeric Taler error code, should be shown to indicate the + error compactly for reporting to developers + + * hint: String; human-readable Taler error code, should be shown for the + user to understand the error + + * detail: String; optional, extended human-readable text provided to elaborate + on the error, should be shown to provide additional context |