Document new OAuth changes for 4.3.0 #1445

ThisIsMissEm · 2024-05-15T18:23:43Z

Add /.well-known/oauth-authorization-server documentation
Document deprecation of redirect_uri on Application and addition of redirect_uris
Document added support for mutliple redirect URIs for OAuth Applications
Add warning hints around client_id, client_secret, access_token and code values that they should be treated as if they are password, and stored securely.
Document removal of required read scope for GET /api/v1/apps/verify_credentials (this now just requires a valid access token)
Reworked OAuth Scopes page to be clearer.
Document client_secret_expires_at on Application, per Add client_secret_expires_at to OAuth Applications mastodon#30317
Document the fact that on 4.2.x Applications could be deleted at any time and result in broken authentication flows, fixed by Fix: remove broken OAuth Application vacuuming & throttle OAuth Application registrations mastodon#30316
Document Application vs CredentialApplication split, per Support multiple redirect_uris when creating OAuth 2.0 Applications mastodon#29192

This branch is based on #1444

ThisIsMissEm · 2024-05-15T18:25:25Z

I have noticed that there is some churn here due to my editor using Prettier for markdown documents. We may want to consider adopting prettier for this repository.

ThisIsMissEm · 2024-05-15T18:26:20Z

content/en/client/authorized.md

+
+{{< hint style="warning" >}}
+Treat the `code` query parameter as if it were a password, you should ensure that it is not logged in request logs.
+{{< /hint >}}


This displays as follows:

ThisIsMissEm · 2024-05-15T18:26:50Z

content/en/client/authorized.md

-
+- See [/api/v1/endorsements]({{< relref "methods/endorsements" >}}) for managing a user profile's featured accounts.
+- See [/api/v1/featured_tags]({{< relref "methods/featured_tags" >}}) for managing a user profile's featured hashtags.
+- See [/api/v1/preferences]({{< relref "methods/preferences" >}}) for reading user preferences.


This is all accidental churn due to prettier.

It would potentially be useful here to run prettier in separate branch/PR, get that merged first, rebase this, etc.

I think it's "fine" for now? But do a follow up to run prettier; I'd rather not be rebasing this branch since there's now quite a lot of commits and rebasing would take quite a long time.

content/en/api/oauth-scopes.md

content/en/client/token.md

content/en/api/oauth-scopes.md

trwnh · 2024-06-10T23:51:36Z

content/en/api/oauth-scopes.md

+It is recommended that you make use of granular scopes, unless you really need full access to everything by using a `scope` of `read write follow push`.
+
+| Scope | Granular Scopes |


i think this information is more accessible in list form as above instead of as a table. tables don't flow well on mobile either.

The reason for changing it to an actual table was because everything referred to the "table of granular scopes", which didn't actually exist.

content/en/client/authorized.md

content/en/methods/oauth.md

trwnh · 2024-06-11T00:48:55Z

content/en/methods/push.md

@@ -45,14 +45,15 @@ Add a Web Push API subscription to receive notifications. Each access token can
 3.3.0 - added `data[alerts][status]`\
 3.4.0 - added `data[policy]`\
 3.5.0 - added `data[alerts][update]` and `data[alerts][admin.sign_up]`\
-4.0.0 - added `data[alerts][admin.report]`
+4.0.0 - added `data[alerts][admin.report]`\
+4.3.0 - added stricter request parameter validation, invalid endpoint URLs and subscription keys will now result in an error, previously these would be accepted, but silently fail.


run-on sentence

What would be your suggested fix? This to me looks fine when I only really have a single sentence to use?

trwnh · 2024-06-11T00:51:47Z

content/en/methods/streaming.md

@@ -668,7 +675,7 @@ An example filter change by the user:
 ```

 {{< hint style="warning" >}}
-Note that the `payload` property is not present for `filters_changed` events.
+Note that the `payload` property is not present for `filters_changed` events. And for `delete` and `announcements.delete` the payload is a string, not an object.


redundant addition here

Was deliberate, since it's easily missed and one of the bugs to fix in v2 of streaming.

trwnh · 2024-06-11T00:53:11Z

content/en/methods/streaming.md

@@ -641,7 +648,7 @@ An example update to the public timeline:
 ```

 {{< hint style="warning" >}}
-Note that while the event is JSON-encoded, the `payload` is string-encoded and escaped, so it must be parsed and loaded as JSON from that string.
+Note that while the event is JSON-encoded, the `payload` is string-encoded and escaped, so it must be parsed and loaded as JSON from that string. However, for `delete` and `announcements.delete` events the payload is a string representing an identifier, not a JSON value.


Make this addition into a completely separate hint after line 665 or so (Below "An example delete event from the public timeline:")

I'm fine with this I think.

github-actions · 2024-06-11T11:04:04Z

This pull request has merge conflicts that must be resolved before it can be merged.

…cated on Application entity

Co-authored-by: Matt Jankowski <[email protected]>

…ation used to create them

…dies

ThisIsMissEm · 2024-06-19T19:20:55Z

Have address majority of the code review comments and left replies where I disagree with said comments or need more information.

github-actions · 2024-06-19T20:01:56Z

This pull request has resolved merge conflicts and is ready for review.

ThisIsMissEm commented May 15, 2024

View reviewed changes

ThisIsMissEm force-pushed the chore/document-oauth-changes branch from 92be172 to 9e25eff Compare May 15, 2024 19:12