diff options
Diffstat (limited to 'doc/manual.html')
| -rw-r--r-- | doc/manual.html | 54 |
1 files changed, 54 insertions, 0 deletions
diff --git a/doc/manual.html b/doc/manual.html index 51d524b..d010685 100644 --- a/doc/manual.html +++ b/doc/manual.html @@ -981,6 +981,60 @@ generator. You can safely delete this directory, but you need to restart the program to actually change the seed. </p> + <h1>Running a Resource Server</h1> + <p> + 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. + </p> + <h2>The authenticator</h2> + <p> + In <emph>(webid-oidc jws)</emph>, the following function + gives a simple API for a web server: + </p> + <info:deffn type="function" + name="make-authenticator" + arguments="jti-list [#server-uri] [#current-time] [#http-get]"> + <p> + Create an authenticator, i.e. a function that takes a request + and request body and returns the webid of the authenticated + user, or <pre>#f</pre> if it is not authenticated. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + The JTIs are checked within a small time frame. By default, + the system time will be used. Otherwise, you can customize the + <pre>current-time</pre> optional keyword argument, to pass a + thunk returning a time from <emph>(srfi srfi-19)</emph>. + </p> + <p> + You may want to customize the <info:var>http-get</info:var> + optional keyword argument to pass a function to replace + <pre>http-get</pre> from <emph>(http client)</emph>. This + function takes an URI and optional <pre>#:headers</pre> + arguments, makes the request, and return two values: the + response, and the response body. + </p> + <p> + This function, in + <emph>(webid-oidc resource-server)</emph>, 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. + </p> + </info:deffn> <h1 type="appendix">GNU Free Documentation License</h1> <info:gfdl /> |