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

Autenticazione

Implementa il flusso con codice di autorizzazione, verifica i token di identità di Parkour Design e gestisci i refresh token a rotazione.

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.

AmbienteEmittenteDocumento di discovery
Produzionehttps://app.parkour.designhttps://app.parkour.design/.well-known/openid-configuration
Testhttps://parkour-test.web.apphttps://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:

FunzioneValore attuale
Tipo di rispostacode
Tipi di concessioneauthorization_code, refresh_token
Autenticazione del clientclient_secret_basic, client_secret_post
Firma dell’ID tokenRS256
Metodi PKCES256, plain
Scopeopenid, profile, email
Claimsub, 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 state monouso ad alta entropia;
  • un nonce OIDC 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:

  1. rifiuta uno state mancante o inatteso;
  2. rifiuta una transazione del browser scaduta o già usata;
  3. consuma la transazione, così il callback non può essere riprodotto;
  4. gestisci un error OAuth 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:

  1. carica le chiavi dal jwks_uri del discovery;
  2. scegli la chiave indicata dal kid del JWT;
  3. richiedi una firma RS256;
  4. richiedi la corrispondenza esatta dell’emittente;
  5. richiedi il client ID come audience;
  6. verifica scadenza e data di emissione con una piccola tolleranza per lo scarto degli orologi;
  7. richiedi il nonce originale;
  8. usa sub come 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

TokenDurataGestione nel client
Codice di autorizzazione5 minutiScambialo una volta e non conservarlo dopo l’uso
ID token15 minutiVerificalo una volta; non usarlo come bearer token per l’API
Token di accesso15 minutiTienilo sul server e invialo solo alle API delle risorse di Parkour Design
Refresh token30 giorniCifralo 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_request nell’elaborazione del consenso vengono reindirizzati al callback con error e lo state originale;
  • 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 400 in JSON.

Anche gli errori dei token e delle API delle risorse usano un corpo JSON compatto:

{"error": "invalid_grant"}
ErroreSignificato
invalid_clientClient mancante, sconosciuto, inattivo o autenticato in modo errato
invalid_redirect_uriURI di callback mancante o non registrato; è un codice specifico dell’implementazione attuale di Parkour Design
invalid_scopeInsieme di scope vuoto o non approvato
invalid_requestCampi mancanti o combinazione PKCE non valida
access_deniedL’utente ha negato il consenso
invalid_grantCodice o refresh token non valido, scaduto, riusato o associato in modo errato
unsupported_response_typeRisposta di autorizzazione diversa da code
unsupported_grant_typeTipo di concessione del token non supportato
invalid_tokenBearer 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, state e nonce vengono accettati ma non controllati dal server; i client partner devono controllarli.
  • Il discovery annuncia PKCE plain; i client partner devono usare S256.
  • 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 openid invece di scope di risorsa dedicati.

Esamina questi limiti durante l’onboarding e non sostituirli silenziosamente con ipotesi prese da un altro provider OAuth.