Flusso di autorizzazione OAuth 2.0 con codice e PKCE

​

Flusso di autorizzazione OAuth 2.0 con codice di autorizzazione e PKCE

​

Introduzione

OAuth 2.0 è un protocollo di autorizzazione standard del settore che consente un controllo più granulare dell’ambito di un’applicazione e dei flussi di autorizzazione su più dispositivi. OAuth 2.0 permette di selezionare ambiti fini e specifici che ti garantiscono determinate autorizzazioni per conto di un utente. 

Per abilitare OAuth 2.0 nella tua App, attivalo nelle impostazioni di autenticazione della tua App, disponibili nella sezione Impostazioni dell’App del developer portal.

​

Per quanto tempo restano valide le mie credenziali?  

Per impostazione predefinita, l’access token che crei tramite l’Authorization Code Flow con PKCE resta valido solo per due ore, a meno che tu non abbia utilizzato lo scope offline.access.

​

Token di refresh

I token di refresh consentono a un’applicazione di ottenere un nuovo access token senza richiedere l’interazione dell’utente, tramite il flusso di refresh token.

Se viene applicato lo scope offline.access, verrà emesso un token di refresh OAuth 2.0. Con questo token di refresh si ottiene un access token. Se questo scope non viene fornito, non genereremo un token di refresh.

Un esempio della richiesta che effettueresti per usare un token di refresh e ottenere un nuovo access token è il seguente:

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

​

Impostazioni dell’App

Puoi impostare l’autenticazione della tua App su OAuth 1.0a oppure OAuth 2.0. Puoi anche abilitare l’App ad accedere a entrambe: OAuth 1.0a e OAuth 2.0.

OAuth 2.0 può essere utilizzato solo con la X API v2. Se selezioni OAuth 2.0, vedrai un Client ID nella sezione Keys and Tokens della tua App. 

​

Client confidenziali

I client confidenziali possono conservare le credenziali in modo sicuro senza esporle a soggetti non autorizzati e autenticarsi in modo sicuro con il server di autorizzazione, mantenendo al sicuro il tuo client secret. I client pubblici, poiché in genere vengono eseguiti in un browser o su un dispositivo mobile, non possono utilizzare i tuoi client secret. Se selezioni un tipo di App che è un client confidenziale, ti verrà fornito un client secret. 

Se nel developer portal hai selezionato un tipo di client che è un client confidenziale, potrai anche vedere un client secret. Le opzioni sono Native App, Single page App, Web App, Automated App o bot. Le Native App e le Single page App sono client pubblici, mentre le Web App e le Automated App o i bot sono client confidenziali.

Non è necessario l’id del client per i client confidenziali con un Authorization Header valido. Devi comunque includere il client id nel body per le richieste effettuate con un client pubblico. 

​

Ambiti

Gli ambiti consentono di impostare un accesso granulare per la tua App, in modo che abbia solo le autorizzazioni necessarie. Per saperne di più su quali ambiti corrispondono a quali endpoint, consulta la nostra guida alla mappatura dell’autenticazione.

Ambito	Descrizione
tweet.read	Tutti i Tweet che puoi visualizzare, inclusi quelli di account protetti.
tweet.write	Pubblica Tweet e Retweet per tuo conto.
tweet.moderate.write	Nascondi e ripristina le risposte ai tuoi Tweet.
users.email	Indirizzo email da un utente autenticato.
users.read	Qualsiasi account che puoi visualizzare, inclusi gli account protetti.
follows.read	Persone che ti seguono e persone che segui.
follows.write	Segui e smetti di seguire persone per tuo conto.
offline.access	Resta connesso al tuo account finché non revochi l’accesso.
space.read	Tutti gli Spaces che puoi visualizzare.
mute.read	Account che hai silenziato.
mute.write	Silenzia e riattiva account per tuo conto.
like.read	Tweet a cui hai messo like e like che puoi visualizzare.
like.write	Metti e rimuovi like ai Tweet per tuo conto.
list.read	Lists, membri delle Lists e follower delle Lists che hai creato o di cui fai parte, incluse quelle private.
list.write	Crea e gestisci Lists per tuo conto.
block.read	Account che hai bloccato.
block.write	Blocca e sblocca account per tuo conto.
bookmark.read	Recupera i Tweet aggiunti ai Segnalibri da un utente autenticato.
bookmark.write	Aggiungi ai Segnalibri e rimuovi Segnalibri dai Tweet.
media.write	Carica contenuti multimediali.

​

Limiti di velocità

Per lo più, i limiti di velocità sono gli stessi dell’autenticazione con OAuth 1.0a, fatta eccezione per il lookup dei Tweet e degli utenti. Stiamo aumentando il limite per App da 300 a 900 richieste ogni 15 minuti quando si utilizza OAuth 2.0 per il lookup dei Tweet e degli utenti. Per ulteriori informazioni, consulta la nostra documentazione sui limiti di velocità.

​

Tipi di grant

Per questo lancio iniziale supportiamo esclusivamente authorization code con PKCE e refresh token come grant types supportati. In futuro potremmo aggiungere altri grant types.

​

Flusso OAuth 2.0

OAuth 2.0 impiega un flusso simile a quello attualmente utilizzato per OAuth 1.0a. È possibile consultare un diagramma e una spiegazione dettagliata nella nostra documentazione su questo argomento. 

​

Glossary

Term	Description
Tipi di grant	Il framework OAuth definisce diversi tipi di grant per differenti casi d’uso e un meccanismo per crearne di nuovi. Esempi includono authorization code, client credentials, device code e refresh token.
Client confidenziale	I client sono applicazioni che possono autenticarsi in modo sicuro con il server di autorizzazione, ad esempio mantenendo al sicuro il proprio client secret registrato.
Client pubblico	I client non possono utilizzare client secret registrati, ad esempio le applicazioni eseguite in un browser o su un dispositivo mobile.
Authorization code flow	Utilizzato sia dai client confidenziali sia da quelli pubblici per scambiare un authorization code con un access token.
PKCE	Un’estensione dell’authorization code flow per prevenire diversi attacchi e consentire di eseguire in modo sicuro lo scambio OAuth dai client pubblici.
Client ID	È reperibile nella sezione chiavi e token del developer portal sotto l’intestazione “Client ID”. Se non lo vedi, contatta direttamente il nostro team. Il Client ID è necessario per generare l’URL di autorizzazione.
Redirect URI	Il tuo callback URL. È necessaria la validazione di corrispondenza esatta.
Authorization code	Consente a un’applicazione di chiamare le API per conto degli utenti. Conosciuto come auth_code. L’auth_code ha una durata di 30 secondi dal momento in cui il proprietario dell’App riceve un auth_code approvato dall’utente. Devi scambiarlo con un access token entro 30 secondi, altrimenti l’auth_code scadrà.
Access token	Gli access token sono i token che le applicazioni utilizzano per effettuare richieste API per conto di un utente.
Refresh token	Consente a un’applicazione di ottenere un nuovo access token senza richiedere l’intervento dell’utente, tramite il refresh token flow.
Client Secret	Se hai selezionato un tipo di App che è un client confidenziale, ti verrà fornito un “Client Secret” sotto “Client ID” nella sezione chiavi e token della tua App.

​

Parametri

Per costruire un URL di autorizzazione OAuth 2.0, assicurati di includere i seguenti parametri nell’URL di autorizzazione.

Parametro	Descrizione
response_type	Devi specificare che si tratta di un code usando la parola “code”.
client_id	Reperibile nel developer portal sotto l’intestazione “Client ID”.
redirect_uri	Il tuo URL di callback. Questo valore deve corrispondere a uno degli URL di callback definiti nelle impostazioni della tua App. Per OAuth 2.0 è richiesta l’exact match validation per l’URL di callback.
state	Una stringa casuale che fornisci per proteggerti da attacchi CSRF. La lunghezza può essere fino a 500 caratteri.
code_challenge	Un parametro PKCE, un segreto casuale per ogni richiesta.
code_challenge_method	Specifica il metodo utilizzato per effettuare la richiesta (S256 oppure plain).

​

URL di autorizzazione 

Con OAuth 2.0 crei un URL di autorizzazione che puoi usare per consentire a un utente di autenticarsi tramite un flusso di autenticazione, simile all’opzione “Accedi” con X. 

Un esempio dell’URL che stai creando è il seguente:

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

Perché questo URL funzioni è necessario utilizzare la codifica corretta; assicurati di consultare la nostra documentazione sulla percent-encoding.