From b3f41c0fa861a668c054bdce92c8fb86707a784c Mon Sep 17 00:00:00 2001 From: Vivien Kraus Date: Tue, 27 Apr 2021 14:07:10 +0200 Subject: Define the access token API --- doc/webid-oidc.texi | 111 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 110 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/webid-oidc.texi b/doc/webid-oidc.texi index 8d2d638..27295e0 100644 --- a/doc/webid-oidc.texi +++ b/doc/webid-oidc.texi @@ -118,9 +118,62 @@ are @emph{strings}, but we hope that in the future SRFI-180 will be more closely respected. @menu +* The access token:: * Generic JWTs:: @end menu +@node The access token +@section The access token + +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. + +The API is defined in @emph{(webid-oidc access-token)}. + +@deffn function access-token? @var{object} +Check that @var{object} is a decoded access token. +@end deffn + +There are field getters for the access token: + +@deffn function access-token-webid @var{token} +@deffnx function access-token-iss @var{token} +@deffnx function access-token-aud @var{token} +@deffnx function access-token-exp @var{token} +@deffnx function access-token-iat @var{token} +@deffnx function access-token-cnf/jkt @var{token} +@deffnx function access-token-client-id @var{token} +Get the suitable field from the payload of @var{token}. +@end deffn + +Access tokens can be signed and encoded as a string, or decoded. + +@deffn function access-token-decode @var{token} @var{[#http-get]} +Decode @var{token}, 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 @code{http-get} optional keyword argument can +set a different implementation of @code{http-get} from +@emph{(web client)}, for instance to re-use the what has been obtained +by the ID token validation. Return @code{#f} if it failed, or the +decoded token otherwise. +@end deffn + +@deffn function access-token-encode @var{token} @var{key} +Encode @var{token} and sign it with the issuer’s @var{key}. +@end deffn + +@deffn function issue-access-token @var{issuer-key} @var{#alg} @var{#webid} @var{#iss} @var{#exp} @var{#iat} @var{[#client-key} @var{|} @var{#cnf/jkt]} @var{#client-id} +Create an access token, and encode it with @var{issuer-key}. You can +either set the @code{#:cnf/jkt} keyword argument with the fingerprint +of the client key, or set @code{#:client-key} directly, in which case +the fingerprint will be computed for you. +@end deffn + @node Generic JWTs @section Generic JWTs @@ -218,13 +271,41 @@ failed. @var{value} is the incorrect input, and @var{cause} is a low-level error. @end deftp +@deftp {exception type} &incorrect-webid-field @var{value} +The @var{value} of the webid field in the JWT is missing (if +@code{#f}), or not an acceptable value. +@end deftp + +@deftp {exception type} &incorrect-iss-field @var{value} +The @var{value} of the iss field is incorrect. +@end deftp + +@deftp {exception type} &incorrect-aud-field @var{value} +The @var{value} of the aud field is incorrect. +@end deftp + +@deftp {exception type} &incorrect-iat-field @var{value} +The @var{value} of the iat field is incorrect. +@end deftp + +@deftp {exception type} &incorrect-exp-field @var{value} +The @var{value} of the exp field is incorrect. +@end deftp + +@deftp {exception type} &incorrect-cnf/jkt-field @var{value} +The @var{value} of the cnf/jkt field is incorrect. +@end deftp + +@deftp {exception type} &incorrect-client-id-field @var{value} +The @var{value} of the client-id field is incorrect. +@end deftp + @node Invalid JWT @section Invalid JWT Each JWT type – access token, DPoP proof, ID token, authorization code (this is internal to the identity provider) has different validation rules, and can fail in different ways. - @deftp {exception type} ¬-json @var{value} @var{cause} Cannot decode @var{value} to a JSON object. @end deftp @@ -291,6 +372,26 @@ The @var{value} string is not an encoding of a valid JWS. The @var{jws} cannot be signed. @end deftp +@deftp {exception type} ¬-an-access-token @var{value} @var{cause} +The @var{value} is not an access token. +@end deftp + +@deftp {exception type} ¬-an-access-token-header @var{value} @var{cause} +The @var{value} is not an access token header. +@end deftp + +@deftp {exception type} ¬-an-access-token-payload @var{value} @var{cause} +The @var{value} is not an access token payload. +@end deftp + +@deftp {exception type} &cannot-decode-access-token @var{value} @var{cause} +The @var{value} string is not an encoding of a valid access token. +@end deftp + +@deftp {exception type} &cannot-encode-access-token @var{access-token} @var{key} @var{cause} +The @var{access-token} cannot be signed. +@end deftp + @node Cannot fetch data on the web @section Cannot fetch data on the web In the client (local and public parts), resource server and identity @@ -314,6 +415,14 @@ The @var{response} (from @emph{(web response)}) is not appropriate. The @var{value} is not appropriate an OIDC configuration. @end deftp +@deftp {exception type} &cannot-fetch-issuer-configuration @var{issuer} @var{cause} +It is impossible to fetch the configuration of @var{issuer}. +@end deftp + +@deftp {exception type} &cannot-fetch-jwks @var{issuer} @var{uri} @var{cause} +It is impossible to fetch the keys of @var{issuer} at @var{uri}. +@end deftp + @node GNU Free Documentation License @appendix GNU Free Documentation License -- cgit v1.2.3