post-authorize-NONCE.rst (3254B)
1 .. http:post:: /authorize/$NONCE 2 3 This is the "authorization" endpoint of the OAuth 2.0 protocol. This 4 endpoint is used by the user-agent. It will return a form to enter the 5 address. 6 7 The NONCE is a unique value identifying the challenge, should be shown to 8 the user so that they can recognize it when they receive the TAN code. 9 10 Note that both for GET and POST requests the request arguments must 11 be given in the URL and the body should be empty. We currently do NOT 12 support using x-www-form-urlencoded arguments in the body, even for 13 a POST. 14 15 **Request:** 16 17 :query response_type: Must be ``code`` 18 :query client_id: Identifier of the client. 19 :query redirect_uri: URI-encoded redirection URI to use upon authorization. 20 :query state: Arbitrary client state to associate with the request. 21 :query scope: Not supported, any value is accepted. 22 :query code_challenge: A string to enhance security using PKCE (available since **v3**). 23 :query code_challenge_method: The method used for the code_challenge. Options are S256 (SHA-256) or plain (available since **v3**). 24 25 **Response:** 26 27 :http:statuscode:`200 OK`: 28 The the response is 29 a `ChallengeStatus`. Since protocol **v1**. 30 :http:statuscode:`302 Found`: 31 Returned when the client explicitly accepts ``text/html`` 32 returning a redirection to the WebUI. 33 Since protocol **v1**. 34 :http:statuscode:`400 Bad Request`: 35 The request does not follow the spec. 36 The response will include error 37 code, hint and detail. Since protocol **v1**. 38 :http:statuscode:`404 Not found`: 39 The service is unaware of a matching challenge. 40 The response will include error 41 code, hint and detail. Since protocol **v1**. 42 :http:statuscode:`406 Not Acceptable`: 43 The client ask for "text/html" and the backend installation does 44 not include the required HTML templates. 45 :http:statuscode:`500 Internal Server Error`: 46 Server is not able to respond due to internal problems. 47 The response will include error 48 code, hint and detail. Since protocol **v1**. 49 50 .. ts:def:: ChallengeStatus 51 52 interface ChallengeStatus { 53 54 // indicates if the given address cannot be changed anymore, the 55 // form should be read-only if set to true. 56 fix_address: boolean; 57 58 // form values from the previous submission if available, details depend 59 // on the ``ADDRESS_TYPE``, should be used to pre-populate the form 60 last_address?: Object; 61 62 // is the challenge already solved? 63 solved: boolean; 64 65 // number of times the address can still be changed, may or may not be 66 // shown to the user 67 changes_left: Integer; 68 69 // when we would re-transmit the challenge the next 70 // time (at the earliest) if requested by the user 71 // only present if challenge already created 72 // @since **v2** 73 retransmission_time: Timestamp; 74 75 // how many times might the PIN still be retransmitted 76 // only present if challenge already created 77 // @since **v2** 78 pin_transmissions_left?: Integer; 79 80 // how many times might the user still try entering the PIN code 81 // only present if challenge already created 82 // @since **v2** 83 auth_attempts_left?: Integer; 84 }