post-authorize-NONCE.rst (5902B)
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 :http:statuscode:`400 Bad Request`: 41 The request does not follow the spec. Since protocol **v1**. 42 Error codes used are: 43 44 * ``TALER_EC_GENERIC_PARAMETER_MISSING`` --- ``response_type``, 45 ``client_id`` or (when a ``code_challenge_method`` was given) 46 ``code_challenge`` is absent; ``detail`` names the argument. 47 * ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` --- the ``$NONCE`` in the URL 48 is not a valid 52-character Crockford-base32 value (``detail`` is 49 ``"nonce"``; since protocol **v8**, previously reported as ``404``), 50 ``response_type`` is not 51 ``code``, ``client_id`` is not a number, ``code_challenge_method`` is 52 neither ``plain`` nor ``S256``, a non-web ``redirect_uri`` was 53 combined with a ``plain``/absent ``code_challenge_method`` (the PKCE 54 downgrade guard), or one of ``redirect_uri``, ``state``, ``scope`` 55 and ``code_challenge`` is not valid UTF-8 (since protocol **v8**; 56 previously such a value reached the database and produced a 57 ``500``); ``detail`` names the argument. 58 :http:statuscode:`404 Not found`: 59 The service is unaware of a matching challenge. Since protocol **v1**. 60 Returned with ``TALER_EC_CHALLENGER_GENERIC_VALIDATION_UNKNOWN`` when 61 the nonce is 62 well-formed but no matching validation was updated. This deliberately 63 conflates four causes: the nonce is unknown, it has expired, the 64 ``client_id`` does not own it, or the ``redirect_uri`` does not match 65 the one registered for the client. Distinguishing them would let an 66 unauthenticated caller enumerate validations. 67 :http:statuscode:`405 Method Not Allowed`: 68 The request used a method other than ``GET``, ``HEAD``, ``POST`` or 69 ``OPTIONS``. 70 Returned by the request router with an ``Allow`` header and an 71 **empty body**; in particular there is no Taler error code. 72 ``HEAD`` is accepted on every endpoint that accepts ``GET``, and is 73 handled identically but without a response body (RFC 9110 section 74 9.3.2); since protocol **v8**. 75 :http:statuscode:`500 Internal Server Error`: 76 Server is not able to respond due to internal problems. 77 Since protocol **v1**. Returned with 78 ``TALER_EC_GENERIC_DB_STORE_FAILED`` (``detail`` is 79 ``"update_validation"``), both for a hard database error and for a 80 serialization failure that survived all retries. 81 82 .. note:: 83 84 Unlike RFC 6749 section 4.1.2.1, errors are never reported by redirecting 85 the user-agent back to the ``redirect_uri`` with an ``error`` argument; 86 all failures above are returned as a JSON body, even when the request 87 asked for ``text/html``. 88 89 .. ts:def:: ChallengeStatusResponse 90 91 interface ChallengeStatusResponse { 92 93 // indicates if the given address cannot be changed anymore, the 94 // form should be read-only if set to true. 95 fix_address: boolean; 96 97 // form values from the previous submission if available, details depend 98 // on the ``ADDRESS_TYPE``, should be used to pre-populate the form 99 // May contain a boolean field ``read_only`` indicating if 100 // the client is not allowed to change the address when posting 101 // it to the ``/challenge`` endpoint. 102 // If ``read_only`` is present and true, the service forces 103 // ``fix_address`` to true and ``changes_left`` to 0. 104 // Omitted entirely (not null) if no address was submitted yet. 105 last_address?: Object; 106 107 // is the challenge already solved? 108 solved: boolean; 109 110 // number of times the address can still be changed, may or may not be 111 // shown to the user 112 changes_left: Integer; 113 114 // when we would re-transmit the challenge the next 115 // time (at the earliest) if requested by the user; 116 // only meaningful if challenge already created 117 // @since **v2** 118 retransmission_time: Timestamp; 119 120 // how many times might the TAN still be retransmitted 121 // @since **v2** 122 pin_transmissions_left: Integer; 123 124 // how many times might the user still try entering the TAN code 125 // @since **v2** 126 auth_attempts_left: Integer; 127 }