Questo documento descrive il flusso attualmente implementato per un’applicazione partner riservata che si collega a Parkour Design. Registrazione del client e accesso alla produzione richiedono un’approvazione tecnica e di sicurezza.
Contratto attuale: il protocollo è in produzione e viene usato per integrazioni coordinate. Non è un servizio di autorizzazione self-service. Parkour Design fornisce client ID, client secret, URI di reindirizzamento registrati e scope consentiti tramite un canale sicuro.
Ambienti e discovery
Usa l’OpenID Connect discovery invece di costruire a mano gli URL degli endpoint.
| Ambiente | Emittente | Documento di discovery |
|---|---|---|
| Produzione | https://app.parkour.design | https://app.parkour.design/.well-known/openid-configuration |
| Test | https://parkour-test.web.app | https://parkour-test.web.app/.well-known/openid-configuration |
Carica il discovery all’avvio dell’applicazione, mettilo in cache per un tempo limitato e aggiornalo quando cambiano le chiavi di firma. Richiedi che l’issuer restituito corrisponda esattamente all’emittente configurato.
Il documento di discovery attuale pubblica:
| Funzione | Valore attuale |
|---|---|
| Tipo di risposta | code |
| Tipi di concessione | authorization_code, refresh_token |
| Autenticazione del client | client_secret_basic, client_secret_post |
| Firma dell’ID token | RS256 |
| Metodi PKCE | S256, plain |
| Scope | openid, profile, email |
| Claim | sub, email, email_verified, name |
Usa client_secret_basic e PKCE S256. Non usare plain, anche se il server attuale lo annuncia per compatibilità.
Prerequisiti della registrazione
Prima dell’implementazione invia a Parkour Design:
- nome dell’applicazione e responsabile tecnico;
- URI di reindirizzamento di test e produzione;
- scope richiesti e percorso utente;
- contatti per la consegna e la rotazione delle credenziali;
- requisiti di logout, scollegamento degli account e conservazione.
Gli URI di reindirizzamento vengono confrontati esattamente. Schema, host, porta, percorso, maiuscole e barra finale devono corrispondere al valore registrato. Usa un callback senza query string o frammento esistenti.
Il servizio attuale supporta client backend riservati. Client che girano solo nel browser e client nativi pubblici non sono supportati, perché ogni richiesta di token richiede un client secret.
Sequenza di autorizzazione
1. Creare la transazione del browser
Crea e conserva sul server:
- un valore
statemonouso ad alta entropia; - un
nonceOIDC ad alta entropia; - un verificatore PKCE e la sua challenge SHA-256;
- la destinazione dopo l’accesso;
- una breve scadenza.
Lega i valori alla sessione del browser dell’utente. Non mettere mai in un URL il client secret, il verificatore o i token.
2. Reindirizzare l’utente
Costruisci l’URL di autorizzazione dall’authorization_endpoint del discovery:
GET {authorization_endpoint}
?response_type=code
&client_id={client_id}
&redirect_uri={url_encoded_registered_redirect_uri}
&scope={url_encoded_approved_scopes}
&state={state}
&nonce={nonce}
&code_challenge={base64url_sha256_verifier}
&code_challenge_method=S256
Usa solo gli scope approvati alla registrazione del client. openid email profile è un esempio per il caso in cui tutti e tre gli scope siano stati approvati; richiedere uno scope non approvato restituisce invalid_scope.
Parkour Design autentica l’utente e chiede il consenso. Una risposta riuscita restituisce:
{redirect_uri}?code={authorization_code}&state={state}
Una richiesta negata restituisce:
{redirect_uri}?error=access_denied&state={state}
3. Verificare il callback
Prima di scambiare il codice:
- rifiuta uno
statemancante o inatteso; - rifiuta una transazione del browser scaduta o già usata;
- consuma la transazione, così il callback non può essere riprodotto;
- gestisci un
errorOAuth senza tentare lo scambio del token.
I codici di autorizzazione scadono dopo cinque minuti e si possono usare una sola volta.
4. Scambiare il codice sul server
Invia dal backend del partner una richiesta con codifica form:
curl --request POST "${TOKEN_ENDPOINT}" \
--user "${CLIENT_ID}:${CLIENT_SECRET}" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=authorization_code" \
--data-urlencode "code=${CODE}" \
--data-urlencode "redirect_uri=${REDIRECT_URI}" \
--data-urlencode "code_verifier=${CODE_VERIFIER}"
redirect_uri deve essere identico al valore della richiesta di autorizzazione.
Una risposta riuscita ha attualmente questa forma:
{
"access_token": "<signed JWT>",
"refresh_token": "<opaque token>",
"token_type": "Bearer",
"expires_in": 900,
"scope": "email openid profile",
"id_token": "<signed JWT>"
}
Le risposte con token usano Cache-Control: no-store e Pragma: no-cache. L’id_token viene restituito solo quando è stato concesso openid.
Verificare l’identità
Prima di creare una sessione partner, verifica l’ID token:
- carica le chiavi dal
jwks_uridel discovery; - scegli la chiave indicata dal
kiddel JWT; - richiedi una firma
RS256; - richiedi la corrispondenza esatta dell’emittente;
- richiedi il client ID come audience;
- verifica scadenza e data di emissione con una piccola tolleranza per lo scarto degli orologi;
- richiedi il
nonceoriginale; - usa
subcome identificatore stabile dell’utente Parkour Design.
Claim attuali dell’ID token:
{
"iss": "https://app.parkour.design",
"sub": "<opaque Parkour Design user ID>",
"aud": "<client ID>",
"email": "user@example.com",
"email_verified": true,
"name": "Example User",
"token_use": "id_token",
"iat": 0,
"exp": 0,
"nonce": "<authorization nonce>"
}
Non collegare gli account solo tramite email. Conserva iss e sub come chiave dell’identità esterna. Tratta email e nome come attributi del profilo che possono cambiare.
UserInfo è disponibile quando il token di accesso contiene openid:
curl "${USERINFO_ENDPOINT}" \
--header "Authorization: Bearer ${ACCESS_TOKEN}" \
--header "Accept: application/json"
{
"sub": "<opaque Parkour Design user ID>",
"email": "user@example.com",
"email_verified": true,
"name": "Example User"
}
Token di accesso e refresh token
| Token | Durata | Gestione nel client |
|---|---|---|
| Codice di autorizzazione | 5 minuti | Scambialo una volta e non conservarlo dopo l’uso |
| ID token | 15 minuti | Verificalo una volta; non usarlo come bearer token per l’API |
| Token di accesso | 15 minuti | Tienilo sul server e invialo solo alle API delle risorse di Parkour Design |
| Refresh token | 30 giorni | Cifralo nella memorizzazione e sostituiscilo in modo atomico dopo ogni rinnovo |
I refresh token ruotano a ogni uso riuscito:
curl --request POST "${TOKEN_ENDPOINT}" \
--user "${CLIENT_ID}:${CLIENT_SECRET}" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=refresh_token" \
--data-urlencode "refresh_token=${REFRESH_TOKEN}"
La risposta contiene un nuovo token di accesso e un refresh token sostitutivo. Non contiene un nuovo ID token. Esegui i rinnovi in sequenza per ogni utente e sessione client, poi sostituisci in modo atomico il refresh token conservato. Riusare un vecchio token restituisce invalid_grant.
Parkour Design consuma il vecchio refresh token prima di restituire il sostituto. Se un timeout o una risposta persa rendono il risultato incerto, non riprovare alla cieca con il vecchio token. Cancella lo stato locale dei token e avvia un nuovo flusso di autorizzazione. Rinnovi contemporanei per la stessa sessione creano lo stesso rischio di recupero.
La durata attuale del rinnovo è scorrevole: ogni rotazione riuscita avvia una nuova durata di 30 giorni. Parkour Design al momento non ha endpoint di revoca o introspezione dei token. Lo scollegamento nell’applicazione partner deve eliminare i token conservati. Un token di accesso può restare valido fino alla scadenza dopo 15 minuti.
Usare i token di accesso per l’API
I token di accesso di Parkour Design hanno sempre l’audience parkour-api. Sono credenziali solo per le API delle risorse di Parkour Design descritte in Scambio di dati. Non inoltrarli mai all’API di un partner o a terzi; le risorse gestite dal partner devono usare un proprio meccanismo di autorizzazione.
L’ID token stabilisce l’identità e una sessione partner. Non usare un ID token per chiamare un’API.
Comportamento attuale degli scope
Gli scope di identità attuali sono openid, email e profile. L’API delle risorse coordinata autorizza attualmente l’accesso agli eventi e ai riepiloghi dei progetti con openid; non ha ancora scope di lettura dedicati.
È un limite dell’implementazione attuale, non un modello per le nuove API. Scope richiesti e risorse disponibili si confermano alla registrazione del client. Contratti futuri delle risorse potranno introdurre scope dedicati.
I token attuali e UserInfo contengono email e nome in misura più ampia di quanto indichino i singoli scope email e profile. I client devono comunque richiedere solo gli scope approvati e non devono contare sul fatto che il comportamento più ampio resti invariato.
Gestione degli errori
L’endpoint di autorizzazione ha due canali di errore:
- dopo la verifica di un URI di reindirizzamento, il consenso negato e alcuni errori
invalid_requestnell’elaborazione del consenso vengono reindirizzati al callback conerrore lostateoriginale; - gli errori di verifica prima che sia stabilito un callback affidabile, compresi quelli di client, URI di reindirizzamento, scope, tipo di risposta e PKCE, restituiscono una risposta diretta HTTP
400in JSON.
Anche gli errori dei token e delle API delle risorse usano un corpo JSON compatto:
{"error": "invalid_grant"}
| Errore | Significato |
|---|---|
invalid_client | Client mancante, sconosciuto, inattivo o autenticato in modo errato |
invalid_redirect_uri | URI di callback mancante o non registrato; è un codice specifico dell’implementazione attuale di Parkour Design |
invalid_scope | Insieme di scope vuoto o non approvato |
invalid_request | Campi mancanti o combinazione PKCE non valida |
access_denied | L’utente ha negato il consenso |
invalid_grant | Codice o refresh token non valido, scaduto, riusato o associato in modo errato |
unsupported_response_type | Risposta di autorizzazione diversa da code |
unsupported_grant_type | Tipo di concessione del token non supportato |
invalid_token | Bearer token per l’API mancante, malformato, scaduto o non valido |
Non mostrare agli utenti finali risposte grezze con token o diagnostica del protocollo. Registra un ID di correlazione, l’endpoint, lo stato e un codice di errore sicuro, senza registrare codici, token, segreti, valori nonce o dati personali.
Limiti attuali
- Registrazione dei client e revoca del consenso si coordinano manualmente.
- PKCE,
stateenoncevengono accettati ma non controllati dal server; i client partner devono controllarli. - Il discovery annuncia PKCE
plain; i client partner devono usareS256. - Non ci sono endpoint di revoca, introspezione, registrazione dinamica o chiusura standardizzata della sessione.
- Il riuso di un refresh token non revoca l’intera famiglia di token.
- I token di accesso restano validi fino alla scadenza dopo il logout locale.
- L’autorizzazione attuale delle risorse usa
openidinvece di scope di risorsa dedicati.
Esamina questi limiti durante l’onboarding e non sostituirli silenziosamente con ipotesi prese da un altro provider OAuth.