api-challenger.rst (5159B)
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 2.1, 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 ``/setup/$CLIENT_ID`` request where a 47 client requests challenger to begin an address validation request. The 48 ``/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 ``/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 ``/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 ``/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 ``/token`` endpoint to obtain an access token which will grant it access to 79 the resource. 80 81 Using the ``/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 **v6**. 93 94 * The Challenger SPA is currently targeting **v6**. 95 96 **Version history:** 97 98 * ``v6``: add the ``address_type`` field to ``/config`` 99 100 **Upcoming versions:** 101 102 * None anticipated. 103 104 **Ideas for future version:** 105 106 * ``vXXX``: marker for features not yet targeted for release 107 108 109 .. include:: tos.rst 110 111 .. _challenger-config: 112 113 ----------------------- 114 Receiving Configuration 115 ----------------------- 116 117 .. include:: challenger/get-config.rst 118 119 .. _challenger-setup: 120 121 ----- 122 Setup 123 ----- 124 125 .. include:: challenger/post-setup-CLIENT_ID.rst 126 127 128 .. _challenger-login: 129 130 ----- 131 Login 132 ----- 133 134 .. include:: challenger/get-authorize-NONCE.rst 135 .. include:: challenger/post-authorize-NONCE.rst 136 137 138 .. _challenger-challenge: 139 140 --------- 141 Challenge 142 --------- 143 144 .. include:: challenger/post-challenge-NONCE.rst 145 146 147 .. _challenger-solve: 148 149 ----- 150 Solve 151 ----- 152 153 .. include:: challenger/post-solve-NONCE.rst 154 155 .. _challenger-auth: 156 157 ---- 158 Auth 159 ---- 160 161 .. include:: challenger/post-token.rst 162 163 164 .. _challenger-info: 165 166 ---- 167 Info 168 ---- 169 170 .. include:: challenger/get-info.rst