Como se conectar a endpoints usando o Fluxo de Código de Autorização do OAuth 2.0 com PKCE

​

Como conectar-se a endpoints usando o fluxo de Código de Autorização do OAuth 2.0 com PKCE

​

Como se conectar aos endpoints

Para autenticar seus usuários, sua App precisará implementar um fluxo de autorização. Esse fluxo permite direcionar seus usuários a uma tela de autorização no X. A partir daí, a experiência principal do X exibirá a tela de autorização e conduzirá o processo em nome da sua App. Seus usuários poderão autorizar sua App ou recusar a permissão. Depois que o usuário fizer sua escolha, o X o redirecionará para sua App, onde você poderá trocar o código de autorização por um access token (se o usuário autorizou sua App) ou tratar a rejeição (se o usuário não autorizou sua App).

​

Trabalhando com clientes confidenciais

Se você estiver trabalhando com clientes confidenciais, será necessário usar um esquema de autenticação básica para gerar um cabeçalho de autorização com codificação base64 ao fazer solicitações aos endpoints de token.

Os userid e password são separados por um único caractere de dois-pontos (”:”) dentro de uma string codificada em base64 nas credenciais.

Um exemplo seria assim:

-header 'Authorization: Basic V1ROclFTMTRiVWhwTWw4M2FVNWFkVGQyTldNNk1UcGphUTotUm9LeDN4NThKQThTbTlKSXQyZm1BanEzcTVHWC1icVozdmpKeFNlR3NkbUd0WEViUA=='

Se o user agent desejar enviar o Client ID “Aladdin” e a senha “open sesame”, usará o seguinte campo de cabeçalho:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Para criar o cabeçalho de autorização básica, você precisará aplicar codificação base64 ao seu Client ID e Client Secret, que podem ser obtidos na página “Keys and Tokens” da sua App dentro do portal do desenvolvedor.

​

Etapas para se conectar usando OAuth 2.0

Etapa 1: Construir uma URL de autorização

Sua App precisará construir uma URL de autorização para a X, indicando os escopos que a App precisa autorizar. Por exemplo, se sua App precisa consultar Tweets, users e gerenciar follows, ela deve solicitar os seguintes escopos:

tweet.read%20users.read%20follows.read%20follows.write

A URL também conterá os parâmetros code_challenge e state, além de outros parâmetros obrigatórios. Em produção, use uma string aleatória para o code_challenge.

Etapa 2: GET oauth2/authorize

Peça para o usuário se autenticar e enviar para o aplicativo um código de autorização. Se você habilitou OAuth 2.0 para sua App, poderá encontrar seu Client ID na página “Keys and Tokens” da sua App.

Um exemplo de URL para redirecionar o usuário seria semelhante a:

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

Um URL de exemplo com offline_access seria assim:

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

Após a autenticação bem-sucedida, no redirect_uri você receberá uma solicitação contendo o parâmetro auth_code. Seu App deve verificar o parâmetro state.

Um exemplo de solicitação a partir do redirecionamento do cliente seria:

https://www.example.com/?state=state&code=VGNibzFWSWREZm01bjN1N3dicWlNUG1oa2xRRVNNdmVHelJGY2hPWGxNd2dxOjE2MjIxNjA4MjU4MjU6MToxOmFjOjE

Etapa 3: POST oauth2/token - Access Token

Neste ponto, você pode usar o código de autorização para criar um access token e um refresh token (apenas se o escopo offline.access tiver sido solicitado). Você pode fazer uma requisição POST para o seguinte endpoint:

https://api.x.com/2/oauth2/token

Você precisará enviar o Content-Type igual a application/x-www-form-urlencoded em um header. Além disso, sua solicitação deve incluir: code, grant_type, client_id, redirect_uri e code_verifier.

Aqui está um exemplo de solicitação de token para um cliente público:

curl --location --request POST 'https://api.x.com/2/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'code=VGNibzFWSWREZm01bjN1N3dicWlNUG1oa2xRRVNNdmVHelJGY2hPWGxNd2dxOjE2MjIxNjA4MjU4MjU6MToxOmFjOjE' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_id=rG9n6402A3dbUJKzXTNX4oWHJ' \
--data-urlencode 'redirect_uri=https://www.example.com' \
--data-urlencode 'code_verifier=challenge'

Aqui está um exemplo com um cliente confidencial:

curl --location --request POST 'https://api.x.com/2/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic V1ROclFTMTRiVWhwTWw4M2FVNWFkVGQyTldNNk1UcGphUTotUm9LeDN4NThKQThTbTlKSXQyZm1BanEzcTVHWC1icVozdmpKeFNlR3NkbUd0WEViUA=='\
--data-urlencode 'code=VGNibzFWSWREZm01bjN1N3dicWlNUG1oa2xRRVNNdmVHelJGY2hPWGxNd2dxOjE2MjIxNjA4MjU4MjU6MToxOmFjOjE' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'redirect_uri=https://www.example.com' \
--data-urlencode 'code_verifier=challenge'

Etapa 4: Conectar às APIs

Agora você está pronto para se conectar aos endpoints usando OAuth 2.0. Para isso, você fará a solicitação à API como faria ao usar a autenticação Bearer Token. Em vez de enviar seu Bearer Token, use o access token gerado na etapa anterior. Como resposta, você deverá ver o payload apropriado correspondente ao endpoint solicitado. Essa solicitação é a mesma para clientes públicos e confidenciais.

Um exemplo da solicitação que você faria seria o seguinte:

curl --location --request GET 'https://api.x.com/2/tweets?ids=1261326399320715264,1278347468690915330' \
--header 'Authorization: Bearer Q0Mzb0VhZ0V5dmNXSTEyNER2MFNfVW50RzdXdTN6STFxQlVkTGhTc1lCdlBiOjE2MjIxNDc3NDM5MTQ6MToxOmF0OjE'

Etapa 5: POST oauth2/token - refresh token

Um refresh token permite que um aplicativo obtenha um novo access token sem exigir ação do usuário. Você pode criar um refresh token fazendo uma solicitação POST para o seguinte endpoint: https://api.x.com/2/oauth2/token. Você precisará adicionar o Content-Type application/x-www-form-urlencoded em um header. Além disso, será necessário enviar seu refresh_token, definir o grant_type como refresh_token e informar o client_id.

Essa solicitação funciona para clientes públicos:

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'

Aqui está um exemplo de um para clientes confidenciais:

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

Etapa 6: POST oauth2/revoke - Revogar token

Um token de revogação invalida um access token ou refresh token. Ele é usado para habilitar um recurso de “logout” nos clientes, permitindo limpar quaisquer credenciais de segurança associadas ao fluxo de autorização que talvez não sejam mais necessárias. O token de revogação é para uma App revogar um token, e não um usuário. Você pode criar uma solicitação de revogação de token fazendo uma requisição POST para a seguinte URL, caso a App queira revogar programaticamente o acesso concedido a ela:

https://api.x.com/2/oauth2/revoke

Você precisará enviar o Content-Type de application/x-www-form-urlencoded por meio de um cabeçalho, seu token e seu client_id.

Em alguns casos, um usuário pode querer revogar o acesso concedido a um App; ele pode fazer isso visitando a página de Apps conectados.

curl --location --request POST 'https://api.x.com/2/oauth2/revoke' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=Q0Mzb0VhZ0V5dmNXSTEyNER2MFNfVW50RzdXdTN6STFxQlVkTGhTc1lCdlBiOjE2MjIxNDc3NDM5MTQ6MToxOmF0OjE' \
--data-urlencode 'client_id=rG9n6402A3dbUJKzXTNX4oWHJ'

Esta solicitação funcionará para clientes confidenciais:

curl --location --request POST 'https://api.x.com/2/oauth2/revoke' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic V1ROclFTMTRiVWhwTWw4M2FVNWFkVGQyTldNNk1UcGphUTotUm9LeDN4NThKQThTbTlKSXQyZm1BanEzcTVHWC1icVozdmpKeFNlR3NkbUd0WEViUA=='\
--data-urlencode 'token=Q0Mzb0VhZ0V5dmNXSTEyNER2MFNfVW50RzdXdTN6STFxQlVkTGhTc1lCdlBiOjE2MjIxNDc3NDM5MTQ6MToxOmF0OjE'