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:
issuercorrisponda esattamente all’emittente di test configurato;- gli endpoint di autorizzazione, token, UserInfo e JWKS usino HTTPS;
- siano presenti
code,authorization_code,refresh_token,RS256eS256; - 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,noncee 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_deniedsenza 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
itemsvuoto; - 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,429e5xxseguono la politica di ripetizione concordata; - i timeout non attivano ripetizioni illimitate;
- un JSON malformato fallisce in modo sicuro e salva una diagnostica ripulita;
- richieste
GETidempotenti 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,429e5xx; - 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.
| Scenario | Risultato atteso |
|---|---|
| Account corretto | Il consenso si completa e vengono restituite solo le risorse di quell’utente |
| Consenso negato | Il partner mostra uno stato di interruzione recuperabile e non salva token |
| Account Parkour Design errato | Il partner mostra l’identità connessa e consente un riavvio sicuro |
| Sessione partner esistente di un altro account | Il cambio di account funziona secondo le istruzioni di assistenza approvate |
| Indietro e aggiorna | Nessun codice di autorizzazione o valore state viene accettato due volte |
| Doppio clic su collega | Resta valida una sola transazione del browser |
| Schede contemporanee | Un callback non può essere associato alla transazione locale sbagliata |
| Callback scaduto | L’utente può ricominciare senza uno stato di collegamento obsoleto |
| Token di accesso scaduto | Il partner rinnova una volta o chiede di nuovo l’autorizzazione |
| Interruzione del partner o di Parkour Design | L’utente riceve un messaggio su un problema recuperabile, senza diagnostica sensibile |
| Scollegamento e ricollegamento | I 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:
- autorizza un account interno approvato;
- verifica l’ID token e carica UserInfo;
- richiedi l’elenco degli eventi;
- richiedi i riepiloghi dei progetti di un evento noto;
- verifica l’isolamento degli utenti e i campi attesi;
- rinnova una volta e salva il token sostitutivo;
- scollega ed elimina le credenziali salvate in locale;
- esamina log e avvisi ripuliti;
- 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.