Integrare Cloud incorporato senza esporre credenziali

Il problema: incorporare non significa consegnare credenziali

Integrare file manager con iframe e API di solito parte da un'esigenza semplice: mostrare file, cartelle, trasformazioni o download all'interno di un prodotto esistente. L'errore abituale è presumere che, se l'interfaccia si vede nel browser, anche le chiavi che permettono di operare su Cloud debbano viaggiare verso il browser. Questa commistione rompe la separazione fondamentale tra esperienza utente e autorità di esecuzione. L'iframe deve servire a presentare una sessione controllata; l'API REST deve essere usata dal server quando occorre gestire risorse, utenti, configurazione o lavori di trasformazione.

Apification offre tre modalità principali per questo scenario: API REST, webhook firmati e Cloud incorporato. Cloud incorporato si integra tramite una sessione controllata e personalizzata, con sessioni iframe firmate, temi e permessi effettivi, e comunicazione JavaScript con l'host. Questo non equivale a replicare tutto lo storage né a esporre percorsi interni. Inoltre, non va confuso con una sincronizzazione continua di sorgenti esterne: quando Google Drive, OneDrive o Dropbox agiscono come sorgenti, l'importazione copia i file selezionati nel Cloud di Apification.

• Non inserire chiavi API nel JavaScript del client.
• Non trasformare un iframe in un proxy senza regole di business.
• Non trattare l'incorporamento come una copia totale dello storage esterno.

Mappa delle responsabilità: frontend, backend e Cloud

Il frontend deve occuparsi dell'esperienza: aprire l'area incorporata, reagire agli eventi consentiti, mostrare stati e richiedere azioni al backend. Un iframe, secondo la definizione generale della piattaforma web, è un contesto di navigazione annidato che incorpora un'altra pagina all'interno di quella corrente. Ogni iframe ha il proprio documento e la propria navigazione, e consuma memoria e risorse aggiuntive, quindi conviene usarlo quando offre un'esperienza completa e non come meccanismo indiscriminato per ogni operazione minima.

Il backend deve custodire le credenziali, applicare le regole proprie del prodotto e chiamare l'API REST di Apification da server a server. L'integrazione REST prevede chiavi API con scope, operazioni di scrittura idempotenti e lavori asincroni di File Transformer. Apification Cloud, da parte sua, mantiene lo spazio di lavoro organizzato e versionato, le risorse condivisibili, i permessi, gli utenti, i gruppi, i ruoli e la visibilità che controllano chi può consultare o modificare ogni elemento.

• Frontend: interfaccia, iframe, messaggi JavaScript limitati e visualizzazione dello stato.
• Backend: autenticazione propria, autorizzazione, scope, idempotenza e chiamate REST.
• Apification Cloud: file, servizi, permessi effettivi, versioni e risultati trasformati.

Quando usare iframe, JavaScript, REST API o OpenAPI

Usa Cloud incorporato quando vuoi che l'utente navighi in un'esperienza di gestione file dentro il tuo prodotto senza ricostruire tutta l'interfaccia. Apification permette sessioni iframe firmate con accesso temporaneo, e il server risolve il tema e i permessi effettivi prima di aprire Cloud. Questo si adatta a portali cliente, pannelli SaaS e back office in cui l'utente deve vedere una parte controllata del workspace, scaricare originali o trasformati, oppure lavorare all'interno di un'esperienza visiva coerente con il prodotto host.

Usa l'API REST quando l'azione ha conseguenze di business o deve essere eseguita con le regole del server: creare un lavoro di trasformazione, gestire risorse Cloud, applicare configurazione o coordinare utenti. Usa JavaScript solo per la comunicazione limitata tra la pagina host e l'iframe, non per esercitare autorità sensibile. Usa il contratto OpenAPI 3.1 scaricabile per allineare schemi di richiesta e risposta, generare client interni o validare integrazioni, ricordando che le credenziali con scope restano di competenza del server.

• Iframe: migliore per un'esperienza Cloud completa e controllata.
• JavaScript: utile per il coordinamento dell'interfaccia, non per i segreti.
• REST API: adatta ad automazione, regole di backend e lavori.
• OpenAPI: utile per contratto tecnico, tipi, test e revisione delle modifiche.

Pattern consigliato: backend come mediatore

Il pattern operativo più robusto inizia con una richiesta dell'utente alla tua applicazione. Il backend valida la sessione propria, verifica che cosa può fare quell'utente secondo il tuo modello di business e decide se sia opportuno aprire Cloud incorporato o eseguire un'azione via API. Se si apre Cloud, il server prepara una sessione firmata e temporanea, con il tema e i permessi effettivi risolti prima di consegnare l'esperienza al browser. Il client riceve quanto necessario per mostrare l'iframe, non una credenziale riutilizzabile.

Per operazioni di scrittura o trasformazione, il backend usa una credenziale con scope e concede solo i permessi di lettura e scrittura necessari. Quando l'azione può ripetersi a causa di ritentativi del browser o problemi di rete, usa operazioni idempotenti per evitare duplicati. Nei flussi pesanti, come importazioni, trasformazioni o render, Apification può elaborare lavori in background. La sequenza consigliata è chiara: credenziale con scope, richiesta idempotente, lavoro asincrono, evento firmato e risultato autenticato.

• Valida l'utente nel tuo backend prima di creare una sessione incorporata.
• Mappa i permessi di business sui permessi effettivi di Cloud.
• Usa scope minimi per la credenziale del server.
• Progetta le scritture in modo che tollerino ritentativi senza duplicare azioni.

Permessi, temi e restrizioni senza ampliare l'accesso

La sicurezza di un'integrazione incorporata dipende meno dall'iframe in sé e più da come vengono risolti i permessi prima di aprirlo. Apification usa utenti, gruppi, ruoli e visibilità come controlli per decidere chi può consultare o modificare ogni elemento. In un'integrazione, questi controlli devono allinearsi con il tuo prodotto: se un cliente può vedere solo un progetto, la sessione incorporata non deve permettergli di navigare verso risorse di un altro cliente, anche se conosce un identificatore o manipola parametri nell'URL.

Anche il tema visivo deve essere risolto dal server quando si prepara la sessione incorporata, perché fa parte dell'esperienza controllata. Sul lato browser, considera gli attributi standard degli iframe come parte della difesa dell'interfaccia: allow definisce una Permissions Policy per le funzioni disponibili in base all'origine, e sandbox può imporre restrizioni al contenuto incorporato. La raccomandazione generale è di non fidarsi del client come fonte dei permessi e di fare attenzione alle combinazioni di sandbox che ne annullano il valore di sicurezza in scenari di stessa origine.

• Verifica utente, gruppo, ruolo e visibilità prima di aprire o eseguire azioni.
• Non accettare permessi, tema o ambito finale solo da parametri del client.
• Limita le funzioni dell'iframe a ciò che serve per l'esperienza.
• Verifica che i download di originali o trasformati appartengano all'utente corretto.

Flussi di esempio: selettore, trasformazione e download

Un flusso di selettore incorporato può funzionare così: l'utente entra nel tuo portale, seleziona un progetto e preme “apri file”. Il tuo backend valida che quell'utente appartenga al progetto e richiede una sessione incorporata con permessi effettivi adeguati. Il frontend inserisce l'iframe e, tramite comunicazione JavaScript limitata con l'host, può ricevere un segnale di selezione o chiusura. L'azione successiva non deve basarsi ciecamente su un ID inviato dal browser; il backend deve verificare che l'elemento selezionato appartenga all'ambito consentito.

Un flusso di trasformazione segue un'altra logica. L'utente richiede di convertire, dividere, unire, ottimizzare o elaborare un documento, un'immagine, un video, un audio o un dato tramite un'azione del tuo prodotto. Il backend valida proprietario e permesso, chiama l'API REST per creare il lavoro asincrono di File Transformer e registra uno stato interno come “in corso”. Quando il risultato è disponibile, l'utente deve accedervi tramite un risultato autenticato, non attraverso percorsi interni di storage. Se il file originale cambia, la cronologia di elementi e versioni di Cloud aiuta a conservare una fonte organizzata.

• Selettore: sessione incorporata, selezione limitata e validazione successiva nel backend.
• Trasformazione: permesso, lavoro asincrono, stato visibile e risultato autenticato.
• Download: originale o trasformato solo per l'utente o il gruppo autorizzato.

Webhook e azioni asincrone senza duplicati

I webhook di Apification permettono di reagire a eventi rilevanti senza consultare continuamente risorse o lavori in background. Includono payload firmati con HMAC, cronologia delle consegne, ritentativi ed eventi di trasformazione completata. Per usarli bene, hai bisogno di un endpoint HTTPS accessibile e stabile. Questo endpoint non deve limitarsi ad accettare qualsiasi payload: deve validare la firma, registrare l'evento ricevuto e collegarlo al lavoro o alla risorsa che il tuo backend ha creato in precedenza.

Poiché ci sono ritentativi, il tuo ricevitore deve essere idempotente. In pratica, registra una chiave di consegna o un riferimento dell'evento ed evita che la stessa trasformazione completata attivi due volte la stessa azione di business. Conviene anche separare lo stato tecnico dallo stato visibile: “ricevuto”, “in elaborazione”, “completato” o “fallito” nei tuoi registri interni; “il tuo file è in preparazione” o “non è stato possibile completare la trasformazione” nell'interfaccia. Così l'utente comprende l'avanzamento senza vedere dettagli interni né percorsi di storage.

• Richiedi HTTPS stabile per l'endpoint del webhook.
• Valida HMAC prima di fidarti del payload.
• Conserva la cronologia delle consegne e il risultato dell'elaborazione.
• Rendi il gestore idempotente rispetto ai ritentativi.

Casi di errore e checklist prima della produzione

Gli errori più pericolosi compaiono quando il team prova a semplificare l'integrazione saltando il backend. Una chiave API in JavaScript può essere estratta dal client. Un proxy generico che inoltra qualsiasi operazione all'API può ampliare i permessi senza volerlo. Un endpoint che si fida degli ID inviati dal browser cade in problemi di autorizzazione a livello di oggetto: l'utente cambia un identificatore e accede a una risorsa altrui. La stessa logica si applica alle proprietà: non ogni campo che arriva dal client deve essere accettato come modificabile.

Ci sono anche errori operativi. Se non registri lavori in corso, errori di integrazione o trasformazioni fallite, l'utente vede solo silenzio. Se non limiti le azioni pesanti, puoi favorire un consumo di risorse non previsto. Se non distingui l'incorporamento dall'importazione da sorgenti esterne, puoi promettere una sincronizzazione che non corrisponde alla realtà. Prima della produzione, verifica che il tuo backend sia l'unico componente con credenziali, che ogni azione validi proprietario e permesso, e che originali e risultati trasformati mantengano un'unica fonte di verità in Cloud.

• Credenziali: nessuna chiave API nel browser.
• Autorizzazione: validare oggetto, proprietario, gruppo, ruolo e visibilità nel backend.
• Scope: concedere solo lettura e scrittura necessarie.
• Proxy: permettere solo le operazioni previste dal tuo prodotto.
• Asincronia: registrare lavori, webhook, ritentativi ed errori visibili al supporto.
• Risorse: controllare le azioni pesanti ed evitare esecuzioni duplicate.
• Messaggi all'utente: mostrare stati comprensibili senza esporre dettagli interni.

Domande frequenti