Negociate a token (client)

1 files changed, 119 insertions, 0 deletions

diff --git a/doc/webid-oidc.texi b/doc/webid-oidc.texi
index dda97bd..55a92d9 100644
--- a/doc/webid-oidc.texi
+++ b/doc/webid-oidc.texi
@@ -51,6 +51,7 @@ Free Documentation License''
 * Caching on server side::
 * Running an Identity Provider::
 * Running a Resource Server::
+* Running a client::
 * Exceptional conditions::
 * GNU Free Documentation License::
 * Index::
@@ -515,6 +516,104 @@ the subject of the access token. If an error happens, it is thrown;
 the function always returns a valid URI.
 @end deffn
 
+@node Running a client
+@chapter Running a client
+
+To run a client, you need to proceed in two steps. First, acquire an
+OIDC ID token and an access token from the identity provider, and then
+present the access token and a proof of possession of the linked key
+in each request, in a DPoP HTTP header.
+
+The first operation is performed by the @emph{(webid-oidc client)}
+module.
+
+@deffn function authorize @var{host/webid} @var{#client-id} @var{#redirect-uri} @var{[#state]} @var{[#http-get]}
+The user enters a valid webid or a host name, and then this function
+will query it (with the @var{http-get} parameter, by default the web
+client from @emph{(web client)}) to determine the authorization
+endpoint. The function will return an alist of authorization URIs,
+indexed by approved identity provider URIs, that the user should
+browse with a traditional web browser.
+
+Each application should have its own webid, or in that case
+@var{client-id}, that can be dereferenced by the identity provider.
+
+Once the user has given authorization, the user’s agent will be
+redirected to @var{redirect-uri}, with the authorization code as a GET
+parameter. It is possible to pass a @var{state}, but this is optional.
+@end deffn
+
+Once the client gets the authorization code, it is necessary to create
+an access token and ID token.
+
+@deffn function token @var{host} @var{client-key} @var{[#authorization-code]} @var{[#refresh-token]} @var{[#http-get]} @var{[#http-post]} @var{[#current-time]}
+Trade an @var{authorization-code}, or a @var{refresh-token}, for an ID
+token and an access token bound to the @var{client-key} issued by
+@var{host}, the identity provider.
+
+You can override the HTTP client used (@var{http-get} and
+@var{http-post}), and how to compute the time (@var{current-time}).
+@end deffn
+
+In an application, you would have a list of profiles in XDG_DATA_HOME,
+consisting of triples (webid, issuer, refresh token).
+
+@deffn function list-profiles @var{[#dir]}
+Read the list of available profiles. Returns a list of triples, webid,
+issuer, reresh token.
+
+By default, this function will look for the profiles file in
+@var{XDG_DATA_HOME}. You can bypass it by providing the @var{#dir}
+optional keyword argument.
+@end deffn
+
+@deffn function setup @var{get-host/webid} @var{choose-provider} @var{browse-authorization-uri} @var{#client-id} @var{#redirect-uri} @var{[#dir]} @var{[#http-get]} @var{[#http-post]} @var{[#current-time]}
+Negociate a refresh token, and save it. The function returns 3 values:
+the decoded ID token pyload, the encoded access token and the key
+pair.
+
+The @var{get-host/webid} thunk should ask the user’s webid or identity
+provider, and return it. @var{choose-provider} is called with a list
+of possible identity providers as host names (strings), and the user
+should choose one. The chosen one is returned. Finally,
+@var{browse-authorization-uri} should ask or let the user browse an
+URI as its argument, and return the authorization code taken from the
+redirect URI.
+
+The refresh token is saved to disk, as a profile, in
+XDG_DATA_HOME. Pass the optional @var{#dir} keyword argument to
+override the location.
+
+You need to set @var{client-id} to the public webid of the app, and
+@var{redirect-uri} to one of the approved redirection URIs for the
+application ID.
+@end deffn
+
+@deffn function login @var{webid} @var{issuer} @var{refresh-token} @var{key} @var{[#dir]} @var{[#http-get]} @var{[#http-post]} @var{[#current-time]}
+If you have already a known profile, you can use it to automatically
+log in. This function might update the refresh token if it changed, so
+you can again set @var{#dir}. Please note that the @var{refresh-token}
+is bound to the client @var{key} on server side, so you must always
+use the same @var{key}.
+@end deffn
+
+@deffn function refresh @var{id-token} @var{key} @var{[#dir]} @var{[#http-get]} @var{[#http-post]} @var{[#current-time]}
+If you have an ID token bound to a known profile, this helper function
+will look up the associated refresh token and log in.
+@end deffn
+
+@deffn function make-client @var{id-token} @var{access-token} @var{key} @var{[#dir]} @var{[#http-get]} @var{[#http-post]} @var{[#http-request]} @var{[#current-time]}
+Return a replacement of @code{http-request} from @emph{(web client)},
+that automatically signs requests and refresh the tokens when needed.
+
+@var{#http-get} and @var{#http-post} are only used to refresh the
+tokens, while @var{#http-request} is used as a back-end for the
+requests.
+
+@var{#current-time} is set to a thunk that returns the time. It is
+used to issue DPoP proofs.
+@end deffn
+
 @node Exceptional conditions
 @chapter Exceptional conditions
 
@@ -913,6 +1012,26 @@ The token request forgot to put a refresh token with the request.
 provider.
 @end deftp
 
+@deftp {exception type} &no-provider-candidates @var{webid} @var{causes}
+The @var{webid} cannot be certified by any identity providers. The
+@var{causes} alist indicates an error for each candidates.
+@end deftp
+
+@deftp {exception type} &neither-identity-provider-nor-webid @var{uri} @var{why-not-identity-provider} @var{why-not-webid}
+The @var{uri} you passed to get an authorization code is neither an
+identity provider (because @var{why-not-identity-provider}) nor a
+webid (because @var{why-not-webid}).
+@end deftp
+
+@deftp {exception type} &token-request-failed @var{cause}
+The token request failed on the server.
+@end deftp
+
+@deftp {exception type} &profile-not-found @var{webid} @var{iss} @var{dir}
+The @var{webid}, as certified by @var{iss}, cannot be refreshed
+because we don’t have a refresh token stored in @var{dir}.
+@end deftp
+
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License