1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
|
<?xml version="1.0" encoding="utf-8"?>
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:info="http://planete-kraus.eu/ns/info"
xml:lang="en">
<head>
<link rel="stylesheet" type="text/css" href="style.css"/>
<title>Webid-oidc manual</title>
<info:subtitle>for version <info:version />,
<info:updated /></info:subtitle>
<info:copying>
<p>
This is the manual of webid-oidc (version <info:version />,
<info:updated />), an implementation of the Solid
authentication protocol for guile, client and server.
</p>
<p>Copyright <info:copyright-symbol /> 2020, 2021 Vivien
Kraus</p>
<info:quotation>
<p>
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''
</p>
</info:quotation>
</info:copying>
<info:author>
<a href="mailto:vivien@planete-kraus.eu">Vivien Kraus</a>
</info:author>
<info:dircategory>
Software libraries
</info:dircategory>
<info:direntry>
<info:direntry-entry name="webid-oidc">
Decentralized Authentication on the Web.
</info:direntry-entry>
</info:direntry>
</head>
<body>
<h1>Decentralized Authentication on the Web</h1>
<p>
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
<info:var>useful-program</info:var> wants to authenticate
<info:var>MegaCorp</info:var> users, then
<info:var>useful-program</info:var> has to register to
<info:var>MegaCorp</info:var> first, and get approved. This goes
against the principle of permission-less innovation, which is at
the heart of the web.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
<h1>The Json Web Token</h1>
<p>
The Json Web Token, or <info:dfn>JWT</info:dfn>, is a terse
representation of a pair of JSON objects: the
<info:dfn>header</info:dfn>, and the
<info:dfn>payload</info:dfn>. The JWT can be
<info:dfn>encoded</info:dfn> as a Json Web Signature
(<info:dfn>JWS</info:dfn>), 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.
</p>
<p>
Decoded JWT are represented as a pair. The car of the pair is
the header, and the cdr is the payload. Both the header and the
payload use the JSON representation from srfi-180: objects are
alists of <strong>symbols</strong> to values, arrays are
vectors. It is unfortunate that guile-json has a slightly
different representation, where alist keys are
<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
functions from <emph>(webid-oidc jws)</emph>.
</p>
<info:deffn type="function" name="jws?" arguments="jwt">
<p>
Check that <info:var>jwt</info:var> is a decoded JWT signed
with JWS.
</p>
</info:deffn>
<info:deffn type="function" name="jws-alg" arguments="jwt">
<p>
Get the algorithm used to sign <info:var>jwt</info:var>.
</p>
</info:deffn>
<info:deffn type="function" name="jws-decode" arguments="str lookup-keys">
<p>
Check and decode a JWT signed with JWS and encoded
as <info:var>str</info:var>.
</p>
<p>
Since the decoding and signature verification happen at the
same time (for user friendliness), the
<info:var>lookup-keys</info:var> function is used. It is
passed as arguments the decoded JWT (but the signature is not
checked yet), and it should return a public key, a public key
set or a list of public keys. If the key lookup failed, this
function should raise an exception.
</p>
</info:deffn>
<info:deffn type="function" name="jws-encode" arguments="jwt key">
<p>
Encode the JWT and sign it with <info:var>key</info:var>.
</p>
</info:deffn>
<h1>Caching on server side</h1>
<p>
Both the identity provider and the resource server need to cache
things. The identity provider will cache application webids, and
the resource server will cache the identity provider keys, for
instance.
</p>
<p>
The solution is to use a file-system cache. Every response
(except those that have a cache-control policy of no-store) are
stored to a sub-directory of <emph>XDG_CACHE_HOME</emph>. Each
store has a 5% chance of triggering a cleanup of the cache. When
a cleanup occurs, each cached response has a 5% chance of being
dropped, including responses that are indicated as valid. This
way, a malicious cache response that has a maliciously long
validity will not stay too long in the cache. A log line will
indicate which items are dropped.
</p>
<p>
The <emph>(webid-oidc cache)</emph> module exports two
functions to deal with the cache.
</p>
<info:deffn type="function" name="clean-cache" arguments="[#percents] [#dir]">
<p>
Drop <info:var>percents</info:var>% of the cache right now, in
<info:var>dir</info:var> (defaults to some place within
<emph>XDG_CACHE_HOME</emph>).
</p>
</info:deffn>
<info:deffn type="function" name="with-cache" arguments="[#current-time] [#http-get] [#dir]">
<p>
Return a function acting as <emph>http-get</emph> from
<emph>(web client)</emph> (takes an URI as the first
parameter, and an optional <info:var>#:headers</info:var> set,
and returns 2 values, the response and its body).
</p>
<p>
The cache will be read and written in <info:var>dir</info:var>
(defaults to some place within <emph>XDG_CACHE_HOME</emph>),
and the <info:var>current-time</info:var> number of seconds,
SRFI-19 time or date, or time-returning thunk will be used to
check for the validity of responses.
</p>
<p>
The back-end function, <info:var>http-get</info:var>, defaults
to that of <emph>(web client)</emph>.
</p>
</info:deffn>
<h1>What if something goes wrong?</h1>
<p>
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
<emph>(webid-oidc errors)</emph>.
</p>
<info:deffn type="function" name="error->str" arguments="error [#depth]">
<p>
Return a string explaining the <info:var>error</info:var>. You
can limit the <info:var>depth</info:var> of the explanation as
an integer.
</p>
</info:deffn>
<info:deftp type="exception type" name="&not-base64" arguments="value cause">
<p>
This exception is raised when the base64 decoding function
failed. <info:var>value</info:var> is the incorrect input,
and <info:var>cause</info:var> is a low-level error.
</p>
</info:deftp>
<info:deftp type="exception type" name="&not-json" arguments="value cause">
<p>
Cannot decode <info:var>value</info:var> to a JSON object.
</p>
</info:deftp>
<info:deftp type="exception type" name="&unsupported-crv" arguments="crv">
<p>
The identifier <info:var>crv</info:var> does not identify an
elliptic curve.
</p>
</info:deftp>
<info:deftp type="exception type" name="&not-a-jwk" arguments="value cause">
<p>
<info:var>value</info:var> does not identify a JWK.
</p>
</info:deftp>
<info:deftp type="exception type" name="&not-a-public-jwk" arguments="value cause">
<p>
<info:var>value</info:var> does not identify a public JWK.
</p>
</info:deftp>
<info:deftp type="exception type" name="&not-a-private-jwk" arguments="value cause">
<p>
<info:var>value</info:var> does not identify a private JWK.
</p>
</info:deftp>
<info:deftp type="exception type" name="&not-a-jwks" arguments="value cause">
<p>
<info:var>value</info:var> does not identify a set of public keys.
</p>
</info:deftp>
<info:deftp type="exception type" name="&unsupported-alg" arguments="value">
<p>
<info:var>value</info:var> does not identify a valid hash algorithm.
</p>
</info:deftp>
<info:deftp type="exception type" name="&invalid-signature" arguments="key payload signature">
<p>
<info:var>key</info:var> has not signed
<info:var>payload</info:var> with
<info:var>signature</info:var>.
</p>
</info:deftp>
<info:deftp type="exception type" name="&missing-alist-key" arguments="value key">
<p>
<info:var>value</info:var> isn’t an alist, or is missing a
value with <info:var>key</info:var>.
</p>
</info:deftp>
<info:deftp type="exception type" name="&not-a-jws-header" arguments="value cause">
<p>
<info:var>value</info:var> does not identify a decoded JWS header.
</p>
</info:deftp>
<info:deftp type="exception type" name="&not-a-jws-payload" arguments="value cause">
<p>
<info:var>value</info:var> does not identify a decoded JWS payload.
</p>
</info:deftp>
<info:deftp type="exception type" name="&not-a-jws" arguments="value cause">
<p>
<info:var>value</info:var> does not identify a decoded JWS.
</p>
</info:deftp>
<info:deftp type="exception type" name="&not-in-3-parts" arguments="string separator">
<p>
<info:var>string</info:var> cannot be split into 3 parts with
<info:var>separator</info:var>.
</p>
</info:deftp>
<info:deftp type="exception type" name="&no-matching-key" arguments="candidates alg payload signature">
<p>
No key among <info:var>candidates</info:var> could verify
<info:var>signature</info:var> signed with
<info:var>alg</info:var> for <info:var>payload</info:var>,
because the signature mismatched for all keys.
</p>
</info:deftp>
<info:deftp type="exception type" name="&cannot-decode-jws" arguments="value cause">
<p>
The <info:var>value</info:var> string is not an encoding of a valid JWS.
</p>
</info:deftp>
<info:deftp type="exception type" name="&cannot-encode-jws" arguments="jws key cause">
<p>
The <info:var>jws</info:var> cannot be signed.
</p>
</info:deftp>
<info:deftp type="exception type" name="&request-failed-unexpectedly" arguments="response-code response-reason-phrase">
<p>
We expected the request to succeed, but the server sent a
non-OK <info:var>response-code</info:var>.
</p>
</info:deftp>
<info:deftp type="exception type" name="&unexpected-header-value" arguments="header value">
<p>
We did not expect the server to respond with
<info:var>header</info:var> set to <info:var>value</info:var>.
</p>
</info:deftp>
<info:deftp type="exception type" name="&unexpected-response" arguments="response cause">
<p>
The <info:var>response</info:var> (from
<emph>(web response)</emph>) is not appropriate.
</p>
</info:deftp>
<info:deftp type="exception type" name="&not-an-oidc-configuration" arguments="value cause">
<p>
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>
<h1 type="appendix">GNU Free Documentation License</h1>
<info:gfdl />
<h1 type="unnumbered">Index</h1>
<info:printindex />
</body>
</html>
<!-- Local Variables: -->
<!-- mode: nxml -->
<!-- End: -->
|
