path: root/doc/webid-oidc.texi

\input texinfo @c -*-texinfo-*-
@comment $Id@w{$}
@documentlanguage en
@comment %**start of header
@include version.texi
@settitle Webid-oidc manual
@syncodeindex pg cp
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex tp cp
@comment %**end of header

@copying
This is the manual of webid-oidc (version @value{VERSION}, @value{UPDATED}), an implementation of the Solid authentication protocol for guile, client and server.

Copyright @copyright{} 2020, 2021 Vivien Kraus
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the section entitled ``GNU
Free Documentation License''
@end quotation
@end copying

@dircategory Software libraries

@direntry
* webid-oidc: (webid-oidc)Decentralized Authentication on the Web.
@end direntry

@titlepage
@title Webid-oidc manual
@subtitle for version @value{VERSION}, @value{UPDATED}
@author Vivien Kraus (@email{vivien@@planete-kraus.eu})
@page
@vskip 0pt plus 1fill
@insertcopying
@end titlepage

@contents
@ifnottex
@node Top
@top Webid-oidc
@end ifnottex

@menu
* Decentralized Authentication on the Web::
* The Json Web Token::
* Exceptional conditions::
* GNU Free Documentation License::
* Index::
@end menu

@node Decentralized Authentication on the Web
@chapter Decentralized Authentication on the Web

Authentication on the web is currently handled in the following way:
anyone can install a server that will authenticate users on the
web. The problem is interoperability. If a client (an application)
wants to authenticate a user, it has to be approved by the
authentication server. In other words, if @var{useful-program} wants
to authenticate @var{MegaCorp} users, then @var{useful-program} has to
register to @var{MegaCorp} first, and get approved. This goes against
the principle of permission-less innovation, which is at the heart of
the web.

In the decentralized authentication web, the best attempt so far is
that of ActivityPub. All servers are interoperable with respect to
authentication: if user A emits an activity, it is forwarded by A's
server to its recipients, and A's server is responsible for A's
identity.

The problem with that approach is that the data is tied to the
application. It is not possible to use another application to process
the data differently, or to use multiple data sources, in an
interoperable way (without the ActivityPub server knowing). This means
that on Activitypub, microblogging applications will not present
different activities correctly. This also means that it is difficult
to write a free replacement to a non-free application program, because
it would need to manage the data.

In the Solid ecosystem, there is a clear distinction between servers
and applications. An application is free to read data from all places
at the same time, using a permission-less authentication system. Since
the applications do not need to store data, the cost of having users
is neglectible, so users do not need prior approval before using them
(making captchas and the like a thing of the past). Servers do not
have a say in which applications the user uses.

The authentication used is a slight modification of the
well-established OpenID Connect. It is intended to work in a web
browser, but this package demonstrates that it also works without a
web browser.

@node The Json Web Token
@chapter The Json Web Token

The Json Web Token, or @dfn{JWT}, is a terse representation of a pair
of JSON objects: the @dfn{header}, and the @dfn{payload}. The JWT can
be @dfn{encoded} as a Json Web Signature (@dfn{JWS}), in which case
the header is encoded to base64 with the URL alphabet, and without
padding characters, the payload is also encoded to base64, and the
concatenation of the encoding of the header, a dot, and the encoding
of the payload is signed with some cryptography algorithm. In the
following, we will only be interested by public-key cryptography. The
concatenation of header, dot, payload, dot and signature in base64 is
the encoding of the JWT.

@node Exceptional conditions
@chapter Exceptional conditions

The library will raise an exception whenever something fishy
occurs. For instance, if a signature is invalid, or the expiration
date has passed. All exception types are defined in
@code{(webid-oidc errors)}.

@deffn function error->str @var{error} @var{[#depth]}
Return a string explaining the @var{error}. You can limit the
@var{depth} of the explanation as an integer.
@end deffn

@menu
* Invalid data format::
* Invalid JWT::
@end menu

@node Invalid data format
@section Invalid data format
There are a few JSON objects with required fields. This exceptions
usually occur as the cause of a higher-level exception.

@deftp {exception type} &not-base64 @var{value} @var{cause}
This exception is raised when the base64 decoding function
failed. @var{value} is the incorrect input, and @var{cause} is a
low-level error.
@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} &unsupported-crv @var{crv}
The identifier @var{crv} does not identify an elliptic curve.
@end deftp

@deftp {exception type} &not-a-jwk @var{value} @var{cause}
@var{value} does not identify a JWK.
@end deftp

@deftp {exception type} &unsupported-alg @var{value}
@var{value} does not identify a valid hash algorithm.
@end deftp

@node GNU Free Documentation License
@appendix GNU Free Documentation License

@include fdl.texi

@node Index
@unnumbered Index

@printindex cp

@bye