Come connettersi agli endpoint usando il flusso Authorization Code di OAuth 2.0 con PKCE

​

Come connettersi agli endpoint con il flusso Authorization Code di OAuth 2.0 e PKCE

​

Come connettersi agli endpoint

Per autenticare gli utenti, la tua App deve implementare un flusso di autorizzazione. Questo flusso consente di indirizzare gli utenti a una schermata di autorizzazione su X. Da lì, l’esperienza principale di X mostrerà la schermata di autorizzazione e gestirà l’autorizzazione per conto della tua App. Gli utenti potranno autorizzare la tua App o negare il consenso. Dopo la scelta dell’utente, X lo reindirizzerà alla tua App, dove potrai scambiare il codice di autorizzazione con un access token (se l’utente ha autorizzato la tua App) oppure gestire un rifiuto (se non l’ha autorizzata).

​

Lavorare con client riservati

Se lavori con client riservati, devi utilizzare uno schema di autenticazione Basic per generare un header di autorizzazione con codifica base64 quando invii richieste agli endpoint dei token.

Il userid e la password sono separati da un singolo carattere due punti (”:”) all’interno di una stringa codificata in base64 nelle credenziali.

Un esempio è il seguente:

-header 'Authorization: Basic V1ROclFTMTRiVWhwTWw4M2FVNWFkVGQyTldNNk1UcGphUTotUm9LeDN4NThKQThTbTlKSXQyZm1BanEzcTVHWC1icVozdmpKeFNlR3NkbUd0WEViUA=='

Se l’user agent desidera inviare il Client ID “Aladdin” e la password “open sesame”, utilizzerà il seguente campo di header:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Per creare l’header di autorizzazione Basic devi applicare la codifica base64 al tuo Client ID e Client Secret, che puoi ottenere dalla pagina “Keys and Tokens” della tua App all’interno del developer portal.

​

Passaggi per connettersi con OAuth 2.0

Passaggio 1: Costruire un URL di autorizzazione

La tua App deve creare un URL di autorizzazione verso X, indicando gli scope di cui ha bisogno. Ad esempio, se la tua App deve eseguire lookup di Tweet, utenti e gestire i follow, dovrebbe richiedere i seguenti scope:

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

L’URL conterrà anche i parametri code_challenge e state, oltre agli altri parametri richiesti. In produzione dovresti utilizzare una stringa casuale per il code_challenge.

Passaggio 2: GET oauth2/authorize

Fai autenticare l’utente e invia all’applicazione un codice di autorizzazione. Se hai abilitato OAuth 2.0 per la tua App, puoi trovare il tuo Client ID nella pagina “Keys and Tokens” della tua App.

Un URL di esempio a cui reindirizzare l’utente potrebbe essere simile al seguente:

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

Un URL di esempio con offline_access avrebbe questo aspetto:

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

Al termine dell’autenticazione, all’indirizzo redirect_uri arriverà una richiesta contenente il parametro auth_code. L’applicazione dovrebbe verificare il parametro state.

Esempio di richiesta inviata dal reindirizzamento del client:

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

Passaggio 3: POST oauth2/token - Access Token

A questo punto puoi utilizzare il codice di autorizzazione per creare un access token e un refresh token (solo se è stato richiesto lo scope offline.access). Puoi inviare una richiesta POST al seguente endpoint:

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

Devi impostare l’header Content-Type su application/x-www-form-urlencoded. Inoltre, nella richiesta devi includere: code, grant_type, client_id, redirect_uri e code_verifier.

Ecco un esempio di richiesta di token per un client pubblico:

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'

Ecco un esempio con un client confidenziale:

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'

Passaggio 4: Connettersi alle API

Ora sei pronto per connetterti agli endpoint utilizzando OAuth 2.0. Per farlo, eseguirai la richiesta all’API come faresti con l’autenticazione Bearer Token. Invece di inviare il tuo Bearer Token, utilizzerai l’access token generato nel passaggio precedente. In risposta, dovresti vedere il payload appropriato relativo all’endpoint richiesto. Questa richiesta è identica sia per i client pubblici sia per quelli riservati.

Un esempio della richiesta che effettueresti è il seguente:

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

Passaggio 5: POST oauth2/token - refresh token

Un refresh token consente a un’applicazione di ottenere un nuovo access token senza richiedere l’interazione dell’utente. Puoi generare un refresh token inviando una richiesta POST al seguente endpoint: https://api.x.com/2/oauth2/token. Dovrai aggiungere l’intestazione Content-Type con valore application/x-www-form-urlencoded. Inoltre, dovrai includere il tuo refresh_token, impostare grant_type su refresh_token e specificare il tuo client_id.

Questa richiesta è valida per i client pubblici:

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'

Ecco un esempio per i client confidenziali:

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'

Passaggio 6: POST oauth2/revoke - Revocare il token

Un revoke token invalida un access token o un refresh token. Viene utilizzato per abilitare una funzione di “log out” nei client, consentendo di eliminare eventuali credenziali di sicurezza associate al flusso di autorizzazione che potrebbero non essere più necessarie. Il revoke token è destinato a un’App per revocare un token, non a un utente. È possibile creare una richiesta di revoke token eseguendo una richiesta POST al seguente URL, se l’App desidera revocare in modo programmatico l’accesso che le è stato concesso:

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

Dovrai includere un’intestazione con il Content-Type impostato su application/x-www-form-urlencoded, il tuo token e il tuo client_id.

In alcuni casi, un utente potrebbe voler revocare l’accesso concesso a un’App; può farlo visitando la pagina delle App connesse.

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'

Questa richiesta funzionerà per i client confidenziali:

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'