address webfinger doc feedbacks ()

This commit is contained in:
micolous 2025-02-25 12:53:53 +10:00 committed by GitHub
parent 38c260214b
commit 3edee485dd
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -85,7 +85,7 @@ URL **(recommended)**
<dt> <dt>
[WebFinger URL **(discouraged)**](#webfinger) [WebFinger URL](#webfinger) **(discouraged)**
</dt> </dt>
@ -162,7 +162,7 @@ Token endpoint
<dt> <dt>
OpenID Connect issuer URI OpenID Connect Issuer URL
</dt> </dt>
@ -458,58 +458,83 @@ Each client has unique signing keys and access secrets, so this is limited to ea
## WebFinger ## WebFinger
[WebFinger](https://datatracker.ietf.org/doc/html/rfc7033) provides a mechanism [WebFinger][webfinger] provides a mechanism for discovering information about
for discovering information about people or other entities. It can be used by an entities at a well-known URL (`https://{hostname}/.well-known/webfinger`).
identity provider to supply OpenID Connect discovery information.
Kanidm provides It can be used by a WebFinger client to
[an Identity Provider Discovery for OIDC URL](https://datatracker.ietf.org/doc/html/rfc7033#section-3.1) [discover the OIDC Issuer URL][webfinger-oidc] of an identity provider from the
response to all incoming WebFinger requests, using a user's SPN as their account hostname alone, and seems to be intended to support dynamic client registration
ID. This does not match on email addresses as they are not guaranteed to be flows for large public identity providers.
unique.
However, WebFinger has a number of flaws which make it difficult to use with Kanidm v1.5.1 and later can respond to WebFinger requests, using a user's SPN as
Kanidm: 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.
* WebFinger assumes that the identity provider will give the same `iss` When setting up an application to authenticate with Kanidm, WebFinger **does not
(Issuer) for every OAuth 2.0/OIDC client, and there is no standard way for a add any security** over configuring an OIDC Discovery URL directly. In an OIDC
WebFinger client to report its client ID. context, the specification makes a number of flawed assumptions which make it
difficult to use with Kanidm:
Kanidm uses a *different* `iss` (Issuer) value for each client. * WebFinger assumes that an identity provider will use the same Issuer URL and
OIDC Discovery document (which contains endpoint URLs and token signing keys)
for *all* OAuth 2.0/OIDC clients.
* WebFinger requires that this be served at the *root* of the domain of a user's Kanidm uses *client-specific* Issuer URLs, endpoint URLs and token signing
keys. This ensures that tokens can only be used with their intended 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 SPN (ie: information about the user with SPN `user@idm.example.com` is at
`https://idm.example.com/.well-known/webfinger`). `https://idm.example.com/.well-known/webfinger?resource=acct%3Auser%40idm.example.com`).
Kanidm *does not* provide a WebFinger endpoint at its root URL, because it has Unlike OIDC Discovery, WebFinger clients do not report their OAuth 2.0/OIDC
no way to know *which* OAuth 2.0/OIDC client a WebFinger request is associated client ID in the request, so there is no way to tell them apart.
with, so could report an incorrect `iss` (Issuer).
You will need a load balancer in front of Kanidm's HTTPS server to redirect As a result, Kanidm *does not* provide a WebFinger endpoint at its root URL,
requests to the appropriate `/oauth2/openid/:client_id:/.well-known/webfinger` because it could report an incorrect Issuer URL and lead the client to an
URL. If the client does not follow redirects, you may need to rewrite the incorrect OIDC Discovery document.
request in the load balancer instead.
You will need a load balancer in front of Kanidm's HTTPS server to send a HTTP
307 redirect to the appropriate
`/oauth2/openid/:client_id:/.well-known/webfinger` URL, *while preserving all
query parameters*. For example, with Caddy:
```caddy
# Match on a prefix, and use {uri} to preserve all query parameters.
# This only supports *one* client.
example.com {
redir /.well-known/webfinger https://idm.example.com/oauth2/openid/:client_id:{uri} 307
}
```
If you have *multiple* WebFinger clients, it will need to map some other If you have *multiple* WebFinger clients, it will need to map some other
property of the request (such as a source IP address or `User-Agent` header) property of the request (such as a source IP address or `User-Agent` header)
to a client ID, and redirect to the appropriate WebFinger URL for that client. to a client ID, and redirect to the appropriate WebFinger URL for that client.
* Kanidm responds to *all* WebFinger queries with * Kanidm responds to *all* WebFinger queries with
[an Identity Provider Discovery for OIDC URL](https://datatracker.ietf.org/doc/html/rfc7033#section-3.1), [an Identity Provider Discovery for OIDC URL][webfinger-oidc], **ignoring**
**regardless** of what [`rel` parameter(s)][webfinger-rel].
[`rel` parameter](https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4.1)
was specified.
This is to work around
[a broken client](https://tailscale.com/kb/1240/sso-custom-oidc) which doesn't
send a `rel` parameter, but expects an Identity Provider Discovery issuer URL
in response.
If you want to use WebFinger in any *other* context on Kanidm's hostname, 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 you'll need a load balancer in front of Kanidm which matches on some property
of the request. of the request.
Because of the flaws of the WebFinger specification and the deployment WebFinger clients *may* omit the `rel=` parameter, so if you host another
difficulties they introduce, we recommend that applications use OpenID Connect service with relations for a Kanidm [`acct:` entity][rfc7565s4] and a client
Discovery or OAuth 2.0 Authorisation Server Metadata for client configuration *does not* supply the `rel=` parameter, your load balancer will need to merge
instead of WebFinger. JSON responses from Kanidm and the other service(s).
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