OAuth 2.0 Authorization Code Flow with PKCE

Introdução

OAuth 2.0 é um protocolo de autorização padrão da indústria que permite maior controle sobre o escopo de uma aplicação e fluxos de autorização entre múltiplos dispositivos. O OAuth 2.0 permite escolher escopos específicos e granulares que concedem permissões específicas em nome de um usuário. Para habilitar OAuth 2.0 no seu App, você deve habilitá-lo nas configurações de autenticação do App, na seção App settings do Developer Console.

Por quanto tempo minhas credenciais permanecem válidas?

Por padrão, o access token que você cria via Authorization Code Flow com PKCE só permanece válido por duas horas, a menos que você tenha usado o escopo offline.access.

Refresh tokens

Refresh tokens permitem que uma aplicação obtenha um novo access token sem solicitar o usuário, via fluxo de refresh token. Se o escopo offline.access for aplicado, um refresh token OAuth 2.0 será emitido. Com esse refresh token, você obtém um access token. Se esse escopo não for passado, não geraremos um refresh token. Um exemplo da solicitação que você faria para usar um refresh token e obter um novo access token é o seguinte:

POST 'https://api.x.com/2/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'refresh_token=bWRWa3gzdnk3WHRGU1o0bmRRcTJ5VUxWX1lZTDdJSUtmaWcxbTVxdEFXcW5tOjE2MjIxNDc3NDM5MTQ6MToxOnJ0OjE' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_id=rG9n6402A3dbUJKzXTNX4oWHJ

Configurações do App

Você pode selecionar as configurações de autenticação do seu App como OAuth 1.0a ou OAuth 2.0. Também é possível habilitar um App para acessar tanto OAuth 1.0a quanto OAuth 2.0. OAuth 2.0 pode ser usado apenas com a X API v2. Se você selecionou OAuth 2.0, poderá ver um Client ID na seção Keys and Tokens do seu App.

Confidential clients

Confidential clients podem manter credenciais de forma segura, sem expô-las a partes não autorizadas, e se autenticar com segurança no authorization server, mantendo seu client secret protegido. Public clients, como aqueles que normalmente rodam em um navegador ou em um dispositivo móvel, não conseguem usar seus client secrets. Se você selecionar um tipo de App que seja um confidential client, receberá um client secret. Se você selecionou um tipo de client que é confidential client no Developer Console, também poderá ver um Client Secret. Suas opções são Native App, Single page App, Web App, Automated App ou bot. Native App e Single page App são public clients, e Web App e Automated App ou bots são confidential clients. Você não precisa do client id para confidential clients com um header Authorization válido. Ainda é necessário incluir o Client Id no body para as solicitações com um public client.

Escopos

Escopos permitem definir acesso granular ao seu App, para que ele tenha apenas as permissões de que precisa. Para saber mais sobre quais escopos mapeiam para quais endpoints, veja nosso guia de mapeamento de autenticação.


Escopo	Descrição
tweet.read	Todos os Tweets que você pode visualizar, incluindo Tweets de contas protegidas.
tweet.write	Tweet e Retweet por você.
tweet.moderate.write	Ocultar e desocultar respostas aos seus Tweets.
users.email	E-mail de um usuário autenticado.
users.read	Qualquer conta que você pode visualizar, incluindo contas protegidas.
follows.read	Pessoas que seguem você e pessoas que você segue.
follows.write	Seguir e deixar de seguir pessoas por você.
offline.access	Manter conexão à sua conta até você revogar o acesso.
space.read	Todos os Spaces que você pode visualizar.
mute.read	Contas que você mutou.
mute.write	Mutar e desmutar contas por você.
like.read	Tweets que você curtiu e likes que você pode visualizar.
like.write	Curtir e descurtir Tweets por você.
list.read	Lists, membros de list e seguidores de lists que você criou ou das quais é membro, incluindo lists privadas.
list.write	Criar e gerenciar Lists por você.
block.read	Contas que você bloqueou.
block.write	Bloquear e desbloquear contas por você.
bookmark.read	Obter Tweets salvos como bookmark de um usuário autenticado.
bookmark.write	Salvar e remover bookmarks de Tweets.
dm.read	Todas as Direct Messages que você pode visualizar, incluindo Direct Messages de contas protegidas.
dm.write	Enviar e gerenciar Direct Messages por você.
media.write	Enviar mídia.

Rate limits

Na maioria dos casos, os rate limits são os mesmos da autenticação com OAuth 1.0a, com exceção de Tweets lookup e Users lookup. Estamos aumentando o limite por App de 300 para 900 solicitações por 15 minutos ao usar OAuth 2.0 para Tweet lookup e user lookup. Para saber mais, confira nossa documentação sobre rate limits.

Grant types

Fornecemos apenas authorization code com PKCE e refresh token como grant types suportados neste lançamento inicial. Podemos fornecer outros grant types no futuro.

Fluxo OAuth 2.0

O OAuth 2.0 usa um fluxo semelhante ao que utilizamos atualmente para OAuth 1.0a. Você pode ver um diagrama e uma explicação detalhada em nossa documentação sobre este assunto.

Glossário


Termo	Descrição
Grant types	O framework OAuth especifica vários grant types para diferentes casos de uso e um framework para criar novos grant types. Exemplos incluem authorization code, client credentials, device code e refresh token.
Confidential client	Clients são aplicações que podem se autenticar com segurança no authorization server, por exemplo, mantendo seguro o client secret registrado.
Public client	Clients que não podem usar client secrets registrados, como aplicações rodando em um navegador ou em dispositivo móvel.
Authorization code flow	Usado tanto por confidential quanto por public clients para trocar um authorization code por um access token.
PKCE	Uma extensão do authorization code flow para prevenir vários ataques e permitir que a troca OAuth seja realizada de forma segura por public clients.
Client ID	Pode ser encontrado na seção keys and tokens do Developer Console sob o título “Client ID.” Se você não estiver vendo, entre em contato diretamente com nossa equipe. O Client ID é necessário para gerar a authorize URL.
Redirect URI	Sua callback URL. Você precisará de exact match validation.
Authorization code	Permite que uma aplicação chame APIs em nome dos usuários. Também conhecido como auth_code. O auth_code tem um limite de tempo de 30 segundos, uma vez que o dono do App recebe um auth_code aprovado do usuário. Você precisará trocá-lo por um access token em até 30 segundos ou o auth_code expirará.
Access token	Access tokens são os tokens que as aplicações usam para fazer solicitações à API em nome de um usuário.
Refresh token	Permite que uma aplicação obtenha um novo access token sem solicitar o usuário, via fluxo de refresh token.
Client Secret	Se você selecionou um tipo de App que é confidential client, receberá um “Client Secret” abaixo de “Client ID” na seção keys and tokens do seu App.

Parâmetros

Para construir uma authorize URL OAuth 2.0, você precisará garantir que os seguintes parâmetros estejam na URL de autorização.


Parâmetro	Descrição
response_type	Você precisará especificar que este é um code com a palavra “code”.
client_id	Pode ser encontrado no Developer Console sob o título “Client ID”.
redirect_uri	Sua callback URL. Este valor deve corresponder a uma das Callback URLs definidas nas configurações do seu App. Para OAuth 2.0, você precisará de exact match validation para sua callback URL.
state	Uma string aleatória que você fornece para verificar contra ataques CSRF. O comprimento dessa string pode ser de até 500 caracteres.
code_challenge	Um parâmetro do PKCE, um segredo aleatório para cada solicitação que você faz.
code_challenge_method	Especifica o método que você está usando para fazer a solicitação (S256 OU plain).

Authorize URL

Com OAuth 2.0, você cria uma authorize URL que pode usar para permitir que um usuário se autentique via um fluxo de autenticação, semelhante ao “Sign In” com X. Um exemplo da URL que você cria é o seguinte:

https://x.com/i/oauth2/authorize?response_type=code&client_id=M1M5R3BMVy13QmpScXkzTUt5OE46MTpjaQ&redirect_uri=https://www.example.com&scope=tweet.read%20users.read%20account.follows.read%20account.follows.write&state=state&code_challenge=challenge&code_challenge_method=plain

Você precisará ter a codificação correta para essa URL funcionar; consulte nossa documentação sobre percent encoding.

Getting Started

Products

Fundamentals

Partners & Customers

Resources

OAuth 2.0 Authorization Code Flow with PKCE