Challenger Service RESTful API

Response is a ChallengeSetupResponse.

400 Bad request:

The request is malformed. Error codes used are:

TALER_EC_GENERIC_PARAMETER_MALFORMED — the $CLIENT_ID in the URL is not a number (detail is "client_id"), the body is valid JSON but not an object (detail is "address"), or read_only is present in the body but is not a boolean (detail is "read_only").
TALER_EC_GENERIC_JSON_INVALID — the body is not well-formed JSON.

403 Forbidden:

The client did not present usable credentials. Since protocol v8; previously reported as 400. In both cases detail is "Authorization". Error codes used are:

TALER_EC_GENERIC_PARAMETER_MISSING — there is no Authorization header at all.
TALER_EC_GENERIC_PARAMETER_MALFORMED — the header is present but does not use the Bearer scheme, or its value lacks the RFC 8959 secret-token: prefix.

The challenger service is unaware of a matching client, or the credentials of the client are invalid. These two cases are deliberately not distinguished. Always returned with TALER_EC_CHALLENGER_GENERIC_CLIENT_UNKNOWN.

500 Internal server error:

The request used a method other than POST or OPTIONS. Returned by the request router with an Allow header and an empty body; in particular there is no Taler error code.

The challenger service encountered an internal error. Error codes used are:

TALER_EC_GENERIC_DB_STORE_FAILED — the database transaction that authenticates the client and inserts the validation failed, either hard or by exhausting the retries for serialization failures (detail is "do_insert_validation").
TALER_EC_GENERIC_PARSER_OUT_OF_MEMORY — the service ran out of memory while buffering the request body.

Details::

interface ChallengeSetupRequest {
  // If true, the given address should not be edited.
  // Defaults to 'false' if not specified.
  read_only?: boolean;

  // Optional, additional fields to pre-populate
  // the address to be validated.
  // The fields depend on the challenger type.
  [x: string]: any;
}

interface ChallengeSetupResponse {
  // Nonce to use when constructing /authorize endpoint.
  nonce: string;

  // Time when this validation process expires.  After this time it can
  // no longer be authorized or exchanged for a token.
  // Available since protocol v9.
  expires: Timestamp;
}

20.8.5. Login #

GET /authorize/$NONCE#

POST /authorize/$NONCE#

This is the “authorization” endpoint of the OAuth 2.0 protocol. This endpoint is used by the user-agent. It will return data to generate a form to enter the address.

The NONCE is a unique value identifying the challenge, should be shown to the user so that they can recognize it when they receive the TAN code.

Note that both for GET and POST requests the request arguments must be given in the URL and the body should be empty. We currently do NOT support using x-www-form-urlencoded arguments in the body, even for a POST.

Request:

Query Parameters:

response_type – Must be code
client_id – Identifier of the client.
redirect_uri – URI-encoded redirection URI to use upon authorization.
state – Arbitrary client state to associate with the request.
scope – Not supported, any value is accepted.
code_challenge – A string to enhance security using PKCE (available since v3).
code_challenge_method – The method used for the code_challenge. Options are S256 (SHA-256) or plain (available since v3).

Response:

The the response is a ChallengeStatusResponse. Since protocol v1. The response carries Cache-Control: no-store,no-cache.

302 Found:

Returned when the client explicitly accepts text/html returning a redirection to the WebUI. Since protocol v1. The Location is the relative URL /webui/ followed by the query string of the request with a nonce=$NONCE argument appended. Note that a request without any Accept header, or with Accept: */*, is answered with 200 OK and JSON instead.

The request does not follow the spec. Since protocol v1. Error codes used are:

TALER_EC_GENERIC_PARAMETER_MISSING — response_type, client_id or (when a code_challenge_method was given) code_challenge is absent; detail names the argument.
TALER_EC_GENERIC_PARAMETER_MALFORMED — the $NONCE in the URL is not a valid 52-character Crockford-base32 value (detail is "nonce"; since protocol v8, previously reported as 404), response_type is not code, client_id is not a number, code_challenge_method is neither plain nor S256, a non-web redirect_uri was combined with a plain/absent code_challenge_method (the PKCE downgrade guard), or one of redirect_uri, state, scope and code_challenge is not valid UTF-8 (since protocol v8; previously such a value reached the database and produced a 500); detail names the argument.

The service is unaware of a matching challenge. Since protocol v1. Returned with TALER_EC_CHALLENGER_GENERIC_VALIDATION_UNKNOWN when the nonce is well-formed but no matching validation was updated. This deliberately conflates four causes: the nonce is unknown, it has expired, the client_id does not own it, or the redirect_uri does not match the one registered for the client. Distinguishing them would let an unauthenticated caller enumerate validations.

The request used a method other than GET, HEAD, POST or OPTIONS. Returned by the request router with an Allow header and an empty body; in particular there is no Taler error code. HEAD is accepted on every endpoint that accepts GET, and is handled identically but without a response body (RFC 9110 section 9.3.2); since protocol v8.

Server is not able to respond due to internal problems. Since protocol v1. Returned with TALER_EC_GENERIC_DB_STORE_FAILED (detail is "update_validation"), both for a hard database error and for a serialization failure that survived all retries.

Note

Unlike RFC 6749 section 4.1.2.1, errors are never reported by redirecting the user-agent back to the redirect_uri with an error argument; all failures above are returned as a JSON body, even when the request asked for text/html.

interface ChallengeStatusResponse {

  // indicates if the given address cannot be changed anymore, the
  // form should be read-only if set to true.
  fix_address: boolean;

  // form values from the previous submission if available, details depend
  // on the ADDRESS_TYPE, should be used to pre-populate the form
  // May contain a boolean field read_only indicating if
  // the client is not allowed to change the address when posting
  // it to the /challenge endpoint.
  // If read_only is present and true, the service forces
  // fix_address to true and changes_left to 0.
  // Omitted entirely (not null) if no address was submitted yet.
  last_address?: Object;

  // is the challenge already solved?
  solved: boolean;

  // number of times the address can still be changed, may or may not be
  // shown to the user
  changes_left: Integer;

  // when we would re-transmit the challenge the next
  // time (at the earliest) if requested by the user;
  // only meaningful if challenge already created
  // @since **v2**
  retransmission_time: Timestamp;

  // how many times might the TAN still be retransmitted
  // @since **v2**
  pin_transmissions_left: Integer;

  // how many times might the user still try entering the TAN code
  // @since **v2**
  auth_attempts_left: Integer;
}

20.8.6. Challenge #

POST /challenge/$NONCE#

This endpoint is used by the user-agent to submit the address to which a challenge should be sent by the challenger service.

Request:

Body should use the mime-type “application/x-www-form-urlencoded”; multipart/form-data is accepted as well. Alternatively, the address may be uploaded directly as a JSON object using the mime-type application/json. In the form encodings, each field name/value pair becomes one string-valued member of the address object, and each field is limited to 1024 bytes. The total request body is limited to 1024 bytes for the form encodings.

The posted form data must contain an address JSON object that follow the restrictions defined in config. If the address provided in the ChallengeSetupRequest of /setup was set to be read_only and that was subsequently returned in the ChallengeStatusResponse, then the body must not change that address. The read_only field itself is ignored when comparing the addresses and is re-inserted by the service, so the client need not (but may) preserve it.

Response:

The response is ChallengeResponse. Since protocol v2. The created variant carries Cache-Control: no-store,no-cache.

The request does not follow the spec. Since protocol v1. Error codes used are:

TALER_EC_GENERIC_PARAMETER_MALFORMED — the $NONCE in the URL is not a valid 52-character Crockford-base32 value (detail is "nonce"), the Content-Length header is not a number (detail is "Content-Length"), an application/json body is valid JSON but not an object (detail is "address"), or a submitted field name or value is not valid UTF-8.
TALER_EC_CHALLENGER_ADDRESS_RESTRICTION_VIOLATED — a field is absent or violates the regular expression configured for it in restrictions, see config; detail names the offending field, so the user agent can highlight it and show the corresponding hint/hint_i18n. Since protocol v8.
TALER_EC_GENERIC_JSON_INVALID — an application/json body is not well-formed JSON.

403 Forbidden:

The address being submitted differs from the previously submitted address but the validation process was set up as read_only and thus the address cannot be changed. Returned with TALER_EC_CHALLENGER_CLIENT_FORBIDDEN_READ_ONLY. Since protocol v4.

404 Not Found:

The service is unaware of a matching challenge. Since protocol v1. Returned with TALER_EC_CHALLENGER_GENERIC_VALIDATION_UNKNOWN when the nonce is well-formed but unknown, or the validation has expired. These two cases are not distinguished.

413 Request entity too large:

The request used a method other than POST or OPTIONS. Returned by the request router with an Allow header and an empty body; in particular there is no Taler error code.

The request body exceeds the 1024 byte limit. Returned with TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT.

415 Unsupported Media Type:

The Content-Type is missing or is not one the service can parse. Returned with TALER_EC_GENERIC_PARAMETER_MALFORMED and detail set to "Content-Type". Since protocol v8; previously reported as 400.

429 Too Many Requests:

There have been too many attempts to request challenge transmissions for this $NONCE. The user-agent should wait and (eventually) request a fresh nonce to be set up by the client. Since protocol v2. Two distinct situations are distinguished, since the appropriate recovery differs. Since protocol v8:

TALER_EC_CHALLENGER_TOO_MANY_ADDRESS_CHANGES — the number of permitted address changes was exhausted. The user must obtain a fresh nonce from the client.
TALER_EC_CHALLENGER_TOO_MANY_PIN_TRANSMISSIONS — the number of permitted TAN transmissions for the current address was exhausted. The user may still try a different address if address changes remain.

Note that merely being within the retransmission cooldown is not an error: it is reported as 200 OK with transmitted set to false.

Server is not able to respond due to internal problems. Since protocol v1. Error codes used are:

TALER_EC_GENERIC_DB_FETCH_FAILED — reading the previously stored address failed (detail is "get_validation_address").
TALER_EC_GENERIC_DB_STORE_FAILED — storing the address or confirming the transmitted TAN failed (detail is "do_challenge_address" or "do_challenge_address_confirm_pin").
TALER_EC_GENERIC_FAILED_TO_EXPAND_TEMPLATE — expanding MESSAGE_TEMPLATE_FILE for the challenge message failed.
TALER_EC_GENERIC_PARSER_OUT_OF_MEMORY — the service ran out of memory while buffering an application/json body.
TALER_EC_CHALLENGER_ADDRESS_RESTRICTION_MALFORMED — the ADDRESS_RESTRICTIONS configuration for the field named in detail has no regular expression, or one that failed to compile. This is an operator error, not a client error; the request is refused because a restriction that cannot be evaluated must not be treated as “no restriction”. Since protocol v8.

502 Bad Gateway:

The challenger service failed to launch or communicate with its helper process for delivering the challenge (SMS, e-mail, postal mail). Returned with TALER_EC_CHALLENGER_HELPER_EXEC_FAILED. The detail distinguishes the failure: "pipe", "exec", "write", or "$EXIT_CODE/$PROCESS_STATUS" when the helper terminated abnormally or with a non-zero exit code.

// Union discriminated by the "type" field.
type ChallengeResponse = ChallengeRedirect | ChallengeCreateResponse

// @since **v2**
interface ChallengeRedirect {
  // Union discriminator field.
  type: "completed";

  // challenge is completed, use should redirect here
  redirect_url: WebURL;
}

interface ChallengeCreateResponse {
   // Union discriminator field.
   type: "created"

   // how many more attempts are allowed, might be shown to the user,
   // highlighting might be appropriate for low values such as 1 or 2 (the
   // form will never be used if the value is zero)
   attempts_left: Integer;

   // the address that is being validated, might be shown or not
   address: Object;

   // true if we just retransmitted the challenge, false if we sent a
   // challenge recently and thus refused to transmit it again this time;
   // might make a useful hint to the user
   transmitted: boolean;

   // when we would re-transmit the challenge the next
   // time (at the earliest) if requested by the user
   // @since **v2**
   retransmission_time: Timestamp;
 }

20.8.7. Solve #

POST /solve/$NONCE#

Used by the user-agent to submit an answer to the challenge. If the answer is correct, the user will be redirected to the client’s redirect URI, otherwise the user may be given another chance to complete the process.

Request:

Body should use the mime-type “application/x-www-form-urlencoded”; multipart/form-data is accepted as well. The posted form data must contain a “pin” field, whose value must be a decimal unsigned integer. The request body is limited to 1024 bytes.

Response:

If the request ask for application/json the response is a ChallengeSolveResponse. Since protocol v2. Note that this status is only used for the successful outcome; an incorrect or unusable TAN is reported with 403, 409 or 429 (see below).

302 Found:

Only possible if request didn’t ask for application/json. Since protocol v2. The user is redirected to the redirect URI of the client to pass the grant to the client. The target will be the redirect URI specified by the client (during registration and again upon /authorize), plus a code argument with the authorization code, and the state argument from the /authorize endpoint. The state argument is omitted entirely if the client did not supply one. The response body is the plain text Ok!.

The request does not follow the spec. Since protocol v1. Error codes used are:

TALER_EC_GENERIC_PARAMETER_MALFORMED — the $NONCE in the URL is not a valid 52-character Crockford-base32 value (detail is "nonce"), the Content-Length header is not a number (detail is "Content-Length"), or the pin field is not a decimal number (detail is "pin").
TALER_EC_GENERIC_PARAMETER_MISSING — there is no pin field in the body (detail is "pin").

403 Forbidden:

The TAN was checked and did not match. The response is InvalidPinResponse. Since protocol v1. Returned with TALER_EC_CHALLENGER_INVALID_PIN.

The service is unaware of a matching challenge, or the validation has expired. Since protocol v1. Returned with TALER_EC_CHALLENGER_GENERIC_VALIDATION_UNKNOWN.

413 Request entity too large:

The request used a method other than POST or OPTIONS. Returned by the request router with an Allow header and an empty body; in particular there is no Taler error code.

409 Conflict:

The service had never actually transmitted a TAN, so solving is naturally impossible. Since protocol v8. The response is an InvalidPinResponse with no_challenge set to true. Returned with TALER_EC_CHALLENGER_NO_CHALLENGE_TRANSMITTED.

The request body exceeds the 1024 byte limit. Returned with TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT.

415 Unsupported Media Type:

The Content-Type is missing or is not one the service can parse. Returned with TALER_EC_GENERIC_PARAMETER_MALFORMED and detail set to "Content-Type". Since protocol v8; previously reported as 400.

429 Too Many Requests:

There have been too many attempts to solve the challenge for this address (and $NONCE). The user-agent should either try a different address (or wait and (eventually) request a fresh nonce to be set up by the client). Since protocol v2. The body is an InvalidPinResponse in both of the cases below, which are told apart by the error code:

TALER_EC_CHALLENGER_NO_PIN_ATTEMPTS_LEFT — the user has run out of TAN guesses but may still request a retransmission or change the address. exhausted is true. Since protocol v8.
TALER_EC_CHALLENGER_TOO_MANY_ATTEMPTS — the user has exhausted address changes, TAN guesses and retransmissions, so the situation is terminal and all three counters are zero. Since protocol v8 this returns an InvalidPinResponse as well; it previously returned a plain error object with only code, hint and detail. Note that the response consuming the very last guess already reports this, rather than TALER_EC_CHALLENGER_INVALID_PIN with a 403: at that point nothing is left to try, which is the more useful thing to tell the user.

Server is not able to respond due to internal problems. Since protocol v1. Returned with TALER_EC_GENERIC_DB_FETCH_FAILED; detail is "do_solve_challenge" when solving failed and "get_validation" when the subsequent construction of the redirect URL failed.

Note

Error responses are always JSON, even when the request asked for text/html; only the success case honours the Accept header by returning a 302 redirect.

Note

Once a challenge has been solved, repeating the request for the same (unexpired) $NONCE succeeds again regardless of the pin submitted, re-issuing the redirect and authorization code.

// Only the "completed" variant occurs with a 200 status; the
// "pending" variant (InvalidPinResponse) is returned with a 403,
// 409 or 429 status.  Since **v8** every unsuccessful /solve uses
// that one shape, so a client need only parse InvalidPinResponse.
type ChallengeSolveResponse = ChallengeRedirect;

interface InvalidPinResponse {
  // Union discriminator field.
  type: "pending";

  // numeric Taler error code, should be shown to indicate the error
  // compactly for reporting to developers
  code: Integer;

  // human-readable Taler error code, should be shown for the user to
  // understand the error
  hint: string;

  // how many times is the user still allowed to change the address;
  // if 0, the user should not be shown a link to jump to the
  // address entry form
  addresses_left: Integer;

  // how many times might the TAN still be retransmitted
  pin_transmissions_left: Integer;

  // how many times might the user still try entering the TAN code
  auth_attempts_left: Integer;

  // if true, the TAN was not even evaluated as the user previously
  // exhausted the number of attempts
  exhausted: boolean;

  // if true, the TAN was not even evaluated as no challenge was ever
  // issued (the user must have skipped the step of providing their
  // address first!)
  no_challenge: boolean;
}

20.8.8. Auth #

POST /token#

This is the token endpoint of the OAuth 2.0 specification. This endpoint is used by the client to provide its authorization code, demonstrating that it has the right to learn a particular user’s validated address. In return, the challenger service returns the access token. Renewal is not supported.

Request:

The request must include an application/x-www-form-urlencoded body (multipart/form-data is accepted as well) specifying the client_id, redirect_uri, client_secret, code and grant_type. The grant_type must be set to authorization_code. The redirect_uri must match the URI from /authorize. The code must be the authorization code that /solve returned to the user. The client_id and client_secret must match the usual client credentials. Since protocol v3, code_verifier can also be included.

The request body is limited to 2048 bytes, as is each individual field. Note that the client credentials must be passed in the body (client_secret_post); HTTP Basic authentication (client_secret_basic) is not supported.

Response:

Error responses follow RFC 6749, section 5.2 with an “error” field in JSON, as well as also returning GNU Taler style error messages. The error values used are invalid_request, unsupported_grant_type, invalid_client, invalid_grant and server_error. Since protocol v8 every error response of this endpoint carries the error field, including 415, 413 and 500.

The body will be a ChallengerAuthResponse.

A required POST field (grant_type, client_id, client_secret, code or redirect_uri) is missing or malformed, grant_type is not authorization_code, or the authorization code was not accepted. Error codes used are:

TALER_EC_GENERIC_PARAMETER_MISSING (error is invalid_request, or invalid_grant for a missing code_verifier) — a required field is absent; detail names it.
TALER_EC_GENERIC_PARAMETER_MALFORMED (error is invalid_request, or unsupported_grant_type when the grant_type is not authorization_code) — the Content-Length header is not a number, client_id is not a number, or the code_verifier violates the length (43–128) or character-set rules of RFC 7636.
TALER_EC_CHALLENGER_CLIENT_FORBIDDEN_BAD_CODE (error is invalid_grant) — the code is not well-formed, does not correspond to a solved validation of this client, does not match its recomputed authentication tag, or the code_verifier does not match the stored code_challenge.
TALER_EC_CHALLENGER_GRANT_UNKNOWN (error is invalid_grant) — the authorization code was already redeemed, or the validation expired between the two database transactions.

Note

Several of these conditions are answered with a byte-identical response on purpose, so that a caller cannot use /token as an oracle to distinguish “this nonce does not exist” from “this validation has no address” from “your authentication tag is wrong”.

401 Unauthorized:

Authentication of the client failed (per RFC 6749, section 5.2): either the client_id/client_secret pair is invalid, or the redirect_uri does not match the one registered with the client. Error codes used are:

TALER_EC_CHALLENGER_CLIENT_AUTHENTICATION_FAILED — the client_id/client_secret pair does not match a registered client. Since protocol v8; previously TALER_EC_CHALLENGER_GENERIC_CLIENT_UNKNOWN, which is now used only by /setup/$CLIENT_ID with a 404 so that each error code maps to exactly one HTTP status.
TALER_EC_CHALLENGER_GENERIC_CLIENT_FORBIDDEN_BAD_REDIRECT_URI

Both are returned with error set to invalid_client and a WWW-Authenticate: Bearer error="invalid_client" header. Note that failures concerning the code itself — including PKCE code_verifier mismatches, which exist since protocol v3 — are reported with 400, not 401.

413 Request entity too large:

The request used a method other than POST or OPTIONS. Returned by the request router with an Allow header and an empty body; in particular there is no Taler error code.

409 Conflict:

A code was presented for a validation process for which the user has not (yet) submitted any address, so the token cannot be issued. Returned with TALER_EC_CHALLENGER_MISSING_ADDRESS. Removed in v8 (to better match RFC 6749, section 5.2); the condition is now reported as 400 with TALER_EC_CHALLENGER_CLIENT_FORBIDDEN_BAD_CODE.

The request body exceeds the 2048 byte limit. Returned with TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT and error set to invalid_request.

415 Unsupported Media Type:

The Content-Type is missing or is not one the service can parse. Returned with TALER_EC_GENERIC_PARAMETER_MALFORMED, detail set to "Content-Type" and error set to invalid_request. Since protocol v8; previously reported as 400.

The challenger service encountered an internal error, for example a database failure or a failure of the SHA-256 or Base64 helpers used for PKCE verification. Error codes used are:

TALER_EC_GENERIC_DB_FETCH_FAILED — detail is "get_client" or "get_validation_pkce".
TALER_EC_GENERIC_DB_STORE_FAILED — detail is "do_insert_token".
TALER_EC_GENERIC_DB_SOFT_FAILURE — a serialization failure that survived all retries.
TALER_EC_GENERIC_DB_INVARIANT_FAILURE (error is server_error) — the stored validation has a code_challenge but no challenge method.
TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE (error is server_error) — the SHA-256 or Base64 helper used for PKCE verification failed.

All of these carry error set to server_error. Note that the stored code_challenge_method being unknown is reported with TALER_EC_GENERIC_DB_INVARIANT_FAILURE since protocol v8; it previously used TALER_EC_GENERIC_PARAMETER_MALFORMED, which wrongly suggested the client’s request was at fault.

Details::

interface ChallengerAuthResponse {
  // Token used to authenticate access in /info.
  access_token: string;

  // Type of the access token.
  token_type: "Bearer";

  // Amount of time that an access token is valid (in seconds).
  expires_in: Integer;

}

20.8.9. Info #

GET /info#

This userinfo endpoint of the OAuth 2.0 specification. This endpoint is used by the client to obtain the user’s validated address.

Request:

Must include the token returned to the client from the /token endpoint as a Bearer token in an Authorization header. The scheme token is matched case-insensitively and may be followed by any amount of whitespace. No query parameters or request body are read.

Response:

Every error response carries an RFC 6749 section 5.2 error field in the JSON body, and every 401 additionally carries the RFC 6750 section 3 challenge:

WWW-Authenticate: Bearer realm="challenger", error="...", error_description="..."

As required by RFC 6750 section 3, the challenge answering a request that carried no authentication credentials at all names only the realm and omits both error and error_description.

The body contains the address as a ChallengerInfoResponse.

401 Unauthorized:

The bearer token is missing, invalid (malformed) or unknown. Error codes used are:

TALER_EC_GENERIC_PARAMETER_MISSING — there is no Authorization header (detail is "Authorization"). Since protocol v8 the JSON body and the WWW-Authenticate challenge omit error in this case, per RFC 6750 section 3.
TALER_EC_GENERIC_PARAMETER_MALFORMED — the Authorization header does not use the Bearer scheme (error is invalid_request, detail is "Authorization").
TALER_EC_CHALLENGER_TOKEN_UNKNOWN — the token does not decode, is unknown, or has expired (error is invalid_token). Since protocol v8; previously TALER_EC_CHALLENGER_GRANT_UNKNOWN, which is now reserved for the authorization grant at /token so that each error code maps to exactly one HTTP status.

Note

A token that does not decode and a token that is simply unknown are answered with a byte-identical response on purpose, so that a caller cannot first learn whether a guessed token is well-formed and only then whether it exists.

The bearer token is invalid (includes unknown or expired). Returned with TALER_EC_CHALLENGER_GRANT_UNKNOWN. Removed in v8 (to better match RFC 6750); the condition is now reported as 401.

The request used a method other than GET, HEAD or OPTIONS. Returned by the request router with an Allow header and an empty body; in particular there is no Taler error code. HEAD is handled exactly like GET but without a response body, as required by RFC 9110 section 9.3.2; since protocol v8.