diff options
Diffstat (limited to 'doc/manual.html')
| -rw-r--r-- | doc/manual.html | 141 |
1 files changed, 139 insertions, 2 deletions
diff --git a/doc/manual.html b/doc/manual.html index 7afe80f..e3e9cbe 100644 --- a/doc/manual.html +++ b/doc/manual.html @@ -114,6 +114,70 @@ <emph>strings</emph>, but we hope that in the future SRFI-180 will be more closely respected. </p> + <h2>The access token</h2> + <p> + The access token is obtained by the client through a token + request, and is presented to the server on each authenticated + request. It is signed by the identity provider, and it contains + enough information so that the server knows who the user is and + who the agent is, and most importantly the fingerprint of the + key that the client should use in a DPoP proof. + </p> + <p> + The API is defined in + <emph>(webid-oidc access-token)</emph>. + </p> + <info:deffn type="function" name="access-token?" arguments="object"> + <p> + Check that <info:var>object</info:var> is a decoded access token. + </p> + </info:deffn> + <p> + There are field getters for the access token: + </p> + <info:deffn type="function" name="access-token-webid" arguments="token"> + <info:deffnx type="function" name="access-token-iss" arguments="token" /> + <info:deffnx type="function" name="access-token-aud" arguments="token" /> + <info:deffnx type="function" name="access-token-exp" arguments="token" /> + <info:deffnx type="function" name="access-token-iat" arguments="token" /> + <info:deffnx type="function" name="access-token-cnf/jkt" arguments="token" /> + <info:deffnx type="function" name="access-token-client-id" arguments="token" /> + <p> + Get the suitable field from the payload + of <info:var>token</info:var>. + </p> + </info:deffn> + <p> + Access tokens can be signed and encoded as a string, or decoded. + </p> + <info:deffn type="function" name="access-token-decode" arguments="token [#http-get]"> + <p> + Decode <info:var>token</info:var>, as a string, into a decoded + token. As with the ID token, the signature verification will + need to fetch the oidc configuration of the claimed issuer, + and check the signature against the published keys. The + <pre>http-get</pre> optional keyword argument can set a + different implementation of <pre>http-get</pre> from + <emph>(web client)</emph>, for instance to re-use the + what has been obtained by the ID token validation. Return + <pre>#f</pre> if it failed, or the decoded token otherwise. + </p> + </info:deffn> + <info:deffn type="function" name="access-token-encode" arguments="token key"> + <p> + Encode <info:var>token</info:var> and sign it with the + issuer’s <info:var>key</info:var>. + </p> + </info:deffn> + <info:deffn type="function" name="issue-access-token" arguments="issuer-key #alg #webid #iss #exp #iat [#client-key | #cnf/jkt] #client-id "> + <p> + Create an access token, and encode it with + <info:var>issuer-key</info:var>. You can either set the + <pre>#:cnf/jkt</pre> keyword argument with the fingerprint of + the client key, or set <pre>#:client-key</pre> directly, in + which case the fingerprint will be computed for you. + </p> + </info:deffn> <h2>Generic JWTs</h2> <p> You can parse generic JWTs signed with JWS with the following @@ -327,8 +391,81 @@ </info:deftp> <info:deftp type="exception type" name="&not-an-oidc-configuration" arguments="value cause"> <p> - The <info:var>value</info:var> is not appropriate an OIDC - configuration. + The <info:var>value</info:var> is not an OIDC configuration. + </p> + </info:deftp> + <info:deftp type="exception type" name="&incorrect-webid-field" arguments="value"> + <p> + The <info:var>value</info:var> of the webid field in the JWT + is missing (if <pre>#f</pre>), or not an acceptable value. + </p> + </info:deftp> + <info:deftp type="exception type" name="&incorrect-iss-field" arguments="value"> + <p> + The <info:var>value</info:var> of the iss field is incorrect. + </p> + </info:deftp> + <info:deftp type="exception type" name="&incorrect-aud-field" arguments="value"> + <p> + The <info:var>value</info:var> of the aud field is incorrect. + </p> + </info:deftp> + <info:deftp type="exception type" name="&incorrect-iat-field" arguments="value"> + <p> + The <info:var>value</info:var> of the iat field is incorrect. + </p> + </info:deftp> + <info:deftp type="exception type" name="&incorrect-exp-field" arguments="value"> + <p> + The <info:var>value</info:var> of the exp field is incorrect. + </p> + </info:deftp> + <info:deftp type="exception type" name="&incorrect-cnf/jkt-field" arguments="value"> + <p> + The <info:var>value</info:var> of the cnf/jkt field is incorrect. + </p> + </info:deftp> + <info:deftp type="exception type" name="&incorrect-client-id-field" arguments="value"> + <p> + The <info:var>value</info:var> of the client-id field is incorrect. + </p> + </info:deftp> + <info:deftp type="exception type" name="&not-an-access-token" arguments="value cause"> + <p> + The <info:var>value</info:var> is not an access token. + </p> + </info:deftp> + <info:deftp type="exception type" name="&not-an-access-token-header" arguments="value cause"> + <p> + The <info:var>value</info:var> is not an access token header. + </p> + </info:deftp> + <info:deftp type="exception type" name="&not-an-access-token-payload" arguments="value cause"> + <p> + The <info:var>value</info:var> is not an access token payload. + </p> + </info:deftp> + <info:deftp type="exception type" name="&cannot-fetch-issuer-configuration" arguments="issuer cause"> + <p> + It is impossible to fetch the configuration of + <info:var>issuer</info:var>. + </p> + </info:deftp> + <info:deftp type="exception type" name="&cannot-fetch-jwks" arguments="issuer uri cause"> + <p> + It is impossible to fetch the keys of + <info:var>issuer</info:var> at <info:var>uri</info:var>. + </p> + </info:deftp> + <info:deftp type="exception type" name="&cannot-decode-access-token" arguments="value cause"> + <p> + The <info:var>value</info:var> string is not an encoding of a + valid access token. + </p> + </info:deftp> + <info:deftp type="exception type" name="&cannot-encode-access-token" arguments="access-token key cause"> + <p> + The <info:var>access-token</info:var> cannot be signed. </p> </info:deftp> |