taler-docs

api-challenger.rst (23852B)

---

 ..
   This file is part of GNU TALER.
   Copyright (C) 2023, 2024 Taler Systems SA
 
   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU Affero General Public License as published by the Free Software
   Foundation; either version 2.1, or (at your option) any later version.
 
   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
   A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
 
   You should have received a copy of the GNU Affero General Public License along with
   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
 
   @author Christian Grothoff
 
 .. _challenger-api:
 
 ==============================
 Challenger Service RESTful API
 ==============================
 
 The challenger service validates that a user is able to receive challenges at
 an address (such as e-mail or SMS) and allows an OAuth 2.0 client to obtain
 access to these validated addresses.
 
 The high-level flow is that an OAuth 2.0 client is first registered with the
 challenger service (via command-line). Using the command-line tool will print
 the resulting client ID to the console.
 
 .. note::
 
   Right now, registration of a unique redirection URI is *mandatory* for
   each client. If multiple redirection URIs are needed, it is suggested to
   just register additional clients.  (While OAuth 2.0 would support not
   registering fixed redirection URIs with a client, this is not recommended
   as it would create an open redirector.)
 
 Once a client is registered, that client can use the challenger service when
 it needs a user to prove that the user is able to receive messages at a
 particular address.  However, asking a user to prove access to a particular
 address can be expensive as it may involve sending an SMS or even postal mail
 depending on the type of address.  Thus, challenger does not allow a user
 agent to begin an address validation process without prior approval by a
 registered client.  Thus, the process begins with a ``/setup/$CLIENT_ID`` request where a
 client requests challenger to begin an address validation request.  The
 ``/setup/$CLIENT_ID`` response contains a ``nonce`` which is then used to construct the
 URL of the endpoint to which the client must redirect the user-agent to begin
 the address validation and authorization process.
 
 The client then redirects the user-agent to the ``/authorize/$NONCE`` endpoint
 of the challenger service, adding its ``state``, ``client_id`` and
 ``redirect_uri`` as query parameters.  The ``redirect_uri`` must match the
 redirect URI registered with the client. From this endpoint, the challenger
 service will return a Web page asking the user to provide its address.
 
 .. note::
 
   Challenger is a bit unusual in that the ``$NONCE`` in the endpoint URL
   makes the authorization endpoint URL (deliberately) unpredictable, while
   for many other OAuth 2.0 APIs this endpoint is static. However, this is
   compliant with OAuth 2.0 as determining the authorization URL is left out
   of the scope of the standard.
 
 When the user has filled in the form with their address, it will be submitted
 to the ``/challenge/$NONCE`` endpoint and the challenger service will send a
 challenge to the user's address and generate an HTML form asking the user to
 enter the received challenge value.
 
 The user can then enter the answer to the challenge which is then submitted to
 the ``/solve/$NONCE`` endpoint.  If the answer is correct, the user agent will
 be redirected to the client redirect URI that was specified by the OAuth 2.0
 client upon ``/authorize``, together with an authorization grant encoded in
 the redirection URI.
 
 Given this authorization grant, the OAuth 2.0 client can then use the
 ``/token`` endpoint to obtain an access token which will grant it access to
 the resource.
 
 Using the ``/info`` endpoint the client can then finally obtain the (now)
 verified address of the user.
 
 .. contents:: Table of Contents
   :local:
 
 
 ---------------
 Version History
 ---------------
 
 The current protocol version is **v6**.
 
 * The Challenger SPA is currently targeting **v6**.
 
 **Version history:**
 
 * ``v6``: add the ``address_type`` field to ``/config``
 
 **Upcoming versions:**
 
 * None anticipated.
 
 **Ideas for future version:**
 
 * ``vXXX``: marker for features not yet targeted for release
 
 
 .. include:: tos.rst
 
 .. _challenger-config:
 
 -----------------------
 Receiving Configuration
 -----------------------
 
 .. http:get:: /config
 
   Obtain the key configuration settings of the storage service.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     Response is a `ChallengerConfigurationResponse`.
 
   .. ts:def:: ChallengerConfigurationResponse
 
     interface ChallengerConfigurationResponse {
       // Name of the service
       name: "challenger";
 
       // libtool-style representation of the Challenger protocol version, see
       // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
       // The format is "current:revision:age".
       version: string;
 
       // URN of the implementation (needed to interpret 'revision' in version).
       // @since v0, may become mandatory in the future.
      implementation?: string;
 
       // @since **v2**.
       // Object; map of keys (names of the fields of the address
       // to be entered by the user) to objects with a "regex" (string)
       // containing an extended Posix regular expression for allowed
       // address field values, and a "hint"/"hint_i18n" giving a
       // human-readable explanation to display if the value entered
       // by the user does not match the regex. Keys that are not mapped
       // to such an object have no restriction on the value provided by
       // the user.  See "ADDRESS_RESTRICTIONS" in the challenger configuration.
       restrictions: Object;
 
       // @since **v6**
       // Defines the set of fields asked to the user.
       // The field names are registered via GANA at
       // https://git.taler.net/gana.git/tree/gnu-taler-form-attributes
       // email: CONTACT_EMAIL
       // phone: CONTACT_PHONE
       // postal: CONTACT_NAME, ADDRESS_LINES, ADDRESS_COUNTRY
       // postal-ch: CONTACT_NAME, ADDRESS_LINES
       address_type: "email" | "phone" | "postal" | "postal-ch";
 
       // Hint to show in the address bar for the user as an example for
       // the format of the address.
       address_hint: string;
     }
 
 .. _challenger-setup:
 
 -----
 Setup
 -----
 
 .. http:post:: /setup/$CLIENT_ID
 
   This endpoint is used by the client to authorize the execution of an address
   validation on its behalf.  An ``Authorization`` header (for now always using
   a ``Bearer`` token) should be included to provide the client's credentials
   to authorize access to the challenger service.  This token must match the
   ``client_secret`` from the registration of the client with the challenger
   service (which will also be used in the later ``/token`` request).
 
   **Request:**
 
   The body can be an address in JSON encoding to pre-initialize the address to
   be used by challenger for this process. If the body is absent, the user will
   have to enter the full address details.  The specific address format depends
   on the address type.  However, `ChallengeSetupRequest` defines the shared
   ``read_only`` bit that has a special meaning independent of the address type:
   it informs Challenger that the address should not be editable.
 
   Passing an address in the ``/setup`` body is supported @since protocol **v4**.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     Response is a `ChallengeSetupResponse`.
   :http:statuscode:`400 Bad request`:
     The request is malformed. Usually returned with an
     error code of ``TALER_EC_GENERIC_PARAMETER_MISSING`` or
     ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
   :http:statuscode:`404 Not found`:
     The challenger service is unaware of a matching client.
     or the credentials of the client are invalid.
     Usually returned with
     ``TALER_EC_CHALLENGER_GENERIC_CLIENT_UNKNOWN``.
   :http:statuscode:`500 Internal server error`:
     The challenger service encountered an internal error.
     Usually returned with
     ``TALER_EC_GENERIC_DB_FETCH_FAILED`` or
     ``TALER_EC_GENERIC_DB_STORE_FAILED`` or
     ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE``.
 
   **Details::**
 
   .. ts:def:: ChallengeSetupRequest
 
     interface ChallengeSetupRequest {
       // If true, the given address should not be edited.
       // Defaults to 'false' if not specified.
       read_only?: boolean;
 
       // Optional, additional fields to pre-populate
       // the address to be validated.
       // The fields depend on the challenger type.
       [x: string]: any;
     }
 
 
   .. ts:def:: ChallengeSetupResponse
 
     interface ChallengeSetupResponse {
       // Nonce to use when constructing ``/authorize`` endpoint.
       nonce: string;
     }
 
 
 .. _challenger-login:
 
 -----
 Login
 -----
 
 .. http:get:: /authorize/$NONCE
 .. http:post:: /authorize/$NONCE
 
   This is the "authorization" endpoint of the OAuth 2.0 protocol.  This
   endpoint is used by the user-agent. It will return a form to enter the
   address.
 
   The NONCE is a unique value identifying the challenge, should be shown to
   the user so that they can recognize it when they receive the TAN code.
 
   Note that both for GET and POST requests the request arguments must
   be given in the URL and the body should be empty. We currently do NOT
   support using x-www-form-urlencoded arguments in the body, even for
   a POST.
 
   **Request:**
 
   :query response_type: Must be ``code``
   :query client_id: Identifier of the client.
   :query redirect_uri: URI-encoded redirection URI to use upon authorization.
   :query state: Arbitrary client state to associate with the request.
   :query scope: Not supported, any value is accepted.
   :query code_challenge: A string to enhance security using PKCE (available since **v3**).
   :query code_challenge_method: The method used for the code_challenge. Options are S256 (SHA-256) or plain (available since **v3**).
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The the response is
     a `ChallengeStatus`. Since protocol **v1**.
   :http:statuscode:`302 Found`:
     Returned when the client explicitly accepts ``text/html``
     returning a redirection to the WebUI.
     Since protocol **v1**.
   :http:statuscode:`400 Bad Request`:
     The request does not follow the spec.
     The response will include error
     code, hint and detail. Since protocol **v1**.
   :http:statuscode:`404 Not found`:
     The service is unaware of a matching challenge.
     The response will include error
     code, hint and detail. Since protocol **v1**.
   :http:statuscode:`406 Not Acceptable`:
     The client ask for "text/html" and the backend installation does
     not include the required HTML templates.
   :http:statuscode:`500 Internal Server Error`:
     Server is not able to respond due to internal problems.
     The response will include error
     code, hint and detail. Since protocol **v1**.
 
   .. ts:def:: ChallengeStatus
 
     interface ChallengeStatus {
 
       // indicates if the given address cannot be changed anymore, the
       // form should be read-only if set to true.
       fix_address: boolean;
 
       // form values from the previous submission if available, details depend
       // on the ``ADDRESS_TYPE``, should be used to pre-populate the form
       last_address?: Object;
 
       // is the challenge already solved?
       solved: boolean;
 
       // number of times the address can still be changed, may or may not be
       // shown to the user
       changes_left: Integer;
 
       // when we would re-transmit the challenge the next
       // time (at the earliest) if requested by the user
       // only present if challenge already created
       // @since **v2**
       retransmission_time: Timestamp;
 
       // how many times might the PIN still be retransmitted
       // only present if challenge already created
       // @since **v2**
       pin_transmissions_left?: Integer;
 
       // how many times might the user still try entering the PIN code
       // only present if challenge already created
       // @since **v2**
       auth_attempts_left?: Integer;
     }
 
 
 .. _challenger-challenge:
 
 ---------
 Challenge
 ---------
 
 .. http:post:: /challenge/$NONCE
 
   This endpoint is used by the user-agent to submit the address to which a
   challenge should be sent by the challenger service.
 
   **Request:**
 
   Body should use the mime-type "application/x-www-form-urlencoded".
   The posted form data must contain an object that follow the restrictions
   defined in :ref:`config <challenger-config>`.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The response is `ChallengeResponse`. Since protocol **v2**.
   :http:statuscode:`400 Bad Request`:
     The request does not follow the spec.
     The response will include error
     code, hint and detail. Since protocol **v1**.
   :http:statuscode:`403 Forbidden`:
     The address being submitted differs from the previously
     submitted address but the validation process was set up
     as ``read_only`` and thus the address cannot be changed.
     Returned with
     ``TALER_EC_CHALLENGER_CLIENT_FORBIDDEN_READ_ONLY``.
     Since protocol **v4**.
   :http:statuscode:`404 Not Found`:
     The service is unaware of a matching challenge.
     The response will include error
     code, hint and detail. Since protocol **v1**.
   :http:statuscode:`406 Not Acceptable`:
     The client ask for "text/html" and the backend installation does
     not include the required HTML templates.
   :http:statuscode:`429 Too Many Requests`:
     There have been too many attempts to request challenge
     transmissions for this $NONCE. The user-agent should
     wait and (eventually) request a fresh nonce to be set
     up by the client.
     Returned with ``TALER_EC_CHALLENGER_TOO_MANY_ATTEMPTS``.
     Since protocol **v2**.
   :http:statuscode:`500 Internal Server Error`:
     Server is not able to respond due to internal problems.
     The response will include error
     code, hint and detail. Since protocol **v1**.
   :http:statuscode:`502 Bad Gateway`:
     The challenger service failed to launch or communicate with
     its helper process for delivering the challenge (SMS, e-mail,
     postal mail).  Returned with
     ``TALER_EC_CHALLENGER_HELPER_EXEC_FAILED``.
 
   .. ts:def:: ChallengeResponse
 
     // Union discriminated by the "type" field.
     type ChallengeResponse = ChallengeRedirect | ChallengeCreateResponse
 
   .. ts:def:: ChallengeRedirect
 
     // @since **v2**
     interface ChallengeRedirect {
       // Union discriminator field.
       type: "completed";
 
       // challenge is completed, use should redirect here
       redirect_url: string;
     }
 
   .. ts:def:: ChallengeCreateResponse
 
    interface ChallengeCreateResponse {
       // Union discriminator field.
       type: "created"
 
       // 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)
       attempts_left: Integer;
 
       // the address that is being validated, might be shown or not
       address: Object;
 
       // 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
       transmitted: boolean;
 
       // @deprecated in **v2**, use retransmission_time
       next_tx_time?: string;
 
       // when we would re-transmit the challenge the next
       // time (at the earliest) if requested by the user
       // @since **v2**
       retransmission_time: Timestamp;
     }
 
 
 .. _challenger-solve:
 
 -----
 Solve
 -----
 
 .. http:post:: /solve/$NONCE
 
   Used by the user-agent to submit an answer to the challenge.  If the answer
   is correct, the user will be redirected to the client's redirect URI,
   otherwise the user may be given another chance to complete the process.
 
   **Request:**
 
   Body should use the mime-type "application/x-www-form-urlencoded".
   The posted form data must contain a "pin" field.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     If the request ask for application/json the response is
     a `ChallengeSolveResponse`. Since protocol **v2**.
   :http:statuscode:`302 Found`:
     Only possible if request didn't ask for application/json. Since protocol **v2**.
     The user is redirected to the redirect URI of the client to pass the
     grant to the client.  The target will be the redirect URI specified
     by the client (during registration and again upon ``/authorize``),
     plus a ``code`` argument with the authorization code, and the
     ``state`` argument from the ``/authorize`` endpoint.
   :http:statuscode:`400 Bad Request`:
     The request does not follow the spec.
     The response will include error
     code, hint and detail. Since protocol **v1**.
   :http:statuscode:`403 Forbidden`:
     The response is `InvalidPinResponse`. Since protocol **v1**.
   :http:statuscode:`404 Not found`:
     The service is unaware of a matching challenge.
     The response will include error
     code, hint and detail. Since protocol **v1**.
   :http:statuscode:`429 Too Many Requests`:
     There have been too many attempts to solve the challenge
     for this address (and $NONCE). The user-agent should
     either try a different address (or wait and (eventually)
     request a fresh nonce to be set up by the client).
     The response will include error
     code, hint and detail. Since protocol **v2**.
   :http:statuscode:`500 Internal Server Error`:
     Server is not able to respond due to internal problems.
     The response will include error
     code, hint and detail. Since protocol **v1**.
 
   .. ts:def:: ChallengeSolveResponse
 
     // Union discriminated by the "type" field.
     type ChallengeSolveResponse = ChallengeRedirect | InvalidPinResponse;
 
   .. ts:def:: InvalidPinResponse
 
     interface InvalidPinResponse {
       // Union discriminator field.
       type: "pending";
 
       // numeric Taler error code, should be shown to indicate the error
       // compactly for reporting to developers
       code: Integer;
 
       // human-readable Taler error code, should be shown for the user to
       // understand the error
       hint: string;
 
       // 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
       addresses_left: Integer;
 
       // how many times might the PIN still be retransmitted
       pin_transmissions_left: Integer;
 
       // how many times might the user still try entering the PIN code
       auth_attempts_left: Integer;
 
       // if true, the PIN was not even evaluated as the user previously
       // exhausted the number of attempts
       exhausted: boolean;
 
       // 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!)
       no_challenge: boolean;
     }
 
 .. _challenger-auth:
 
 ----
 Auth
 ----
 
 .. http:post:: /token
 
   This is the token endpoint of the OAuth 2.0 specification.
   This endpoint is used by the client to provide its authorization code,
   demonstrating that it has the right to learn a particular user's validated
   address.  In return, the challenger service returns the access token.
   Renewal is not supported.
 
   **Request:**
 
   The request must include an ``application/www-form-urlencoded`` body
   specifying the ``client_id``, ``redirect_uri``, ``client_secret``, ``code``
   and ``grant_type``.  The ``grant_type`` must be set to
   ``authorization_code``.  The ``redirect_uri`` must match the URI from
   ``/authorize``. The ``code`` must be the authorization code that ``/solve``
   returned to the user.  The ``client_id`` and ``client_secret`` must match
   the usual client credentials. Since protocol **v3**, ``code_verifier`` can also be included.
 
   **Response:**
 
   Error responses follow RFC 6749, section 5.2 with an "error" field in JSON,
   as well as also returning GNU Taler style error messages.
 
   :http:statuscode:`200 OK`:
     The body will be a `ChallengerAuthResponse`.
   :http:statuscode:`400 Bad Request`:
     A required POST field (``grant_type``, ``client_id``,
     ``client_secret``, ``code`` or ``redirect_uri``) is missing
     or malformed, or ``grant_type`` is not ``authorization_code``.
     Usually returned with ``TALER_EC_GENERIC_PARAMETER_MISSING``
     or ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
   :http:statuscode:`401 Unauthorized`:
     Authentication of the client failed.  Returned (per
     RFC 6749, section 5.2) when the client credentials are
     invalid, when the supplied ``code`` is malformed or does
     not match the validation, when the ``redirect_uri`` does
     not match the one registered with the client, or when the
     ``code_verifier`` does not match the saved
     ``code_challenge``.  Returned with
     ``TALER_EC_CHALLENGER_GENERIC_CLIENT_FORBIDDEN_BAD_REDIRECT_URI``,
     ``TALER_EC_CHALLENGER_CLIENT_FORBIDDEN_BAD_CODE``,
     ``TALER_EC_CHALLENGER_GENERIC_VALIDATION_UNKNOWN`` or
     ``TALER_EC_CHALLENGER_GRANT_UNKNOWN``.
     PKCE-related rejections are since protocol **v3**.
   :http:statuscode:`404 Not found`:
     The service is unaware of a matching login process or client.
     Returned with error codes of
     ``TALER_EC_CHALLENGER_GENERIC_CLIENT_UNKOWN``
   :http:statuscode:`409 Conflict`:
     A ``code`` was presented for a validation process for which
     the user has not (yet) submitted any address, so the token
     cannot be issued.  Returned with
     ``TALER_EC_CHALLENGER_MISSING_ADDRESS``.
   :http:statuscode:`500 Internal Server Error`:
     The challenger service encountered an internal error,
     for example a database failure or a failure of the SHA-256
     or Base64 helpers used for PKCE verification.
     Error codes used are:
     * ``TALER_EC_CHALLENGER_GENERIC_DB_FETCH_FAILED``
     * ``TALER_EC_CHALLENGER_GENERIC_DB_STORE_FAILED``
 
   **Details::**
 
   .. ts:def:: ChallengerAuthResponse
 
     interface ChallengerAuthResponse {
       // Token used to authenticate access in ``/info``.
       access_token: string;
 
       // Type of the access token.
       token_type: "Bearer";
 
       // Amount of time that an access token is valid (in seconds).
       expires_in: Integer;
 
     }
 
 
 .. _challenger-info:
 
 ----
 Info
 ----
 
 .. http:get:: /info
 
   This userinfo endpoint of the OAuth 2.0 specification.
   This endpoint is used by the client to obtain the user's validated address.
 
   **Request:**
 
   Must include the token returned to the client from the ``/token`` endpoint
   as a ``Bearer`` token in an ``Authorization`` header.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The body contains the address as a `ChallengerInfoResponse`.
   :http:statuscode:`403 Forbidden`:
     The bearer token is missing or invalid (malformed).
   :http:statuscode:`404 Not found`:
     The bearer token is invalid (includes unknown or expired).
     Returned with ``TALER_EC_CHALLENGER_GRANT_UNKNOWN``.
   :http:statuscode:`500 Internal Server Error`:
     The challenger service encountered an internal error,
     typically a database failure.  Usually returned with
     ``TALER_EC_GENERIC_DB_FETCH_FAILED``.
 
   **Details::**
 
   .. ts:def:: ChallengerInfoResponse
 
     interface ChallengerInfoResponse {
 
       // Unique ID of the record within Challenger
       // (identifies the rowid of the token).
       id: Integer;
 
       // Address that was validated.
       // Key-value pairs, details depend on the
       // address_type.
       address: Object;
 
      // Type of the address.
       address_type: string;
 
       // How long do we consider the address to be
       // valid for this user.
       expires: Timestamp;
 
     }