Run the identity provider as a script

1 files changed, 67 insertions, 0 deletions

diff --git a/doc/webid-oidc.texi b/doc/webid-oidc.texi
index a33da87..edea16d 100644
--- a/doc/webid-oidc.texi
+++ b/doc/webid-oidc.texi
@@ -49,6 +49,7 @@ Free Documentation License''
 * Decentralized Authentication on the Web::
 * The Json Web Token::
 * Caching on server side::
+* Running an Identity Provider::
 * Exceptional conditions::
 * GNU Free Documentation License::
 * Index::
@@ -366,6 +367,72 @@ The back-end function, @var{http-get}, defaults to that of
 @emph{(web client)}.
 @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-issuer} program,
+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{-i @var{URI}}, or @code{--issuer=@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 Exceptional conditions
 @chapter Exceptional conditions