Miscellaneous fixes (#1110)
* Fix typos in method examples * Fix broken link to sanitize_config (#1115) * Add SIDEKIQ_CONCURRENCY * Fix relref to FilterResult (#1114) * Fix status_ids and rule_ids description (#1126) * fix typo (#1129) * clarify confusing example (mastodon/mastodon#22854) * fix formatting on linked headings (#1139) * fix placeholder entity names (#1157) * better wording * fix scheduledstatus#params.visibility * fix missing: tootctl accounts modify --remove-role * add: status/translate * add deprecation/removal warning to microformats page * clarify further how link verification works * clarify mastodon requirements for webfinger * fix: push param policy -> data[policy]
This commit is contained in:
trwnh
GitHub
parent
5b0cd8b7f0
commit
b458498d25
24 changed files with 237 additions and 44 deletions
|
|
@ -221,7 +221,7 @@ published
|
|||
|
||||
## HTML sanitization {#sanitization}
|
||||
|
||||
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/lib/sanitize_config.rb" caption="app/lib/sanitize_config.rb" >}}
|
||||
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/sanitize_ext/sanitize_config.rb" caption="lib/sanitize_ext/sanitize_config.rb" >}}
|
||||
|
||||
Mastodon sanitizes incoming HTML in order to not break assumptions for API client developers. Supported elements include `<p>`, `<span>`, `<br>`, and `<a>`. Unsupported elements will be converted to `<p>`.The sanitizer will keep classes if they begin with microformats prefixes or are semantic classes:
|
||||
|
||||
|
|
|
|||
|
|
@ -7,6 +7,10 @@ menu:
|
|||
parent: spec
|
||||
---
|
||||
|
||||
{{< hint style="info" >}}
|
||||
As of v4.0.0, HTML permalinks for statuses and profiles have been deprecated and removed from Mastodon. As a result, Microformats are currently not used within nor generated by Mastodon.
|
||||
{{< /hint >}}
|
||||
|
||||
## What are microformats? {#intro}
|
||||
|
||||
[Microformats 2.0](https://microformats.io/) is a standard used to embed metadata directly within an HTML document. Rather than needing to use an API for read-only purposes, a web page can be parsed for certain CSS classes in order to extract information that you have already fetched just by viewing the page, rather than having to separately request that same information from an API. The use of microformats classes allows for semantic parsing of data within a given web page, and can be used to generate feeds, cards, or representations of that data.
|
||||
|
|
|
|||
|
|
@ -11,12 +11,6 @@ menu:
|
|||
|
||||
The Mastodon API has many methods that require authentication from a client or authorization from a user. This is accomplished with OAuth 2.0, an authorization framework described in [RFC 6749](https://tools.ietf.org/html/rfc6749) that allows third-party applications to obtain limited access to an HTTP service on behalf of a resource owner, through the use of a standardized authorization flow that generates a client access token to be used with HTTP requests.
|
||||
|
||||
Mastodon supports the following OAuth 2 flows:
|
||||
|
||||
* **Authorization code flow**: For end-users
|
||||
* **Password grant flow**: For bots and other single-user applications
|
||||
* **Client credentials flow**: For applications that do not act on behalf of users
|
||||
|
||||
To obtain an OAuth token for a Mastodon website, make sure that you allow your users to specify the domain they want to connect to before login. Use that domain to [acquire a client id/secret]({{< relref "methods/apps#create" >}}) and then [proceed with normal OAuth 2]({{< relref "methods/oauth" >}}).
|
||||
|
||||
## OAuth 2 endpoints implemented {#implementation}
|
||||
|
|
@ -25,17 +19,32 @@ The following descriptions are taken from the [Doorkeeper documentation](https:/
|
|||
|
||||
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/config/initializers/doorkeeper.rb" caption="Doorkeeper config initializer" >}}
|
||||
|
||||
### [GET /oauth/authorize]({{< relref "methods/oauth#authorize" >}})
|
||||
### Authorization endpoint (RFC 6749 Section 3.1) {#authorization}
|
||||
|
||||
[GET /oauth/authorize]({{% relref "methods/oauth#authorize" %}})
|
||||
|
||||
Displays an authorization form to the user. If approved, it will create and return an authorization code, then redirect to the desired `redirect_uri`, or show the authorization code if `urn:ietf:wg:oauth:2.0:oob` was requested.
|
||||
|
||||
### [POST /oauth/token]({{< relref "methods/oauth#token" >}}) {#post-oauth-token}
|
||||
### Token endpoint (RFC 6749 Section 3.2) {#token}
|
||||
|
||||
Obtain an access token. This corresponds to the token endpoint, section 3.2 of the OAuth 2 RFC.
|
||||
[POST /oauth/token]({{% relref "methods/oauth#token" %}})
|
||||
|
||||
### [POST /oauth/revoke]({{< relref "methods/oauth#revoke" >}}) {#post-oauth-revoke}
|
||||
Obtain an access token. Mastodon supports the following OAuth 2 flows:
|
||||
|
||||
Post here with client credentials to revoke an access token. This corresponds to the token endpoint, using the OAuth 2.0 Token Revocation RFC (RFC 7009).
|
||||
Authorization code flow
|
||||
: For end-users
|
||||
|
||||
Password grant flow
|
||||
: For bots and other single-user applications
|
||||
|
||||
Client credentials flow
|
||||
: For applications that do not act on behalf of users
|
||||
|
||||
### Token revocation endpoint (RFC 7009 Section 2) {#revoke}
|
||||
|
||||
[POST /oauth/revoke]({{% relref "methods/oauth#revoke" %}})
|
||||
|
||||
Post here with client credentials to revoke an access token.
|
||||
|
||||
## Common gotchas {#gotchas}
|
||||
|
||||
|
|
|
|||
|
|
@ -71,5 +71,39 @@ This way, we have translated `@Gargron@mastodon.social` to `https://mastodon.soc
|
|||
```
|
||||
{{< /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.
|
||||
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/ld+json; profile="https://www.w3.org/ns/activitystreams"` or `application/activity+json` type. This link should also have the link relation `rel="self"`.
|
||||
|
||||
## Mastodon's requirements for WebFinger
|
||||
|
||||
When given an account in the form `username@domain` or `@username@domain`, Mastodon will do the following:
|
||||
|
||||
- Construct an `acct:` URI using that username and domain
|
||||
- Make a WebFinger request for that `resource`
|
||||
|
||||
Using that WebFinger response, Mastodon will check the following:
|
||||
|
||||
- The `subject` is present
|
||||
- The `links` array contains a link with `rel` of `self` and `type` of either `application/ld+json; profile="https://www.w3.org/ns/activitystreams"` or `application/activity+json`
|
||||
- The `href` for this link resolves to an ActivityPub actor
|
||||
|
||||
Using that ActivityPub actor representation (which may be provided directly, without the initial WebFinger request), Mastodon will do the following:
|
||||
|
||||
- Take `preferredUsername` and the hostname of the actor's server
|
||||
- Construct an `acct:` URI using that username and domain
|
||||
- Make a Webfinger request for that `resource`
|
||||
|
||||
If the `subject` matches the `resource`, then the process stops here. Otherwise, if the `subject` contains a different canonical account URI, then Mastodon will perform an additional Webfinger request for that canonical account URI in order to ensure that this new `resource` links to the same ActivityPub actor with the same criteria being checked.
|
||||
|
||||
In other words, the following cases are valid:
|
||||
|
||||
- Asking `example.com` for the resource `acct:alice@example.com` yields a link to an actor on the domain `example.com` with a `preferredUsername` of `alice`, and the `subject` matches the requested resource `acct:alice@example.com`
|
||||
- Asking `example.com` for the resource `acct:alice@example.com` yields a link to an actor on the domain `ap.example.com` with a `preferredUsername` of `alice`
|
||||
- ...then, asking `ap.example.com` for the resource `acct:alice@ap.example.com` yields a `subject` of `acct:alice@example.com` and a link to the same actor
|
||||
|
||||
## See also
|
||||
|
||||
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/services/activitypub/fetch_remote_actor_service.rb" caption="app/services/activitypub/fetch_remote_actor_service.rb" >}}
|
||||
|
||||
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/services/resolve_account_service.rb" caption="app/services/resolve_account_service.rb" >}}
|
||||
|
||||
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/webfinger.rb" caption="app/lib/webfinger.rb" >}}
|
||||
Loading…
Add table
Add a link
Reference in a new issue