diff options
Diffstat (limited to 'core/api-challenger.rst')
-rw-r--r-- | core/api-challenger.rst | 194 |
1 files changed, 168 insertions, 26 deletions
diff --git a/core/api-challenger.rst b/core/api-challenger.rst index 914d8d01..f8631977 100644 --- a/core/api-challenger.rst +++ b/core/api-challenger.rst @@ -1,6 +1,6 @@ .. This file is part of GNU TALER. - Copyright (C) 2023 Taler Systems SA + 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 @@ -29,19 +29,19 @@ 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:: +.. note:: - The current service mandates that redirection URIs - start with "http://" or "https://". See issue #7838 - for what should be done to lift this restriction. + The current service mandates that redirection URIs + start with "http://" or "https://". See issue #7838 + for what should be done to lift this restriction. - .. note:: +.. 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.) + 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 @@ -61,13 +61,13 @@ of the challenger service, adding its ``state``, ``client_id`` and 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:: +.. 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. + 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 @@ -99,7 +99,7 @@ Receiving Configuration .. http:get:: /config Obtain the key configuration settings of the storage service. - This specification corresponds to ``current`` protocol being version **0**. + This specification corresponds to ``current`` protocol being version **1**. **Response:** @@ -168,6 +168,16 @@ Login 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. + + This endpoint typically also supports requests with the "Accept" header + requesting "text/html". In this case, an HTML response using the template + :ref:`enter-$ADDRESS_TYPE-form <challenger_enter-address_type-form>` is + returned. If the backend installation does not include the required HTML + templates, a 406 status code is returned. + + **Request:** :query response_type: Must be ``code`` @@ -179,10 +189,55 @@ Login **Response:** :http:statuscode:`200 OK`: - The body contains a form to be submitted by the user-agent. + If the request ask for application/json then the response is + a `ChallengeStatus`. Since protocol **v1**. + Otherwise, the body contains a form to be submitted by the user-agent + using the template :ref:`enter-$ADDRESS_TYPE-form <challenger_enter-address_type-form>`. The form will ask the user to specify their address. + :http:statuscode:`400 Bad Request`: + The request does not follow the spec. + If the request ask for application/json the response will include error + code, hint and detail. Since protocol **v1**. + Otherwise, the body contains information using the template :ref:`invalid-request <challenger_invalid-request>`. :http:statuscode:`404 Not found`: - The backup service is unaware of a matching $NONCE. + The service is unaware of a matching challenge. + If the request ask for application/json the response will include error + code, hint and detail. Since protocol **v1**. + Otherwise, the body contains information using the template :ref:`validation-unknown <challenger_validation-unknown>`. + :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. + If the request ask for application/json the response will include error + code, hint and detail. Since protocol **v1**. + Otherwise, the body contains information using the template :ref:`internal-error <challenger_internal-error>`. + + .. ts:def:: ChallengeStatus + + interface ChallengeStatus { + // 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; + + // 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; + + // number of times the address can still be changed, may or may not be + // shown to the user + changes_left: Integer; + } .. _challenger-challenge: @@ -204,15 +259,57 @@ Challenge **Response:** :http:statuscode:`200 OK`: - The body contains a form asking for the answer to - the challenge to be entered by the user. - :http:statuscode:`404 Not found`: - The challenger service is unaware of a matching nonce. + If the request ask for application/json the response is `ChallengeCreateResponse`. Since protocol **v1**. + Otherwise, the body contains a form asking for the answer to + the challenge to be entered by the user using the + template :ref:`enter-tan-form <challenger_enter-tan-form>`. + :http:statuscode:`400 Bad Request`: + The request does not follow the spec. + If the request ask for application/json the response will include error + code, hint and detail. Since protocol **v1**. + Otherwise, the body contains information using the template :ref:`invalid-request <challenger_invalid-request>`. + :http:statuscode:`404 Not Found`: + The service is unaware of a matching challenge. + If the request ask for application/json the response will include error + code, hint and detail. Since protocol **v1**. + Otherwise, the body contains information using the template :ref:`validation-unknown <challenger_validation-unknown>`. + :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. + :http:statuscode:`500 Internal Server Error`: + Server is not able to respond due to internal problems. + If the request ask for application/json the response will include error + code, hint and detail. Since protocol **v1**. + Otherwise, the body contains information using the template :ref:`internal-error <challenger_internal-error>`. + + .. ts:def:: ChallengeCreateResponse + + interface ChallengeCreateResponse { + + // 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; + + // timestamp explaining when we would re-transmit the challenge the next + // time (at the earliest) if requested by the user + next_tx_time: String; + + } + .. _challenger-solve: @@ -239,16 +336,61 @@ Solve 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. + If the request ask for application/json the response will include error + code, hint and detail. Since protocol **v1**. + Otherwise, the body contains information using the template :ref:`invalid-request <challenger_invalid-request>`. :http:statuscode:`403 Forbidden`: - The solution of the user to the challenge is invalid. + If the request ask for application/json the response is `InvalidPinResponse`. Since protocol **v1**. + Otherwise, the body contains information using the template :ref:`invalid-pin <challenger_invalid-pin>`. :http:statuscode:`404 Not found`: The service is unaware of a matching challenge. + If the request ask for application/json the response will include error + code, hint and detail. Since protocol **v1**. + Otherwise, the body contains information using the template :ref:`validation-unknown <challenger_validation-unknown>`. :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). - + :http:statuscode:`500 Internal Server Error`: + Server is not able to respond due to internal problems. + If the request ask for application/json the response will include error + code, hint and detail. Since protocol **v1**. + Otherwise, the body contains information using the template :ref:`internal-error <challenger_internal-error>`. + + .. ts:def:: InvalidPinResponse + + interface InvalidPinResponse { + // numeric Taler error code, should be shown to indicate the error + // compactly for reporting to developers + ec: 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: |