TypeScript SDK in Frame.io – Authentifizierungsleitfaden

In diesem Leitfaden wird erklärt, wie Sie sich mit der Frame.io-API über das TypeScript SDK in Frame.io (frameio) authentifizieren.In der Frame.io V4-API wird der Adobe Identity Management Service (IMS) genutzt, die OAuth-2.0-Identitätsplattform von Adobe.Dies ist eine eigenständige Referenz für TypeScript-/JavaScript-Entwickelnde.Alle unten stehenden Codebeispiele und Flüsse gelten ausschließlich für das frameio-Paket.

Authentifizierungstypen im TypeScript SDK

Im TypeScript SDK werden vier OAuth-Authentifizierungsklassen plus die direkte Token-Nutzung unterstützt:

Dienstkonto-User

Bei der Server-zu-Server-Authentifizierung fungiert Ihre Anwendung als Dienstkonto-User, ein spezieller Kontotyp, mit dem im Namen des Services Aktionen durchgeführt werden können.Diese sind für andere Benutzende in Frame.io sichtbar: Wenn eine Aktion von einem Dienstkonto durchgeführt wird, wird dessen Name in der Bedienoberfläche angezeigt.Sie können dem Dienstkonto über die Adobe Admin Console und die Developer Console Zugriff gewähren und diesen widerrufen.Die Namen von Dienstkonten werden über die Frame.io-Bedienoberfläche verwaltet.Standardmäßig heißt Ihre erste S2S-Verbindung Dienstkonto-User, die zweite Dienstkonto-User 2 und so weiter.

Schnellstart

Voraussetzungen

1. Anmeldedaten von der Adobe Developer Console:

• Client-ID – für alle OAuth-Flüsse erforderlich - Clientschlüssel – für Server-zu-Server- und Web-Anwendungsflüsse erforderlich - Umleitungs-URI – für Web-Anwendungs-, SPA- und native Anwendungsflüsse erforderlich; muss in Ihrem Adobe-Projekt registriert sein

2. SDK installieren:

$
npm install frameio

Auswählen einer Methode

• **Keine Benutzenden beteiligt?**Verwenden Sie Server-zu-Server (ServerToServerAuth).
• **Benutzende beteiligt und Sie können einen Schlüssel speichern?**Verwenden Sie Web-Anwendung (WebAppAuth).
• **Benutzende beteiligt, aber Sie können keinen Schlüssel speichern?**Verwenden Sie bei Browser-Anwendungen SPA (SPAAuth) und bei Desktop- oder mobilen Anwendungen Native App (NativeAppAuth).

Zugriffstoken

Falls Sie bereits über einen Zugriffstoken verfügen (aus einem anderen OAuth-System oder von einem vorherigen Austausch, z. B. über unseren API-Explorer), können Sie ihn direkt übergeben:

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

Dies ist die einfachste Herangehensweise, aber der Token wird letztendlich ablaufen und wird nicht vom SDK aktualisiert.

Ältere Entwicklungstoken

Bei V4-migrierten Konten, die noch nicht über die Adobe Admin Console verwaltet werden, können Sie weiterhin ältere Entwicklungstoken von der Frame.io-Entwickelnden-Website verwenden.Sie müssen den Header x-frameio-legacy-token-auth einbeziehen und auf true setzen:

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
});

Ältere Entwicklungstoken laufen nicht ab, sind aber ein Übergangsmechanismus.Für neue Integrationen und Produktionskapazität empfehlen wir die Verwendung einen der unten stehenden OAuth-2.0-Flüsse.Weitere Details finden Sie im Migrationsleitfaden.

Server-zu-Server (Client-Anmeldedaten)

Verwenden Sie dies für Backend-Services und Skripte, die Zugriff auf Frame.io ohne Benutzendeninteraktion benötigen.Dieser Fluss ist nur für Frame.io V4-Konten verfügbar, die über die Adobe Admin Console verwaltet werden.Deine Anwendung wird ohne menschliche Eingriffe als Dienstkonto-User authentifiziert.

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() });

Das ist alles.auth.getToken() ist eine asynchrone Funktion, die bei jeder Anfrage vom SDK aufgerufen wird.Wenn der aktuelle Token noch gültig ist, wird er sofort zurückgegeben.Wenn er kurz vor dem Ablauf steht, wird zuerst ein neuer Token abgerufen, völlig transparent.

So funktioniert es

Ihre Client-Anmeldedaten (Client-ID und Schlüssel) laufen niemals ab.Sie rotieren sie lediglich manuell, aus Sicherheitsgründen.Durch S2S haben Sie praktisch permanenten, ununterbrochenen API-Zugriff ohne manuelle Eingriffe.

Unter der Haube:

1. Beim ersten API-Aufruf wird von getToken() mithilfe des client_credentials-Grant ein neues Zugriffstoken von Adobe IMS angefordert.
2. Der Token wird im Arbeitsspeicher zwischengespeichert.Einzelne Zugriffstoken laufen ab (in der Regel nach 24 Stunden), aber das wird für Sie gehandhabt.
3. Wenn ein zwischengespeicherter Token innerhalb des Aktualisierungspuffers liegt (Standard: 60 Sekunden vor Ablauf), wird vom SDK mit denselben Client-Anmeldedaten automatisch ein neuer abgerufen.
4. Es sind keine Aktualisierungstoken beteiligt.Die Client-Anmeldedaten selbst sind das langlebige Geheimnis, und sie können immer verwendet werden, um einen neuen Zugriffstoken zu prägen.

Explizite Authentifizierung

Wenn Sie den Token frühzeitig abrufen möchten (zum Beispiel, um beim Start schnell mit ungültigen Anmeldedaten zu scheitern):

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-Anwendung (Autorisierungscode)

Eignet sich für serverseitige Anwendungen, bei denen sich Benutzende mit ihrer Adobe ID anmelden.Für diesen Fluss ist ein Clientschlüssel erforderlich, der sicher auf Ihrem Server gespeichert werden muss.

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() });

Vollständiges Express-Beispiel

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);

Single Page App / PKCE (Autorisierungscode und PKCE)

Dies ist für browserbasierte Anwendungen, Desktop-Anwendungen oder CLI-Tools vorgesehen, in denen ein Clientschlüssel nicht sicher gespeichert werden kann.In dem Fluss wird PKCE (RFC 7636) eingesetzt, um den Austausch des Autorisierungscodes zu schützen.

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() });

Native App (Autorisierungscode und PKCE)

Verwenden Sie dies für Desktop- und mobile Anwendungen.Wenn Sie in der Adobe Developer Console Anmeldedaten für eine Native App erstellen, wird Ihnen von Adobe eine Umleitungs-URI in der Form adobe+<hash>://callback</hash> zugewiesen. Sie registrieren Ihre Anwendung, um dieses selbstdefinierte URI-Schema auf BS-Ebene zu verarbeiten.Loopback-Umleitungen (http://127.0.0.1:<port>/callback</port>) werden bei der lokalen Entwicklung ebenfalls unterstützt.Der Fluss ist mit SPA identisch, dabei wird PKCE ohne Clientschlüssel verwendet.

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() });

Regeln für Umleitungs-URIs

Die Regeln für Umleitungs-URI werden an zwei Punkten von Adobe durchgesetzt: wenn Sie die Anmeldedaten in der Adobe Developer Console registrieren, und wenn der Parameter redirect_uri den Endpunkt /authorize/v2 erreicht.Der Wert, den Sie in diesem SDK an redirectUri weitergeben, muss einem der „Umleitungs-URI-Muster“ entsprechen, die Sie für die Anmeldedaten registriert haben. Andernfalls wird zu dem Standard-Umleitungs-URI der Anmeldedaten umgeleitet.

• Für die Anmeldedaten für Web-Anwendungen und SPA ist HTTPS erforderlich.
• Bei Anmeldedaten für Native App wird eine nicht-HTTPS-Umleitung verwendet, in der Regel der adobe+<hash>://callback</hash>-URI, der in der Developer Console für die Anmeldedaten angezeigt wird.

Die genauen Muster, die für Ihre Anmeldedaten akzeptiert werden, finden Sie in der Adobe Developer Console.

Manuelle Aktualisierung der Token

Bei Web-Anwendungs-, SPA- und Native App-Flüssen werden Token durch das SDK automatisch über getToken() aktualisiert.Falls Sie explizite Steuerung benötigen, können Sie refresh() direkt aufrufen:

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

Das ist nützlich, wenn Sie vor einem wichtigen Vorgang eine Aktualisierung erzwingen möchten, anstatt sich auf den automatischen Aktualisierungspuffer zu verlassen.

refresh() ist in WebAppAuth, SPAAuth und NativeAppAuth verfügbar.Damit wird ein ConfigurationError ausgelöst, wenn kein Aktualisierungstoken verfügbar ist (d. h., Sie müssen zuerst exchangeCode() aufrufen).Bei ServerToServerAuth gibt es keine refresh()-Methode. Hier wird authenticate() verwendet, um stattdessen über Client-Anmeldedaten ein neues Token abzurufen.

Token-Persistenz

exportTokens() und importTokens() werden von allen Auth-Klassen unterstützt, um den Tokenstatus auch nach Neustarts aufrechtzuerhalten.Für Web-Anwendungs-, SPA- und Native App-Flows ist das besonders wichtig, da Zugriffs- und Aktualisierungstoken standardmäßig im Arbeitsspeicher gespeichert werden. Wenn Ihre Anwendung neu startet, müssten Benutzende sich erneut authentifizieren, es sei denn, Sie speichern sie dauerhaft.Bei Server-zu-Server ist die Persistenz optional (es kann immer ein neuer Token mit den Anmeldedaten erstellt werden), doch durch das Importieren eines zwischengespeicherten Tokens wird ein zusätzlicher Umlauf beim Start vermieden.

Exportieren und Importieren

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

Automatische Persistenz mit onTokenRefreshed

Damit Token bei jeder Aktualisierung automatisch dauerhaft gespeichert werden, verwenden Sie den Rückruf 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
}

Der Rückruf erhält die gleiche Form wie exportTokens() und wird nach jeder erfolgreichen Tokenaktualisierung ausgelöst.

Widerrufen von Token

So melden Sie Benutzende ab und machen deren Token mit Adobe IMS ungültig:

1
await auth.revoke();

Damit werden parallel zwei bestmögliche Widerrufsanfragen an Adobe IMS gesendet, eine für den Zugriffstoken und eine für den Aktualisierungstoken. Anschließend wird der Status aller lokalen Token gelöscht. Bei vertraulichen Clients (WebAppAuth) wird HTTP Basic Auth für Widerrufsanfragen verwendet; bei öffentlichen Clients (SPAAuth, NativeAppAuth) wird die client_id als Abfrageparameter gesendet.Widerrufsfehler werden protokolliert, aber nicht ausgelöst.Nach dem Widerruf müssen Benutzende sich erneut authentifizieren.

Fehlerbehandlung

Alle Authentifizierungsfehler übernehmen von FrameioAuthError, sodass Sie sie allgemein abfangen oder spezifische Fälle behandeln können:

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
}

Fehlerreferenz

Umgang mit abgelaufenen Aktualisierungstoken in der Produktion

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
}

Konfigurationsreferenz

Diese Parameter haben sinnvolle Standardwerte und müssen selten eingestellt werden.Falls Sie das Verhalten anpassen müssen – etwa auf ein Staging-IMS weisen, einen selbstdefinierten fetch einschleusen, Timeouts anpassen oder eine Protokolleinrichtung verschalten – übergeben Sie beim Erstellen der Authentifizierungsklasse beliebige davon als optionale Parameter:

Staging-Umgebungen

Weisen Sie auf eine Staging-Instanz von Adobe IMS, indem Sie imsBaseUrl überschreiben.Vom SDK wird auch DEFAULT_IMS_BASE_URL (https://ims-na1.adobelogin.com) exportiert, falls Sie den Produktionswert programmgesteuert referenzieren müssen.

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

Selbstdefinierter Abruf

Für Proxy-Unterstützung oder selbstdefinierte TLS-Konfiguration:

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
});

Sicherheit bei Nebenläufigkeit

Das TypeScript SDK kann bedenkenlos nebenläufig verwendet werden.Wenn mehrere getToken()-Aufrufe gleichzeitig stattfinden und eine Aktualisierung erforderlich ist, wird nur eine Aktualisierungsanfrage ausgelöst.Die anderen warten auf dasselbe Versprechen und erhalten dasselbe Ergebnis.Es ist keine externe Sperrung erforderlich.Bei dieser Deduplizierung wird die Ereignisschleife mit einzelnem Thread von JavaScript und ein geteiltes Promise verwendet. Falls bereits eine Aktualisierung läuft, schließen gleichzeitige Aufrufer sich dieser an, anstatt eine zweite Anfrage zu starten.Wird während einer Aktualisierung revoke() aufgerufen, wird die Aktualisierung mit einem AuthenticationError abgelehnt und die Token bleiben gelöscht – der Widerruf hat stets Vorrang.