From 8c89e88577dd2da79559f03a901339013da1e162 Mon Sep 17 00:00:00 2001 From: Vivien Kraus Date: Tue, 27 Jul 2021 15:05:13 +0200 Subject: Rework --help output --- doc/webid-oidc.texi | 131 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 131 insertions(+) (limited to 'doc') 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 -- cgit v1.2.3