Flusso Authorization Code + redirect personalizzato

Usa il flusso Authorization Code + redirect HTTPS personalizzato per applicazioni web che agiscono per conto di un utente che ha effettuato l’accesso e ricevono il callback OAuth sul proprio dominio. Usa Authorization Code con PKCE, un URI di redirect HTTPS con corrispondenza esatta e un client secret opzionale per i client confidenziali lato server.

Rivedi prima la guida Per iniziare se non hai ancora coperto i prerequisiti, l’accesso di rete e il modello di sicurezza.

---

Cosa farai

1. Creare un’applicazione OAuth: registra un’app web in Prevu3D con il tuo URL di callback HTTPS
2. Configurare l’accesso dell’utente: assicurati che l’utente che accede possa raggiungere i dati di cui ha bisogno
3. Autorizzare con PKCE: invia l’utente attraverso la pagina di consenso nel browser
4. Scambiare il codice con un token: scambia il codice di autorizzazione con un access token
5. Trovare l’URL della tua API: scopri l’URL di base della tua organizzazione (varia in base alla regione)
6. Effettuare la prima chiamata: testa la connessione con una semplice richiesta

Passaggio 1: crea la tua applicazione OAuth

1. Accedi alla Prevu3D Platform.
2. Vai su Settings → OAuth.
3. Fai clic per creare una nuova applicazione.
4. Abilita il flusso Authorization Code.
5. Lascia Native Application disattivato.
6. Inserisci il tuo Redirect URI, ad esempio https://app.example.com/oauth/callback. Deve essere HTTPS con un nome di dominio completo e deve corrispondere esattamente al momento dell’autorizzazione e dello scambio del token.
7. Facoltativamente, abilita un client secret se la tua app può conservarlo lato server. I client pubblici solo-browser non dovrebbero usare un secret.
8. Copia e conserva in modo sicuro il tuo Client ID (e il secret se generato).

Passaggio 2: configura l’accesso dell’utente

Questo flusso chiama l’API come l’utente che ha effettuato l’accesso, non un utente di servizio. Questo copre i livelli 2 e 3 del modello di sicurezza: quali nodi l’utente può vedere (accesso ai contenuti) e cosa può farci (accesso a ruoli / permessi).

1. Assicurati che l’utente che effettuerà l’accesso abbia l’accesso ai contenuti dei nodi (organizzazioni, divisioni, siti, ecc.) richiesti dal tuo caso d’uso.
2. Assicurati che l’utente abbia un ruolo su quei nodi con i permessi di cui la tua integrazione ha bisogno (lettura, modifica, gestione, ecc.).

Nella schermata di consenso, l’utente seleziona anche quale organizzazione autorizzare. Gli scope che l’utente approva lì configurano il livello 1.

Passaggio 3: autorizza con PKCE

Prima di aprire la pagina di consenso, genera tre valori:

Valore	Come
code_verifier	Stringa casuale, da 43 a 128 caratteri
code_challenge	BASE64URL(SHA256(code_verifier)) senza padding
state	Stringa casuale; validala quando il redirect ritorna

Apri il browser dell’utente sulla pagina di consenso.

URL di consenso: https://cloud.prevu3d.com/oauth

Parametri di query (tutti obbligatori):

Parametro	Valore
response_type	code
code_challenge_method	S256
client_id	Il tuo Client ID
redirect_uri	Il tuo URI di callback HTTPS registrato (corrispondenza esatta, nessuna barra finale a meno che non sia registrata)
scopes	Uno per scope, ad esempio scopes=read:basic&scopes=read:hierarchy
code_challenge	Il challenge PKCE generato sopra
state	Il tuo valore di stato casuale

Dopo che l’utente ha effettuato l’accesso e ha fatto clic su Allow, il browser reindirizza al tuo callback:

https://app.example.com/oauth/callback?code={authorization_code}&state={state}

Se l’utente nega l’accesso, ricevi invece ?error=access_denied. I codici di autorizzazione scadono dopo 60 secondi, quindi scambiali subito.

Passaggio 4: scambia il codice con un access token

Endpoint: POST https://cloud-api.prevu3d.com/oauth/token

Header: Content-Type: application/x-www-form-urlencoded

Body:

Campo	Valore
grant_type	authorization_code
client_id	Il tuo Client ID
code	Codice dal redirect
redirect_uri	Lo stesso URI usato nel Passaggio 3
code_verifier	Il verifier PKCE originale
client_secret	Solo se la tua app ha un secret

Puoi inviare client_id e client_secret nel body oppure usare Authorization: Basic base64(client_id:client_secret).

Esempio di risposta:

{
  "hasError": false,
  "expires_in": 86400,
  "access_token": "eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "..."
}

Salva entrambi i token. Usa l’access_token per le chiamate all’API. Quando scade, richiedine uno nuovo con grant_type=refresh_token e il tuo refresh_token salvato.

Passaggio 5: ottieni l’URL di base della tua API

Chiama l’endpoint di discovery per ottenere l’apiUrl della tua organizzazione. Non codificare staticamente un URL regionale.

Endpoint: GET https://cloud-api.prevu3d.com/oauth/api-info

Header: Authorization: Bearer <your_access_token>

Esempio di risposta:

{
  "user": { "..." : "..." },
  "organization": {
    "id": "217ebd23-ec54-4af0-a6d6-4a441a6d1966",
    "name": "Test Organization"
  },
  "scopes": ["read:basic", "read:hierarchy"],
  "apiUrl": "https://api-ue1.prevu3d.com/realityconnect-api"
}

Usa il valore apiUrl come base per tutte le tue chiamate all’API. Annota anche l’organization.id, che ti servirà per molti endpoint.

Passaggio 6: effettua la tua prima chiamata all’API

Ora hai tutto ciò che ti serve: un access token e il tuo URL di base. Facciamo una semplice richiesta per recuperare le divisioni della tua organizzazione:

GET {apiUrl}/v1/nodes/{organization_id}/browse
Authorization: Bearer <your_access_token>

Esempio con valori reali:

GET https://api-ue1.prevu3d.com/realityconnect-api/v1/nodes/217ebd23-ec54-4af0-a6d6-4a441a6d1966/browse HTTP/1.1
Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9...

Una risposta di successo contenente un elenco di divisioni conferma che la tua integrazione funziona correttamente.

Risoluzione dei problemi

Sintomo	Cosa verificare
Redirect URI mismatch al consenso o allo scambio del token	Il redirect_uri deve corrispondere carattere per carattere al valore registrato sull’app OAuth
Invalid OAuth redirect URI durante il salvataggio dell’app	Usa https, un nome di dominio valido, nessuna query string o frammento nell’URI registrato
Bad OAuth application secret	Includi client_secret solo se l’app è stata creata con un secret
Grant exchange expired	I codici di autorizzazione scadono dopo 60 secondi; riavvia il flusso
403 sulle chiamate RCAPI	L’utente potrebbe non avere l’accesso ai contenuti, il ruolo sul nodo o lo scope OAuth per l’operazione

Hai bisogno di un redirect loopback per un’app desktop o una CLI? Usa invece il Flusso Native Application.

Cosa c’è dopo?

• Flusso Native Application per localhost / PKCE senza un dominio personalizzato
• Flusso Client Credentials per l’accesso server-to-server
• Riferimento API interattivo per il catalogo completo degli endpoint