Autenticazione App only e OAuth 2.0 Bearer Token

​

Autenticazione App only e OAuth 2.0 Bearer Token

X offre alle applicazioni la possibilità di inviare richieste autenticate per conto dell’applicazione stessa, anziché per conto di uno specifico utente. L’implementazione di X si basa sul flusso Client Credentials Grant della specifica OAuth 2.

L’autenticazione App only non include alcun contesto utente ed è una forma di autenticazione in cui un’applicazione effettua richieste all’API per proprio conto. Questo metodo è pensato per sviluppatori che necessitano solo di accesso in sola lettura alle informazioni pubbliche.

È possibile eseguire l’autenticazione App only utilizzando le consumer API keys della tua App oppure utilizzando un App only Access Token (Bearer Token). Questo significa che le uniche richieste che puoi effettuare verso una X API non devono richiedere un utente autenticato.

Con l’autenticazione App only puoi eseguire azioni come:

• Recuperare le timeline degli utenti
• Accedere agli amici e ai follower di qualsiasi account
• Accedere alle risorse delle List
• Cercare Tweet

Tieni presente che solo OAuth 1.0a o il OAuth 2.0 Authorization Code Flow con PKCE sono richiesti per inviare richieste per conto degli utenti. La pagina API reference descrive il metodo di autenticazione richiesto per utilizzare un’API. Avrai bisogno di autenticazione utente (contesto utente) con un access token per eseguire le seguenti operazioni:

• Pubblicare Tweet o altre risorse
• Cercare utenti
• Utilizzare qualsiasi endpoint geo
• Accedere ai Messaggi Diretti o alle credenziali dell’account
• Recuperare gli indirizzi email degli utenti

​

Flusso di autenticazione

Per utilizzare questo metodo, devi usare un App only Access Token (noto anche come Bearer Token). Puoi generare un App only Access Token (Bearer Token) passando la consumer key e la consumer secret all’endpoint POST oauth2/token.

Il flusso di autenticazione application-only prevede questi passaggi:

• L’applicazione codifica la propria consumer key e consumer secret in un set di credenziali appositamente codificato.
• L’applicazione invia una richiesta all’endpoint POST oauth2/token per scambiare queste credenziali con un App only Access Token.
• Quando accede alla REST API, l’applicazione utilizza l’App only Access Token per autenticarsi.

Poiché non è necessario firmare la richiesta, questo approccio è molto più semplice rispetto al modello standard OAuth 1.0a.

​

Informazioni sull’autenticazione App only

I token sono password

Tieni presente che la consumer key e il secret e l’App only Access Token (Bearer Token) concedono l’accesso per effettuare richieste per conto di un’applicazione. Questi valori devono essere considerati sensibili quanto le password e non devono essere condivisi o distribuiti a soggetti non affidabili.

SSL obbligatorio

Tutte le richieste (sia per ottenere sia per utilizzare i token) devono utilizzare endpoint HTTPS. Segui le best practice descritte in Connessione a X API tramite TLS — i peer devono sempre essere verificati.

Nessun contesto utente

Quando si inviano richieste utilizzando l’autenticazione App only, non esiste il concetto di “utente corrente”. Pertanto, endpoint come POST statuses/update non funzioneranno con l’autenticazione App only. Vedi uso di OAuth per ulteriori informazioni sull’invio di richieste per conto di un utente.

Rate limiting

Le applicazioni dispongono di due tipi di pool di rate limiting.

Le richieste effettuate per conto degli utenti con access token, note anche come contesto utente, attingono da un contesto di rate limiting diverso da quello utilizzato nell’autenticazione App only. In altre parole, le richieste effettuate per conto degli utenti non consumeranno i limiti di velocità disponibili tramite l’autenticazione App only, e le richieste effettuate tramite l’autenticazione App only non consumeranno i limiti di velocità usati nell’autenticazione basata su utente.

Per saperne di più su API Rate Limiting e verifica i limiti.

​

Invio di richieste in modalità App only

Passaggio 1: Codificare consumer key e consumer secret

I passaggi per codificare la consumer key e la consumer secret di un’app in un set di credenziali per ottenere un Bearer Token sono:

1. Eseguire la codifica URL (URL encode) della consumer key e della consumer secret secondo la RFC 1738. Nota: al momento della stesura, questo non modifica effettivamente la consumer key e la consumer secret, ma è comunque consigliabile eseguire questo passaggio nel caso in cui il formato di tali valori cambi in futuro.
2. Concatenare la consumer key codificata, un carattere due punti ”:” e la consumer secret codificata in un’unica stringa.
3. Eseguire la codifica Base64 della stringa ottenuta al passaggio precedente.

Di seguito sono riportati valori di esempio che mostrano il risultato di questo algoritmo. Nota che la consumer secret utilizzata in questa pagina è solo a scopo di test e non funzionerà per richieste reali.

Consumer key	xvz1evFS4wEEPTGEFPHBog
Consumer secret	L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg
Consumer key codificata secondo RFC 1738 (nessuna modifica)	xvz1evFS4wEEPTGEFPHBog
Consumer secret codificata secondo RFC 1738 (nessuna modifica)	L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg
Credenziali del Bearer Token	xvz1evFS4wEEPTGEFPHBog:L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg
Credenziali del Bearer Token codificate in Base64	:: eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJnNmllS0dFS2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw==

Passaggio 2: Ottenere un App only Access Token (Bearer Token)

Il valore calcolato nel passaggio 1 deve essere scambiato con un App only Access Token emettendo una richiesta a POST oauth2/token:

• La richiesta deve essere un’HTTP POST.
• La richiesta deve includere un’intestazione Authorization con il valore Basic <base64 encoded value from step 1>.
• La richiesta deve includere un’intestazione Content-Type con il valore application/x-www-form-urlencoded;charset=UTF-8.
• Il corpo della richiesta deve essere grant_type=client_credentials.

Esempio di richiesta (l’intestazione Authorization è stata spezzata):

POST /oauth2/token HTTP/1.1
Host: api.x.com
User-Agent: My X App v1.0.23
Authorization: Basic eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJn
                     NmllS0dFK2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw==
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Content-Length: 29
Accept-Encoding: gzip

grant\_type=client\_credentials

Se la richiesta è formattata correttamente, il server risponderà con un payload codificato in JSON:

Risposta di esempio:

HTTP/1.1 200 OK
Status: 200 OK
Content-Type: application/json; charset=utf-8
...
Content-Encoding: gzip
Content-Length: 140

{"token\_type":"bearer","access\_token":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"}

Le applicazioni devono verificare che il valore associato alla chiave token_type dell’oggetto restituito sia bearer. Il valore associato alla chiave access_token è l’App only Access Token (Bearer Token).

Nota che un App only Access Token è valido per un’applicazione alla volta. L’invio di un’altra richiesta con le stesse credenziali a /oauth2/token restituirà lo stesso token finché non viene invalidato.

Passaggio 3: Autenticare le richieste API con l’App only Access Token (Bearer Token)

L’App only Access Token (Bearer Token) può essere utilizzato per inviare richieste agli endpoint API che supportano l’autenticazione solo applicativa. Per utilizzare l’App Access Token, crea una normale richiesta HTTPS e includi un’intestazione Authorization con il valore Bearer <base64 bearer token value from step 2>. Signing is not required.

Esempio di richiesta (l’intestazione Authorization è stata spezzata su più righe):

GET /1.1/statuses/user\_timeline.json?count=100&screen\_name=twitterapi HTTP/1.1
Host: api.x.com
User-Agent: My X App v1.0.23
Authorization: Bearer AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAA
                      AAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
Accept-Encoding: gzip

Invalidazione di un App only Access Token (Bearer Token)

Se un App only Access Token viene compromesso o deve essere invalidato per qualsiasi motivo, invia una chiamata a POST oauth2/invalidate_token.

Esempio di richiesta (l’intestazione Authorization è stata a capo):

POST /oauth2/invalidate_token HTTP/1.1
Authorization: Basic eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJn
                     NmllS0dFS2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw==
User-Agent: La mia X App v1.0.23
Host: api.x.com
Accept: */*
Content-Length: 119
Content-Type: application/x-www-form-urlencoded

access_token=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA

Esempio di risposta:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 127
...

{"access_token":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"}

​

Casi comuni di errore

Questa sezione descrive alcuni errori comuni nella negoziazione e nell’uso dei Bearer Token. Tieni presente che non tutte le possibili risposte di errore sono incluse qui: presta attenzione a codici e risposte di errore non gestiti.

Richieste non valide per ottenere o revocare un App only Access Token

Tentativi di:

• Ottenere un App only Access Token (Bearer Token) con una richiesta non valida (ad esempio, omettendo grant_type=client_credentials).
• Ottenere o revocare un App only Access Token (Bearer Token) con credenziali dell’App errate o scadute.
• Invalidare un App only Access Token (Bearer Token) non corretto o già revocato.
• Ottenere un App only Access Token (Bearer Token) troppo frequentemente in un breve intervallo di tempo.

Comporteranno:

HTTP/1.1 403 Forbidden
Content-Length: 105
Content-Type: application/json; charset=utf-8
...

{"errors":\[{"code":99,"label":"authenticity\_token\_error","message":"Impossibile verificare le credenziali"}\]}

​

La richiesta all’API contiene un App only Access Token (Bearer Token) non valido

L’uso di un Access Token errato o revocato per effettuare richieste all’API comporterà:

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 61
...

{"errors":\[{"message":"Token non valido o scaduto","code":89}\]}

​

App only Access Token (Bearer Token) utilizzato su un endpoint che non supporta l’autenticazione App only

Inviare una richiesta a un endpoint che richiede un contesto utente (ad esempio statuses/home_timeline) con un App only Access Token (Bearer Token) produrrà:

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
Content-Length: 91
...

{"errors":\[{"message":"Le tue credenziali non consentono l'accesso a questa risorsa","code":220}\]}