Rework --help output

1 files changed, 131 insertions, 0 deletions

diff --git a/doc/webid-oidc.texi b/doc/webid-oidc.texi
index 2ad0ca8..e7df400 100644
--- a/doc/webid-oidc.texi
+++ b/doc/webid-oidc.texi
@@ -47,6 +47,7 @@ Free Documentation License''
 
 @menu
 * Decentralized Authentication on the Web::
+* Invoking webid-oidc::
 * The Json Web Token::
 * Caching on server side::
 * Content negociation::
@@ -99,6 +100,136 @@ well-established OpenID Connect. It is intended to work in a web
 browser, but this package demonstrates that it also works without a
 web browser.
 
+@node Invoking webid-oidc
+@chapter Invoking webid-oidc
+
+The @samp{webid-oidc} program provides different modes of operations:
+
+@table @samp
+@item reverse-proxy
+Run an authenticating reverse proxy. With this command, you specify a
+backend server. When an authenticated user makes a request, you
+receive an additional header containing the user’s identity.
+@item identity-provider
+Run the identity provider only.
+@item client-service
+The client applications must serve some resources: namely, the client
+manifest and the redirect URI.
+@item server
+Run both an identity provider and a resource server.
+@end table
+
+The server is configured with command-line arguments, and environment
+variables.
+
+@menu
+* General options::
+* General server configuration::
+* Configuration for the resource server::
+* Configuration for the identity provider::
+* Configuration for the client service::
+@end menu
+
+@node General options
+@section General options
+The server will respond to @samp{-h} and @samp{-v} commands, to get
+the help output and the version information.
+
+The server output (command-line, logs) are localized for the system
+administrator. You can control it with the @samp{LANG} environment
+variable. So if your locale is not English, you can have the same
+commands as in this manual by running with @code{LANG=C}.
+
+The programs respect the @samp{XDG_DATA_HOME} and
+@samp{XDG_CACHE_HOME} to store persistent data and disposable
+data. The cache directory can be deleted at any time. If one of these
+variables is not set, its value is computed from the @samp{HOME}
+environment variable.
+
+@node General server configuration
+@section General server configuration
+All servers are published under the Affero GPL, which means that the
+service provider needs to publish all changes made to the program to
+users over the network. The @samp{webid-oidc} command provides a
+@samp{--complete-corresponding-source} option so that the system
+administrator can specify a means to download the source.
+
+The servers will add a @samp{Source:} header in each response,
+containing the value of this configuration option.
+
+The servers can be configured to redirect output and errors to a log
+file and an error file, with the @samp{--log-file} and
+@samp{--error-file} options.
+
+The server will listen to port 8080 by default, but this may be
+configured with @samp{--port}. Since the servers do not support TLS,
+and they only support HTTP/1.1, they are intended to run behind a
+reverse proxy (even for the authenticating reverse proxy).
+
+Finally, the servers are required to know their public name. This is
+configured with the @samp{--server-name} option.
+
+The server will make requests on the world-wide web, for instance to
+download client manifests. The requests can be redirected with XML
+Catalog, by setting the @samp{XML_CATALOG_FILES} to a space-separated
+list of URIs (can be @code{file:} URIs). The requests cannot be
+directed to the file system.
+
+@node Configuration for the resource server
+@section Configuration for the resource server
+The reverse proxy sets an identity header to authenticated
+requests. By default, it is @samp{XXX-Agent}, but it can be configured
+with @samp{--header}.
+
+The reverse proxy is configured to contact a backend URI with
+@samp{--backend-uri}. This backend URI should not be directly exposed,
+because a malicious user could set the identity header.
+
+@node Configuration for the identity provider
+@section Configuration for the identity provider
+The identity provider can only handle one user. If you want to handle
+multiple users, it is highly advised to use a different host name for
+each user, in case the server is accessed from a web browser. You can
+set the identity of the user with @samp{--subject}, and the user’s
+password with @samp{--encrypted-password}.
+
+The encrypted password format is defined by the crypt function in the
+C library. For glibc, it looks like this:
+@code{$@var{N}$@var{salt}$@var{hash}}, where @var{N} is the algorithm
+identifier, @var{salt} is the password salt annd @var{hash} is its
+hash.
+
+The server uses a key, which is not the same thing as the TLS
+certificate of the server (remember, the servers don’t support
+TLS). It is in the JWK format. You set its file name with
+@samp{--key-file}. If the key file does not exist, it will be
+generated.
+
+Finally, the public openid configuration requires you to set the JWKS
+URI (@samp{--jwks-uri}), authorization endpoint URI
+(@samp{--authorization-endpoint-uri}) and token endpoint URI
+(@samp{--token-endpoint-uri}). The identity provider will publish the
+full URIs, but will respond to their path, regardless of the host.
+
+@node Configuration for the client service
+@section Configuration for the client service
+The client will serve a stupid page for the redirect URI that will
+only display the authorization code. The redirect URI is set with
+@samp{--redirect-uri}.
+
+The client ID is set with @samp{--client-id}. This is the URI under
+which the client registrationn is served.
+
+Finally, you can set some cosmetic options, but since it can confuse
+the user, they are hidden by default by the identity provider.
+
+@table @samp
+@item --client-name
+set the name of the application.
+@item --client-uri
+set an URI where to find more information about the client.
+@end table
+
 @node The Json Web Token
 @chapter The Json Web Token