mirror of
https://github.com/mastodon/documentation
synced 2025-04-11 22:56:17 +02:00
3628b6d434
* add rules * join date on profiles * deprecate follow scope * deprecate identity proofs * familiar followers * use definition lists instead of tables for defining activitypub properties * reformat notifications page into markdown * fix broken links to publicKey header * Application website is now nullable * update environment variables added and removed * fix typo * fix heading level * min_id and max_id can be used at the same time (3.3) * fix typo * new tootctl options * reformat tootctl page to use definition lists for params * add rules and configuration to Instance * fix typo * refactor instance api page * 3.3.0 duration on mutes * 3.3.0 mute_expires_at * improve section headings * 3.4.0 resend email confirmation api * 3.4.0 policy on push subscriptions * 3.4.0 add details to account registration error * refactor accounts api page and start adding relrefs to entity pages * 3.4.0 accounts/lookup api * add see also to accounts methods * add more see-also links * 3.5.0 appeal mod decisions * 3.5.0 reformat reports and add category/rule_ids params * document report entity and missing responses * fix typos * fix relrefs and url schema, add aliases to old urls * add archetypes for new methods/entities * update archetypes with see-also stubs * clearer presentation of rate limits * announcements api methods * refactor apps methods * refactor bookmarks methods + some anchors * refactor conversations methods * custom_emojis methods refactor * anchors * refactor directory methods * refactor domain_blocks methods * add see also to emails methods * fix page relref shortcodes to specific methods + refactor endorsements methods * min_id max_id * refactor favourites methods * refactor featured_tags methods * refactor filters methods, make path params consistent, i18n required shortcode * follow_requests methods * lists methods * markers methods * forgot to add entity links * media methods, also fix formatting of some json errors * mutes methods, add more see-also links * oembed methods * preferences methods * proofs methods * push methods * suggestions methods * 3.5.0 add new trend types, fix formatting * refactor streaming methods * refactor oauth methods * note that streaming api casts payload to string * refactor search methods * refactor polls methods * remove unnecessary link * reformat scheduled_statuses methods * reformat timelines methods * reformat statuses methods * 3.5.0 editing statuses * consistent use of array brackets in form data parameters * update dev setup guide, add vagrant and clean up text * add admin/accounts methods * 3.6 role entity * admin/accounts methods v2 * minor fix * stub admin/reports methods * document admin reports * add 403 example to methods archetype * cleanup entities for admin reports and add new attrs * 3.6.0 domain allows methods + normalize admin entity namespace * fix search-and-replace error * add aliases for admin entities * 3.6.0 canonical email blocks entity * 3.5.0 admin/retention api * 3.5.0 add admin::ip doc * 3.5.0 admin/reports * 3.6.0 admin/domain_allows * 3.5.0 admin/dimensions * 3.6.0 permissions and roles * minor formatting fix * add anchor link to headings * checkpoint * add update commands to dev env setup guide * change mentions of v3.6 to v4.0 * tootctl now uses custom roles * fix formatting * v2 instance api * update frontmatter, add better titles to pages * minor wording change * consistency * add more aliases * add placeholders and WIP notices * explain link pagination and stub out todos * switch baseURL to https * 422 on reports with rules but category!=violation * document bug fixes * fix typo * remove duplicate API method definition * s/tootsuite/mastodon for github links * remove unnecessary escaping * s/tootsuite/mastodon in Entity archetype * add missing nullable shortcode * clarify oauth scope when requesting a user token * api/v2/media now synchronous for images * DISALLOW_UNAUTHENTICATED_API_ACCESS * add undocumented env variables * add instance domain blocks and extended description api * add SMTP_ENABLE_STARTTLS * add description to SMTP_ENABLE_STARTTLS * take suggestions from open PRs * normalize links and flavour language * Fully document streaming API based on source code * Add mention of MIME types * bump to ruby 3.0.4 * clarify how to check on async media processing * validation of replies_policy * remove TODOs on admin account action * EmailDomainBlocks * IpBlocks * Admin::DomainBlock * remove TODOs * following hashtags * followed_tags * remove reference to unused parameter * add new oauth scopes for admin blocks and allows * fix command signature for i18n-tasks normalize * reformat code structure page * document fixes for following tags (assume 4.0.3) * Add warning about pre-4.0 hardcoded roles * add note about case sensitivity * remove use of 'simply' from docs * remove reference to silencing * add reference to IDN normalization for verified links * add lang parameter
76 lines
4.2 KiB
Markdown
76 lines
4.2 KiB
Markdown
---
|
|
title: WebFinger
|
|
description: Translate `user@domain` mentions to actor profile URIs.
|
|
menu:
|
|
docs:
|
|
weight: 20
|
|
parent: spec
|
|
---
|
|
|
|
## What is WebFinger, and why is it used? {#intro}
|
|
|
|
On Mastodon, user profiles can be hosted either locally on the same website as yours, or remotely on a completely different website. The same username may be used on a different domain. Therefore, a Mastodon user's full mention consists of both the username and the domain, in the form `@username@domain`. In practical terms, `@user@example.com` is not the same as `@user@example.org`. If the domain is not included, Mastodon will try to find a local user named `@username`. However, in order to deliver to someone over ActivityPub, the `@username@domain` mention is not enough -- **mentions must be translated to an HTTPS URI first**, so that the remote actor's inbox and outbox can be found.
|
|
|
|
Enter WebFinger. WebFinger as described in [RFC 7033](https://tools.ietf.org/html/rfc7033) is a spec that defines **a method for resolving links to a resource**, given only a URI on a particular server. This allows anyone to look up where a resource is located without having to know its exact location beforehand; for example, by email or phone number. This lookup is directed at the endpoint `/.well-known/webfinger`, and a `resource` query parameter is passed along with the lookup. The resource URI used with Mastodon is the `acct:` URI as described in [RFC 7565](https://tools.ietf.org/html/rfc7565), with the username of a profile that is hosted on a particular domain.
|
|
|
|
{{< hint style="danger" >}}
|
|
**Because Mastodon heavily relies on mentions for addressing other profiles, WebFinger is required for fully interoperating with Mastodon.** Users can generally load profiles by searching for the direct HTTPS URI if they know it, or for the `username@domain` address, but Mastodon's internal logic depends almost completely on `acct`: URIs or `username@domain` representations. Searching for any objects or profiles from an ActivityPub implementation without WebFinger will fail because the author cannot be converted to a user in the local database.
|
|
{{< /hint >}}
|
|
|
|
## Sample WebFinger flow {#example}
|
|
|
|
Suppose we want to lookup the user `@Gargron` hosted on the `mastodon.social` website.
|
|
|
|
Just make a request to that domain's `/.well-known/webfinger` endpoint, with the `resource` query parameter set to an `acct:` URI.
|
|
|
|
{{< code title="https://mastodon.social/.well-known/webfinger?resource=acct:gargron@mastodon.social" >}}
|
|
```json
|
|
{
|
|
"subject": "acct:Gargron@mastodon.social",
|
|
"aliases": [
|
|
"https://mastodon.social/@Gargron",
|
|
"https://mastodon.social/users/Gargron"
|
|
],
|
|
"links": [
|
|
{
|
|
"rel": "http://webfinger.net/rel/profile-page",
|
|
"type": "text/html",
|
|
"href": "https://mastodon.social/@Gargron"
|
|
},
|
|
{
|
|
"rel": "self",
|
|
"type": "application/activity+json",
|
|
"href": "https://mastodon.social/users/Gargron"
|
|
},
|
|
{
|
|
"rel": "http://ostatus.org/schema/1.0/subscribe",
|
|
"template": "https://mastodon.social/authorize_interaction?uri={uri}"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
{{< /code >}}
|
|
|
|
You can parse this JSON response to find a link with your desired type. For ActivityPub `id`, we are interested in finding `application/activity+json` specifically.
|
|
|
|
This way, we have translated `@Gargron@mastodon.social` to `https://mastodon.social/users/Gargron` and we can now interact over ActivityPub by referring to this URI as `id` where appropriate.
|
|
|
|
{{< code title="Sample activity" >}}
|
|
```json
|
|
{
|
|
"id": "https://social.example/activities/1",
|
|
"type": "Create",
|
|
"actor": "https://social.example/actors/1",
|
|
"object": {
|
|
"id": "https://social.example/objects/1",
|
|
"type": "Note",
|
|
"content": "Hello, Gargron!"
|
|
},
|
|
"to": "https://mastodon.social/users/Gargron"
|
|
}
|
|
```
|
|
{{< /code >}}
|
|
|
|
Note in the above example that `social.example` does not use the same URI structure as Mastodon. Thus, we cannot guess the actor `id` given only the username and domain. However, if `social.example` supports WebFinger, then we can get this `id` by requesting `https://social.example/.well-known/webfinger?resource=acct:username@social.example`and parsing the response for a link with the `application/activity+json` type.
|
|
|