Subaccount delegate senza esporre chiavi: pattern sicuro per agenzie

Il problema: autonomia del cliente senza perdere controllo

Un’agenzia che gestisce deliverable per più clienti di solito ha bisogno di due cose che sembrano opposte: che ogni cliente possa consultare, revisionare, caricare o scaricare file con una certa autonomia, e che le operazioni privilegiate restino sotto il controllo tecnico dell’agenzia. Il rischio nasce quando si prova a risolvere rapidamente condividendo credenziali, creando un utente generico per tutti o lasciando che il browser invochi azioni interne con una chiave API. Questa strada può mescolare spazi, compromettere la tracciabilità e rendere molto difficile revocare accessi senza coinvolgere altri clienti.

L’obiettivo corretto non è nascondere un’interfaccia, ma separare le responsabilità. Il cliente deve vedere solo il proprio contesto autorizzato; il backend dell’agenzia deve eseguire le azioni con privilegi; e Apification Cloud deve applicare permessi, visibilità, gruppi, restrizioni e sessioni incorporate limitate. Questo pattern consente di delegare subaccount senza esporre chiavi API, mantenendo i segreti sul server e riducendo la dipendenza da operazioni manuali come spostare file, generare link o controllare uno per uno i lavori di trasformazione.

• Evita di consegnare credenziali API al cliente o di includerle in JavaScript.
• Non usare un account condiviso per più clienti se hai bisogno di isolamento operativo.
• Definisci fin dall’inizio quali azioni sono dell’utente e quali sono del backend.
• Tratta ogni esposizione di contenuto come un’eccezione esplicita su risorse private per impostazione predefinita.

Modello mentale: tre livelli separati

Il primo livello è l’interfaccia incorporata. Apification consente di integrare Cloud tramite iframe, configurazione ereditata e temi visuali, così un’agenzia o un reseller può offrire un’esperienza integrata nel proprio ecosistema. In questo modello, la sessione dell’iframe deve essere costruita prima di mostrarlo: identità, policy effettiva e configurazione visuale vengono risolte sul server per ogni avvio. La sessione incorporata può essere limitata alla subaccount, all’utente e alle risorse consentite, evitando che sia il browser a decidere autonomamente cosa può aprire.

Il secondo livello è il backend proprietario. È lì che risiedono le credenziali API, i segreti dei webhook e il materiale di firma, perché Apification specifica che devono restare sul server e che il browser deve ricevere solo un contesto limitato o temporaneo. Il terzo livello sono i controlli di Cloud: permessi, utenti, gruppi, visibilità, restrizioni, OTP, autenticazione esterna quando applicabile e finestre di pubblicazione. La regola di progettazione è semplice: l’interfaccia guida l’utente, il backend esegue le azioni privilegiate e Cloud conserva la policy di accesso associata alla risorsa.

• Iframe: esperienza utente e selezione all’interno di un contesto limitato.
• Backend: creazione di sessioni firmate, chiamate API e validazione delle regole del cliente.
• Cloud: file, cartelle, servizi modificabili, risultati, cronologia, permessi e visibilità.
• Webhook: notifiche di eventi con firma, nuovi tentativi, cronologia e statistiche.

Che cosa apporta Apification a questo pattern

Apification riunisce i componenti necessari per una delega controllata. Cloud conserva file, cartelle, servizi modificabili e risultati generati all’interno di un unico spazio di lavoro organizzato e versionato. Le nuove risorse sono private per impostazione predefinita e vengono pubblicate o condivise solo quando la loro visibilità o i destinatari vengono configurati espressamente. Inoltre, possono essere condivise con utenti o gruppi senza modificare la visibilità pubblica, un aspetto importante quando un’agenzia deve dare accesso interno ai revisori del cliente senza rendere pubblico un deliverable.

Per l’integrazione, Apification offre una REST API server-to-server per gestire risorse Cloud, utenti, configurazione e lavori di trasformazione dal backend, oltre a un contratto OpenAPI scaricabile con schemi di richiesta e risposta. Consente inoltre di integrare Cloud e servizi tramite iframe, API, webhook e JavaScript, ma il punto chiave è non confondere “integrazione con JavaScript” con “segreti nel browser”. Per le operazioni asincrone, i webhook firmati con nuovi tentativi, cronologia e statistiche sono preferibili al polling in produzione quando si attendono eventi di trasformazione completata o non riuscita.

• Usa chiavi API specifiche e con soli gli scope necessari.
• Sfrutta OpenAPI per validare i contratti prima di programmare.
• Utilizza i webhook in produzione per ridurre le query ripetitive e migliorare la tracciabilità.
• Riserva l’OTP alle interazioni pubbliche; usa utenti, gruppi e visibilità per l’accesso interno.

Architettura consigliata per subaccount delegate

Il flusso consigliato inizia nel portale dell’agenzia. L’utente del cliente si autentica nel sistema dell’agenzia e richiede di aprire la propria area file o una specifica operazione. Il backend valida a quale cliente appartiene, quale ruolo ha e quali risorse può usare. Solo allora richiede una sessione iframe firmata e di breve durata dal backend di fiducia, con il contesto del cliente isolato: subaccount, utente e risorse consentite. Il browser riceve quella sessione limitata, non una chiave API né un segreto riutilizzabile.

Quando il cliente ha bisogno di un’azione privilegiata, come creare un lavoro di trasformazione, consultare una risorsa o preparare un download trasformato, il browser deve chiamare il backend dell’agenzia, non direttamente con credenziali permanenti. Il backend applica regole di business, invoca l’API REST di Apification con autenticazione Bearer dal server e registra l’azione. Se l’host e l’iframe si coordinano tramite messaggi del browser, quei messaggi devono essere validati: il destinatario deve controllare origine, intenzione e dati attesi, seguendo il principio generale di validazione delle comunicazioni tra finestre.

• Passo 1: autentica il cliente nel portale dell’agenzia.
• Passo 2: risolvi sul server identità, policy effettiva e tema visuale.
• Passo 3: richiedi una sessione iframe firmata, limitata e di breve durata.
• Passo 4: esegui chiamate REST solo dal backend con una chiave dagli scope minimi.
• Passo 5: registra eventi e risposte per l’audit operativo.

Delega per cliente: permessi, spazi e regole

La separazione non deve dipendere soltanto dal nome di una cartella. In Apification, spostare un elemento Cloud ne modifica l’organizzazione, non l’identità: le sue proprietà e regole di accesso restano associate allo stesso elemento. Questo è utile per riordinare i deliverable senza perdere i controlli, ma dimostra anche perché l’isolamento deve basarsi su permessi, utenti, gruppi, visibilità e risorse autorizzate, non su convenzioni fragili come “tutto ciò che sta sotto /cliente-a”. L’agenzia deve documentare la matrice di accesso per cliente e rivederla quando cambia il contratto di servizio.

Una matrice pratica distingue almeno cinque azioni: caricare o incorporare file, trasformare o processare contenuto, revisionare versioni, scaricare originali o formati generati, e pubblicare link o accessi. Cloud consente di scaricare il file sorgente o generare un formato compatibile dal flusso di condivisione, quindi conviene decidere chi può consegnare originali e chi invece deve ricevere solo derivati. Se si usano servizi modificabili, come documenti d’ufficio, modifica di immagini o editor multimediali, si applica la stessa logica: il cliente non ha bisogno di un permesso universale, ma del set minimo di azioni per il proprio caso.

• Definisci gruppi per cliente o per ruolo all’interno del cliente.
• Separa revisione, trasformazione, download e pubblicazione come permessi distinti nel tuo design.
• Evita che un cambio di cartella sia l’unico meccanismo di controllo.
• Mantieni una procedura di revoca quando un contatto del cliente smette di partecipare.

Operazioni tipiche e come automatizzarle

In un’operazione quotidiana, il cliente può selezionare file dall’iframe, revisionare deliverable in Cloud, scaricare un originale o richiedere una versione trasformata. L’agenzia, dal canto suo, può creare lavori dal backend, applicare regole del cliente e usare la cronologia degli elementi per revisionare versioni precedenti o ripristinare contenuto quando necessario. Questo approccio riduce le email isolate ed evita che il team interno debba fare da intermediario per ogni download o revisione di base.

Per i processi asincroni, progetta intorno agli eventi. Se una trasformazione viene completata o fallisce, un webhook firmato può avvisare il backend dell’agenzia. Quel backend deve verificare la firma con il segreto salvato sul server, deduplicare gli eventi e aggiornare il proprio stato. Apification supporta scritture idempotenti tramite una chiave di idempotenza nelle operazioni compatibili, quindi le azioni che potrebbero ripetersi per nuovi tentativi, doppio clic o riconnessioni devono inviare una chiave stabile. Così eviti di creare lavori duplicati o di pubblicare due volte lo stesso risultato.

• Usa i webhook per la chiusura dei lavori e gli errori, non solo query periodiche.
• Verifica la firma prima di fidarti del contenuto dell’evento.
• Salva identificatori di eventi o risultati per deduplicare.
• Applica chiavi di idempotenza nelle scritture compatibili che possono ripetersi.
• Conserva un registro operativo di chi ha richiesto l’azione, quale risorsa ha interessato e qual è stato il risultato.

Errori frequenti e modalità di errore

L’errore più grave è inserire chiavi in JavaScript. Anche se un’interfaccia è privata o protetta da login, qualsiasi segreto consegnato al browser deve essere considerato esposto. Un altro errore comune è usare un unico utente per tutti i clienti: può sembrare comodo all’inizio, ma impedisce di attribuire le azioni, rende difficile revocare accessi e aumenta l’impatto di qualsiasi errore di configurazione. È pericoloso anche affidarsi solo ai nomi delle cartelle, perché l’organizzazione visuale non sostituisce le regole di accesso associate a risorse e utenti.

Nell’automazione, gli errori emergono spesso perché non si verificano le firme dei webhook, si processa due volte lo stesso evento o si presume che un’importazione una tantum equivalga a una sincronizzazione continua. Se una consegna webhook viene ritentata e il tuo backend non è idempotente, puoi duplicare lavori o notifiche. Se non fai test con utenti a privilegi inferiori, puoi scoprire tardi che un ruolo può scaricare originali quando avrebbe dovuto vedere solo trasformati. La difesa consiste nel testare i casi negativi: utente sbagliato, risorsa di un altro cliente, sessione scaduta, firma non valida e ripetizione dell’evento.

• Non esporre Bearer token, segreti webhook né materiale di firma nel frontend.
• Non mescolare clienti sotto un’unica identità operativa.
• Non processare webhook senza verificare la firma e deduplicare.
• Non trattare un’importazione una tantum da provider esterni come sincronizzazione continua.
• Non concedere scope API ampi se l’integrazione ne richiede solo una parte.

Checklist di implementazione prima della produzione

Prima di aprire l’accesso ai clienti, prepara una checklist tecnica e una operativa. In quella tecnica, crea una chiave API specifica per l’integrazione e concedi soltanto gli scope necessari di account, Cloud, trasformazioni, utenti o webhook. Conserva la chiave e i segreti in variabili o storage di server, mai nel client. Implementa la validazione del cliente in ogni endpoint interno: nessuna richiesta del browser deve poter indicare liberamente un altro cliente, subaccount o risorsa senza che il backend lo verifichi rispetto alla propria autorizzazione.

Nella checklist operativa, documenta chi può caricare, trasformare, revisionare, scaricare, condividere e revocare. Crea test con utenti a privilegi inferiori, valida sessioni iframe scadute e controlla che le risorse restino private salvo pubblicazione esplicita. Per i webhook, testa firma non valida, evento duplicato e nuovo tentativo. Per le scritture, applica l’idempotenza quando disponibile. Infine, definisci come ritirare l’accesso a un cliente o utente senza influire sugli altri: questa capacità di revoca è una delle ragioni principali per separare le subaccount e non dipendere da credenziali condivise.

• Matrice dei permessi per cliente, ruolo e azione.
• Chiavi API specifiche, scope minimi e segreti solo sul server.
• Sessione iframe firmata, breve e creata dal backend di fiducia.
• Validazione di subaccount, utente e risorsa in ogni operazione.
• Verifica delle firme webhook, deduplicazione e idempotenza.
• Test negativi con ruoli limitati e risorse di altri clienti.
• Piano documentato di revoca di utenti, gruppi e accessi pubblicati.

Domande frequenti