Autenticarsi all'API

01In una frase #sec_36fbfa52

L'API REVIEWIT accetta solo un metodo di autenticazione — OAuth 2.0 client credentials — e riconosce solo macchine: non esiste alcun modo per chiamare l'API a nome di una persona.

02Un'identità di macchina, mai un utente #sec_ca4b0dd0

È una scelta, non una limitazione da aggirare. Una decisione di ricertificazione trae tutto il suo valore dalla sua imputabilità a una persona che ha guardato, giudicato e che ne risponde. Un'identità di macchina non può portare questo tipo di decisione — quindi l'API non lo consente, e il suo metodo di autenticazione lo rende impossibile piuttosto che sconsigliato.

Concretamente: l'unico flusso autorizzato è client_credentials . I flussi che presuppongono un utente davanti a un browser — codice di autorizzazione, password, implicito — non sono attivati. Un client che li tenta riceve un rifiuto dal server di token, non una pagina di login.

03Ottenere un token #sec_02b8bbd6

Il punto di chiamata è POST /connect/token . Attende i parametri standard del flusso client credentials, in application/x-www-form-urlencoded.

POST /connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=VOTRE_CLIENT_ID
&client_secret=VOTRE_SECRET
&scope=campaigns.read reviews.read

La risposta porta un token di accesso e la sua durata di vita.

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Il token si presenta poi su ogni chiamata, nell'intestazione Authorization.

Authorization: Bearer eyJhbGciOi...

04Quanto dura un token #sec_4d63dc43

Sessanta minuti per impostazione predefinita. Il valore è un'impostazione di distribuzione ( Api:AccessTokenMinutes ): la tua installazione potrebbe averla accorciata, mai allungata senza che l'editore lo sappia.

Non richiedere un token per chiamata. Il punto di chiamata dei token ha il proprio limite di flusso, più basso di quello dei punti di chiamata dei dati: sessanta al minuto. Un client che richiede nuovamente un token ad ogni richiesta esaurisce questo limite molto prima di quello dei dati, e si ritrova bloccato sull'autenticazione mentre il suo quoziente di lettura è intatto. Conserva il token e rinnovalo quando si avvicina alla scadenza.

05Il token è firmato, non è crittografato #sec_fb3f6e49

Il token è un JWT firmato da un certificato. È leggibile: chiunque lo detenga può leggerne il contenuto — l'identificatore del client, le portata concesse, la scadenza.

È deliberato. La riservatezza del trasporto è assicurata da TLS; la crittografia del token non aggiungerebbe nulla contro un attaccante che lo possiede già, e renderebbe illeggibili gli strumenti di diagnostica che aiutano a comprendere un rifiuto. D'altra parte, un token che trapela è un token utilizzabile: va trattato come un segreto fino alla sua scadenza.

06Le portata #sec_682200d2

Una portata è un diritto di lettura o scrittura su un dominio. Il token ne porta solo quello che richiedi, e il client ottiene solo ciò che gli è stato concesso alla registrazione: chiedere di più non dà di più.

Esistono quattro portata senza che alcun punto di chiamata le richieda ancora: campaigns.manage, delegations.manage, collect.trigger e deletions.manage. Sono dichiarate perché il server di token le conosce, e un client può richiederle; oggi non aprono alcuna scrittura, perché i punti di chiamata corrispondenti non esistono ancora. Richiederle non rompe nulla e non serve a nulla.

07Chiedete il minimo possibile #sec_00fcfeab

Una portata concessa rimane concessa. Chiedete quelle di cui l'integrazione ha bisogno, non quelle di cui potrebbe aver bisogno un giorno: quando arriverà quel giorno, una portata si aggiunge in una riga, mentre un token che perde porta via tutto ciò che trasportava.

08Verificare cosa trasporta un token #sec_b38a4efa

Due punti di chiamata diagnostica rispondono alla domanda senza dover decodificare il token manualmente.

GET /api/v1/diagnostics/whoami dice quale cliente siete e quali portate trasportate. GET /api/v1/diagnostics/scope-probe dice se una portata data passa la porta.

Servono per comprendere un rifiuto. Un 403 su una chiamata di dati si diagnostica in tre secondi con il primo, e in tre ore senza di esso.

09Da ricordare #sec_082cfbe9

Un modo di autenticazione, quello delle macchine. Un token di un'ora, conservato e riutilizzato. Delle portate richieste nel modo più preciso. E due punti di chiamata diagnostica che rispondono prima di aprire un ticket.