Python SDK in Frame.io – Authentifizierungsleitfaden

In diesem Leitfaden wird erklärt, wie Sie sich mit der Frame.io-API über das Python 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 Python-Entwickelnde.Alle unten stehenden Codebeispiele und Flüsse gelten ausschließlich für das frameio-Paket.

Authentifizierungstypen im Python SDK

Im Python SDK werden vier Authentifizierungsoptionen 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-App-Flüsse erforderlich - Umleitungs-URI: für Web-Anwendungs- und SPA-Flüsse erforderlich; muss in Ihrem Adobe-Projekt registriert sein

2. SDK installieren:

$
pip 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 SPA (SPAAuth).

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
from frameio import Frameio
2
3
client = Frameio(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
from frameio import Frameio
2
3
client = Frameio(
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
    from frameio import Frameio
2
    from frameio.auth import ServerToServerAuth
3
4
    auth = ServerToServerAuth(
5
        client_id="YOUR_CLIENT_ID",
6
        client_secret="YOUR_CLIENT_SECRET",
7
    )
8
9
    client = Frameio(token=auth.get_token)

Das ist alles.auth.get_token ist eine aufrufbare 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 get_token mithilfe des client_credentials-Grants ein neuer 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
auth = ServerToServerAuth(client_id="...", client_secret="...")
2
auth.authenticate()  # raises AuthenticationError if credentials are invalid
3
client = Frameio(token=auth.get_token)

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
    auth.refresh()  # fetches a new access token using the refresh token

1
    auth.refresh()  # fetches a new access token using the refresh token

1
        from frameio import Frameio
2
3
        client = Frameio(token=auth.get_token)

Vollständiges Flask-Beispiel

1
import secrets
2
from flask import Flask, redirect, request, session
3
from frameio import Frameio
4
from frameio.auth import WebAppAuth
5
6
app = Flask(__name__)
7
app.secret_key = secrets.token_bytes(32)
8
9
auth = WebAppAuth(
10
    client_id="YOUR_CLIENT_ID",
11
    client_secret="YOUR_CLIENT_SECRET",
12
    redirect_uri="http://localhost:5000/callback",
13
)
14
15
@app.route("/login")
16
def login():
17
    state = secrets.token_urlsafe(32)
18
    session["oauth_state"] = state
19
    return redirect(auth.get_authorization_url(state=state))
20
21
@app.route("/callback")
22
def callback():
23
    if request.args.get("state") != session.pop("oauth_state", None):
24
        return "Invalid state parameter", 403
25
26
    auth.exchange_code(code=request.args["code"])
27
28
    client = Frameio(token=auth.get_token)
29
    accounts = client.accounts.index()
30
    return f"Authenticated — {len(accounts.data)} account(s) accessible."

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
        from frameio.auth import SPAAuth
2
3
        auth = SPAAuth(
4
            client_id="YOUR_CLIENT_ID",
5
            redirect_uri="https://yourapp.com/callback",
6
        )
7
8
        import secrets
9
        state = secrets.token_urlsafe(32)
10
11
        result = auth.get_authorization_url(state=state)
12
        # result.url            -> redirect the user here
13
        # result.code_verifier  -> store this securely until the callback

1
        auth.exchange_code(
2
            code="CODE_FROM_CALLBACK",
3
            code_verifier=result.code_verifier,
4
        )

1
        from frameio import Frameio
2
3
        client = Frameio(token=auth.get_token)

Asynchrone Verwendung

Zu jeder Autorisierungsklasse gibt es ein asynchrones Gegenstück, dem das Präfix Async vorangestellt ist. Die obigen Codebeispiele enthalten die Registerkarten Sync und Async, wo zutreffend.

Manuelle Aktualisierung der Token

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

1
    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.

Token-Persistenz

export_tokens() und import_tokens() werden von allen Authentifizierungsklassen unterstützt, um den Tokenstatus auch nach Neustarts aufrechtzuerhalten.Für Web-Anwendungs- und SPA-Flüsse 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 die Token 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 exchange_code(), save the token state
2
token_data = auth.export_tokens()
3
# token_data is a dict: {"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.import_tokens(token_data)
8
client = Frameio(token=auth.get_token)
9
# The SDK will automatically refresh if the token is near expiry

Automatische Persistenz mit on_token_refreshed

Damit Token bei jeder Aktualisierung automatisch dauerhaft gespeichert werden, verwenden Sie den Rückruf on_token_refreshed:

1
import json
2
from pathlib import Path
3
4
TOKEN_FILE = Path("tokens.json")
5
6
def save_tokens(tokens: dict):
7
    TOKEN_FILE.write_text(json.dumps(tokens))
8
9
auth = WebAppAuth(
10
    client_id="...",
11
    client_secret="...",
12
    redirect_uri="...",
13
    on_token_refreshed=save_tokens,
14
)
15
16
# On startup, restore if available
17
if TOKEN_FILE.exists():
18
    auth.import_tokens(json.loads(TOKEN_FILE.read_text()))

Der Rückruf erhält die gleiche dict-Form wie export_tokens() und wird nach jeder erfolgreichen Tokenaktualisierung ausgelöst. Für die asynchronen Klassen kann on_token_refreshed entweder eine reguläre Funktion oder eine async-Funktion sein.Beide werden unterstützt.

Widerrufen von Token

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

1
auth.revoke()

Damit wird sowohl für den Zugriffstoken als auch für den Aktualisierungstoken eine bestmögliche Widerrufsanfrage an Adobe IMS gesendet. Anschließend wird der Status aller lokalen Token gelöscht.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
from frameio.auth import (
2
    FrameioAuthError,
3
    AuthenticationError,
4
    TokenExpiredError,
5
    ConfigurationError,
6
    NetworkError,
7
    RateLimitError,
8
)
9
10
try:
11
    auth.exchange_code(code="...")
12
except TokenExpiredError:
13
    # The refresh token has expired; redirect the user to sign in again
14
    pass
15
except AuthenticationError as e:
16
    # Token exchange failed
17
    print(f"Error: {e.error_code} - {e.error_description}")
18
except NetworkError:
19
    # Timeout or connection failure (after retries)
20
    pass
21
except RateLimitError as e:
22
    # 429 from Adobe IMS; retry after e.retry_after seconds
23
    pass
24
except FrameioAuthError:
25
    # Catch-all for any other auth error
26
    pass

Fehlerreferenz

Umgang mit abgelaufenen Aktualisierungstoken in der Produktion

1
from frameio.auth import TokenExpiredError
2
3
try:
4
    client = Frameio(token=auth.get_token)
5
    assets = client.files.list(project_id="...")
6
except TokenExpiredError:
7
    # Clear persisted tokens and redirect user to login
8
    auth.revoke()
9
    return redirect("/login")

Konfigurationsreferenz

Diese optionalen Parameter werden von allen Authentifizierungsklassen akzeptiert:

Staging-Umgebungen

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

1
auth = ServerToServerAuth(
2
    client_id="...",
3
    client_secret="...",
4
    ims_base_url="https://ims-na1-stg1.adobelogin.com",
5
)

Selbstdefinierter HTTP-Client

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

1
import httpx
2
3
http_client = httpx.Client(
4
    proxy="http://corporate-proxy:8080",
5
    verify="/path/to/custom-ca-bundle.pem",
6
)
7
8
auth = ServerToServerAuth(
9
    client_id="...",
10
    client_secret="...",
11
    http_client=http_client,
12
)

Thread-Sicherheit

Die synchronen Authentifizierungsklassen sind vollkommen Thread-sicher.Wenn get_token von mehreren Threads gleichzeitig aufgerufen wird und eine Aktualisierung erforderlich ist, wird die Aktualisierung nur von einem Thread durchgeführt.Die anderen warten und erhalten das gleiche Ergebnis.Es ist keine externe Sperrung erforderlich.Die asynchronen Klassen bieten mit asyncio.Lock dieselbe Garantie, sicher für gleichzeitige Koroutinen innerhalb einer einzelnen Ereignisschleife.