use link refs, suggest static serving, reword SPN spiel

book/src/integrations/oauth2.md

@@ -458,27 +458,24 @@ Each client has unique signing keys and access secrets, so this is limited to ea
 
 ## WebFinger
 
-> [!NOTE]
->
-> WebFinger support requires Kanidm v1.5.1 or later.
-
-[WebFinger](https://datatracker.ietf.org/doc/html/rfc7033) provides a mechanism
-for discovering information about entities at a well-known URL
-(`http://example.com/.well-known/webfinger`).
+[WebFinger][webfinger] provides a mechanism for discovering information about
+entities at a well-known URL (`https://{hostname}/.well-known/webfinger`).
 
 It can be used by a WebFinger client to
-[discover the OIDC issuer URL](https://datatracker.ietf.org/doc/html/rfc7033#section-3.1)
-of an identity provider from the hostname alone, and seems to be intended to
-support dynamic client registration flows for large public identity providers.
+[discover the OIDC issuer URL][webfinger-oidc] of an identity provider from the
+hostname alone, and seems to be intended to support dynamic client registration
+flows for large public identity providers.
 
 Kanidm v1.5.1 and later can respond to WebFinger requests, using a user's SPN as
-the account (eg: `user@idm.example.com`). This *does not* match on email
-addresses, because they are not required by Kanidm nor guaranteed to be unique.
+part of [an `acct` URI][rfc7565] (eg: `acct:user@idm.example.com`). While SPNs
+and `acct` URIs look like email addresses, [as per RFC 7565][rfc7565s4], there
+is no guarantee that it is valid for any particular application protocol, unless
+an administrator explicitly provides for it.
 
-When setting up an (enterprise) application to authenticate with Kanidm,
-WebFinger **does not add any security** over configuring an OpenID Discovery
-URL directly. In an OIDC context, the specification makes a number of flawed
-assumptions which make it difficult to use with Kanidm:
+When setting up an application to authenticate with Kanidm, WebFinger **does not
+add any security** over configuring an OpenID Discovery URL directly. In an OIDC
+context, the specification makes a number of flawed assumptions which make it
+difficult to use with Kanidm:
 
 * WebFinger assumes that the identity provider will give the same `iss`
   (issuer) and OpenID Discovery document, including all URLs and signing keys,
@@ -486,11 +483,11 @@ assumptions which make it difficult to use with Kanidm:
 
   Kanidm uses *different* `iss` (issuer), signing keys, and some client-specific
   endpoint URLs, which ensures that tokens can only be used with their intended
-  service. *Changing this behaviour would reduce Kanidm's security.*
+  service.
 
 * WebFinger endpoints must be served at the *root* of the domain of a user's
   SPN (ie: information about the user with SPN `user@idm.example.com` is at
-  `https://idm.example.com/.well-known/webfinger?resource=acct%3Auser%40idm.example.com&rel=...`).
+  `https://idm.example.com/.well-known/webfinger?resource=acct%3Auser%40idm.example.com`).
 
   Unlike OIDC Discovery, WebFinger clients do not report their OAuth 2.0/OIDC
   client ID in the request, so there is no way to tell them apart.
@@ -517,19 +514,28 @@ assumptions which make it difficult to use with Kanidm:
   to a client ID, and redirect to the appropriate WebFinger URL for that client.
 
 * Kanidm responds to *all* WebFinger queries with
-  [an Identity Provider Discovery for OIDC URL](https://datatracker.ietf.org/doc/html/rfc7033#section-3.1),
-  **ignoring** any supplied
-  [`rel` parameter](https://datatracker.ietf.org/doc/html/rfc7033#section-4.3).
+  [an Identity Provider Discovery for OIDC URL][webfinger-oidc], **ignoring**
+  any supplied [`rel` parameter][webfinger-rel].
 
   If you want to use WebFinger in any *other* context on Kanidm's hostname,
   you'll need a load balancer in front of Kanidm which matches on some property
   of the request.
 
-  WebFinger clients *may* omit the `rel=` parameter, so if another service has
-  relations for an `acct:` entity and a client *does not* supply the `rel=`
-  parameter, your load balancer will need to merge JSON responses from Kanidm
-  and the other service(s).
+  WebFinger clients *may* omit the `rel=` parameter, so if you host another
+  service with relations for a Kanidm [`acct:` entity][rfc7565s4] and a client
+  *does not* supply the `rel=` parameter, your load balancer will need to merge
+  JSON responses from Kanidm and the other service(s).
 
-Because of these issues, we recommend that (enterprise) applications support
-*directly* configuring OIDC using a Discovery URL or OAuth 2.0 Authorisation
-Server Metadata URL instead of WebFinger.
+Because of these issues, we recommend that applications support *directly*
+configuring OIDC using a Discovery URL or OAuth 2.0 Authorisation Server
+Metadata URL instead of WebFinger.
+
+If a WebFinger client only checks WebFinger once during setup, you may wish to
+temporarily serve an appropriate static WebFinger document for that client
+instead.
+
+[rfc7565]: https://datatracker.ietf.org/doc/html/rfc7565
+[rfc7565s4]: https://datatracker.ietf.org/doc/html/rfc7565#section-4
+[webfinger]: https://datatracker.ietf.org/doc/html/rfc7033
+[webfinger-oidc]: https://datatracker.ietf.org/doc/html/rfc7033#section-3.1
+[webfinger-rel]: https://datatracker.ietf.org/doc/html/rfc7033#section-4.3