Login Único com OAuth no Mastodon: Configuração Passo a Passo

Você quer permitir que usuários façam login no seu site ou aplicativo usando a conta do Mastodon. O Mastodon suporta OAuth 2.0, que permite que serviços externos autentiquem usuários sem compartilhar a senha do Mastodon. Essa configuração habilita o login único (SSO) para sua instância do Mastodon, facilitando o acesso dos usuários a ferramentas conectadas. Neste artigo, você aprenderá a registrar um aplicativo na sua instância do Mastodon, configurar os endpoints OAuth e implementar o fluxo de código de autorização.

O que é OAuth do Mastodon e como funciona para SSO

OAuth 2.0 é um padrão aberto para autenticação baseada em token. O Mastodon implementa o fluxo de concessão de código de autorização, que é o método mais seguro para SSO. Nesse fluxo, seu aplicativo externo nunca vê a senha do Mastodon do usuário. Em vez disso, o usuário aprova a solicitação de acesso do seu aplicativo na própria instância do Mastodon. O Mastodon então emite um código de autorização de curta duração para seu aplicativo, que você troca por um token de acesso e um token de atualização. O token de acesso permite que seu aplicativo leia o perfil do usuário e execute ações com base nos escopos solicitados.

Antes de começar, você precisa do seguinte:

• Uma instância do Mastodon onde você tenha privilégios de administrador. Você precisa de acesso ao painel de administração para registrar aplicativos.
• A URL base da sua instância do Mastodon. Por exemplo, https://mastodon.social ou a URL da sua própria instância.
• A URI de redirecionamento do seu aplicativo externo. Este é o endpoint no seu aplicativo para onde o Mastodon enviará o código de autorização após o usuário aprovar a solicitação.

Escopos OAuth necessários

Ao registrar seu aplicativo, você deve especificar quais escopos seu aplicativo precisa. Para SSO, o escopo mais comum é read:accounts, que permite que seu aplicativo leia as informações do perfil do usuário, como nome de usuário, nome de exibição e avatar. Se seu aplicativo precisar publicar em nome do usuário, você precisará de write:statuses. Você pode selecionar vários escopos. Mantenha os escopos mínimos para seguir o princípio do menor privilégio.

Passos para configurar OAuth do Mastodon para login único

1. Registre um novo aplicativo na sua instância do Mastodon
   Faça login no painel de administração da sua instância do Mastodon. Navegue até Preferências > Administração > Aplicativos. Clique no botão Novo Aplicativo. Digite um nome para seu aplicativo, por exemplo MeuAppSSO. Insira a URI de redirecionamento do seu aplicativo externo. Selecione os escopos necessários, como read:accounts. Clique em Enviar. O Mastodon gera um client ID e um client secret. Copie e salve esses valores com segurança.
2. Construa a URL de autorização
   Monte a URL que redireciona os usuários para sua instância do Mastodon para autenticação. A URL base é https://suainstancia.com/oauth/authorize. Adicione os seguintes parâmetros de consulta: response_type=code, client_id com seu client ID, redirect_uri com a URI de redirecionamento do seu aplicativo e scope=read:accounts. Opcionalmente, adicione state com um valor aleatório para proteção contra falsificação de solicitação entre sites. Exemplo: https://mastodon.social/oauth/authorize?response_type=code&client_id=SEU_CLIENT_ID&redirect_uri=https://meuapp.com/callback&scope=read:accounts&state=VALOR_UNICO.
3. Lide com o redirecionamento de autorização
   Quando o usuário clicar na URL de autorização, o Mastodon exibirá uma tela de consentimento. O usuário aprova seu aplicativo. O Mastodon então redireciona o navegador do usuário para sua URI de redirecionamento com um parâmetro code e o parâmetro state. Seu aplicativo deve verificar se o valor de state corresponde ao que você enviou. Se corresponder, extraia o código de autorização do parâmetro code.
4. Troque o código de autorização por um token de acesso
   Faça uma solicitação POST do seu servidor para o endpoint de token: https://suainstancia.com/oauth/token. Inclua os seguintes parâmetros no corpo da solicitação: grant_type=authorization_code, code com o código de autorização recebido, client_id com seu client ID, client_secret com seu client secret, redirect_uri com a URI de redirecionamento do seu aplicativo e scope=read:accounts. O Mastodon responde com um objeto JSON contendo access_token, token_type (Bearer), scope e created_at. Armazene o token de acesso com segurança no seu servidor.
5. Autentique o usuário usando o token de acesso
   Use o token de acesso para chamar o endpoint da API do Mastodon https://suainstancia.com/api/v1/accounts/verify_credentials. Inclua o cabeçalho Authorization: Bearer SEU_TOKEN_DE_ACESSO. O Mastodon retorna as informações do perfil do usuário, incluindo id, username, display_name e avatar. Use essas informações para criar uma sessão no seu aplicativo ou vincular a conta do Mastodon a uma conta de usuário existente.

Erros comuns e o que evitar durante a configuração do OAuth

Incompatibilidade de URI de redirecionamento causando falha na autorização

O Mastodon valida rigorosamente a URI de redirecionamento. Se a URI na solicitação de autorização não corresponder exatamente à registrada nas configurações do aplicativo, o Mastodon retorna um erro. Certifique-se de que a URI de redirecionamento use o mesmo esquema (http vs https), porta, caminho e parâmetros de consulta. Registre apenas uma URI de redirecionamento por aplicativo para simplificar. Se precisar de várias URIs para desenvolvimento e produção, crie aplicativos separados.

Client secret exposto no código do lado do cliente

Nunca inclua o client secret em JavaScript do lado do cliente ou código de aplicativo móvel. O client secret é uma credencial do lado do servidor. Se um invasor obtiver o client secret, ele pode se passar pelo seu aplicativo e solicitar tokens. Sempre faça a solicitação de troca de token a partir do seu servidor. Para aplicativos móveis, use o fluxo de código de autorização com PKCE (Proof Key for Code Exchange) em vez do client secret.

Escopos não correspondentes entre a solicitação de autorização e a troca de token

Os escopos na solicitação de autorização devem corresponder aos escopos na solicitação de troca de token. Se forem diferentes, o Mastodon retorna um erro. Defina os escopos uma vez e reutilize a mesma string em ambas as solicitações. Use os valores de escopo exatos que você registrou nas configurações do aplicativo.

Parâmetro state não usado ou não verificado

Omitir o parâmetro state ou não verificá-lo expõe seu aplicativo a ataques CSRF. Um invasor pode interceptar o redirecionamento de autorização e injetar um código. Sempre gere um valor state único para cada solicitação de autorização, armazene-o na sessão do usuário e verifique-o quando o redirecionamento retornar. Se o state não corresponder, rejeite a solicitação.

Comparação de fluxos OAuth: Código de Autorização vs Concessão Implícita

Item	Concessão de Código de Autorização	Concessão Implícita
Segurança	Maior porque o client secret nunca é exposto	Menor porque o token é retornado no fragmento da URL
Vida útil do token	Token de acesso mais token de atualização para sessões mais longas	Apenas token de acesso, sem token de atualização
Caso de uso	Aplicativos web do lado do servidor e aplicativos móveis com backend	Aplicativos de página única e clientes públicos sem backend
Suporte do Mastodon	Totalmente suportado e recomendado	Suportado, mas obsoleto e não recomendado

A concessão de código de autorização é o fluxo recomendado para OAuth no Mastodon. Ele oferece melhor segurança e suporte a tokens de atualização. Use a concessão implícita apenas se seu aplicativo não puder ter um componente de servidor e considere usar PKCE para segurança adicional.

Agora você pode configurar o SSO com OAuth do Mastodon para seu aplicativo externo. Comece registrando seu aplicativo no painel de administração do Mastodon e configurando o fluxo de código de autorização. Teste o fluxo com um único usuário antes de disponibilizá-lo para todos. Para produção, implemente a atualização de token usando o token de atualização retornado pelo endpoint de token para manter sessões de longa duração sem exigir que o usuário se autentique novamente com frequência.