Skip to Content

API

Protegga le Sue API come risorse OAuth: definisca gli scope, controlli l'accesso machine-to-machine e utente, imposti formato e durata dei token.

Un'API rappresenta una risorsa protetta per la quale le applicazioni ottengono access token. La registrazione di un'API comunica alla piattaforma l'identificatore della risorsa (la sua audience), gli scope (autorizzazioni) che espone, quali applicazioni possono chiamarla e come vengono strutturati e firmati gli access token emessi per essa.

Le API si gestiscono nell'Admin Console in Integrazioni → API.

Che cos'è un'API

Ogni API dispone di:

  • un nome: un'etichetta per gli amministratori, e
  • un identificatore: il valore di audience che compare nei token emessi per questa API (ad esempio https://api.example.com).

Per un'API personalizzata può inoltre indicare dei contatti, ovvero i dipendenti a cui rivolgersi in merito. Hanno solo valore informativo e non ricevono alcun diritto.

Esistono due tipi:

  • System API: l'API di gestione della piattaforma stessa. Nome, identificatore e scope sono fissi e non possono essere modificati.
  • Custom API: un'API che Lei registra e governa: ne definisce gli scope, chi può chiamarla e le impostazioni dei token.

Scope (autorizzazioni)

Uno scope è una singola autorizzazione che un token può contenere, ad esempio read:documents oppure orders.write.

  • La System API espone un catalogo fisso di scope di gestione (ad esempio users.read, users.write, groups.read, roles.write, logs.read). Sono gli scope che Lei concede alle applicazioni che chiamano l'API di gestione della piattaforma.
  • Una Custom API espone gli scope definiti da Lei. Nella scheda delle autorizzazioni dell'API, aggiunga ogni scope con un nome e una descrizione. Alcuni scope OpenID Connect riservati (come openid, profile, email, offline_access) non possono essere ridefiniti.

Alcuni scope di gestione si affiancano deliberatamente al proprio scope di base invece di esserne inclusi. Quello da conoscere è users.mfa.read, che copre le registrazioni MFA di un utente (quali secondi fattori sono registrati e quando ciascuno è stato utilizzato l'ultima volta). È richiesto su ogni endpoint che restituisce un utente, comprese le risposte delle chiamate di creazione, aggiornamento, eliminazione, disattivazione e attivazione. Un token che contiene solo users.read o users.write riceve l'utente senza l'elenco delle registrazioni, quindi conceda anche users.mfa.read quando un'integrazione ne ha bisogno.

Chi può chiamare un'API

Due policy indipendenti controllano l'accesso, una per ciascun tipo di chiamante:

Accesso delegato dall'utente

Quando un'applicazione interattiva richiede un token per conto di un utente che ha effettuato l'accesso, la user policy dell'API decide se è consentito:

  • Allow all: qualsiasi applicazione interattiva può richiedere token per questa API.
  • Require grant: solo le applicazioni a cui Lei ha concesso esplicitamente l'accesso possono richiedere token, e solo per gli scope che ha concesso loro.
  • Deny all: nessuna applicazione interattiva può richiedere token.

Accesso machine-to-machine

Quando un'applicazione si autentica per conto proprio con il grant client credentials (senza alcun utente coinvolto), la client policy dell'API decide se è consentito:

  • Require grant: solo le applicazioni a cui Lei ha concesso esplicitamente l'accesso possono richiedere token, limitatamente agli scope concessi.
  • Deny all: nessuna applicazione machine-to-machine può richiedere token.

Concedere l'accesso a un'applicazione

Quando una policy è impostata su require grant, autorizzi un'applicazione dalla scheda Accesso all'applicazione dell'API:

  1. Scelga Aggiungi applicazione nella sezione delegata dall'utente o nella sezione client (machine-to-machine).
  2. Selezioni l'applicazione.
  3. Selezioni gli scope da concedere, oppure scelga Concedi sempre tutte le autorizzazioni per includere automaticamente gli scope attuali e futuri.
  4. Salvi. I token che la piattaforma emette a quell'applicazione per questa API contengono ora gli scope concessi.

Un'applicazione machine-to-machine è in genere del tipo di applicazione machine-to-machine, vedere Applicazioni.

L'elenco delle API nell'Admin Console

Testare un token API

Quando per un'API è autorizzata almeno un'applicazione machine-to-machine (con il grant client credentials), la scheda Test dell'API Le consente di provare un token dall'inizio alla fine senza scrivere codice:

  1. Selezioni una delle applicazioni machine-to-machine autorizzate.
  2. La pagina mostra un esempio di token request pronto all'uso verso il token endpoint, con il client ID e il secret di quell'applicazione e l'identificatore di questa API come audience.
  3. Mostra la token response e decodifica l'access token emesso nei suoi header, payload e firma, così può verificare che audience e scope concessi siano quelli attesi.
  4. Mostra un esempio di chiamata API che invia il token come header Bearer.

Copi i comandi per eseguirli nel Suo terminale. Se la scheda Test Le chiede di autorizzare prima un'applicazione, conceda l'accesso a un'applicazione machine-to-machine nella scheda Accesso all'applicazione e ricarichi la pagina.

Resource indicator e token

Ogni access token che la piattaforma emette per un'API contiene l'identificatore di quell'API come audience, così la risorsa può verificare che il token fosse destinato a lei. Le applicazioni scelgono l'API per cui desiderano un token tramite il resource indicator, il che consente a un'applicazione di detenere token separati, ciascuno con la propria audience, per più API.

Nella scheda delle impostazioni dell'API Lei controlla come sono strutturati questi token:

  • Algoritmo di firma: l'algoritmo asimmetrico (RS256, RS384, RS512 o PS256) utilizzato per firmare i token. Scelga PS256 per un'API chiamata da un'applicazione che utilizza un profilo di sicurezza Financial-grade API: tale profilo firma i token dell'applicazione stessa con PS256 e sconsiglia RS256. Questa impostazione è indipendente dal profilo, quindi deve essere modificata anche qui.
  • Access token lifetime: per quanto tempo un token è valido (il valore predefinito è un giorno).
  • Implicit access token lifetime: una durata più breve applicata ai token emessi tramite i flussi implicit basati su browser (il valore predefinito è due ore).

Una API o più API?

Un access token contiene sempre esattamente una audience. I token con più audience non vengono emessi: un token emesso per un'API non viene accettato da un'altra (vedere L'API come contratto verificabile). Se il Suo backend è un insieme di microservizi, ne deriva una scelta di progettazione:

Una API logica per un dominio di fiducia. Registri una singola API il cui identificatore rappresenta l'intero backend (ad esempio https://api.example.com) e assegni a ogni servizio un proprio namespace di scope (orders.read, inventory.write e così via). Ogni servizio convalida la stessa audience e applica solo i propri scope; il client detiene un unico token per l'intero backend e un nuovo servizio si aggiunge con nuovi scope anziché con una nuova registrazione. Scelga questa opzione quando i servizi vengono sviluppati e gestiti insieme, tipicamente dietro un unico gateway. Tenga presente il compromesso: all'interno dell'audience condivisa i servizi non si isolano più a vicenda tramite il controllo dell'audience (ciascuno accetta un token inviato a un servizio fratello), ma solo tramite gli scope.

Una API per ogni confine di fiducia. Registri API separate quando le risorse hanno livelli di fiducia o proprietari diversi, oppure quando sono coinvolte terze parti. Un client richiede allora un token separato per ogni API tramite il resource indicator (vedere Resource indicator e token), e un servizio backend può scambiare un token già in suo possesso tramite il token exchange. Oltre il confine, il controllo dell'audience mantiene il suo significato: un token intercettato presso un'API non ha alcun valore presso l'altra.

Combinare entrambi gli approcci è comune: una API logica per il nucleo coeso, API separate per le parti che richiedono un isolamento più forte.

Fino a dove inoltrare il token di un utente. Tratti l'access token dell'utente come una credenziale, non come contesto della richiesta. Lo inoltri al massimo di un passaggio, dal client al bordo della Sua API (il gateway o il primo servizio). I servizi più in profondità in una catena di chiamate dovrebbero trovarsi dietro l'audience condivisa dell'API logica oppure ricevere un token più ristretto emesso tramite token exchange; ogni passaggio aggiuntivo compiuto dal token originale amplia i punti in cui un token trapelato può essere riutilizzato.

Token exchange

Il token endpoint supporta OAuth 2.0 Token Exchange (RFC 8693), così che un servizio possa chiamare un'API a valle per conto di un utente che ha effettuato l'accesso senza inoltrare il token originale: l'applicazione scambia un access token utente già in suo possesso con un nuovo token, più ristretto, destinato a un'altra API.

Il grant è deliberatamente limitato al downscoping:

  • Solo un'applicazione web (confidential) può utilizzarlo, e solo quando Token exchange è attivato tra i suoi tipi di grant (vedere Applicazioni).
  • Il subject token deve essere un access token utente ancora valido, emesso alla stessa applicazione che esegue lo scambio. Lo scambio di token di altre applicazioni, di token senza utente o la delega con un actor_token non sono supportati.
  • La richiesta indica esattamente un'API di destinazione tramite resource. La policy di accesso delegato dall'utente dell'API di destinazione si applica all'applicazione che esegue lo scambio come per qualsiasi altra token request.
  • Il token emesso non è mai più ampio del subject token: i suoi scope sono l'intersezione tra gli scope richiesti, gli scope del subject token, gli scope dell'API di destinazione e ciò a cui l'utente ha diritto.
  • Il nuovo token resta legato allo stesso utente e alla stessa sessione e segue le impostazioni di durata dei token dell'API di destinazione.

Esempio di richiesta verso il token endpoint (l'applicazione si autentica come di consueto, ad esempio con il proprio client secret):

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

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=<the user access token>
&subject_token_type=urn:ietf:params:oauth:token-type:access_token
&resource=https://inventory.example.com
&scope=inventory.read

La risposta contiene il nuovo access_token insieme a expires_in e allo scope effettivamente concesso.

Scope e autorizzazioni

Definire uno scope su un'API lo rende solo richiedibile, ma non concede a nessuno l'accesso. Ciò che finisce effettivamente in un token viene deciso separatamente:

  • Per i token machine-to-machine, il token contiene esattamente gli scope autorizzati dal client grant dell'applicazione (vedere Concedere l'accesso a un'applicazione). Un client macchina non ha utente né ruoli, quindi assegnare un ruolo a un'applicazione machine-to-machine non ha alcun effetto: i suoi scope provengono esclusivamente dal grant.
  • Per i token legati a un utente (emessi quando un'app interattiva richiede un token per conto di un utente che ha effettuato l'accesso), il controllo degli accessi basato sui ruoli decide a quali scope l'utente ha diritto. Gli scope che finiscono nel token sono l'intersezione tra ciò che l'applicazione ha richiesto e ciò a cui l'utente ha diritto.

Questa è la risposta abituale alla domanda "perché lo scope che ho richiesto manca senza alcun avviso nel mio token?": lo scope è stato richiesto, ma il chiamante non vi aveva diritto, quindi è stato scartato anziché rifiutato.

Difesa in profondità: uno scope presente in un token è una concessione, non una garanzia. La Sua API dovrebbe comunque applicare i propri controlli a livello di oggetto (questo utente è proprietario di questo record?); un token valido con uno scope ampio non sostituisce l'autorizzazione sulla risorsa stessa.

Controllo degli accessi basato sui ruoli

Nota sul piano: Il controllo degli accessi basato sui ruoli è disponibile a partire dal piano Advanced (e nel Trial).

Una Custom API può attivare RBAC, che consente alla piattaforma di incorporare i ruoli e le autorizzazioni di un utente direttamente nei token che emette per quell'API. Nella scheda delle impostazioni dell'API:

  • Includi ruoli e autorizzazioni (RBAC) lo attiva per l'API.
  • Includi il claim permissions include gli scope concessi all'utente per questa API come claim permissions.
  • Includi il claim roles include i nomi dei ruoli dell'utente come claim roles.

Questi claim vengono aggiunti solo ai token legati a un utente. L'applicazione prende poi le decisioni di autorizzazione in base a tali claim. Per definire i ruoli e assegnarli a utenti e gruppi, vedere Ruoli.

È nell'access token che vanno prese queste decisioni. Un claim roles arriva anche nell'ID token quando un'applicazione richiede lo scope roles, ma quello serve solo alla presentazione, vedere Applicare l'autorizzazione sull'access token, non sull'ID token.

L'API come contratto verificabile

Un'API registrata è, di fatto, un contratto tra Lei e il resource server:

  • Il suo identificatore è stabile e diventa l'audience di ogni token emesso per essa.
  • La piattaforma firma ogni token con la propria chiave di firma (vedere Chiavi di firma).
  • Il resource server convalida il token prima di fidarsi di qualsiasi scope: verifica la firma, che l'issuer sia questa piattaforma e che l'audience corrisponda al proprio identificatore, quindi legge gli scope.

Se uno qualsiasi di questi controlli fallisce, il resource server dovrebbe rifiutare la richiesta senza eccezioni.

Chiamare l'API di gestione (guida rapida machine-to-machine)

Per consentire a uno script o a un servizio backend di chiamare l'API di gestione della piattaforma:

  1. Crei un'applicazione machine-to-machine, vedere Applicazioni.
  2. Nella scheda Accesso all'applicazione della System API, conceda a tale applicazione gli scope di gestione di cui ha bisogno (ad esempio users.read, groups.write). Conceda solo gli scope effettivamente utilizzati dall'integrazione.
  3. Dal Suo servizio, richieda un token con il grant client credentials verso il token endpoint, utilizzando l'identificatore della System API come audience.
  4. Chiami gli endpoint di gestione sotto /api/v1/... con il token restituito nell'header Authorization: Bearer.

La scheda Test della System API genera esattamente questi due comandi, precompilati con un'applicazione reale: li copi come punto di partenza.

Un token smette di funzionare prima della scadenza non appena l'applicazione perde il proprio accesso alla System API, il suo client secret viene ruotato oppure l'applicazione viene eliminata. Il servizio riceve allora HTTP 401 e deve richiedere un nuovo token.

Limiti dei token machine-to-machine

Ai token emessi tramite il grant client credentials si applicano due limiti. Entrambi sono visibili nella panoramica Integrazioni → API. I token per gli accessi interattivi degli utenti non sono mai interessati da nessuno dei due.

Richieste di token al minuto, per client: il limite di throughput. Le richieste oltre tale limite ricevono una risposta HTTP 429 con un header Retry-After; il client può riprovare una volta trascorso il tempo di attesa indicato nell'header.

PianoRichieste di token al minuto
Trial30
Free60
Essential1.200
Advanced6.000
Pro30.000

Token al mese, per l'intero tenant: un budget di volume che esiste solo nei piani di ingresso. Copre tutte le applicazioni machine-to-machine e tutte le API insieme e viene azzerato il 1° di ogni mese. Una volta esaurito, le ulteriori richieste client credentials ricevono la risposta access_denied fino all'inizio del mese successivo.

PianoToken al mese
Trial / Free1.000
Essential e superioriIllimitati

Un client che memorizza nella cache il proprio access token per l'intera durata del token necessita di circa 720 token al mese e resta ben al di sotto di entrambi i limiti, quindi di norma uno dei due viene raggiunto solo da un client che richiede un nuovo token per ogni singola chiamata API. Memorizzi il token nella cache del servizio chiamante e lo riutilizzi fino a poco prima della scadenza; la durata del token si configura per ogni API nella scheda delle impostazioni dell'API.

Riferimento per sviluppatori / API

La piattaforma include una documentazione API interattiva integrata nel prodotto all'indirizzo /admin/api-docs. Elenca ogni endpoint di gestione con i relativi parametri, consente di provare le chiamate nel browser e permette di scaricare dalla stessa pagina la definizione OpenAPI in formato leggibile dalle macchine.

L'API di gestione copre l'amministrazione di utenti, gruppi, organizzazioni, applicazioni, ruoli, log e dispositivi. Utilizzi /admin/api-docs come riferimento autorevole per gli endpoint, anziché un elenco statico in questa pagina.

Riferimento

TermineSignificato
Identificatore (audience)Il valore che identifica l'API; compare nei token emessi per essa.
Scope / autorizzazioneUna singola capacità che un token può contenere.
User policySe le applicazioni interattive possono ottenere token per conto di un utente.
Client policySe le applicazioni possono ottenere token per sé stesse (machine-to-machine).
GrantUn'autorizzazione esplicita di un'applicazione a chiamare questa API con scope specifici.
RBACL'incorporazione dei ruoli e delle autorizzazioni di un utente nei token dell'API.
Token exchangeLo scambio di un access token utente con un token più ristretto destinato a un'altra API (RFC 8693).

Risoluzione dei problemi

  • La token request viene rifiutata con uno scope non valido. Un'applicazione può richiedere solo gli scope che le sono stati concessi sull'API. Aggiunga lo scope al grant dell'applicazione per questa API, quindi richieda un nuovo token.
  • Le chiamate restituiscono un errore di scope insufficiente anche se è stato emesso un token. Una richiesta riesce solo se il token contiene effettivamente lo scope richiesto dall'endpoint. Decodifichi il token e verifichi che gli scope concessi lo includano; gli scope non concessi all'applicazione vengono scartati dal token senza alcun avviso.
  • Il token ha l'audience sbagliata. Il token deve essere richiesto per l'identificatore (audience) di questa API. Un token emesso per un'altra API, o senza audience, non viene accettato qui.
  • Il test del token non restituisce nulla o restituisce un errore. Il test emette un token per l'applicazione e gli scope selezionati. Si assicuri che l'applicazione disponga di un grant attivo su questa API e che sia selezionato almeno uno scope.
  • Un token exchange viene rifiutato. Il subject token deve essere un access token legato a un utente, ancora valido ed emesso alla stessa applicazione che esegue lo scambio; l'applicazione deve avere attivato il grant token exchange e la richiesta deve indicare esattamente un'API di destinazione tramite resource. I token machine-to-machine (senza utente) non possono essere scambiati.

Vedere anche il glossario.

In questa pagina