From 80e48446548701eb0dd2c5d6693ce5e015225a33 Mon Sep 17 00:00:00 2001 From: Benjamin Neff Date: Sun, 27 Aug 2017 02:05:46 +0200 Subject: [PATCH] Update documentation for RFC 7033 WebFinger --- docs/discovery/webfinger.md | 111 ++++++++++++------------------------ 1 file changed, 36 insertions(+), 75 deletions(-) diff --git a/docs/discovery/webfinger.md b/docs/discovery/webfinger.md index b2044f2..1f4903e 100644 --- a/docs/discovery/webfinger.md +++ b/docs/discovery/webfinger.md @@ -2,88 +2,43 @@ title: WebFinger --- -diaspora\* uses an old draft of [WebFinger][webfinger-draft] to discover users from other pods. - -{% include warning_box.html - title="Old WebFinger" - content="

diaspora* doesn't yet fully support the RFC 7033 WebFinger!

" -%} - -## WebFinger endpoint discovery - -To find the WebFinger endpoint, the requesting server must get the [host metadata][host-meta] information for the -domain of the searched diaspora\* ID. - -### Request - -Let's assume we are searching for `alice@example.org`, then we need the host metadata for `example.org`. - -The request should first be tried with https, if this doesn't work, the requesting server should fallback to http. - -If the server response indicates that the host-meta resource is located elsewhere (a 301, 302, or 307 response status -code), the requesting server should try to obtain the resource from the location provided in the response. - -#### Example - -~~~ -GET /.well-known/host-meta -Host: example.org -~~~ - -### Response - -The host-meta document must be in the [XRD 1.0 document format][xrd] and should be served with the -`application/xrd+xml` media type. - -#### Mandatory Link Relations - -The Host Metadata response must contain the following link relations: - -| Link Relation | Type | Description | -| ------------- | ------------ | ------------------------------------------------------------------------- | -| lrdd | url template | The template to the URL where the server provides the WebFinger endpoint. | - -The Host Metadata response may contain other optional link relations. - -#### Example - -~~~ -Status: 200 OK -Content-Type: application/xrd+xml; charset=utf-8 -~~~ -~~~xml - - - - -~~~ +diaspora\* uses [WebFinger][webfinger-rfc] to discover users from other pods. ## WebFinger ### Request +~~~ +GET /.well-known/webfinger +~~~ + +Let's assume we are searching for `alice@example.org`, then we need to make a request to `example.org`. + +The request should first be tried with https, if this doesn't work, the requesting server should fallback to http. + #### Parameters -The requesting server must replace the ``{uri}`` in the lrdd-template from the host-meta request with the diaspora\* ID -of the searched person. +| Name | Description | +| ---------- | ------------------------------------------------------------ | +| `resource` | The "acct" URI for the diaspora\* ID of the searched person. | #### Example ~~~ -GET /.well-known/webfinger.xml?resource=acct:alice@example.org +GET /.well-known/webfinger?resource=acct:alice@example.org Host: example.org ~~~ ### Response -The webfinger document must be in the [XRD 1.0 document format][xrd] and should be served with the -`application/xrd+xml` media type. +The WebFinger document must be in the [JSON Resource Descriptor (JRD) format][jrd] and should be served with the +`application/jrd+json` media type. If the requested diaspora\* ID is unknown by the server, it must return a 404 status code. #### Subject -The ``Subject`` element should contain the webfinger address that was asked for. If it does not, then this webfinger +The `subject` element should contain the WebFinger address that was asked for. If it does not, then this WebFinger profile must be ignored. #### Mandatory Link Relations @@ -101,26 +56,32 @@ The WebFinger response may contain other optional link relations. ~~~ Status: 200 OK -Content-Type: application/xrd+xml; charset=utf-8 +Content-Type: application/jrd+json; charset=utf-8 +Access-Control-Allow-Origin: * ~~~ -~~~xml - - - acct:alice@example.org - - - +~~~json +{ + "subject": "acct:alice@example.org", + "links": [ + { + "rel": "http://microformats.org/profile/hcard", + "type": "text/html", + "href": "https://example.org/hcard/users/7dba7ca01d64013485eb3131731751e9" + }, + { + "rel": "http://joindiaspora.com/seed_location", + "type": "text/html", + "href": "https://example.org/" + } + ] +} ~~~ ## Additional information and specifications -* [RFC 6415: Web Host Metadata][host-meta] -* [WebFinger draft][webfinger-draft] -* [Extensible Resource Descriptor (XRD) Version 1.0][xrd] * [RFC 7033: WebFinger][webfinger-rfc] +* [JSON Resource Descriptor (JRD)][jrd] -[host-meta]: https://tools.ietf.org/html/rfc6415 -[webfinger-draft]: https://tools.ietf.org/html/draft-jones-appsawg-webfinger-06 [webfinger-rfc]: https://tools.ietf.org/html/rfc7033 -[xrd]: http://docs.oasis-open.org/xri/xrd/v1.0/xrd-1.0.html +[jrd]: https://www.packetizer.com/json/jrd/ [hcard]: {{ site.baseurl }}/discovery/hcard.html