post-authorize-NONCE.rst (6743B)
1 .. http:get:: /authorize/$NONCE 2 .. http:post:: /authorize/$NONCE 3 4 This is the "authorization" endpoint of the OAuth 2.0 protocol. This 5 endpoint is used by the user-agent. It will return data to 6 generate a form to enter the address. 7 8 The NONCE is a unique value identifying the challenge, should be shown to 9 the user so that they can recognize it when they receive the TAN code. 10 11 Note that both for GET and POST requests the request arguments must 12 be given in the URL and the body should be empty. We currently do NOT 13 support using x-www-form-urlencoded arguments in the body, even for 14 a POST. 15 16 **Request:** 17 18 :query response_type: Must be ``code`` 19 :query client_id: Identifier of the client. 20 :query redirect_uri: URI-encoded redirection URI to use upon authorization. 21 :query state: Arbitrary client state to associate with the request. 22 :query scope: Not supported, any value is accepted. 23 :query code_challenge: A string to enhance security using PKCE (available since **v3**). 24 :query code_challenge_method: The method used for the code_challenge. Options are S256 (SHA-256) or plain (available since **v3**). 25 26 **Response:** 27 28 :http:statuscode:`200 OK`: 29 The the response is 30 a `ChallengeStatusResponse`. Since protocol **v1**. 31 The response carries ``Cache-Control: no-store,no-cache``. 32 :http:statuscode:`302 Found`: 33 Returned when the client explicitly accepts ``text/html`` 34 returning a redirection to the WebUI. 35 Since protocol **v1**. 36 The ``Location`` is the relative URL ``/webui/`` followed by the query 37 string of the request with a ``nonce=$NONCE`` argument appended. 38 Note that a request without any ``Accept`` header, or with 39 ``Accept: */*``, is answered with ``200 OK`` and JSON instead. 40 Since protocol **v10**, a validation that failed permanently is 41 instead redirected to the client, see ``410 Gone`` below. 42 :http:statuscode:`400 Bad Request`: 43 The request does not follow the spec. Since protocol **v1**. 44 Error codes used are: 45 46 * ``TALER_EC_GENERIC_PARAMETER_MISSING`` --- ``response_type``, 47 ``client_id`` or (when a ``code_challenge_method`` was given) 48 ``code_challenge`` is absent; ``detail`` names the argument. 49 * ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` --- the ``$NONCE`` in the URL 50 is not a valid 52-character Crockford-base32 value (``detail`` is 51 ``"nonce"``; since protocol **v8**, previously reported as ``404``), 52 ``response_type`` is not 53 ``code``, ``client_id`` is not a number, ``code_challenge_method`` is 54 neither ``plain`` nor ``S256``, a non-web ``redirect_uri`` was 55 combined with a ``plain``/absent ``code_challenge_method`` (the PKCE 56 downgrade guard), or one of ``redirect_uri``, ``state``, ``scope`` 57 and ``code_challenge`` is not valid UTF-8 (since protocol **v8**; 58 previously such a value reached the database and produced a 59 ``500``); ``detail`` names the argument. 60 :http:statuscode:`404 Not found`: 61 The service is unaware of a matching challenge. Since protocol **v1**. 62 Returned with ``TALER_EC_CHALLENGER_GENERIC_VALIDATION_UNKNOWN`` when 63 the nonce is 64 well-formed but no matching validation was updated. This deliberately 65 conflates four causes: the nonce is unknown, it has expired, the 66 ``client_id`` does not own it, or the ``redirect_uri`` does not match 67 the one registered for the client. Distinguishing them would let an 68 unauthenticated caller enumerate validations. 69 :http:statuscode:`405 Method Not Allowed`: 70 The request used a method other than ``GET``, ``HEAD``, ``POST`` or 71 ``OPTIONS``. 72 Returned by the request router with an ``Allow`` header and an 73 **empty body**; in particular there is no Taler error code. 74 ``HEAD`` is accepted on every endpoint that accepts ``GET``, and is 75 handled identically but without a response body (RFC 9110 section 76 9.3.2); since protocol **v8**. 77 :http:statuscode:`410 Gone`: 78 The validation failed permanently: the user exhausted every address 79 change, TAN transmission and TAN attempt (an address the client set 80 as ``read_only`` counts as one that cannot be changed), so it can never 81 succeed. Returned with ``TALER_EC_CHALLENGER_VALIDATION_FAILED``; the 82 response is a `ValidationFailedResponse`. The user-agent must send the 83 user to its ``redirect_url`` so that the client learns about the 84 failure. If the request asked for ``text/html``, the service instead 85 redirects to that URL with a ``302 Found`` right away. 86 Since protocol **v10**. 87 This lets a user who returns to the validation get back to the 88 client. 89 :http:statuscode:`500 Internal Server Error`: 90 Server is not able to respond due to internal problems. 91 Since protocol **v1**. Returned with 92 ``TALER_EC_GENERIC_DB_STORE_FAILED`` (``detail`` is 93 ``"update_validation"``), both for a hard database error and for a 94 serialization failure that survived all retries. 95 96 .. note:: 97 98 Unlike RFC 6749 section 4.1.2.1, errors are never reported by redirecting 99 the user-agent back to the ``redirect_uri`` with an ``error`` argument; 100 all failures above are returned as a JSON body, even when the request 101 asked for ``text/html``. 102 103 .. ts:def:: ChallengeStatusResponse 104 105 interface ChallengeStatusResponse { 106 107 // indicates if the given address cannot be changed anymore, the 108 // form should be read-only if set to true. 109 fix_address: boolean; 110 111 // form values from the previous submission if available, details depend 112 // on the ``ADDRESS_TYPE``, should be used to pre-populate the form 113 // May contain a boolean field ``read_only`` indicating if 114 // the client is not allowed to change the address when posting 115 // it to the ``/challenge`` endpoint. 116 // If ``read_only`` is present and true, the service forces 117 // ``fix_address`` to true and ``changes_left`` to 0. 118 // Omitted entirely (not null) if no address was submitted yet. 119 last_address?: Object; 120 121 // is the challenge already solved? 122 solved: boolean; 123 124 // number of times the address can still be changed, may or may not be 125 // shown to the user 126 changes_left: Integer; 127 128 // when we would re-transmit the challenge the next 129 // time (at the earliest) if requested by the user; 130 // only meaningful if challenge already created 131 // @since **v2** 132 retransmission_time: Timestamp; 133 134 // how many times might the TAN still be retransmitted 135 // @since **v2** 136 pin_transmissions_left: Integer; 137 138 // how many times might the user still try entering the TAN code 139 // @since **v2** 140 auth_attempts_left: Integer; 141 }