DOCS
HomePer i fornitori di logistica Autenticazione OAuth 2.0

Autenticazione OAuth 2.0

Autentica i tuoi servizi backend con Zonos utilizzando la crittografia a chiave asimmetrica, senza segreti condivisi.

Zonos supporta l'autenticazione da macchina a macchina tramite Concessione token bearer JWT OAuth 2.0 (RFC 7523). Il tuo servizio firma un JWT di breve durata con la tua chiave privata RSA; Zonos lo verifica utilizzando la chiave pubblica registrata e restituisce un token Bearer con ambito della tua organizzazione.

Riepilogo del flusso:

  1. Genera una coppia di chiavi RSA e registra la tua chiave pubblica con Zonos.
  2. In fase di esecuzione, firma un'asserzione JWT con la tua chiave privata e inviala con una richiesta POST all'endpoint del token.
  3. Zonos restituisce un token di accesso di breve durata.
  4. Includi il token di accesso come Authorization: Bearer <token> su ogni richiesta API.

Ciclo di vita e memorizzazione nella cache dei token 

Per impostazione predefinita, i token di accesso scadono dopo 5 minuti. Memorizza il token nella cache e aggiornalo in modo proattivo: non richiedere un nuovo token a ogni chiamata API. Ogni aggiornamento richiede un'asserzione JWT appena firmata.

1import time, requests
2 
3_cache = {"access_token": None, "expires_at": 0}
4 
5def get_access_token():
6 if time.time() < _cache["expires_at"] - 30:
7 return _cache["access_token"]
8 
9 assertion = build_jwt_assertion()
10 data = requests.post(
11 "https://auth.zonos.com/oauth/token",
12 json={
13 "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
14 "assertion": assertion,
15 },
16 ).json()
17 
18 _cache["access_token"] = data["access_token"]
19 _cache["expires_at"] = time.time() + data["expires_in"]
20 return _cache["access_token"]

Riferimento all'errore 

Tutti gli errori seguono il formato di risposta agli errori OAuth 2.0 (RFC 6749 §5.2):

1{
2 "error": "invalid_grant",
3 "error_description": "JWT assertion has expired"
4}
Stato HTTP↕error↕Causa↕
400unsupported_grant_typegrant_type non corrispondeva a urn:ietf:params:oauth:grant-type:jwt-bearer
400invalid_requestCampo mancante o non valido
401invalid_grantFirma non valida, asserzione scaduta, organizzazione sconosciuta o chiave non registrata
500server_errorErrore interno: contattare l'assistenza Zonos se persistente

Cause comuni di invalid_grant:

  • exp è nel passato: assicurati che l'orologio di sistema sia sincronizzato con NTP
  • aud non è esattamente "zonos-auth"
  • iss non corrisponde all'ID dell'organizzazione registrata
  • La chiave pubblica è stata ruotata ma non ancora aggiornata con Zonos

Migliori pratiche di sicurezza 

  • Proteggi la tua chiave privata. Archiviala in un gestore dei segreti dedicato, mai nel controllo del codice sorgente, nelle variabili di ambiente o nei log.
  • Mantieni le affermazioni di breve durata. 60–300 secondi è lo standard; non c'è motivo di emetterne di più lunghi.
  • Includi jti. Un valore univoco per asserzione consente il rilevamento della riproduzione lato server.
  • Ruota periodicamente le coppie di chiavi. Registra una nuova chiave pubblica con Zonos prima di revocare quella vecchia per evitare tempi di inattività.
  • Non registrare mai i valori di access_token o assertion nei log. Tratta entrambi come credenziali.

Questa pagina è stata utile?

Ottieni supporto·Documenti legali·© 2026 Zonos
In questa pagina:
  • Autenticazione OAuth 2.0
  • Generate private key
  • Extract public key
  • Ciclo di vita e memorizzazione nella cache dei token
  • Riferimento all'errore
  • Migliori pratiche di sicurezza