diff options
Diffstat (limited to 'doc/disfluid.texi')
| -rw-r--r-- | doc/disfluid.texi | 314 |
1 files changed, 71 insertions, 243 deletions
diff --git a/doc/disfluid.texi b/doc/disfluid.texi index 7e47022..3e6c91c 100644 --- a/doc/disfluid.texi +++ b/doc/disfluid.texi @@ -74,8 +74,7 @@ A PDF version of this manual is available at * The HTTP Link header:: * Content negociation:: * Server endpoints:: -* Running an Identity Provider:: -* Running a Resource Server:: +* Resources stored on the server:: * Running a client:: * Serialization to (S)XML:: * Exceptional conditions:: @@ -127,31 +126,12 @@ web browser. @node Invoking disfluid @chapter Invoking disfluid -The @samp{disfluid} 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. +The @samp{disfluid} program runs a server, if the user specifies a +configuration file, or the graphical browser otherwise. @menu * General options:: -* General server configuration:: -* Configuration for the resource server:: -* Configuration for the identity provider:: -* Configuration for the client service:: +* Running a server:: @end menu @node General options @@ -164,22 +144,23 @@ 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{disfluid} command provides a +The programs respect the @samp{XDG_DATA_HOME} (if not overriden by the +server configuration) 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 Running a server +@section Running a server +The disfluid code is 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{disfluid} 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. +containing the value of this configuration option. It can be, for +instance, an URI where to download the modified source code. The servers can be configured to redirect output and errors to a log file and an error file, with the @samp{--log-file} and @@ -190,8 +171,55 @@ 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. +Finally, you configure the server by passing the +@samp{--configuration} parameter pointing to a configuration file. The +configuration file is plain guile code, that must evaluate to an +@code{<endpoint>}. + +Here is an example configuration that runs a resource server with an +identity provider: + +@lisp +(use-modules (webid-oidc server endpoint) + (webid-oidc server endpoint resource-server) + (webid-oidc server endpoint identity-provider) + (webid-oidc server endpoint authentication) + (webid-oidc oidc-configuration) + (oop goops)) + +(make <identity-provider> + #:host "example.com" + #:oidc-discovery + (make <oidc-discovery> + #:path "/.well-known/openid-configuration" + #:configuration + (make <oidc-configuration> + #:jwks-uri "https://example.com/keys" + #:authorization-endpoint "https://example.com/authorize" + #:token-endpoint "https://example.com/token")) + #:authorization-endpoint + (make <authorization-endpoint> + #:path "/authorize" + #:subject "https://example.com/profile/card#me" + #:encrypted-password (crypt "secretpassword123" "$6$secret.salt") + #:key-file "/var/lib/disfluid/key-file.jwk") + #:token-endpoint + (make <token-endpoint> + #:path "/token" + #:issuer "https://example.com" + #:key-file "/var/lib/disfluid/key-file.jwk") + #:jwks-endpoint + (make <jwks-endpoint> + #:path "/keys" + #:key-file "/var/lib/disfluid/key-file.jwk") + #:default + (make <authenticator> + #:backend + (make <resource-server> + #:server-name "https://example.com" + #:owner "https://example.com/profile/card#me") + #:server-uri "https://example.com")) +@end lisp The server will make requests on the world-wide web, for instance to download client manifests. The requests can be redirected with XML @@ -199,64 +227,6 @@ 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 write the -user’s password in a file. Pass the file name with -@samp{--encrypted-password-file}. You can pass the encrypted password -directly with @samp{--encrypted-password}, but the encrypted password -will be public. - -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 Running disfluid with GNU Guix @chapter Running disfluid with GNU Guix @@ -266,30 +236,17 @@ with guix. It defines the package at the latest commit, and a service definition in @emph{(vkraus services disfluid)}. @defvr {service type} disfluid-service-type -This service runs a bunch of disfluid servers with the @emph{disfluid} -system user, each with a unique name. The value it takes is an alist -of service configurations: the keys are unique names (to differenciate -the generated shepherd services), and the values are configuration -records for an issuer, reverse proxy, server, or client service. +This service runs a disfluid server with the @emph{disfluid} system +user. The value it takes is a service configuration. @end defvr -@deftp {configuration record} <disfluid-issuer-configuration> [@var{disfluid}] @var{complete-corresponding-source} @var{issuer} @var{key-file} @var{subject} @var{encrypted-password-file} @var{jwks-uri} @var{authorization-endpoint-uri} @var{token-endpoint-uri} @var{port} [@var{extra-options}] +@deftp {configuration record} <disfluid-configuration> [@var{disfluid}] @var{complete-corresponding-source} @var{port} @var{configuration-file} [@var{extra-options}] The configuration for the identity provider. The optional @var{disfluid} argument is the package containing the binary to run, if you want to apply some patches, and @var{extra-options} is an empty list by default. -@end deftp - -@deftp {configuration record} <disfluid-reverse-proxy-configuration> [@var{disfluid}] @var{complete-corresponding-source} @var{port} @var{inbound-uri} @var{outbound-uri} @var{header} [@var{extra-options}] -This record configures an authenticating reverse proxy. -@end deftp -@deftp {configuration record} <disfluid-client-service-configuration> [@var{disfluid}] @var{complete-corresponding-source} @var{client-id} @var{redirect-uri} [@var{client-name}] [@var{client-uri}] @var{port} [@var{extra-options}] -This record configures a server to serve public application pages. -@end deftp - -@deftp {configuration record} <disfluid-server-configuration> [@var{disfluid}] @var{complete-corresponding-source} @var{server-name} @var{key-file} @var{subject} @var{encrypted-password-file} @var{jwks-uri} @var{authorization-endpoint-uri} @var{token-endpoint-uri} @var{port} [@var{extra-options}] -The configuration for the full server. +@var{configuration-file} is a file-like object or a file name. @end deftp @node Common parameters @@ -1881,137 +1838,8 @@ Return the directory where @var{resource-server} stores persistent data. @end deffn -@node Running an Identity Provider -@chapter Running an Identity Provider - -This project is packaged with a barebones identity provider. It has an -authorization endpoint and a token endpoint (and it serves its public -keys), but it is only intended for one specific person. - -You can start it by invoking the @code{webid-oidc} program with the -@code{issuer} command, with the following options: - -@table @asis -@item @code{-h}, or @code{--help} -prints a summary of options and exit. -@item @code{-v}, or @code{--version} -prints the version of the program and exits. -@item @code{-n @var{URI}}, or @code{--server-name=@var{URI}} -sets the global server name of the identity provider. It should have -an empty path. -@item @code{-k @var{FILE.jwk}}, or @code{--key-file=@var{FILE.jwk}} -sets the file name where to read or generate a key for the identity -provider. This file should be JSON, containing the representation of a -JWK key pair. -@item @code{-s @var{WEBID}}, or @code{--subject=@var{WEBID}} -sets the webid of the only user of the identity provider. This is an -URI, pointing to a RDF node corresponding to the user’s profile. -@item @code{-w @var{PASSWORD}}, or @code{--password=@var{PASSWORD}} -sets the password that the user must enter to authorize an -application. -@item @code{-j @var{URI}}, or @code{--jwks-uri=@var{URI}} -tells the server that requests to @var{URI} should be responded with -the public key used to sign the tokens. -@item @code{-a @var{URI}}, or @code{--authorization-endpoint-uri=@var{URI}} -tells the server that requests to @var{URI} should be treated as -authorization requests. -@item @code{-t @var{URI}}, or @code{--token-endpoint-uri=@var{URI}} -tells the server that requests to @var{URI} should be treated as token -negociation requests. -@item @code{-p @var{PORT}}, or @code{--port=@var{PORT}} -change the port number used by the server. By default, it is set to -8080. -@item @code{-l @var{FILE.log}}, or @code{--log-file=@var{FILE.log}} -let the server dump all its output to @var{FILE.log}. Since I don’t -know how to deal with syslog, this is the only way to keep logs with a -shepherd service. -@item @code{-e @var{FILE.err}}, or @code{--error-file=@var{FILE.err}} -let the server dump all its errors to @var{FILE.err}. -@end table - -The program is sensitive to the environment variables. The most -important one is @emph{LANG}, which influences how the program is -internationalized to the server administrator (the pages served to the -user use the user agent’s locale). This changes the long form of the -options, and the language in the log files. - -The @emph{XDG_DATA_HOME} should point to some place where the program -will store refresh tokens, under the @code{webid-oidc} directory. For -a system service, you might want to define that environment to -@code{/var/lib}, for instance. - -The @emph{XDG_CACHE_HOME} should point to a directory where to store -the seed of the random number generator (under a @code{webid-oidc} -directory, again). Changing the seed only happens when a program -starts to require the random number generator. You can safely delete -this directory, but you need to restart the program to actually change -the seed. - -@node Running a Resource Server -@chapter Running a Resource Server - -@menu -* The authenticator:: -* The full server:: -* Resources stored on the server:: -@end menu - -A Solid server is the server that manages your data. It needs to check -that the proofs of possession are correct, and the possessed key is -signed by the identity provider. - -@node The authenticator -@section The authenticator - -In @emph{(webid-oidc resource-server)}, the following function gives a -simple API for a web server: - -@deffn function make-authenticator @var{jti-list} @var{[#server-uri]} @var{[#current-time]} @var{[#http-get]} -Create an authenticator, i.e. a function that takes a request and -request body and returns the webid of the authenticated user, or -@code{#f} if it is not authenticated. - -To prevent replay attacks, each request is signed by the client with a -different unique padding value. If such a value has already been seen, -then the request must fail. - -The authenticator expects the client to demonstrate the possession of -a key that the identity provider knows. So the client creates a DPoP -proof, targetted to a specific URI. In order to check that the URI is -correct, the authenticator needs the public URI of the service. - -The JTIs are checked within a small time frame. By default, the system -time will be used. Otherwise, you can customize the -@code{current-time} optional keyword argument, to pass a thunk -returning a time from @emph{(srfi srfi-19)}. - -You may want to customize the @var{http-get} optional keyword argument -to pass a function to replace @code{http-get} from @emph{(http -client)}. This function takes an URI and optional @code{#:headers} -arguments, makes the request, and return two values: the response, and -the response body. - -This function, in @emph{(webid-oidc resource-server)}, returns a web -request handler, taking the request and request body, and returning -the subject of the access token. If an error happens, it is thrown; -the function always returns a valid URI. -@end deffn - -@node The full server -@section The full server - -@deffn {function from @emph{(webid-oidc resource-server)}} make-server @var{[#:server-uri]} @var{[#:owner]} @var{[#:authenticator]} @var{[#:current-time]} @var{[#:http-get]} -Return a server handler, a function taking 2 values, a request and a -request body, and returning 2 values, the response and response body. - -The optional @var{[#:authenticator]} argument defaults to the -webid-oidc authenticator, @var{[#:current-time]} defaults to a thunk -returning the system time and @var{[#:http-get]} to the web client -from @emph{(web client)}. -@end deffn - @node Resources stored on the server -@section Resources stored on the server +@chapter Resources stored on the server To store and serve resources, the server has two distinct mechanisms. A @dfn{content} is a read-only possible value for a |