doc: README.md

Author: obiltschnig

README.md

@@ -63,12 +63,16 @@ Furthermore, the following executables are included:
     creates a tunnel connection from your local machine (Windows, macOS) to a remote Windows device
     (which must have the remote desktop feature enabled), then launches a Microsoft Remote Desktop (RDP)
     client using that tunnel connection.
+  - [`remote-login`](WebTunnel/WebTunnelLogin/README.md): This executable obtains an OAuth 2 token from
+    the macchina.io REMOTE server and stores it locally.
+    The token can be used by the other client programs to authenticate against the server, without
+    the user having to enter the credentials each time, until the token expires.
 
-There are also [`WebTunnelAgentLib`](WebTunnel/WebTunnelAgentLib/README.md) and 
-[`WebTunnelClientLib`](WebTunnel/WebTunnelClientLib/README.md), which provide the functionality of 
+There are also [`WebTunnelAgentLib`](WebTunnel/WebTunnelAgentLib/README.md) and
+[`WebTunnelClientLib`](WebTunnel/WebTunnelClientLib/README.md), which provide the functionality of
 `WebTunnelAgent` and `remote-client`, respetively, in a C API, suitable for integration into applications (not written in C++).
 
-The macchina.io REMOTE SDK, like the [POCO C++ Libraries](https://github.com/pocoproject/poco) the SDK is based on, 
+The macchina.io REMOTE SDK, like the [POCO C++ Libraries](https://github.com/pocoproject/poco) the SDK is based on,
 is licensed under the [Boost Software License](https://spdx.org/licenses/BSL-1.0).
 
 
@@ -221,7 +225,7 @@ increases their size.
 You should run `xxx-yyy-linux-strip` on the resulting executables to reduce their
 size before deploying them to the device.
 
-NOTE: See [README_iOS.md](README_iOS.md) for iOS builds 
+NOTE: See [README_iOS.md](README_iOS.md) for iOS builds
 and [README_Android.md](README_Android.md) for Android builds.
 
 ### Installing

WebTunnel/WebTunnelClient/README.md

@@ -35,9 +35,9 @@ programs for specific protocols:
 `remote-client` usually does not need a configuration file, most parameters can be passed
 via command-line arguments. Some settings can be set using a configuration file
 (see the `WebTunnelAgent` [documentation](../WebTunnelAgent/README.md#configuration-file-format) for more
-information on configuration files). Also, see the [Configuration](#configuration) section below. 
+information on configuration files). Also, see the [Configuration](#configuration) section below.
 
-At startup, `remote-client` will look for a configuration file `.remote-client.properties` 
+At startup, `remote-client` will look for a configuration file `.remote-client.properties`
 in the current user's home directory, and read it if it's present.
 
 To run `remote-client`, you'll need to specify the URL of the remote device to connect
@@ -102,7 +102,7 @@ or `/help` on Windows) to see a help screen with available command-line options.
 In some environments it may be required to connect to the macchina.io REMOTE server
 via a HTTP proxy. This can be done by providing the address of the proxy server
 on the command-line (`--proxy`, `-P` for short, or `/proxy` on Windows), or by providing the
-proxy server and optionally credentials for the proxy server in a configuration file 
+proxy server and optionally credentials for the proxy server in a configuration file
 (see below).
 
 Below is an example for specifying a proxy server on the command-line:
@@ -132,11 +132,12 @@ The following settings can be provided via a configuration file:
   - `remote.username`: The username for the macchina.io REMOTE server.
   - `remote.password`: The password for the macchina.io REMOTE server.
   - `remote.token`: A token (JSON Web Token) for authenticating against the macchina.io REMOTE server.
-    If a token is given, username and password are not required. NOTE: A token is supported
-    by `remote-client` only, not any of the other client programs like `remote-ssh`.
+    If a token is given, username and password are not required. The `remote-login` program
+    will create a configuration file containing the token, which is read by all
+    client applications.
 
-Credentials specified in command-line arguments or via environment variables 
-(`REMOTE_USERNAME`, `REMOTE_PASSWORD`) will override those in a configuration file.
+Credentials specified in command-line arguments or via environment variables
+(`REMOTE_USERNAME`, `REMOTE_PASSWORD`, `REMOTE_TOKEN`) will override those in a configuration file.
 
 When storing credentials in the configuration file, make sure to keep your configuration
 file secure. From a security perspective it's recommended to not store the credentials

WebTunnel/WebTunnelLogin/README.md

@@ -0,0 +1,78 @@
+# macchina.io REMOTE Login (remote-login)
+
+`remote-login` is a command-line program that obtains an OAuth 2.0 token (JWT) from
+the macchina.io REMOTE server. The program will ask the user for their
+username and password (unless these are provided via command-line parameters).
+
+The program then uses the macchina.io REMOTE server API to request a token,
+using the given credentials. If the user has two-factor authentication enabled
+on the server, the program will also ask for a time-based one-time password (TOTP),
+typically provided by an authenticator app like Authy or Google Authenticator.
+
+The received token will then be stored in the file `.remote-credentials.properties`
+in the user's home directory. If present, this file will be read by all macchina.io REMOTE
+client programs (`remote-client`, `remote-ssh`, etc.) on startup, and the stored
+token will be used for authentication against the macchina.io REMOTE server.
+
+The main advantage of `remote-login` over using environment variables or
+configuration files to store the credentials is that only the token is
+stored on the local machine. The token has a limited validity, typically
+24 hours, but depending on the macchina.io REMOTE server configuration.
+
+## Running remote-login
+
+`remote-login` usually does not need a configuration file, any parameters can be passed
+via command-line arguments. Some settings can be set using a configuration file
+(see the `remote-client` [documentation](../WebTunnelClient/README.md) for more
+information on configuration files).
+
+At startup, `remote-login` will look for a configuration file named
+`.remote-login.properties`  in the current user's home directory, and read it if it's present.
+
+To request a token, run `remote-login` without parameters. The program will ask
+for a username and password, and, if two-factor authentication has been enabled for
+the user, will also ask for a time-based one-time password.
+
+If no further command-line parameters or configuration files are given, `remote-login`
+will use https://remote.macchina.io to obtain the token. To use a different server,
+specify the `--reflector-uri` command-line parameter, e.g.:
+
+```
+remote-login --reflector-uri=https://remote.company.com
+```
+
+Alternatively, you can create a configuration file
+(`.remote-login.properties` in the home directory) containing:
+
+```
+remote.reflectorURI = https://remote.company.com
+```
+
+To check the validity of an existing token, run:
+
+```
+remote-login --status
+```
+
+To clear the token (and delete the `.remote-credentials.properties` file), run:
+
+```
+remote-login --clear
+``
+
+## Configuration
+
+### Command-Line Arguments Help
+
+You can run `remote-ssh` without command-line options (or with `--help`
+or `/help` on Windows) to see a help screen with available command-line options.
+
+### SSL/TLS Configuration
+
+Please refer to the [`WebTunnelAgent`](../WebTunnelAgent/README.md#ssltls-configuration)
+documentation for SSL/TLS configuration settings.
+
+### HTTP Proxy Configuration
+
+Please refer to the [`WebTunnelAgent`](../WebTunnelAgent/README.md#http-configuration)
+documentation for configuring a HTTP proxy, including proxy credentials.