From 0d74f8c1ca9c1e9bf9a04b85f598ba7a175d1d86 Mon Sep 17 00:00:00 2001
From: Vivien Kraus <vivien@planete-kraus.eu>
Date: Tue, 21 Sep 2021 19:49:24 +0200
Subject: OIDC configuration: use GOOPS and document it

---
 doc/disfluid.texi | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

(limited to 'doc')

diff --git a/doc/disfluid.texi b/doc/disfluid.texi
index 42437c2..6247bfa 100644
--- a/doc/disfluid.texi
+++ b/doc/disfluid.texi
@@ -61,6 +61,7 @@ is tracked in the Guix channel
 * Invoking disfluid::
 * Running disfluid with GNU Guix::
 * Managing keys::
+* OIDC discovery::
 * The Json Web Token::
 * Caching on server side::
 * Content negociation::
@@ -458,6 +459,65 @@ If the JWKS cannot be downloaded, or is incorrect, this exception is
 raised.
 @end deftp
 
+@node OIDC discovery
+@chapter OIDC discovery
+An identity provider is known by its server name. The different
+endpoints can be discovered from there.
+
+@deftp {Class} <oidc-configuration> () @var{jwks-uri} @var{authorization-endpoint} @var{token-endpoint}
+The OIDC configuration for an identity provider. @var{jwks-uri},
+@var{authorization-endpoint} adn @var{token-endpoint} are all URIs.
+
+You can construct an OIDC configuration two different ways:
+@itemize
+@item
+by passing @code{#:@var{jwks-uri}},
+@code{#:@var{authorization-endpoint}} and
+@code{#:@var{token-endpoint}} to the constructor;
+@item
+by passing @code{#:@var{server}}, and optionally
+@code{#:@var{http-request}} to the constructor, to query the
+@var{server} for its configuration.
+@end itemize
+@end deftp
+
+@deftp {Exception type} &invalid-oidc-configuration
+This exception is raised when the configuration is unusable or
+incomplete.
+@end deftp
+
+@deffn {function} make-invalid-oidc-configuration
+Constructor for the @code{&invalid-oidc-configuration} exception type.
+@end deffn
+
+@deffn {function} invalid-oidc-configuration? @var{exception}
+Check whether @var{exception} was raised because of an invalid OIDC
+configuration.
+@end deffn
+
+@deffn {Generic} jwks-uri @var{oidc-configuration}
+Return the JWKS uri of @var{oidc-configuration}.
+@end deffn
+
+@deffn {Generic} jwks @var{oidc-configuration}
+Query the JWKS uri of @var{oidc-configuration}.
+@end deffn
+
+@deffn {Generic} authorization-endpoint @var{oidc-configuration}
+Return the authorization endpoint of @var{oidc-configuration}.
+@end deffn
+
+@deffn {Generic} token-endpoint @var{oidc-configuration}
+Return the token endpoint of @var{oidc-configuration}.
+@end deffn
+
+@deffn {Generic} serve @var{configuration} @var{expiration-date}
+Return 2 values: the response, and response body, needed to serve
+@var{configuration}. It is very much recommended to let clients cache
+this value. They will not revalidate it until after
+@var{expiration-date}, a SRFI-19 date.
+@end deffn
+
 @node The Json Web Token
 @chapter The Json Web Token
 
-- 
cgit v1.2.3