mart-w/kanidm
1
0
Fork 0
mirror of https://github.com/kanidm/kanidm.git synced 2025-02-23 20:47:01 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

use link refs, suggest static serving, reword SPN spiel

Browse source
This commit is contained in:
Michael Farrell 2025-02-20 17:19:57 +10:00
parent 230396c20c
commit a0eb51b6ce
1 changed files with 22 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

39
book/src/integrations/oauth2.md
View file

@ -458,20 +458,19 @@ 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 entities at a well-known URL entities at a well-known URL (`https://{hostname}/.well-known/webfinger`).
(`https://{hostname}/.well-known/webfinger`).
It can be used by a WebFinger client to It can be used by a WebFinger client to
[discover the OIDC issuer URL](https://datatracker.ietf.org/doc/html/rfc7033#section-3.1) [discover the OIDC issuer URL][webfinger-oidc] of an identity provider from the
of an identity provider from the hostname alone, and seems to be intended to hostname alone, and seems to be intended to support dynamic client registration
support dynamic client registration flows for large public identity providers. flows for large public identity providers.
Kanidm v1.5.1 and later can respond to WebFinger requests, using a user's SPN as Kanidm v1.5.1 and later can respond to WebFinger requests, using a user's SPN as
[an `acct` URI][rfc7565] (eg: `acct:user@idm.example.com`). part of [an `acct` URI][rfc7565] (eg: `acct:user@idm.example.com`). While SPNs
[As per RFC 7565][rfc7565s4], there is no guarantee that account IDs are valid and `acct` URIs look like email addresses, [as per RFC 7565][rfc7565s4], there
for any particular application protocol (such as email), unless an administrator is no guarantee that it is valid for any particular application protocol, unless
explicitly provides it. an administrator explicitly provides for it.
When setting up an application to authenticate with Kanidm, WebFinger **does not 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 add any security** over configuring an OpenID Discovery URL directly. In an OIDC
@ -515,22 +514,28 @@ difficult to use with Kanidm:
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**
**ignoring** any supplied any supplied [`rel` parameter][webfinger-rel].
[`rel` parameter](https://datatracker.ietf.org/doc/html/rfc7033#section-4.3).
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.
WebFinger clients *may* omit the `rel=` parameter, so if another service has WebFinger clients *may* omit the `rel=` parameter, so if you host another
relations for an `acct:` entity and a client *does not* supply the `rel=` service with relations for a Kanidm [`acct:` entity][rfc7565s4] and a client
parameter, your load balancer will need to merge JSON responses from Kanidm *does not* supply the `rel=` parameter, your load balancer will need to merge
and the other service(s). JSON responses from Kanidm and the other service(s).
Because of these issues, we recommend that applications support *directly* Because of these issues, we recommend that applications support *directly*
configuring OIDC using a Discovery URL or OAuth 2.0 Authorisation Server configuring OIDC using a Discovery URL or OAuth 2.0 Authorisation Server
Metadata URL instead of WebFinger. 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 [rfc7565]: https://datatracker.ietf.org/doc/html/rfc7565
[rfc7565s4]: https://datatracker.ietf.org/doc/html/rfc7565#section-4 [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