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 escopooffline.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 escopooffline.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:
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). |