Menu della documentazione
Specifico per il partner Ultimo aggiornamento: 27 luglio 2026

Test e lancio

Verifica OAuth, identità, isolamento degli utenti, contratti delle risorse, gestione degli errori e prontezza per la produzione.

Prima del rilascio delle credenziali di produzione, testa l’intera integrazione nell’ambiente di test di Parkour Design. I controlli automatici dimostrano che protocollo e contratto funzionano; l’accettazione manuale dimostra il percorso utente e il ripristino operativo.

Regola di lancio: un callback di autorizzazione riuscito non basta per l’accettazione. Il lancio richiede verifica dell’identità, isolamento degli utenti, rotazione dei token, test del contratto delle risorse, ripristino dagli errori e approvazione di entrambi i team.

Prerequisiti dei test

Parkour Design e il partner devono preparare:

  • un client di test registrato e un segreto consegnato in modo sicuro;
  • un URI di reindirizzamento di test esatto;
  • l’insieme di scope approvato;
  • almeno due utenti di test di Parkour Design;
  • eventi e progetti posseduti separatamente da ciascun utente;
  • un account o un evento vuoto, dove pertinente;
  • contatti tecnici e per gli incidenti;
  • risultati attesi per ogni caso di accettazione.

Usa l’emittente di test:

https://parkour-test.web.app

Non riusare in produzione credenziali, URL di callback, token o dati utente di test.

Controlli iniziali

Discovery

curl --fail-with-body \
  "https://parkour-test.web.app/.well-known/openid-configuration"

Verifica che:

  • issuer corrisponda esattamente all’emittente di test configurato;
  • gli endpoint di autorizzazione, token, UserInfo e JWKS usino HTTPS;
  • siano presenti code, authorization_code, refresh_token, RS256 e S256;
  • nel discovery non compaia alcun client secret né altro valore privato dell’ambiente.

Chiavi di firma

Carica il jwks_uri dal discovery e verifica che ogni chiave utilizzabile abbia kid, kty, uso di firma e un algoritmo approvato. Il client deve gestire un kid sconosciuto aggiornando una volta il JWKS prima di rifiutare il token.

Richiesta di risorse senza autenticazione

curl --include "https://parkour-test.web.app/api/events"

Risultato atteso:

HTTP/2 401
Content-Type: application/json

{"error":"invalid_token"}

Test OAuth automatici

Automatizza questi casi al confine del partner. Usa dati di test controllati e simula il passaggio esterno nel browser solo quando un test completo nel browser non è pratico.

Richiesta di autorizzazione

  • contiene esattamente client ID, URI di reindirizzamento e scope approvati;
  • genera valori state, nonce e verificatori PKCE univoci e ad alta entropia;
  • invia code_challenge_method=S256;
  • non mette nell’URL il client secret né il verificatore;
  • in un test negativo dell’ambiente rifiuta un URI di reindirizzamento non registrato o leggermente diverso.

Callback

  • accetta lo state corretto una sola volta;
  • rifiuta uno state mancante, errato, scaduto o riusato;
  • gestisce access_denied senza scambiare un codice;
  • rifiuta un codice mancante in un callback altrimenti riuscito;
  • conserva solo un percorso di ritorno locale verificato;
  • non espone al browser diagnostica del protocollo o dati personali.

Scambio del codice

  • si autentica con client_secret_basic;
  • usa lo stesso URI di reindirizzamento della richiesta di autorizzazione;
  • invia il verificatore PKCE originale;
  • rifiuta codici scaduti, riusati, di un altro client o con verificatore errato;
  • tratta le risposte con token come non memorizzabili in cache e le tiene sul server.

Verifica dell’ID token

Rifiuta i token con:

  • firma non valida;
  • chiave di firma sconosciuta dopo un aggiornamento del JWKS;
  • emittente errato;
  • audience errata;
  • algoritmo diverso da RS256;
  • nonce mancante o errato;
  • claim temporali scaduti o non plausibili;
  • subject mancante.

Verifica che il collegamento degli account usi la coppia iss e sub, non la sola email.

Rotazione al rinnovo

  • un refresh token valido restituisce un nuovo token di accesso e un refresh token sostitutivo;
  • il sostituto viene salvato in modo atomico;
  • i rinnovi avvengono in sequenza per ogni utente e sessione client;
  • il riuso del vecchio refresh token viene rifiutato;
  • un token emesso per un altro client viene rifiutato;
  • un token scaduto richiede un nuovo flusso di autorizzazione;
  • un timeout o una risposta di rinnovo persa con esito incerto cancella lo stato locale dei token e avvia un nuovo flusso di autorizzazione invece di riprovare con il vecchio token;
  • tentativi di rinnovo contemporanei non possono contendersi lo stesso token;
  • lo scollegamento locale elimina il refresh token attivo e i dati della sessione.

Parkour Design al momento non ha un endpoint pubblico di revoca. I test non devono presentare l’eliminazione locale come revoca sul server.

Test automatici delle risorse

Autenticazione e isolamento

  • senza token si ottiene 401 invalid_token;
  • un token scaduto o malformato restituisce 401 invalid_token;
  • un ID token usato come bearer token per l’API viene rifiutato;
  • l’utente A vede solo gli eventi e i progetti dell’utente A;
  • l’utente B non può caricare un evento dell’utente A copiandone l’ID;
  • eventi non accessibili e inesistenti restituiscono entrambi 404 not_found.

Contratto dello schema

Verifica ogni risposta rispetto a uno schema di proprietà del partner:

  • le proprietà obbligatorie sono presenti;
  • le proprietà che possono essere null accettano null;
  • le date vengono interpretate come valori ISO 8601;
  • proprietà aggiuntive sconosciute non devono rompere il client;
  • le raccolte vuote restituiscono un array items vuoto;
  • gli identificatori sono trattati come stringhe opache;
  • il testo supporta Unicode e viene mostrato in modo sicuro.

Non ricavare un grafico del percorso completo dallo schema dei riepiloghi.

Limiti ed errori

  • il client gestisce l’elenco di eventi più grande approvato;
  • l’attuale limite di 500 progetti nella vista di dettaglio fa parte della valutazione dei rischi prima del lancio;
  • le risposte 401, 404, 405, 429 e 5xx seguono la politica di ripetizione concordata;
  • i timeout non attivano ripetizioni illimitate;
  • un JSON malformato fallisce in modo sicuro e salva una diagnostica ripulita;
  • richieste GET idempotenti ripetute non cambiano lo stato del partner.

Test dell’esportazione da Parkour Design al partner

Quando Parkour Design invia dati a un partner, aggiungi test di contratto reciproci per:

  • elenco delle destinazioni e verifica degli identificatori;
  • consegna del solo file;
  • consegna dei soli dati strutturati;
  • consegna riuscita di tutte le parti;
  • ogni possibile combinazione di consegna parzialmente riuscita;
  • dati strutturati malformati;
  • file vuoti e troppo grandi;
  • risposte del partner 401, 403, 404, 409, 413, 429 e 5xx;
  • timeout di connessione e di risposta;
  • invii doppi e idempotenza;
  • scollegamento, ricollegamento e token scaduto.

Accettazione manuale

Esegui quanto segue in un browser reale contro l’ambiente di test in produzione.

ScenarioRisultato atteso
Account correttoIl consenso si completa e vengono restituite solo le risorse di quell’utente
Consenso negatoIl partner mostra uno stato di interruzione recuperabile e non salva token
Account Parkour Design erratoIl partner mostra l’identità connessa e consente un riavvio sicuro
Sessione partner esistente di un altro accountIl cambio di account funziona secondo le istruzioni di assistenza approvate
Indietro e aggiornaNessun codice di autorizzazione o valore state viene accettato due volte
Doppio clic su collegaResta valida una sola transazione del browser
Schede contemporaneeUn callback non può essere associato alla transazione locale sbagliata
Callback scadutoL’utente può ricominciare senza uno stato di collegamento obsoleto
Token di accesso scadutoIl partner rinnova una volta o chiede di nuovo l’autorizzazione
Interruzione del partner o di Parkour DesignL’utente riceve un messaggio su un problema recuperabile, senza diagnostica sensibile
Scollegamento e ricollegamentoI token locali vengono eliminati e si può stabilire una nuova identità

Ripeti il flusso di base in ogni lingua supportata dall’interfaccia. I valori del protocollo devono restare invariati, mentre i messaggi per l’utente vengono localizzati.

Documentazione per la revisione di sicurezza

Fornisci ai revisori:

  • un diagramma del flusso dei dati con browser, entrambi i backend, provider di identità, API e memorizzazione dei token;
  • URI di reindirizzamento e origini consentiti;
  • scope richiesti e loro corrispondenza con le risorse;
  • impostazioni di cifratura e conservazione dei token;
  • impostazioni di verifica dell’ID token;
  • esempi ripuliti di log e avvisi;
  • risultati della scansione di dipendenze e segreti;
  • risultati dei test automatici;
  • verbale compilato dell’accettazione manuale;
  • procedure di rotazione delle credenziali e gestione degli incidenti.

Non allegare mai come documentazione codici reali, token, client secret, chiavi private, risposte UserInfo grezze o dati dei clienti.

Osservabilità

Conserva abbastanza informazioni per diagnosticare gli errori senza conservare credenziali o dati personali:

  • ID di correlazione generato dal partner;
  • ambiente e direzione dell’integrazione;
  • nome dell’operazione;
  • categoria dell’endpoint a monte, non i parametri della query;
  • stato HTTP e codice di errore OAuth sicuro;
  • durata e numero di ripetizioni;
  • conteggio ripulito delle risorse, quando utile operativamente.

Non registrare codici di autorizzazione, token di accesso, refresh token, ID token, client secret, state, nonce, verificatori PKCE, URL di reindirizzamento completi, indirizzi email o contenuto dei grafici dei percorsi.

Gli avvisi devono distinguere errori di autenticazione, errori di autorizzazione, interruzioni del partner, latenza, errori di schema e limitazione persistente della frequenza.

Prontezza per la produzione

Prima del rilascio delle credenziali di produzione, entrambi i team devono approvare:

  • emittente e URI di reindirizzamento di produzione esatti;
  • autenticazione del client e proprietario delle credenziali;
  • scope e risorse disponibili;
  • volume previsto e limiti attuali dell’API;
  • privacy, conservazione, scollegamento e cancellazione;
  • regole per timeout, ripetizioni, idempotenza e consegne parzialmente riuscite;
  • monitoraggio ed escalation degli incidenti;
  • istruzioni di assistenza per gli utenti;
  • procedura di ripristino o disattivazione dell’integrazione;
  • finestra temporale e responsabile dello smoke test in produzione.

Usa credenziali client diverse per test e produzione. Consegnale tramite il canale approvato per i segreti e verifica la rotazione prima del lancio.

Smoke test in produzione

Mantieni il primo test in produzione ristretto:

  1. autorizza un account interno approvato;
  2. verifica l’ID token e carica UserInfo;
  3. richiedi l’elenco degli eventi;
  4. richiedi i riepiloghi dei progetti di un evento noto;
  5. verifica l’isolamento degli utenti e i campi attesi;
  6. rinnova una volta e salva il token sostitutivo;
  7. scollega ed elimina le credenziali salvate in locale;
  8. esamina log e avvisi ripuliti;
  9. documenta il risultato e decidi se attivare un accesso più ampio.

Non testare in produzione comportamenti distruttivi o volumi elevati, a meno che non facciano esplicitamente parte della procedura di lancio approvata.

Verbale di accettazione

Per ogni scenario documenta:

  • ambiente e versione della build;
  • responsabile del test e data;
  • identità anonimizzata dei dati di test;
  • risultato atteso;
  • risultato effettivo;
  • dove si trova la documentazione;
  • errore o limite accettato;
  • responsabile dell’approvazione.

Un limite non documentato non è un limite accettato. Aggiungi i problemi di contratto o di sicurezza irrisolti alla decisione di lancio prima di attivare l’accesso alla produzione.