api-challenger.rst (5771B)
1 .. 2 This file is part of GNU TALER. 3 Copyright (C) 2023, 2024 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero General Public License as published by the Free Software 7 Foundation; either version 3.0, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 16 @author Christian Grothoff 17 18 .. _challenger-api: 19 20 ============================== 21 Challenger Service RESTful API 22 ============================== 23 24 The challenger service validates that a user is able to receive challenges at 25 an address (such as e-mail or SMS) and allows an OAuth 2.0 client to obtain 26 access to these validated addresses. 27 28 The high-level flow is that an OAuth 2.0 client is first registered with the 29 challenger service (via command-line). Using the command-line tool will print 30 the resulting client ID to the console. 31 32 .. note:: 33 34 Right now, registration of a unique redirection URI is *mandatory* for 35 each client. If multiple redirection URIs are needed, it is suggested to 36 just register additional clients. (While OAuth 2.0 would support not 37 registering fixed redirection URIs with a client, this is not recommended 38 as it would create an open redirector.) 39 40 Once a client is registered, that client can use the challenger service when 41 it needs a user to prove that the user is able to receive messages at a 42 particular address. However, asking a user to prove access to a particular 43 address can be expensive as it may involve sending an SMS or even postal mail 44 depending on the type of address. Thus, challenger does not allow a user 45 agent to begin an address validation process without prior approval by a 46 registered client. Thus, the process begins with a :http:post:`/setup/$CLIENT_ID </setup/$CLIENT_ID>` request where a 47 client requests challenger to begin an address validation request. The 48 :http:post:`/setup/$CLIENT_ID </setup/$CLIENT_ID>` response contains a ``nonce`` which is then used to construct the 49 URL of the endpoint to which the client must redirect the user-agent to begin 50 the address validation and authorization process. 51 52 The client then redirects the user-agent to the :http:get:`/authorize/$NONCE </authorize/$NONCE>` endpoint 53 of the challenger service, adding its ``state``, ``client_id`` and 54 ``redirect_uri`` as query parameters. The ``redirect_uri`` must match the 55 redirect URI registered with the client. From this endpoint, the challenger 56 service will return a Web page asking the user to provide its address. 57 58 .. note:: 59 60 Challenger is a bit unusual in that the ``$NONCE`` in the endpoint URL 61 makes the authorization endpoint URL (deliberately) unpredictable, while 62 for many other OAuth 2.0 APIs this endpoint is static. However, this is 63 compliant with OAuth 2.0 as determining the authorization URL is left out 64 of the scope of the standard. 65 66 When the user has filled in the form with their address, it will be submitted 67 to the :http:post:`/challenge/$NONCE </challenge/$NONCE>` endpoint and the challenger service will send a 68 challenge to the user's address and generate an HTML form asking the user to 69 enter the received challenge value. 70 71 The user can then enter the answer to the challenge which is then submitted to 72 the :http:post:`/solve/$NONCE </solve/$NONCE>` endpoint. If the answer is correct, the user agent will 73 be redirected to the client redirect URI that was specified by the OAuth 2.0 74 client upon ``/authorize``, together with an authorization grant encoded in 75 the redirection URI. 76 77 Given this authorization grant, the OAuth 2.0 client can then use the 78 :http:post:`/token </token>` endpoint to obtain an access token which will grant it access to 79 the resource. 80 81 Using the :http:get:`/info </info>` endpoint the client can then finally obtain the (now) 82 verified address of the user. 83 84 .. contents:: Table of Contents 85 :local: 86 87 88 --------------- 89 Version History 90 --------------- 91 92 The current protocol version is **v10**. 93 94 * The Challenger SPA is currently targeting **v6**. 95 96 **Version history:** 97 98 * ``v6``: add the ``address_type`` field to :http:get:`/config </config>` 99 * ``v7``: adds ``build_version`` to :http:get:`/config </config>` 100 * ``v8``: HTTP status code and error code corrections. 101 * ``v9``: adds ``expires`` to the :http:post:`/setup/$CLIENT_ID 102 </setup/$CLIENT_ID>` response. 103 * ``v10``: a validation the user can no longer pass is reported to the 104 client with an ``access_denied`` error redirect; 105 :http:post:`/solve/$NONCE`, :http:post:`/challenge/$NONCE` and 106 :http:post:`/authorize/$NONCE` answer it with ``410 Gone``. 107 108 **Upcoming versions:** 109 110 * None anticipated. 111 112 **Ideas for future version:** 113 114 * ``vXXX``: marker for features not yet targeted for release 115 116 117 .. include:: tos.rst 118 119 .. _challenger-config: 120 121 ----------------------- 122 Receiving Configuration 123 ----------------------- 124 125 .. include:: challenger/get-config.rst 126 127 .. _challenger-setup: 128 129 ----- 130 Setup 131 ----- 132 133 .. include:: challenger/post-setup-CLIENT_ID.rst 134 135 136 .. _challenger-login: 137 138 ----- 139 Login 140 ----- 141 142 .. include:: challenger/post-authorize-NONCE.rst 143 144 145 .. _challenger-challenge: 146 147 --------- 148 Challenge 149 --------- 150 151 .. include:: challenger/post-challenge-NONCE.rst 152 153 154 .. _challenger-solve: 155 156 ----- 157 Solve 158 ----- 159 160 .. include:: challenger/post-solve-NONCE.rst 161 162 .. _challenger-auth: 163 164 ---- 165 Auth 166 ---- 167 168 .. include:: challenger/post-token.rst 169 170 171 .. _challenger-info: 172 173 ---- 174 Info 175 ---- 176 177 .. include:: challenger/get-info.rst