Add documentation for PKCE

content/en/methods/oauth.md

@@ -45,6 +45,15 @@ redirect_uri
 scope
 : String. List of requested OAuth scopes, separated by spaces (or by pluses, if using query parameters). Must be a subset of `scopes` declared during app registration. If not provided, defaults to `read`.
 
+state
+: String. Arbitrary value to passthrough to your server when the user authorizes or rejects the authorization request.
+
+code_challenge
+: String. The [PKCE code challenge]({{< relref ref="spec/oauth#pkce" >}}) for the authorization request.
+
+code_challenge_method
+: String. Must be `S256`, as this is the only code challenge method that is supported by Mastodon for PKCE.
+
 force_login
 : Boolean. Forces the user to re-login, which is necessary for authorizing with multiple accounts from the same instance.
 
@@ -99,7 +108,7 @@ grant_type
 : {{<required>}} String. Set equal to `authorization_code` if `code` is provided in order to gain user-level access. Otherwise, set equal to `client_credentials` to obtain app-level access only.
 
 code
-: String. A user authorization code, obtained via [GET /oauth/authorize](#authorize).
+: {{<required>}} String. A user authorization code, obtained from the redirect after an [Authorization request](#authorize) is approved. May alternatively be displayed to the user if `urn:ietf:wg:oauth:2.0:oob` is used as the `redirect_uri`.
 
 client_id
 : {{<required>}} String. The client ID, obtained during app registration.
@@ -108,7 +117,10 @@ client_secret
 : {{<required>}} String. The client secret, obtained during app registration.
 
 redirect_uri
-: {{<required>}} String. Set a URI to redirect the user to. If this parameter is set to urn:ietf:wg:oauth:2.0:oob then the token will be shown instead. Must match one of the `redirect_uris` declared during app registration.
+: {{<required>}} String. Must match the `redirect_uri` used during the [Authorization request](#authorize).
+
+code_verifier
+: String. Required if [PKCE]({{< relref ref="spec/oauth#pkce" >}}) is used during the authorization request. This is the code verifier which was used to create the `code_challenge` using the `code_challenge_method` for the authorization request.
 
 scope
 : String. When `grant_type` is set to `client_credentials`, the list of requested OAuth scopes, separated by spaces (or pluses, if using query parameters). Must be a subset of the scopes requested at the time the application was created. If omitted, it defaults to `read`. Has no effect when `grant_type` is `authorization_code`.

content/en/spec/oauth.md

@@ -66,6 +66,22 @@ Post here with client credentials to revoke an access token.
 
 {{< page-relref ref="methods/oauth#revoke" caption="POST /oauth/revoke" >}}
 
+## OAuth 2 Security Considerations
+
+### Proof Key for Code Exchange (PKCE) {#pkce}
+
+When performing an OAuth 2 [authorization code flow]({{< relref ref="methods/oauth#authorize" >}}), there is an additional security mechanism that you can employ to increase the security of the authorization code when the user is redirected back to your application. This is known as Proof Key for Code Exchange, or PKCE (pronounced pixie), and is supported by Mastodon 4.3.0 and above.
+
+We recommend, inline with [OAuth 2 Security Best Current Practices](https://www.ietf.org/archive/id/draft-ietf-oauth-security-topics-27.html#name-pkce), to use PKCE with the Authorization Code flow for both confidential clients and public clients.
+
+{{< caption-link url="https://oauth.net/2/pkce/" caption="Learn more about PKCE on the OAuth.net website" >}}
+
+### State Parameter {#state-parameter}
+
+When performing an OAuth 2 [authorization code flow]({{< relref ref="methods/oauth#authorize" >}}), you can  use the [`state` parameter](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1) of the Authorization endpoint to prevent mix-up and cross site request forgery attacks. This parameter is returned back to your server unchanged via the redirect URI upon completion of the OAuth Authorization Code flow.
+
+It is also possible to use this parameter to passthrough arbitrary information to your server via the Authorization Code flow. If you use the `state` parameter, it is recommended that you compare or validate the state value before finishing the authorization code flow (i.e., exchanging the authorization code for an access token).
+
 ## Common gotchas {#gotchas}
 
 - When registering an application using Mastodon's REST API, there is a `scopes` parameter. When interfacing with OAuth endpoints, you must use the `scope` parameter instead, and this parameter's value must be a subset of the `scopes` registered with the app. You cannot include anything that wasn't in the original set.