post-authorize-NONCE.rst (3284B)
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 a form to enter the 6 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 `ChallengeStatus`. Since protocol **v1**. 31 :http:statuscode:`302 Found`: 32 Returned when the client explicitly accepts ``text/html`` 33 returning a redirection to the WebUI. 34 Since protocol **v1**. 35 :http:statuscode:`400 Bad Request`: 36 The request does not follow the spec. 37 The response will include error 38 code, hint and detail. Since protocol **v1**. 39 :http:statuscode:`404 Not found`: 40 The service is unaware of a matching challenge. 41 The response will include error 42 code, hint and detail. Since protocol **v1**. 43 :http:statuscode:`406 Not Acceptable`: 44 The client ask for "text/html" and the backend installation does 45 not include the required HTML templates. 46 :http:statuscode:`500 Internal Server Error`: 47 Server is not able to respond due to internal problems. 48 The response will include error 49 code, hint and detail. Since protocol **v1**. 50 51 .. ts:def:: ChallengeStatus 52 53 interface ChallengeStatus { 54 55 // indicates if the given address cannot be changed anymore, the 56 // form should be read-only if set to true. 57 fix_address: boolean; 58 59 // form values from the previous submission if available, details depend 60 // on the ``ADDRESS_TYPE``, should be used to pre-populate the form 61 last_address?: Object; 62 63 // is the challenge already solved? 64 solved: boolean; 65 66 // number of times the address can still be changed, may or may not be 67 // shown to the user 68 changes_left: Integer; 69 70 // when we would re-transmit the challenge the next 71 // time (at the earliest) if requested by the user 72 // only present if challenge already created 73 // @since **v2** 74 retransmission_time: Timestamp; 75 76 // how many times might the PIN still be retransmitted 77 // only present if challenge already created 78 // @since **v2** 79 pin_transmissions_left: Integer; 80 81 // how many times might the user still try entering the PIN code 82 // only present if challenge already created 83 // @since **v2** 84 auth_attempts_left: Integer; 85 }