From 68221cd57d155c33a207cc89ced90b48ef5b1699 Mon Sep 17 00:00:00 2001 From: Vivien Kraus Date: Sun, 18 Apr 2021 19:27:50 +0200 Subject: Negociate a token (client) --- doc/webid-oidc.texi | 119 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 119 insertions(+) (limited to 'doc') 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 -- cgit v1.2.3