Leitfaden: Autorisieren

Einführung

In diesem Leitfaden wird der Authentifizierungs- und Autorisierungsvorgang für C2C-Geräte (Camera to Cloud) in einem Frame.io-Projekt erläutert.Wir werden sowohl die standardmäßige manuelle Codeeingabe als auch den verbesserten Ansatz zur QR-Code-Kopplung für eine optimale Benutzererfahrung beleuchten.

Was benötige ich?

Lesen Sie den Leitfaden Vorbereitung der Implementierung, wenn Sie dies noch nicht getan haben.Sie haben ein client_secret von unserem Team erhalten, um Ihre Integration zu identifizieren.Falls nicht, lesen Sie bitte diese Einführung in das C2C-Ökosystem und wenden Sie sich an unser Team.

Voraussetzungen für die URL- und QR-Code-Kopplung

Um die URL- und QR-Code-Kopplung zu implementieren, stellen Sie sicher, dass Sie die folgenden Anforderungen erfüllen:

• Gerätekompatibilität: Stellen Sie sicher, dass das Gerät die Generierung von URL-/QR-Code während des Kopplungsprozesses unterstützt.

Führung durch den Autorisierungsfluss

Um den Autorisierungsfluss aus der Benutzerperspektive zu verstehen, verweisen Sie auf die folgenden Ressourcen:

• Support-Artikel zum Hinzufügen neuer Geräte.
• Schulungsvideo zur Autorisierung eines Teradek Cube.

Durch diesen Autorisierungsprozess werden die Implementierungsanforderungen minimiert.Folgendes ist nicht erforderlich:

• Weiterleitung an Webbrowser (außer bei Verwendung von URL-Code-Kopplung)
• Bearbeitung der Frame.io-Benutzerauthentifizierung
• Bereitstellung von Schnittstellen für die Konto-/Projektauswahl
• Entwicklung komplexer UI-Komponenten, die über grundlegende Informationsanzeigen hinausgehen

Verbesserung der Benutzererfahrung durch URL-Code-Kopplung

Moderne Benutzende erwarten effiziente Interaktionen mit Geräten.Der derzeitige manuelle Kopplungsprozess funktioniert zwar zufriedenstellend, lässt sich jedoch optimieren.

Durch die Einführung einer Kopplung von URL und QR-Code – ähnlich wie bei Streaming-Diensten wie Netflix oder Disney+ – können wir den Prozess erheblich vereinfachen, Eingabefehler minimieren und die Kopplungszeit verkürzen.

Geräteidentifikation (client_id)

Jedes physische Gerät benötigt eine eindeutige Kennung zur Nachverfolgung der Verbindung innerhalb des Projekts eines Benutzenden.

Bei Geräten ist diese Kennung die client_id, die während der Autorisierung erforderlich ist.Berücksichtigen Sie bei der Implementierung geeignete Identifikationsquellen wie Seriennummern von Geräten, UUIDs oder andere eindeutige Zeichenfolgen.Wenn Sie die Integration auf einem Apple-Gerät vornehmen, empfehlen wir die Verwendung einer eindeutigen, dauerhaften UUID, die auch nach einem Neustart des Geräts unverändert bleibt.Seien Sie vorsichtig in Bezug auf personenbezogene Daten.E-Mail-Adressen von Benutzenden sind keine geeigneten client_id-Werte.

Achten Sie außerdem darauf, die Kennung zu kontrollieren.Geräte-MAC-Adressen sind ungeeignet, da sie nicht im Besitz Ihrer Software sind und personenbezogene Daten darstellen können.

Wenn Sie Hilfe bei der Auswahl einer geeigneten Kennung benötigen, kann unser Team Ihnen bei der Ermittlung eines geeigneten Werts helfen, der die Integration vereinfacht.

Schritt 1: Einen Gerätecode anfordern

Um mit der Implementierung zu beginnen, fordern Sie einen Gerätecode über den /v2/auth/device/code-Endpunkt an:

Herkömmliche Kopplungsmethode

curl -X POST https://api.frame.io/v2/auth/device/code \
    --form 'client_id=[client_id]' \
    --form 'client_secret=[client_secret]' \
    --form 'scope=asset_create offline' \
    | python -m json.tool

URL-Code-Kopplung aktivieren

Um eine URL-Code-Kopplung vorzunehmen, ergänzen Sie den API-Aufruf um zusätzliche Header:

curl -X POST https://api.frame.io/v2/auth/device/code \
    --header "x-client-version: 2.0.0" \
    --header "x-client-platypus-enabled: true" \  # New header to enable URL pairing
    --form 'client_id=[client_id]' \
    --form 'client_secret=[client_secret]' \
    --form 'scope=asset_create offline' \
    | python -m json.tool

Hinweis: Diese Authentifizierungsendpunkte akzeptieren ausschließlich Formulardaten, nicht JSON.Nach der Authentifizierung akzeptieren andere Endpunkte JSON-Payloads, während Authentifizierungsendpunkte JSON-Anfragen ablehnen.

Payload-Parameter

• client_id: Die eindeutige Kennung für Ihr physisches Gerät.Diese muss eindeutig sein, wie z. B. eine Seriennummer oder eine UUID.

• client_secret: Wird von Frame.io zur Identifizierung Ihres Gerätemodells bereitgestellt.Dieser vertrauliche Wert sollte vor Benutzenden geschützt und bei der Speicherung verschlüsselt bleiben.

• scope: Die angeforderten Berechtigungen, getrennt durch Leerzeichen.Geräte können Folgendes anfordern:

• asset_create: Ermöglicht das Erstellen und Hochladen von Assets.* offline: Ermöglicht die Aktualisierung der Autorisierung über einen Aktualisierungstoken.Ohne diesen Gültigkeitsbereich müssten Nutzer ihr Gerät alle 8 Stunden neu autorisieren, da die Autorisierungstoken ablaufen.

In der Praxis fordern Geräte in der Regel beide Gültigkeitsbereiche an.

API-Antwort verstehen

Die Anfrage erzeugt eine Antwort ähnlich der folgenden:

Herkömmliche Kopplungsreaktion

{
  "device_code": "[device_code]",
  "expires_in": 120,
  "interval": 5,
  "name": "MyDevice-[client_id]",
  "user_code": "573131"
}

URL-Kopplungsreaktion

{
  "device_code": "[device_code]",
  "expires_in": 120,
  "interval": 5,
  "name": "MyDevice-[client_id]",
  "user_code": "573131",
  "verification_uri": "https://next.frame.io/pair",
  "verification_uri_complete": "https://next.frame.io/pair/573131"
}

Aufschlüsselung der Antworten

• device_code: Diese interne Kennung sollte für Benutzende verborgen bleiben und die Autorisierungsanfrage während der Abfrage identifizieren.
• expires_in: Der Gültigkeitszeitraum des Codes in Sekunden.
• interval: Das empfohlene Abfrageintervall in Sekunden.
• name: Die Kennung des Verbindungsgeräts.
• user_code: Der sechsstellige Code für die manuelle Eingabe in Frame.io zur Gerätekopplung.
• verification_uri: Die Basis-URL für die manuelle Eingabe, wenn kein QR-Scannen verfügbar ist.
• verification_uri_complete: Die vollständige URL mit dem Kopplungscode, die für die Verlinkung innerhalb einer mobilen App oder die Erstellung eines QR-Codes vorgesehen ist, um die Navigation der Benutzenden zur Kopplungsoberfläche zu vereinfachen.

QR-Codes für Benutzende anzeigen

Erstellen Sie mithilfe von verification_uri_complete einen QR-Code und zeigen Sie ihn auf dem Bildschirm des Geräts an, damit der Benutzende ihn scannen kann, was eine effiziente Kopplung ermöglicht.

Beispiel: Gerätebildschirm mit QR-Code

Bieten Sie stets Ausweichmöglichkeiten an: Zeigen Sie den user_code und die verification_uri zur manuellen Eingabe an, falls das Scannen des QR-Codes nicht möglich ist.Alternativ können Sie die verification_uri als statischen QR-Code für mobiles Scannen anzeigen.Bei der Integration in mobile Apps sollten Sie den Parameter verification_uri_complete als anklickbaren Hyperlink einfügen, da Nutzer auf dem Gerät, auf dem die App läuft, keine QR-Codes scannen können.

Schritt 2: Die Benutzerautorisierung abfragen

Nachdem Sie den Kopplungscode oder den URL-Code angegeben haben, überprüfen Sie die Benutzereingabe mit dieser Anfrage:

curl -X POST https://api.frame.io/v2/auth/token \
    --form 'client_id=[client_id]' \
    --form 'device_code=[device_code]' \
    --form 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \
    | python -m json.tool

Payload-Parameter

• client_id: Dieselbe Kennung wie in Schritt 1.
• device_code: Der Wert device_code, der zuvor zurückgegeben wurde.
• grant_type: Die OAuth-Berechtigungstyp-ID, konsistent urn:ietf:params:oauth:grant-type:device_code für diese Implementierung.

Erste Abfrageversuche liefern in der Regel folgende Ergebnisse:

{
  "error": "authorization_pending"
}

Dieser nicht schwerwiegende Fehler zeigt an, dass der Benutzende die Codeeingabe nicht abgeschlossen hat.Fahren Sie mit der Abfrage fort, bis der Vorgang abgeschlossen ist.

Hinweis für iOS-Geräte: Wenn der Benutzende zur Frame.io-iOS-App wechselt, um den Kopplungscode einzugeben, wird Ihre App möglicherweise in den Hintergrund verschoben.Wenn Ihre App wieder aktiv wird, beispielsweise in der Methode applicationDidBecomeActive, setzen Sie die Abfrage fort, damit der Autorisierungsablauf fortgesetzt werden kann, ohne dass der Benutzende die Kopplung neu starten muss.

Wenn Sie Folgendes erhalten:

{
  "error": "expired_token"
}

Der Code ist vor der Benutzereingabe abgelaufen.Generieren Sie einen neuen Code/QR-Code über Schritt 1, stellen Sie ihn dem Benutzenden bereit und setzen Sie die Abfrage fort.

Bei erfolgreicher Autorisierung wird Folgendes ausgegeben:

{
  "access_token": "[access_token]",
  "expires_in": 28800,
  "refresh_token": "[refresh_token]",
  "token_type": "bearer"
}

Herzlichen Glückwunsch! Sie haben Ihre Kamera erfolgreich für das Cloud-Gerät autorisiert.

Sehen wir uns diese Antwort an:

• access_token: Ihre Authentifizierungsanmeldedaten für den Frame.io-Backend-Zugriff, erforderlich in Headern für zukünftige API-Anfragen.
• expires_in: Der Gültigkeitszeitraum des Zugriffstokens in Sekunden, nach dem eine Aktualisierung erforderlich ist.
• refresh_token: Wird für die Verwaltung von Zugriffstoken verwendet, hauptsächlich für die Aktualisierung der Autorisierung, aber auch für den Widerruf.
• token_type: Wird bei C2C-API-Implementierungen stets als bearer verwendet; es sind keine Maßnahmen erforderlich.

Die Schritte zusammenfügen

Wir implementieren nun diese API-Aufrufe in Python-ähnlichem Pseudocode und behandeln den möglichen Ablauf von Gerätecodes:

1
def authorize_with_frame():
2
    """
3
    Handles authorizing our device with Frame.io.
4
    """
5
6
    # Our client ID can be a serial number, UUID, or some other unique string.
7
    client_id = THIS_DEVICE.get_serial_number()
8
9
    while True:
10
        # Make the call to Frame.io to get our device codes.
11
        pairing_codes = c2c.get_device_codes(client_id)
12
13
        # We need to keep track of how long we have been polling for
14
        polling_started = datetime.now()
15
16
        # Now we are going to poll for authorization until the user enters the code.
17
        while True:
18
19
            # Re-write this output each time we poll. Note: This message will only update once
20
            # per `interval` (e.g., 5 seconds), so if a smooth countdown is desired, that will
21
            # need a different implementation.
22
            print(
23
                f"\rPAIRING CODE: {pairing_codes.user_code}, "
24
                f"EXPIRES IN: {pairing_codes.expires_in - (datetime.now() - polling_started).seconds} seconds"
25
            )
26
27
            # Wait for `interval` before polling each time.
28
            sleep(pairing_codes.interval)
29
30
            # Make a call to Frame.io to see if the user has entered the code and authorized
31
            # the device.
32
            authorization, error = c2c.poll_for_authorization(
33
                client_id, pairing_codes.device_code
34
            )
35
36
            if error and error.message == "authorization_pending":
37
                # If the authorization is pending, try again.
38
                continue
39
            elif error and error.message == "expired_token":
40
                # If the pairing codes have expired, break to generate new codes.
41
                break
42
            elif error:
43
                # If there was some other error, raise it.
44
                raise error
45
            else:
46
                # If there was no error, we have our authorization!
47
                return authorization
48
49
        # If we get here, our pairing codes expired. Let's try again.
50
        print("\nPairing code expired. Generating a new one...")

Hinweis: Die äußere Schleife behandelt Fälle, in denen Kopplungscodes ablaufen und neue Codes benötigt werden.

Rufen Sie als letzten Schritt die Projektinformationen aus Frame.io ab und zeigen Sie sie an, um zu überprüfen, ob die Kopplung mit dem gewünschten Projekt erfolgreich war.Dies wird im nächsten Tutorial behandelt.

QR-Codes für die Kopplung erstellen und anzeigen

Bei der Implementierung der Kopplung von URL und QR-Code müssen Sie anhand des Werts verification_uri_complete in der Antwort einen QR-Code generieren.Hier sind einige Beispiele für die Verwendung gängiger Bibliotheken in verschiedenen Programmiersprachen:

Python-Beispiel mit QR-Code

1
import qrcode
2
from PIL import Image
3
import io
4
5
def generate_qr_code(verification_uri_complete, size=250):
6
    """
7
    Generate a QR code from the verification_uri_complete URL.
8
    
9
    Args:
10
        verification_uri_complete (str): The complete verification URI returned by Frame.io
11
        size (int, optional): Size of the QR code in pixels. Defaults to 250.
12
    
13
    Returns:
14
        PIL.Image: QR code image that can be displayed or saved
15
    """
16
    qr = qrcode.QRCode(
17
        version=1,
18
        error_correction=qrcode.constants.ERROR_CORRECT_L,
19
        box_size=10,
20
        border=4,
21
    )
22
    qr.add_data(verification_uri_complete)
23
    qr.make(fit=True)
24
    
25
    img = qr.make_image(fill_color="black", back_color="white")
26
    
27
    # Resize the image if needed
28
    img = img.resize((size, size))
29
    return img
30
31
# Example usage in authorization flow
32
def display_qr_for_pairing(pairing_codes):
33
    """
34
    Generate and display QR code along with manual pairing instructions.
35
    """
36
    if hasattr(pairing_codes, 'verification_uri_complete'):
37
        # Generate QR code from the verification URI
38
        qr_img = generate_qr_code(pairing_codes.verification_uri_complete)
39
        
40
        # Display the QR code on screen
41
        # For GUI applications like Tkinter, PyQt, etc.
42
        # display_image(qr_img)
43
        
44
        # For headless devices or testing, save to file
45
        qr_img.save("frame_io_pairing_qr.png")
46
        
47
        print(f"Scan the QR code or visit: {pairing_codes.verification_uri}")
48
        print(f"Manual code: {pairing_codes.user_code}")
49
    else:
50
        # Fallback for devices that received traditional pairing response
51
        print(f"Enter code on Frame.io: {pairing_codes.user_code}")

JavaScript-Beispiel (Web oder Electron)

1
import QRCode from 'qrcode';
2
3
/**
4
 * Generate and display a QR code from the verification URI
5
 * @param {string} verificationUriComplete - The complete verification URI from Frame.io
6
 * @param {string} elementId - ID of the HTML element to display the QR code in
7
 */
8
function displayQRCode(verificationUriComplete, elementId = 'qrcode-container') {
9
  const element = document.getElementById(elementId);
10
  
11
  if (!element) {
12
    console.error(`Element with ID ${elementId} not found`);
13
    return;
14
  }
15
  
16
  // Clear any existing content
17
  element.innerHTML = '';
18
  
19
  // Generate QR code
20
  QRCode.toCanvas(element, verificationUriComplete, { width: 250 }, function(error) {
21
    if (error) {
22
      console.error('Error generating QR code:', error);
23
      // Fallback to displaying the URL as a link
24
      element.innerHTML = `<a href="${verificationUriComplete}" target="_blank">Click here to pair</a>`;
25
    }
26
  });
27
  
28
  // Also display manual pairing information
29
  const manualInfoDiv = document.createElement('div');
30
  manualInfoDiv.innerHTML = `
31
    <p>Scan the QR code or <a href="${verificationUriComplete}" target="_blank">click here</a> to pair your device.</p>
32
    <p>Manual code: ${userCode}</p>
33
  `;
34
  element.parentNode.appendChild(manualInfoDiv);
35
}
36
37
// Example usage in authorization flow
38
async function requestDeviceCode() {
39
  try {
40
    const response = await fetch('https://api.frame.io/v2/auth/device/code', {
41
      method: 'POST',
42
      headers: {
43
        'x-client-version': '2.0.0',
44
        'x-client-platypus-enabled': 'true'
45
      },
46
      body: new URLSearchParams({
47
        'client_id': YOUR_CLIENT_ID,
48
        'client_secret': YOUR_CLIENT_SECRET,
49
        'scope': 'asset_create offline'
50
      })
51
    });
52
    
53
    const data = await response.json();
54
    
55
    if (data.verification_uri_complete) {
56
      displayQRCode(data.verification_uri_complete);
57
      window.userCode = data.user_code; // Store for display purposes
58
    } else {
59
      // Fallback for traditional pairing
60
      displayManualPairingCode(data.user_code);
61
    }
62
    
63
    // Begin polling for authorization
64
    beginPollingForAuthorization(data.device_code, data.interval);
65
    
66
  } catch (error) {
67
    console.error('Error requesting device code:', error);
68
  }
69
}

Android-Beispiel (Java)

1
import android.graphics.Bitmap;
2
import android.widget.ImageView;
3
import com.google.zxing.BarcodeFormat;
4
import com.google.zxing.MultiFormatWriter;
5
import com.google.zxing.common.BitMatrix;
6
import com.journeyapps.barcodescanner.BarcodeEncoder;
7
8
public void generateAndDisplayQRCode(String verificationUriComplete, ImageView qrCodeImageView) {
9
    try {
10
        MultiFormatWriter multiFormatWriter = new MultiFormatWriter();
11
        BitMatrix bitMatrix = multiFormatWriter.encode(verificationUriComplete, 
12
            BarcodeFormat.QR_CODE, 250, 250);
13
        BarcodeEncoder barcodeEncoder = new BarcodeEncoder();
14
        Bitmap bitmap = barcodeEncoder.createBitmap(bitMatrix);
15
        
16
        // Display in ImageView
17
        qrCodeImageView.setImageBitmap(bitmap);
18
        
19
    } catch (Exception e) {
20
        e.printStackTrace();
21
        // Fallback to displaying the URL as text
22
    }
23
}

iOS-Beispiel (Swift)

1
import UIKit
2
import CoreImage
3
4
func generateQRCode(from string: String) -> UIImage? {
5
    let data = string.data(using: String.Encoding.utf8)
6
    
7
    if let filter = CIFilter(name: "CIQRCodeGenerator") {
8
        filter.setValue(data, forKey: "inputMessage")
9
        filter.setValue("H", forKey: "inputCorrectionLevel")
10
        
11
        if let outputImage = filter.outputImage {
12
            // Scale the image
13
            let transform = CGAffineTransform(scaleX: 10, y: 10)
14
            let scaledImage = outputImage.transformed(by: transform)
15
            
16
            // Convert to UIImage
17
            let context = CIContext()
18
            if let cgImage = context.createCGImage(scaledImage, from: scaledImage.extent) {
19
                return UIImage(cgImage: cgImage)
20
            }
21
        }
22
    }
23
    
24
    return nil
25
}
26
27
// Usage in your view controller
28
func displayPairingQRCode(verificationUriComplete: String) {
29
    if let qrCodeImage = generateQRCode(from: verificationUriComplete) {
30
        qrCodeImageView.image = qrCodeImage
31
        
32
        // Also show manual pairing information
33
        pairingInstructionsLabel.text = "Scan the QR code or enter code manually"
34
        pairingCodeLabel.text = userCode
35
    } else {
36
        // Fallback to manual code display
37
        pairingInstructionsLabel.text = "Enter this code on Frame.io:"
38
        pairingCodeLabel.text = userCode
39
    }
40
}

Best Practices für die Anzeige von QR-Codes

Beachten Sie bei der Implementierung der QR-Code-Kopplung die folgenden Richtlinien, um ein optimales Benutzererlebnis zu gewährleisten:

1. Optimale Größe: Zeigen Sie QR-Codes mit mindestens 200–250 quadratischen Pixeln für zuverlässiges Scannen an.

2. Kontrast: Stellen Sie einen hohen Kontrast zwischen QR-Code und Hintergrund sicher (Schwarz auf Weiß ist ideal).

3. Fehlerkorrektur: Verwenden Sie mäßige Fehlerkorrekturstufen (L oder M), um Codedichte und Zuverlässigkeit auszugleichen.

4. Klare Anweisungen: Geben Sie klare Hinweise dazu, wie der Code gescannt werden soll, z. B. „Scannen Sie diesen Code mit der Kamera Ihres Smartphones, um Ihr Gerät zu koppeln.“

5. Mehrere Optionen: Geben Sie neben dem QR-Code stets den manuellen Kopplungscode als Ausweichmöglichkeit an:

   Scan to pair:
   [QR CODE]
   
   Or enter code manually: 573131

6. Hyperlink für mobile Apps: Wenn es sich bei Ihrer Integration um eine mobile App handelt, fügen Sie den verification_uri_complete als anklickbaren Link ein, da Benutzende einen QR-Code nicht vom selben Gerät aus scannen können.

7. Testen: Testen Sie Ihre QR-Codes mit verschiedenen Geräten und unter unterschiedlichen Lichtverhältnissen, um ein zuverlässiges Scannen sicherzustellen.

Fehlerbehebung

Sollten Probleme auftreten, sehen Sie sich diese häufigen Fälle und Lösungen an:

• “Connect Device” Button Not Visible (Schaltfläche „Gerät verbinden“ ist nicht sichtbar): Beim Aufrufen des C2C-Verwaltungsfensters kann dies folgende Ursachen haben:

• Insufficient Permissions (Unzureichende Berechtigungen): Wenn eine Berechtigungsmeldung angezeigt wird, wenden Sie sich an Ihren Account Manager, um die Berechtigungen anzupassen oder eine entsprechende Rolle zuzuweisen.* Existing Device Connection (Bestehende Geräteverbindung): Nach dem Anschließen eines Geräts wird die primäre Schaltfläche „Neues Gerät hinzufügen“ durch ein Drei-Punkte-Menü in der oberen rechten Ecke der C2C-Anschlussleiste ersetzt.

• Invalid Client Error (Ungültiger Client-Fehler): Die Antwort invalid_client weist auf eine Diskrepanz der Geräteinformationen hin, die in der Regel auf ein falsches client_secret zurückzuführen ist.

• Bad Request Error (Fehler „Ungültige Anfrage“): Die Antwort bad_request weist auf fehlerhafte Anfragedaten hin. Überprüfen Sie die Feldnamen und stellen Sie sicher, dass alle erforderlichen Felder enthalten sind.

Wenn Ihr Problem hier nicht behandelt wird, teilen Sie uns bitte Ihre Erfahrungen mit, damit wir diesen Abschnitt zur Fehlerbehebung verbessern können.

Nächste Schritte

Wir empfehlen Ihnen, sich an unser Team zu wenden und den Leitfaden zum Autorisierungsmanagement zu lesen.Wir freuen uns auf Ihr Feedback!