Fluxo de código de autorização do OAuth 2.0 com PKCE

​

Fluxo de Código de Autorização OAuth 2.0 com PKCE

​

Introdução

OAuth 2.0 é um protocolo de autorização padrão do setor que oferece maior controle sobre o escopo de uma App e sobre os fluxos de autorização em vários dispositivos. O OAuth 2.0 permite selecionar escopos granulares específicos, que concedem permissões precisas em nome de um usuário.

Para habilitar o OAuth 2.0 na sua App, ative-o nas configurações de autenticação da App, localizadas na seção de configurações da App no portal do desenvolvedor.

​

Por quanto tempo minhas credenciais permanecerão válidas?  

Por padrão, o access token que você cria por meio do Authorization Code Flow with PKCE permanecerá válido por apenas duas horas, a menos que você tenha usado o escopo offline.access.

​

Refresh tokens

Refresh tokens permitem que um aplicativo obtenha um novo access token sem solicitar interação do usuário, por meio do fluxo de refresh token.

Se o escopo offline.access for aplicado, um refresh token do OAuth 2.0 será emitido. Com esse refresh token, você obtém um access token. Se esse escopo não for enviado, 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 da App

Você pode definir as configurações de autenticação da sua App como OAuth 1.0a ou OAuth 2.0. Você também pode habilitar uma App para usar tanto OAuth 1.0a quanto OAuth 2.0.

OAuth 2.0 só pode ser usado com a X API v2. Se você selecionar OAuth 2.0, poderá ver um Client ID na seção Keys and Tokens da sua App. 

​

Clientes confidenciais

Clientes confidenciais podem manter credenciais de forma segura, sem expô-las a partes não autorizadas, e se autenticar com segurança no servidor de autorização, mantendo seu client secret protegido. Clientes públicos, por normalmente serem executados em um navegador ou em um dispositivo móvel, não conseguem usar client secrets. Se você selecionar um tipo de App que seja um cliente confidencial, receberá um client secret. 

Se você selecionou no portal do desenvolvedor um tipo de cliente que seja confidencial, 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 clientes públicos; Web App e Automated App ou bots são clientes confidenciais.

Você não precisa de id do cliente para clientes confidenciais quando houver um Authorization Header válido. Ainda é necessário incluir Client Id no corpo das requisições feitas com um cliente público. 

​

Escopos

Os escopos permitem definir acessos granulares para sua App, garantindo que ela tenha apenas as permissões necessárias. Para saber mais sobre quais escopos correspondem a quais endpoints, consulte 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	Publicar Tweets e fazer Retweet por você.
tweet.moderate.write	Ocultar e reexibir 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	Permanecer conectado à sua conta até você revogar o acesso.
space.read	Todos os Spaces que você pode visualizar.
mute.read	Contas que você silenciou.
mute.write	Silenciar e reativar contas por você.
like.read	Tweets que você curtiu e likes que você pode visualizar.
like.write	Curtir e remover like em Tweets por você.
list.read	Lists, membros de Lists e seguidores de Lists que você criou ou das quais você é 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 com Bookmark de um usuário autenticado.
bookmark.write	Adicionar e remover Bookmarks de Tweets.
media.write	Enviar mídia.

​

Limites de requisições

Em geral, os limites de requisições são os mesmos que ao autenticar com OAuth 1.0a, com exceção das pesquisas de Tweets e de usuários. Estamos aumentando o limite por App de 300 para 900 requisições por 15 minutos ao usar OAuth 2.0 para pesquisa de Tweet e de usuário. Para saber mais, confira nossa documentação sobre limites de requisições.

​

Tipos de concessão

Neste lançamento inicial, oferecemos apenas authorization code com PKCE e refresh token como grant types compatíveis. Podemos disponibilizar mais tipos de concessão no futuro.

​

Fluxo do OAuth 2.0

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

​

Glossário

Termo	Descrição
Tipos de concessão	O framework OAuth especifica vários tipos de concessão para diferentes casos de uso e também um framework para criar novos tipos de concessão. Exemplos incluem authorization code, client credentials, device code e refresh token.
Cliente confidencial	Clientes são aplicativos que conseguem se autenticar com segurança no servidor de autorização, por exemplo, mantendo seu client secret registrado em sigilo.
Cliente público	Clientes que não podem usar client secrets registrados, como aplicativos executados em um navegador ou dispositivo móvel.
Fluxo de authorization code	Usado por clientes confidenciais e públicos para trocar um authorization code por um access token.
PKCE	Uma extensão do fluxo de authorization code para prevenir diversos ataques e permitir realizar a troca OAuth com segurança a partir de clientes públicos.
Client ID	Pode ser encontrado na seção de chaves e tokens do portal do desenvolvedor, sob o cabeçalho “Client ID”. Se você não visualizar isso, entre em contato diretamente com nossa equipe. O Client ID será necessário para gerar a URL de authorize.
Redirect URI	Sua callback URL. Você precisará ter validação de correspondência exata.
Authorization code	Permite que um aplicativo acesse APIs em nome de usuários. Conhecido como auth_code. O auth_code tem um limite de tempo de 30 segundos a partir do momento em que o proprietário da App recebe um auth_code aprovado do usuário. Você terá que trocá-lo por um access token dentro de 30 segundos, ou o auth_code expirará.
Access token	Access tokens são o token que aplicativos usam para fazer solicitações à API em nome de um usuário.
Refresh token	Permite que um aplicativo obtenha um novo access token sem solicitar ação do usuário, por meio do fluxo de refresh token.
Client Secret	Se você selecionou um tipo de App que é um cliente confidencial, você receberá um “Client Secret” sob “Client ID” na seção de chaves e tokens da sua App.

​

Parâmetros

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

Parâmetro	Descrição
response_type	Especifique que se trata de um código usando a palavra “code”.
client_id	Pode ser encontrado no portal do desenvolvedor sob o rótulo “Client ID”.
redirect_uri	Sua URL de callback. Esse valor deve corresponder a um dos Callback URLs definidos nas configurações da sua App. Para OAuth 2.0, é necessário ter validação de correspondência exata para sua URL de callback.
state	Uma string aleatória fornecida por você para proteção contra ataques CSRF. O comprimento dessa string pode ser de até 500 caracteres.
code_challenge	Um parâmetro PKCE: um segredo aleatório para cada solicitação.
code_challenge_method	Especifica o método usado para fazer a solicitação (S256 ou plain).

​

URL de autorização 

Com o OAuth 2.0, você cria uma URL de autorização que pode ser usada para permitir que um usuário se autentique por meio de um fluxo de autenticação, semelhante ao “Entrar com X”. 

Um exemplo da URL que você está criando é 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á usar a codificação adequada para que esta URL funcione. Consulte nossa documentação sobre codificação por porcentagem.