diff options
Diffstat (limited to 'doc/webid-oidc.texi')
-rw-r--r-- | doc/webid-oidc.texi | 102 |
1 files changed, 102 insertions, 0 deletions
diff --git a/doc/webid-oidc.texi b/doc/webid-oidc.texi index 70df6d4..c9c164a 100644 --- a/doc/webid-oidc.texi +++ b/doc/webid-oidc.texi @@ -118,11 +118,77 @@ are @emph{strings}, but we hope that in the future SRFI-180 will be more closely respected. @menu +* The ID token:: * The access token:: * The DPoP proof:: * Generic JWTs:: @end menu +@node The ID token +@section The ID token + +The ID token is a special JWT that the application keeps for +itself. It is signed by the identity provider, and contains the +following claims: + +@table @emph +@item webid +the URI of the user’s webid; +@item iss +the URI of the identity provider (issuer); +@item sub +the username (the webid-oidc issuer puts the webid again here, but it +could be any string); +@item aud +the ID of the client application that is intended to receive the ID +token; +@item nonce +some random data to change the signature; +@item exp +an UTC time (in seconds) for when the token expires; +@item iat +the time when it was issued. +@end table + +There are functions to work with ID tokens in +@emph{(webid-oidc oidc-id-token)}. + +@deffn function id-token? @var{object} +Check that @var{object} is a decoded ID token. +@end deffn + +The following helper functions convert URIs to the URIs from +@emph{(web uri)} and times to @emph{(srfi srfi-19)} dates. + +@deffn function id-token-webid @var{token} +@deffnx function id-token-iss @var{token} +@deffnx function id-token-sub @var{token} +@deffnx function id-token-aud @var{token} +@deffnx function id-token-nonce @var{token} +@deffnx function id-token-exp @var{token} +@deffnx function id-token-iat @var{token} +Get the suitable field from the payload of @var{token}. +@end deffn + +ID tokens can be signed and encoded as a string, or decoded. + +@deffn function id-token-decode @var{token} @var{[#http-get]} +Decode @var{token}, as a string, into a decoded 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)}. Return +@code{#f} if it failed, or the decoded token otherwise. +@end deffn + +@deffn function id-token-encode @var{token} @var{key} +Encode @var{token} and sign it with the issuer’s @var{key}. +@end deffn + +@deffn function issue-id-token @var{issuer-key} @var{#alg} @var{#webid} @var{#iss} @var{#sub} @var{#aud} @var{#exp} @var{#iat} +Create an ID token, and encode it with @var{issuer-key}. +@end deffn + @node The access token @section The access token @@ -400,6 +466,22 @@ The @var{value} of the typ field in the DPoP proof header is incorrect. @end deftp +@deftp {exception type} &incorrect-sub-field @var{value} +The @var{value} of the sub field is incorrect. +@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-nonce-field @var{value} +The @var{value} of the nonce field in the DPoP proof is incorrect. +@end deftp + +@deftp {exception type} &incorrect-htm-field @var{value} +The @var{value} of the htm field in the DPoP proof is incorrect. +@end deftp + @deftp {exception type} ¬-a-client-manifest @var{value} @var{cause} The @var{client-manifest} is incorrect. @end deftp @@ -533,6 +615,26 @@ code. The @var{authorization-code} cannot be signed. @end deftp +@deftp {exception type} ¬-an-id-token @var{value} @var{cause} +The @var{value} is not an ID token. +@end deftp + +@deftp {exception type} ¬-an-id-token-header @var{value} @var{cause} +The @var{value} is not an ID token header. +@end deftp + +@deftp {exception type} ¬-an-id-token-payload @var{value} @var{cause} +The @var{value} is not an ID token payload. +@end deftp + +@deftp {exception type} &cannot-decode-id-token @var{value} @var{cause} +The @var{value} string is not an encoding of a valid ID token. +@end deftp + +@deftp {exception type} &cannot-encode-id-token @var{id-token} @var{key} @var{cause} +The @var{id-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 |