Mastodon Instance Single Sign On With OAuth: Setup

You want to let users log in to your website or app using their Mastodon account. Mastodon supports OAuth 2.0, which allows external services to authenticate users without sharing their Mastodon password. This setup enables single sign-on SSO for your Mastodon instance, making it easier for users to access connected tools. In this article, you will learn how to register an application on your Mastodon instance, configure OAuth endpoints, and implement the authorization code flow.

What Is Mastodon OAuth and How Does It Work for SSO

OAuth 2.0 is an open standard for token-based authentication. Mastodon implements the authorization code grant flow, which is the most secure method for SSO. In this flow, your external application never sees the user’s Mastodon password. Instead, the user approves your app’s access request on the Mastodon instance itself. Mastodon then issues a short-lived authorization code to your app, which you exchange for an access token and a refresh token. The access token allows your app to read the user’s profile and perform actions based on the scopes you requested.

Before you start, you need the following:

• A Mastodon instance where you have admin privileges. You need access to the admin panel to register applications.
• The base URL of your Mastodon instance. For example, https://mastodon.social or your own instance URL.
• The redirect URI of your external application. This is the endpoint in your app where Mastodon will send the authorization code after the user approves the request.

OAuth Scopes You Need

When registering your application, you must specify which scopes your app requires. For SSO, the most common scope is read:accounts, which allows your app to read the user’s profile information such as username, display name, and avatar. If your app needs to post on behalf of the user, you need write:statuses. You can select multiple scopes. Keep scopes minimal to follow the principle of least privilege.

Steps to Set Up Mastodon OAuth for Single Sign On

1. Register a new application on your Mastodon instance
   Log in to your Mastodon instance admin panel. Navigate to Preferences > Administration > Applications. Click the New Application button. Enter a name for your application, for example MySSOApp. Enter the redirect URI of your external application. Select the required scopes, such as read:accounts. Click Submit. Mastodon generates a client ID and client secret. Copy and save these values securely.
2. Construct the authorization URL
   Build the URL that redirects users to your Mastodon instance for authentication. The base URL is https://yourinstance.com/oauth/authorize. Add the following query parameters: response_type=code, client_id with your client ID, redirect_uri with your app’s redirect URI, and scope=read:accounts. Optionally add state with a random value to protect against cross-site request forgery. Example: https://mastodon.social/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https://myapp.com/callback&scope=read:accounts&state=UNIQUE_VALUE.
3. Handle the authorization redirect
   When the user clicks the authorization URL, Mastodon shows a consent screen. The user approves your app. Mastodon then redirects the user’s browser to your redirect URI with a code parameter and the state parameter. Your app must verify that the state value matches the one you sent. If they match, extract the authorization code from the code parameter.
4. Exchange the authorization code for an access token
   Make a POST request from your server to the token endpoint: https://yourinstance.com/oauth/token. Include the following parameters in the request body: grant_type=authorization_code, code with the authorization code you received, client_id with your client ID, client_secret with your client secret, redirect_uri with your app’s redirect URI, and scope=read:accounts. Mastodon responds with a JSON object containing access_token, token_type (Bearer), scope, and created_at. Store the access token securely on your server.
5. Authenticate the user using the access token
   Use the access token to call the Mastodon API endpoint https://yourinstance.com/api/v1/accounts/verify_credentials. Include the header Authorization: Bearer YOUR_ACCESS_TOKEN. Mastodon returns the user’s profile information, including id, username, display_name, and avatar. Use this information to create a session in your application or link the Mastodon account to an existing user account.

Common Mistakes and Things to Avoid During OAuth Setup

Redirect URI Mismatch Causing Authorization Failure

Mastodon strictly validates the redirect URI. If the URI in the authorization request does not exactly match the one registered in the application settings, Mastodon returns an error. Ensure the redirect URI uses the same scheme http vs https, port, path, and query parameters. Register only one redirect URI per application for simplicity. If you need multiple URIs for development and production, create separate applications.

Client Secret Exposed in Client-Side Code

Never include the client secret in client-side JavaScript or mobile app code. The client secret is a server-side credential. If an attacker obtains the client secret, they can impersonate your application and request tokens. Always make the token exchange request from your server. For mobile apps, use the authorization code flow with PKCE Proof Key for Code Exchange instead of the client secret.

Scopes Not Matching Between Authorization Request and Token Exchange

The scopes in the authorization request must match the scopes in the token exchange request. If they differ, Mastodon returns an error. Define scopes once and reuse the same string in both requests. Use the exact scope values that you registered in the application settings.

State Parameter Not Used or Not Verified

Omitting the state parameter or failing to verify it exposes your application to CSRF attacks. An attacker could intercept the authorization redirect and inject a code. Always generate a unique state value for each authorization request, store it in the user’s session, and verify it when the redirect comes back. If the state does not match, reject the request.

OAuth Flow Comparison: Authorization Code vs Implicit Grant

Item	Authorization Code Grant	Implicit Grant
Security	Higher because client secret is never exposed	Lower because token is returned in URL fragment
Token lifetime	Access token plus refresh token for longer sessions	Access token only, no refresh token
Use case	Server-side web apps and mobile apps with backend	Single-page apps and public clients without backend
Mastodon support	Fully supported and recommended	Supported but deprecated and not recommended

The authorization code grant is the recommended flow for Mastodon OAuth. It provides better security and supports refresh tokens. Use the implicit grant only if your application cannot have a server component, and consider using PKCE for additional security.

You can now set up Mastodon OAuth SSO for your external application. Start by registering your application in the Mastodon admin panel and configuring the authorization code flow. Test the flow with a single user before rolling it out to all users. For production, implement token refresh using the refresh token returned by the token endpoint to maintain long-lived sessions without requiring the user to re-authenticate frequently.