SDK TypeScript Frame.io — Guida all’autenticazione

Questa guida spiega come eseguire l’autenticazione con l’API Frame.io usando l’SDK TypeScript Frame.io (frameio). L’API V4 Frame.io usa Adobe Identity Management Service (IMS), la piattaforma di identità OAuth 2.0 di Adobe. Questo è un riferimento autonomo per sviluppatori TypeScript/JavaScript. Tutti gli esempi di codice e i flussi seguenti sono solo per il pacchetto frameio.

Tipi di autenticazione nell’SDK TypeScript

L’SDK TypeScript supporta quattro classi di autenticazione OAuth, oltre all’uso diretto di token:

Utenti dell’account di servizio

Quando usi l’autenticazione server-to-server, l’applicazione agisce come utente dell’account di servizio, un tipo di account distinto che può eseguire azioni per conto del servizio. Questi sono visibili agli altri utenti in Frame.io: quando un account di servizio esegue un’azione, il nome viene visualizzato nell’interfaccia utente. Puoi concedere e revocare l’accesso dell’account di servizio tramite Adobe Admin Console e Developer Console. I nomi degli account di servizio vengono gestiti dall’interfaccia utente Frame.io. Per impostazione predefinita, la prima connessione S2S viene denominata Service Account User, la seconda Service Account User 2 e così via.

Avvio rapido

Prerequisiti

1. Credenziali da Adobe Developer Console:

• ID client: richiesto per tutti i flussi OAuth - Secret client: richiesto per i flussi server-to-server e web app - URI di reindirizzamento: richiesto per i flussi web app, SPA e app nativa; deve essere registrato nel progetto Adobe

2. Installa l’SDK:

$
npm install frameio

Scelta di un metodo

• Non è coinvolto nessun utente? Usa server-to-server (ServerToServerAuth).
• È coinvolto un utente e puoi archiviare un secret? Usa web app (WebAppAuth).
• È coinvolto un utente, ma non puoi archiviare un secret? Utilizza SPA (SPAAuth) per le app basate su browser, o App nativa (NativeAppAuth) per le app desktop/mobile.

Token di accesso

Se hai già un token di accesso (da un altro sistema OAuth o da uno scambio precedente, ad esempio tramite il nostro Explorer di API) puoi passarlo direttamente:

1
import { FrameioClient } from "frameio";
2
3
const client = new FrameioClient({ token: "YOUR_ACCESS_TOKEN" });

Questo è l’approccio più semplice, ma il token scadrà e l’SDK non lo aggiornerà automaticamente.

Token sviluppatore legacy

Per gli account migrati a V4 e non ancora amministrati tramite Adobe Admin Console, puoi continuare a utilizzare i token sviluppatore legacy dal sito per sviluppatori di Frame.io. Devi includere l’intestazione x-frameio-legacy-token-auth e impostarla su true:

1
import { FrameioClient } from "frameio";
2
3
const client = new FrameioClient({
4
    token: "YOUR_LEGACY_DEVELOPER_TOKEN",
5
    headers: { "x-frameio-legacy-token-auth": "true" },
6
});

I token sviluppatore legacy non scadono, ma sono un meccanismo di transizione. Per le nuove integrazioni e i carichi di lavoro di produzione, consigliamo di utilizzare uno dei flussi OAuth 2.0 indicati di seguito. Consulta la guida alla migrazione per i dettagli.

Server-to-server (credenziali client)

Utilizza questo metodo per servizi e script backend che necessitano dell’accesso a Frame.io senza interazioni da parte dell’utente. Questo flusso è disponibile solo per gli account Frame.io V4 amministrati tramite Adobe Admin Console. La tua applicazione si autentica come utente dell’account di servizio senza intervento umano.

1
import { FrameioClient, ServerToServerAuth } from "frameio";
2
3
const auth = new ServerToServerAuth({
4
    clientId: "YOUR_CLIENT_ID",
5
    clientSecret: "YOUR_CLIENT_SECRET",
6
});
7
8
const client = new FrameioClient({ token: () => auth.getToken() });

Ecco fatto. auth.getToken() è una funzione asincrona che l’SDK richiama ad ogni richiesta. Se il token corrente è ancora valido, restituisce immediatamente il risultato. Se sta per scadere, ne recupera prima uno nuovo, in modo completamente trasparente.

Come funziona

Le tue credenziali client (ID client + secret) non scadono mai. Basta ruotarle manualmente per garantire l’integrità della sicurezza. S2S offre un accesso API permanente e ininterrotto senza alcun intervento manuale.

Dietro le quinte:

1. Alla prima chiamata API, getToken() richiede un nuovo token di accesso da Adobe IMS utilizzando la concessione client_credentials.
2. Il token viene memorizzato nella cache in memoria. I singoli token di accesso scadono (in genere 24 ore), ma questo viene gestito automaticamente.
3. Quando un token memorizzato nella cache si trova entro il buffer di aggiornamento (predefinito: 60 secondi prima della scadenza), l’SDK ne recupera automaticamente uno nuovo utilizzando le stesse credenziali client.
4. Non sono coinvolti token di aggiornamento. Le credenziali client stesse sono il secret di lunga durata e possono sempre essere utilizzate per generare un nuovo token di accesso.

Autenticazione esplicita

Se desideri recuperare il token in modo proattivo (ad esempio, per generare rapidamente un errore in caso di credenziali errate all’avvio):

1
const auth = new ServerToServerAuth({ clientId: "...", clientSecret: "..." });
2
await auth.authenticate(); // throws AuthenticationError if credentials are invalid
3
const client = new FrameioClient({ token: () => auth.getToken() });

Web app (codice di autorizzazione)

Utilizza questo metodo per applicazioni lato server in cui gli utenti accedono con il proprio Adobe ID. Questo flusso richiede un client secret, che deve essere archiviato in modo sicuro sul server.

1
    import { WebAppAuth } from "frameio";
2
    import crypto from "crypto";
3
4
    const auth = new WebAppAuth({
5
        clientId: "YOUR_CLIENT_ID",
6
        clientSecret: "YOUR_CLIENT_SECRET",
7
        redirectUri: "https://yourapp.com/callback",
8
    });
9
10
    // Generate a cryptographically random state value to prevent CSRF attacks
11
    const state = crypto.randomBytes(32).toString("hex");
12
13
    const authorizationUrl = auth.getAuthorizationUrl({ state });
14
    // Store `state` in the user's session, then redirect them to `authorizationUrl`

1
    // In your callback handler (e.g. an Express route):
2
    await auth.exchangeCode(req.query.code as string);

1
    import { FrameioClient } from "frameio";
2
3
    const client = new FrameioClient({ token: () => auth.getToken() });

Esempio completo di Express

1
import crypto from "crypto";
2
import express from "express";
3
import session from "express-session";
4
import { FrameioClient, WebAppAuth } from "frameio";
5
6
const auth = new WebAppAuth({
7
    clientId: "YOUR_CLIENT_ID",
8
    clientSecret: "YOUR_CLIENT_SECRET",
9
    redirectUri: "http://localhost:3000/callback",
10
});
11
12
const app = express();
13
app.use(session({ secret: crypto.randomBytes(32).toString("hex"), resave: false, saveUninitialized: false }));
14
15
app.get("/login", (req, res) => {
16
    const state = crypto.randomBytes(32).toString("hex");
17
    (req.session as any).oauthState = state;
18
    res.redirect(auth.getAuthorizationUrl({ state }));
19
});
20
21
app.get("/callback", async (req, res) => {
22
    if (req.query.state !== (req.session as any).oauthState) {
23
        return res.status(403).send("Invalid state parameter");
24
    }
25
26
    await auth.exchangeCode(req.query.code as string);
27
28
    const client = new FrameioClient({ token: () => auth.getToken() });
29
    const accounts = await client.accounts.index();
30
    res.json(accounts);
31
});
32
33
app.listen(3000);

App a singola pagina/PKCE (codice di autorizzazione + PKCE)

Utilizza questa opzione per applicazioni basate su browser, applicazioni desktop o strumenti CLI che non possono archiviare in modo sicuro un secret del client. Questo flusso utilizza PKCE (RFC 7636) per proteggere lo scambio del codice di autorizzazione.

1
    import { SPAAuth } from "frameio";
2
3
    const auth = new SPAAuth({
4
        clientId: "YOUR_CLIENT_ID",
5
        redirectUri: "https://yourapp.com/callback",
6
    });
7
8
    const state = crypto.randomUUID();
9
    const result = await auth.getAuthorizationUrl({ state });
10
    // result.url            -> redirect the user here
11
    // result.codeVerifier   -> store this securely until the callback

1
    await auth.exchangeCode({
2
        code: "CODE_FROM_CALLBACK",
3
        codeVerifier: result.codeVerifier,
4
    });

1
    import { FrameioClient } from "frameio";
2
3
    const client = new FrameioClient({ token: () => auth.getToken() });

App nativa (codice di autorizzazione + PKCE)

Usa questo metodo per le applicazioni desktop e mobile. Quando crei una credenziale di app nativa in Adobe Developer Console, Adobe ti assegna un URI di reindirizzamento nel formato adobe+<hash>://callback</hash>: devi registrare l’applicazione per gestire quello schema URI personalizzato a livello di sistema operativo. Sono supportati anche i reindirizzamenti loopback (http://127.0.0.1:<port>/callback</port>) per lo sviluppo locale. Il flusso è identico a SPA: usa PKCE senza secret del client.

1
import { NativeAppAuth } from "frameio";
2
3
const auth = new NativeAppAuth({
4
    clientId: "YOUR_CLIENT_ID",
5
    redirectUri: "adobe+abc123def456://callback", // from your Adobe Developer Console Native App credential
6
    // Also supports loopback: "http://127.0.0.1:8080/callback"
7
});
8
9
const { url, codeVerifier } = await auth.getAuthorizationUrl({
10
    state: crypto.randomUUID(),
11
});
12
13
// Open system browser to `url`
14
// Listen for redirect on your custom URI scheme or loopback server
15
16
await auth.exchangeCode({ code: "CODE_FROM_REDIRECT", codeVerifier });
17
const client = new FrameioClient({ token: () => auth.getToken() });

Regole per l’URI di reindirizzamento

Adobe applica le regole per l’URI di reindirizzamento in due punti: quando registri le credenziali in Adobe Developer Console e quando il parametro redirect_uri raggiunge l’endpoint /authorize/v2. Il valore che passi a redirectUri in questo SDK deve corrispondere a uno dei pattern dell’URI di reindirizzamento che hai registrato nelle credenziali, altrimenti Adobe reinvia all’URI di reindirizzamento predefinito delle credenziali.

• Le credenziali per web app e SPA richiedono HTTPS.
• Le credenziali per app nativa usano un reindirizzamento non HTTPS, di solito l’URI adobe+<hash>://callback</hash> mostrato in Developer Console per le credenziali.

Consulta Adobe Developer Console per i pattern esatti accettati per le tue credenziali.

Aggiornamento manuale del token

Per i flussi di web app, SPA e app nativa, l’SDK aggiorna automaticamente i token tramite getToken(). Se hai bisogno di un controllo esplicito, puoi chiamare direttamente refresh():

1
await auth.refresh(); // fetches a new access token using the refresh token

Questo è utile quando vuoi forzare un aggiornamento prima di un’operazione critica anziché affidarti al buffer di aggiornamento automatico.

refresh() è disponibile su WebAppAuth, SPAAuth e NativeAppAuth. Genera ConfigurationError se non è disponibile alcun token di aggiornamento (ovvero devi prima chiamare exchangeCode()). ServerToServerAuth non ha un metodo refresh(). Devi usare authenticate() per recuperare un nuovo token tramite le credenziali client.

Persistenza del token

Tutte le classi di autenticazione supportano exportTokens() e importTokens() per mantenere lo stato del token durante i riavvii. Questo è particolarmente importante per i flussi di web app, SPA e app nativa, poiché i token di accesso e di aggiornamento risiedono in memoria per impostazione predefinita. Se l’applicazione si riavvia, gli utenti dovrebbero autenticarsi nuovamente, a meno che non li rendi persistenti. Per gli scenari server-to-server, la persistenza è facoltativa (le credenziali client possono sempre generare un nuovo token), ma l’importazione di un token memorizzato in cache evita un round-trip aggiuntivo all’avvio.

Esportazione e importazione

1
// After exchangeCode(), save the token state
2
const tokenData = auth.exportTokens();
3
// tokenData is: { access_token: "...", refresh_token: "...", expires_at: 1234567890.0 }
4
// Save it to your database, file, or secret store
5
6
// On next startup, restore it
7
auth.importTokens(tokenData);
8
const client = new FrameioClient({ token: () => auth.getToken() });
9
// The SDK will automatically refresh if the token is near expiry

Persistenza automatica con onTokenRefreshed

Per rendere automaticamente persistenti i token ogni volta che vengono aggiornati, usa il callback onTokenRefreshed:

1
import fs from "fs/promises";
2
3
const TOKEN_FILE = "tokens.json";
4
5
const auth = new WebAppAuth({
6
    clientId: "...",
7
    clientSecret: "...",
8
    redirectUri: "...",
9
    onTokenRefreshed: (tokens) => {
10
        fs.writeFile(TOKEN_FILE, JSON.stringify(tokens));
11
    },
12
});
13
14
// On startup, restore if available
15
try {
16
    const saved = JSON.parse(await fs.readFile(TOKEN_FILE, "utf-8"));
17
    auth.importTokens(saved);
18
} catch {
19
    // No saved tokens — user will need to authenticate
20
}

Il callback riceve la stessa forma di exportTokens() e viene attivato dopo ogni aggiornamento riuscito del token.

Revoca dei token

Per disconnettere un utente e invalidare i suoi token con Adobe IMS:

1
await auth.revoke();

Vengono inviate due richieste di revoca a Adobe IMS: una per il token di accesso e una per il token di aggiornamento, in parallelo. Lo stato del token locale viene cancellato completamente.Per i client riservati (WebAppAuth), le richieste di revoca utilizzano l’autenticazione HTTP Basic; per i client pubblici (SPAAuth, NativeAppAuth), il client_id viene inviato come parametro di query. Gli errori di revoca vengono registrati, ma non restituiti. Dopo la revoca, l’utente dovrà autenticarsi di nuovo.

Gestione degli errori

Tutti gli errori di autenticazione ereditano da FrameioAuthError, quindi puoi intercettarli in modo generale o gestire casi specifici:

1
import {
2
    FrameioAuthError,
3
    AuthenticationError,
4
    TokenExpiredError,
5
    ConfigurationError,
6
    NetworkError,
7
    RateLimitError,
8
} from "frameio";
9
10
try {
11
    await auth.exchangeCode("...");
12
} catch (error) {
13
    if (error instanceof TokenExpiredError) {
14
        // The refresh token has expired; redirect the user to sign in again
15
    } else if (error instanceof AuthenticationError) {
16
        // Token exchange failed
17
        console.error(`Error: ${error.errorCode} - ${error.errorDescription}`);
18
    } else if (error instanceof NetworkError) {
19
        // Timeout or connection failure (after retries)
20
    } else if (error instanceof RateLimitError) {
21
        // 429 from Adobe IMS; retry after error.retryAfter seconds
22
    } else if (error instanceof FrameioAuthError) {
23
        // Catch-all for any other auth error
24
    }
25
}

Riferimento dell’errore

Gestione dei token di aggiornamento scaduti in produzione

1
import { TokenExpiredError } from "frameio";
2
3
try {
4
    const client = new FrameioClient({ token: () => auth.getToken() });
5
    const assets = await client.files.list({ projectId: "..." });
6
} catch (error) {
7
    if (error instanceof TokenExpiredError) {
8
        // Clear persisted tokens and redirect user to login
9
        await auth.revoke();
10
        return res.redirect("/login");
11
    }
12
}

Riferimento della configurazione

Questi parametri hanno impostazioni predefinite sensibili e raramente devono essere impostati. Se devi personalizzarne il comportamento (ad esempio puntando a un IMS temporaneo, inserendo un fetch personalizzato, regolando i timeout o configurando un logger), passa qualsiasi di questi valori come parametri opzionali durante la creazione della classe di autenticazione:

Ambienti temporanei

Punta a un’istanza Adobe IMS temporanea sostituendo imsBaseUrl. L’SDK esporta anche DEFAULT_IMS_BASE_URL (https://ims-na1.adobelogin.com) se devi fare riferimento al valore di produzione a livello programmatico.

1
const auth = new ServerToServerAuth({
2
    clientId: "...",
3
    clientSecret: "...",
4
    imsBaseUrl: "https://ims-na1-stg1.adobelogin.com",
5
});

Recupero personalizzato

Per il supporto proxy o la configurazione TLS personalizzata:

1
import { ProxyAgent } from "undici";
2
3
const proxyAgent = new ProxyAgent("http://corporate-proxy:8080");
4
5
const auth = new ServerToServerAuth({
6
    clientId: "...",
7
    clientSecret: "...",
8
    fetch: (url, init) => fetch(url, { ...init, dispatcher: proxyAgent }),
9
});

Sicurezza della contemporaneità

TypeScript SDK è sicuro per l’uso contemporaneo. Quando vengono eseguite più chiamate getToken() contemporaneamente e serve un aggiornamento, viene attivata una sola richiesta di aggiornamento. Le altre attendono la stessa promessa e ricevono lo stesso risultato. Non è richiesto alcun blocco esterno. Questa deduplicazione usa il ciclo di eventi a thread singolo di JavaScript e una promessa (promise) condivisa: se un aggiornamento è già in corso, i chiamanti contemporanei si uniscono ad esso, invece di avviare una seconda richiesta. Se revoke() viene chiamato mentre un aggiornamento è in corso, l’aggiornamento viene rifiutato con un AuthenticationError e i token rimangono cancellati: la revoca ha sempre la priorità.