OAuth

What is OAuth?

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 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.

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 and then proceed with normal OAuth 2.

OAuth 2 client types

OAuth 2 defines two client types: confidential and public, based on their ability to authenticate securely with the authorization server (i.e., ability to maintain the confidentiality of their client credentials). Confidential clients are allowed to use the client credentials grant flow, where as public clients cannot.

At present Mastodon only supports confidential clients, however work is underway to add support for public clients.

OAuth 2 endpoints implemented

The following descriptions are taken from the Doorkeeper documentation. Mastodon uses Doorkeeper to implement OAuth 2. For more information on how to use these endpoints, see the API documentation for OAuth.

Authorization Server Metadata endpoint (RFC 8414)

Returns a JSON document representing the configuration of the OAuth 2 server in Mastodon. Information includes scopes available for use when registering Applications or requesting access tokens, grant_types_supported which are can be used when requesting access tokens, and various endpoints for interacting with the Mastodon OAuth server, such as authorization_endpoint and token_endpoint.

Version history:
4.3.0 - added

Dynamic Client Registration endpoint (RFC 7591)

At present, Mastodon does not support the Dynamic Client Registration protocol, however it does support a proprietary endpoint for registering an OAuth Application.

Authorization endpoint (RFC 6749 Section 3.1)

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.

Token endpoint (RFC 6749 Section 3.2)

Obtain an access token. Mastodon supports the following OAuth 2 flows:

Authorization code flow

For end-users

Client credentials flow

For applications that do not act on behalf of users

Mastodon has historically supported the Password Grant flow, however, usage is not recommended by the OAuth 2 Specification authors due to security issues, and has subsequently been removed from future versions of Mastodon. Instead, it is recommended that you create an OAuth Application for that user, and use the generated Access Token for interacting with the API.

Token revocation endpoint (RFC 7009 Section 2)

Post here with client credentials to revoke an access token.

OAuth 2 Security Considerations

Proof Key for Code Exchange (PKCE)

When performing an OAuth 2 authorization code flow, 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, to use PKCE with the Authorization Code flow for both confidential clients and public clients.

State Parameter

When performing an OAuth 2 authorization code flow, you can use the state parameter 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

• 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.
• When registering an application using Mastodon’s REST API, there is a redirect_uris parameter. When interfacing with OAuth endpoints, you must use the redirect_uri parameter instead, and this parameter’s value must be one of the redirect_uris registered with the app.

Last updated October 10, 2024 · Improve this page