nocebo/diaspora_federation
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update documentation for RFC 7033 WebFinger

Browse source
This commit is contained in:
Benjamin Neff 2017-08-27 02:05:46 +02:00
parent 3e7e649025
commit 80e4844654
No known key found for this signature in database
GPG key ID: 971464C3F1A90194
1 changed files with 36 additions and 75 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

111
docs/discovery/webfinger.md
View file

@ -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="<p>diaspora* doesn't yet fully support the RFC 7033 WebFinger!</p>"
%}
## 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
<?xml version="1.0" encoding="UTF-8"?>
<XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0">
<Link rel="lrdd" type="application/xrd+xml" template="https://example.org/.well-known/webfinger.xml?resource={uri}"/>
</XRD>
~~~
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
<?xml version="1.0" encoding="UTF-8"?>
<XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0">
<Subject>acct:alice@example.org</Subject>
<Link rel="http://microformats.org/profile/hcard" type="text/html" href="https://example.org/hcard/users/7dba7ca01d64013485eb3131731751e9"/>
<Link rel="http://joindiaspora.com/seed_location" type="text/html" href="https://example.org/"/>
</XRD>
~~~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