diff options
| -rw-r--r-- | core/api-challenger.rst | 32 | ||||
| -rw-r--r-- | taler-challenger-manual.rst | 53 |
2 files changed, 43 insertions, 42 deletions
diff --git a/core/api-challenger.rst b/core/api-challenger.rst index be8a36c3..25c84d3e 100644 --- a/core/api-challenger.rst +++ b/core/api-challenger.rst @@ -29,19 +29,19 @@ The high-level flow is that an OAuth 2.0 client is first registered with the challenger service (via command-line). Using the command-line tool will print the resulting client ID to the console. - .. note:: +.. note:: - The current service mandates that redirection URIs - start with "http://" or "https://". See issue #7838 - for what should be done to lift this restriction. + The current service mandates that redirection URIs + start with "http://" or "https://". See issue #7838 + for what should be done to lift this restriction. - .. note:: +.. note:: - Right now, registration of a unique redirection URI is *mandatory* for - each client. If multiple redirection URIs are needed, it is suggested to - just register additional clients. (While OAuth 2.0 would support not - registering fixed redirection URIs with a client, this is not recommended - as it would create an open redirector.) + Right now, registration of a unique redirection URI is *mandatory* for + each client. If multiple redirection URIs are needed, it is suggested to + just register additional clients. (While OAuth 2.0 would support not + registering fixed redirection URIs with a client, this is not recommended + as it would create an open redirector.) Once a client is registered, that client can use the challenger service when it needs a user to prove that the user is able to receive messages at a @@ -61,13 +61,13 @@ of the challenger service, adding its ``state``, ``client_id`` and redirect URI registered with the client. From this endpoint, the challenger service will return a Web page asking the user to provide its address. - .. note:: +.. note:: - Challenger is a bit unusual in that the ``$NONCE`` in the endpoint URL - makes the authorization endpoint URL (deliberately) unpredictable, while - for many other OAuth 2.0 APIs this endpoint is static. However, this is - compliant with OAuth 2.0 as determining the authorization URL is left out - of the scope of the standard. + Challenger is a bit unusual in that the ``$NONCE`` in the endpoint URL + makes the authorization endpoint URL (deliberately) unpredictable, while + for many other OAuth 2.0 APIs this endpoint is static. However, this is + compliant with OAuth 2.0 as determining the authorization URL is left out + of the scope of the standard. When the user has filled in the form with their address, it will be submitted to the ``/challenge/$NONCE`` endpoint and the challenger service will send a diff --git a/taler-challenger-manual.rst b/taler-challenger-manual.rst index dab1d954..4ff2b40e 100644 --- a/taler-challenger-manual.rst +++ b/taler-challenger-manual.rst @@ -326,15 +326,15 @@ to be initialized with the following command: [root@exchange-online]# sudo -u challenger-httpd challenger-dbinit - ..note:: +.. note:: - To run this command, the user must have ``CREATE TABLE``, ``CREATE - INDEX``, ``ALTER TABLE`` and (in the future possibly even) ``DROP TABLE`` - permissions. Those permissions are only required for this step (which may - have to be repeated when upgrading a deployment). Afterwards, during - normal operation, permissions to ``CREATE`` or ``ALTER`` tables are not - required by Challenger and thus should not be granted. For more - information, see :doc:`manpages/challenger-dbinit.1`. + To run this command, the user must have ``CREATE TABLE``, ``CREATE + INDEX``, ``ALTER TABLE`` and (in the future possibly even) ``DROP TABLE`` + permissions. Those permissions are only required for this step (which may + have to be repeated when upgrading a deployment). Afterwards, during + normal operation, permissions to ``CREATE`` or ``ALTER`` tables are not + required by Challenger and thus should not be granted. For more + information, see :doc:`manpages/challenger-dbinit.1`. Deployment @@ -402,10 +402,11 @@ have terminated unexpectedly. Furthermore, the hypervisor to limit Postgres database memory utilization. .. note:: - The ``challenger-httpd`` does not ship with HTTPS enabled by default. - It must thus be run behind an HTTPS reverse proxy that performs - TLS termination on the same system. Thus, it would typically be configured - to listen on a UNIX domain socket. + + The ``challenger-httpd`` does not ship with HTTPS enabled by default. + It must thus be run behind an HTTPS reverse proxy that performs + TLS termination on the same system. Thus, it would typically be configured + to listen on a UNIX domain socket. Given proper packaging, all of the above are realized via a simple systemd target. This enables Challenger to be properly started using a simple command: @@ -422,13 +423,13 @@ Before clients can use Challenger, they must be explicitly configured. Each client is identified via its OAuth 2.0 REDIRECT URI. Thus, a client must have exactly one REDIRECT URI - ..note:: +.. note:: - The OAuth 2.0 specification allows for a client to register - zero or multiple REDIRECT URIs. However, zero is insecure - as it creates an open redirector, and multiple REDIRECT URIs - can trivially be implemented with Challenger by adding more - clients. + The OAuth 2.0 specification allows for a client to register + zero or multiple REDIRECT URIs. However, zero is insecure + as it creates an open redirector, and multiple REDIRECT URIs + can trivially be implemented with Challenger by adding more + clients. You can add or remove clients at any time; the Challenger service does not need to be running, but if it is you can still add or remove clients without @@ -460,12 +461,12 @@ info endpoints. For Challenger, these are ``/authorize``, ``/token`` and ``/authorize/$NONCE`` where ``$NONCE`` is a nonce that must be first requested by the client using the ``/setup/$CLIENT_ID`` endpoint! - ..note:: +.. note:: - This extra step prevents user-agents from (ab)using the Challenger service - to send challenges to addresses even when there is no authorized client - that desires address validation. This is an important feature as address - validation could be expensive. + This extra step prevents user-agents from (ab)using the Challenger service + to send challenges to addresses even when there is no authorized client + that desires address validation. This is an important feature as address + validation could be expensive. Thus, to generate the authorization URL, a client must first POST to ``/setup/$CLIENT_ID`` using their client secret in an ``Authorization: Bearer $SECRET`` @@ -493,10 +494,10 @@ the configuration file syntax: Database management ------------------- - .. note:: +.. note:: - We advise to make good backups before experimenting with - the database. + We advise to make good backups before experimenting with + the database. To update the Challenger database after upgrading to a newer version of Challenger, you should simply re-run ``challenger-dbinit``. |