Authentifizierung

Auth Keys

Bei der Kommunikation mit der Transloadit REST API muss der Parameter auth Teil der Multipart-Formularanfrage sein. Nachfolgend sehen Sie ein Beispiel für das JSON, das für dieses Feld erforderlich ist.

{
  "auth": {
    "key": "23c96d084c744219a2ce156772ec3211"
  }
}

Das Feld key verweist auf den Auth Key, der Ihrem Transloadit-Workspace zugeordnet ist und auf der Seite Zugangsdaten zu finden ist. Dies ist somit die Mindestanforderung für die Authentifizierung bei den meisten Transloadit-API-Endpunkten und für nahezu alle Anfragen erforderlich.

Signature Authentication

Wir empfehlen, Signature Authentication für Ihr Konto zu aktivieren, insbesondere wenn Sie Transloadit aus einer nicht vertrauenswürdigen Umgebung integrieren, etwa aus dem Browser mit Uppy⁠. Sie können Signature Authentication in Ihren Workspace-Einstellungen aktivieren.

Wenn Signature Authentication aktiviert ist, wird das dem Workspace zugeordnete Auth Secret (das Sie neben dem Auth Key auf der Seite Zugangsdaten finden) dazu verwendet, einen aus dem Anfrage-Body erzeugten Hash zu salzen. Dieser enthält sowohl den Parameter key (also den zuvor genannten Auth Key) als auch den Parameter expires. Letzterer ist ein Zeitstempel in naher Zukunft, der als Ablaufdatum der Anfrage dient.

Beim Erstellen von Assemblies mit Transloadit könnte Ihr Backend eine Signature berechnen, die nur bestimmte Parameter, authentifizierte Benutzer und einen Zeitraum abdeckt, den es als legitime Nutzung einstuft. Beispielsweise würde es sich weigern, eine Signatur für Benutzer zu erzeugen, die nicht angemeldet sind. Sie können auf dem Server beliebige Geschäftslogik einsetzen, um zu entscheiden, ob Sie eine Signatur ausgeben. Transloadit kann so konfiguriert werden, dass jede Anfrage für Ihr Konto abgelehnt wird, wenn für die Nutzlast keine korrekte Signatur mitgesendet wird.

Wenn Signature Authentication für alle Anfragen zu Ihrem Konto verpflichtend sein soll:

1. Öffnen Sie in Ihrem Konto die Workspace-Einstellungen.
2. Aktivieren Sie im Bereich „API-Einstellungen“ die Option Korrekte Signature erforderlich.
3. Klicken Sie auf die Schaltfläche „Speichern“.

Signaturen erzeugen

Wie sieht das konkret aus?

Das typische Feld params beim Erstellen einer Assembly ohne Signature Authentication sieht wie folgt aus:

{
  "auth": {
    "key": "23c96d084c744219a2ce156772ec3211"
  },
  "steps": {
    // …
  }
}

auth.key ist in diesem Beispiel der Auth Key aus den API-Zugangsdaten in Ihrem Konto.

Um diese Anfrage zu signieren, muss das zusätzliche Feld auth.expires hinzugefügt werden. Dadurch wird es Teil unserer Nutzlast, die durch die Signatur geschützt ist. Würde jemand den Wert ändern, würde Transloadit die Anfrage ablehnen, da die Signatur nicht mehr übereinstimmt. Sie hätten eine andere Nutzlast signiert als die, die wir empfangen haben. Wenn die Signatur übereinstimmt, vergleichen wir selbstverständlich das Datum und lehnen die Anfrage entsprechend den Vorgaben ab. So wird es für Dritte, die diese Nutzlast erlangt haben, sehr schwierig, Anfragen unbegrenzt zu wiederholen. Denn obwohl unser mit A+ bewertetes HTTPS dies bereits weitgehend verhindern sollte, könnte ein Browser-Cache leichter ausgelesen werden.

Die Eigenschaft expires muss einen Zeitstempel in der (nahen) Zukunft enthalten. Verwenden Sie für das Datum das ISO-8601-Format (YYYY-MM-DDTHH:mm:ss.sssZ) und achten Sie darauf, UTC als Zeitzone zu verwenden. Zum Beispiel:

{
  "auth": {
    "key": "23c96d084c744219a2ce156772ec3211",
    "expires": "2009-08-28T01:02:03.000Z"
  },
  "steps": {
    // …
  }
}

So berechnen Sie die Signatur für diese Anfrage:

1. Wandeln Sie das obige JavaScript-Objekt in Ihrem Frontend in einen JSON-String um und senden Sie ihn an Ihr Backend.
2. Berechnen Sie in Ihrem Backend eine RFC-6234-konforme⁠ HMAC-Hex-Signatur für den String. Verwenden Sie dabei das Auth Secret Ihres Kontos als Schlüssel und SHA384 als Hash-Algorithmus. Stellen Sie dem String signature den kleingeschriebenen Namen des Algorithmus voran. Verwenden Sie für SHA384 beispielsweise sha384:<HMAC-signature>. Sie können diesen String an Ihr Frontend senden, sofern Sie die erforderlichen Prüfungen vorgenommen haben, um sicherzustellen, dass die Anfrage tatsächlich von Ihrem Frontend stammt.
3. Fügen Sie Ihrer Anfrage im Frontend ein Multipart-POST-Feld signature hinzu, das diesen Wert enthält (z. B. über ein ausgeblendetes Feld in einem HTML-Formular).

Die vollständige Anfrage sollte ungefähr wie folgt aussehen:

{
  "params": {
    "auth": {
      "key": "23c96d084c744219a2ce156772ec3211",
      "expires": "2009-08-28T01:02:03.000Z",
      "nonce": "04ac6cb6-df43-41fb-a7fd-e5dd711a64e1",
    },
    "steps": {
      // …
    },
  },
  "signature": "9cf67cbba601e37ee10c442b037e0",
}

Sobald Transloadit die Anfrage empfangen hat, erzeugen auch wir nach demselben Verfahren eine Signatur und vergleichen beide Signaturen. Unterscheiden sie sich, antworten unsere Server mit INVALID_SIGNATURE.

Zusammengefasst läuft der Prozess wie folgt ab:

1. Erzeugen Sie eine JSON-Nutzlast, die als Feld params an Transloadit gesendet wird.
2. Berechnen Sie anhand des Inhalts der Nutzlast eine Signatur und verwenden Sie das Auth Secret Ihres Kontos als Schlüssel.
3. Senden Sie die Anfrage an Transloadit und übergeben Sie die Signatur im Feld signature.
4. Transloadit berechnet anhand des Auth Secret Ihres Kontos und des Inhalts der Nutzlast dieselbe Signatur.
5. Stimmen die Signaturen überein, wird die Anfrage zugelassen und eine entsprechende Antwort gesendet. Andernfalls wird die Anfrage abgelehnt und ein Fehler mit dem Code INVALID_SIGNATURE zurückgegeben.

So können beide Parteien die Authentifizierung der jeweils anderen verifizieren, da Dritte ohne Zugriff auf das Auth Secret Ihres Kontos keine übereinstimmende Signatur berechnen könnten, ohne das Auth Secret jemals direkt zu übertragen.

Nachfolgend finden Sie einige Beispiele für eine POST-Anfrage zum Erstellen einer Assembly. Wir empfehlen dringend, eines unserer SDKs zu verwenden. Diese übernehmen die Signaturerzeugung automatisch und sind umfassend getestet.

Beispielcode für verschiedene Sprachen

Die folgenden Beispiele zeigen, wie Sie mit unseren offiziellen SDKs Assemblies erstellen. Die SDKs übernehmen die gesamte Signaturerzeugung intern und machen die Integration dadurch einfacher und sicherer.

// yarn add transloadit
// or
// npm install --save transloadit

import { Transloadit } from 'transloadit'

const transloadit = new Transloadit({
  authKey: 'YOUR_TRANSLOADIT_KEY',
  authSecret: 'YOUR_TRANSLOADIT_SECRET',
})

const response = await transloadit.createAssembly({
  params: {
    template_id: 'YOUR_TRANSLOADIT_TEMPLATE_ID',
    // your other params like notify_url, fields, etc.
  },
  waitForCompletion: true,
})

console.log(response)

const { signature, params } = transloadit.calcSignature({
  template_id: 'YOUR_TRANSLOADIT_TEMPLATE_ID',
})

console.log(signature, params)

curl --location 'https://api2.transloadit.com/assemblies' \
  --form 'params="{\"auth\":{\"key\":\"\23c96d084c744219a2ce156772ec3211\",\"expires\":\"2024/02/28 15:09:32.941Z\"},\"template_id\":\"\9cf67cbba601e37ee10c442b037e0\"}"' \
  --form 'signature="sha1:46253af0d7b2f0603375bbc6bfd5393363a8138c"' \
  --form 'files=@/path/to/your/file.jpg'

Signierte Smart CDN-URLs

Zum Signieren einer Smart CDN-URL wird ein ähnliches Verfahren wie bei regulären API-Signaturen verwendet. Für einen aus der Smart CDN-URL abgeleiteten String wird ein HMAC-Digest berechnet, wobei das Auth Secret als Schlüssel dient. Damit die Signatur gültig ist, muss der verwendete Auth Key für die Nutzung von Smart CDN aktiviert sein.

Eine Smart CDN-Signatur muss im Backend erzeugt werden. Das Verfahren verwendet das Auth Secret. Dieses ist vertraulich und darf Ihren Benutzern nicht im Frontend offengelegt werden.

Eine typische Smart CDN-URL hat folgende Struktur:

https://[your-workspace].tlcdn.com/[template-name]/[file-path]?[parameters]

• [your-workspace] ist der Name Ihres Transloadit-Workspaces
• [template-name] ist der Name Ihres Templates
• [file-path] ist der Pfad zu der Datei, die Sie transformieren möchten
• [parameters] sind die gewünschten Transformationsparameter, z. B. h=100

Eine signierte Smart CDN-URL wird mit den folgenden Schritten erzeugt:

1. Fügen Sie den Abfrageparameter exp hinzu, um einen Zeitpunkt in der Zukunft festzulegen, nach dem die Signatur vom Smart CDN nicht mehr akzeptiert wird. So können Sie den zeitlichen Zugriff auf eine Datei begrenzen. Der Ablaufzeitpunkt wird als Anzahl der Millisekunden seit Beginn der UNIX-Epoche dargestellt, also seit Mitternacht am 1. Januar 1970 UTC. Dieser Parameter ist optional, wir empfehlen jedoch dringend, immer eine Ablaufzeit festzulegen. Eine Signatur mit exp=1722517200000 ist beispielsweise bis Donnerstag, den 1. August 2024, 13:00:00 GMT gültig.
2. Fügen Sie den Abfrageparameter auth_key hinzu, um den Auth Key anzugeben, der dem zum Erzeugen der Signatur verwendeten Auth Secret entspricht. Wenn dieser Parameter nicht gesetzt ist, nimmt die Transloadit-API an, dass das älteste für Smart CDN aktivierte Auth Key-Paar für die Signatur verwendet wurde. Durch das Setzen des Parameters auth_key können Sie den verwendeten Auth Key ohne Unterbrechung für Ihre Benutzer rotieren. Daher empfehlen wir dringend, ihn zu setzen. Zum Beispiel: auth_key=23c96d084c744219a2ce156772ec3211
3. Sortieren Sie die Abfrageparameter anhand der UTF-16-Codeeinheiten ihrer Schlüssel in aufsteigender Reihenfolge. Die Sortierung sollte stabil sein. Wenn ein Schlüssel also mehrfach im Abfrage-String vorkommt, müssen die entsprechenden Werte ihre relative Reihenfolge beibehalten. Beispielsweise wird h=100&f=png&f=jpg&auth_key=hello&exp=123 zu auth_key=hello&exp=123&f=png&f=jpg&h=100 sortiert.
4. Erstellen Sie den zu signierenden String, indem Sie die Werte verketten:

   [your-workspace]/[template-name]/[file-path]?[sorted-parameters]
   

   Die Werte für [your-workspace], [template-name] und [file-path] müssen URL-codiert werden, damit sie ausschließlich URL-sichere Zeichen enthalten. Beachten Sie, dass der String nicht mit einem führenden Schrägstrich beginnt. Das Zeichen ? muss entfallen, wenn [sorted-parameters] leer ist.
5. Berechnen Sie eine RFC-6234-konforme⁠ HMAC-Hex-Signatur für den zu signierenden String. Verwenden Sie dabei das Auth Secret Ihres Kontos als Schlüssel und SHA256 als Hash-Algorithmus. Stellen Sie der Hex-Signatur den kleingeschriebenen Namen des Algorithmus und einen Doppelpunkt voran, also sha256. Verwenden Sie für SHA256 beispielsweise sha256:[hmac-signature].
6. Hängen Sie die Hex-Signatur mit Präfix unter dem Abfrageparameter sig an die URL an. So erhalten Sie die signierte Smart CDN-URL:

   https://[your-workspace].tlcdn.com/[template-name]/[file-path]?[parameters]&sig=sha256:[hmac-signature]
   

   Die Werte für [your-workspace], [template-name] und [file-path] müssen URL-codiert werden, damit sie ausschließlich URL-sichere Zeichen enthalten. Diese signierte URL kann anschließend bis zum Ablaufdatum an Ihr Frontend gesendet oder dort verwendet werden.

Sicherheit und Cache-Lebensdauer

Signierte Smart CDN-URLs dienen nicht nur der Zugriffskontrolle. Ihr Ablaufzeitpunkt bestimmt außerdem, wie lange ein neu erzeugtes Ergebnis im Cache verbleiben darf.

• Kürzere exp-Werte verkleinern das Replay-Zeitfenster und verschärfen die Zugriffskontrolle.
• Längere exp-Werte erhöhen die Cache-Wiederverwendung, reduzieren die Verarbeitung am Ursprung und senken im Allgemeinen die Latenz sowie das Encoding-Volumen.
• In der Praxis wird die effektive Cache-Lebensdauer einer signierten Smart CDN-Antwort durch die verbleibende Gültigkeitsdauer der Signatur begrenzt.

Daraus ergibt sich ein klarer Kompromiss:

• Höhere Sicherheitsanforderungen: Verwenden Sie einen kürzeren exp-Wert. Dadurch verkürzt sich auch die effektive Cache-TTL.
• Mehr Cache-Wiederverwendung und geringere Kosten: Verwenden Sie einen längeren exp-Wert. Dadurch bleibt auch die URL länger nutzbar.

Wählen Sie das Ablaufzeitfenster anhand der Vertraulichkeit der Inhalte und der gewünschten Cache-Wiederverwendung. Für viele Bild- und Vorschauanwendungen bietet ein moderates Ablaufzeitfenster ein ausgewogenes Verhältnis. Verwenden Sie für hochsensible Inhalte ein deutlich kürzeres Zeitfenster.

Beispielcode

Nachfolgend finden Sie Beispiele in verschiedenen Sprachen, mit denen Sie über unsere SDKs signierte Smart CDN-URLs erzeugen können.

// yarn add transloadit
// or
// npm install --save transloadit

import { Transloadit } from 'transloadit'

const transloadit = new Transloadit({
  authKey: 'YOUR_TRANSLOADIT_KEY',
  authSecret: 'YOUR_TRANSLOADIT_SECRET',
})

const url = transloadit.getSignedSmartCDNUrl({
  workspace: 'YOUR_WORKSPACE',
  template: 'YOUR_TEMPLATE',
  input: 'image.png',
  urlParams: { height: 100, width: 100 },
})

console.log(url)

Bearer-Tokens (Client-Zugangsdaten)

Wenn Sie ein kurzlebiges Token für Server-zu-Server- oder Headless-Clients benötigen, können Sie den Auth Key und das Auth Secret Ihres Kontos gegen ein Bearer-Token austauschen. Dies entspricht einem Flow von OAuth 2.0 mit client_credentials, wird jedoch direkt von der Transloadit-API verarbeitet. Die vollständige Endpunktreferenz finden Sie in der Dokumentation zur /token-API.

POST /token

Anfrage

• Authentifizierung: Basic Auth mit dem Auth Key und dem Auth Secret Ihres Kontos
• Content-Type: application/x-www-form-urlencoded
• Body:
  • grant_type=client_credentials (erforderlich)
  • scope=assemblies:read assemblies:write (optional; durch Leerzeichen oder Kommas getrennt)
  • aud=api2 (optional)

curl --request POST \
  --url 'https://api2.transloadit.com/token' \
  --user 'auth_key:auth_secret' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=assemblies:read assemblies:write'

Antwort

{
  "access_token": "opaque-token",
  "token_type": "Bearer",
  "expires_in": 21600,
  "scope": "assemblies:read assemblies:write"
}

Tokens sind sechs Stunden gültig (expires_in: 21600).

Token verwenden

Übergeben Sie das Token bei API-Anfragen als Authorization: Bearer <access_token>. Wenn eine Anfrage mit einem gültigen Bearer-Token authentifiziert wurde, betrachtet API2 die Signature Authentication als erfüllt und überspringt die Signaturprüfung. Signature Authentication wird nur bei Anfragen mit Schlüssel und Secret erzwungen. Prüfungen des Berechtigungsumfangs gelten weiterhin. Sie können auth.key in params weglassen, die params-Hülle bleibt jedoch für Endpunkte erforderlich, die sie erwarten. Der Wert aud wird für eine zukünftige Zielgruppenprüfung gespeichert.

curl --request POST \
  --url 'https://api2.transloadit.com/assemblies' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --form 'params={"steps":{}}'

Automatische MCP-Authentifizierung für /ai/chat

Wenn Ihre /ai/chat-Steps einen von Transloadit gehosteten MCP-Server aufrufen, kann API2 automatisch ein kurzlebiges Bearer-Token erzeugen und einfügen. Diese automatische Authentifizierung muss für jeden MCP-Server-Eintrag separat aktiviert werden:

{
  "mcp_servers": [
    {
      "type": "http",
      "url": "https://api2.transloadit.com/mcp",
      "auth": "transloadit"
    }
  ]
}

Verhalten:

• Wenn auth: "transloadit" gesetzt und kein Authorization-Header vorhanden ist, erzeugt API2 ein Token und fügt Authorization: Bearer <token> ein.
• Wenn Authorization bereits in mcp_servers[].headers angegeben ist, bleibt der Wert unverändert.
• Die automatische Authentifizierung funktioniert nur über HTTPS für Transloadit-Hosts (*.transloadit.com, *.transloadit.dev, *.transloadit.work).

Häufig gestellte Fragen

Fügt Transloadit seinen Anfragen Signaturen hinzu?

Ja, Signature Authentication funktioniert in beide Richtungen. Daher stellen wir auch für alle Anfragen zu Webhooks, die wir an Sie senden, eine Signatur bereit. So können Sie die Authentizität jeder von Ihren Servern empfangenen Anfrage verifizieren.

Warum kann ich mein Auth Secret nicht als Bearer-Token verwenden?

Gemäß kryptografischen Standards sollte das Auth Secret Ihres Kontos niemals als Teil der Anfrage übertragen, sondern ausschließlich als Salt für den Signatur-Hash verwendet werden. Dadurch kann ein Angreifer die Anfrage nicht abfangen und Ihr Secret verwenden, um Anfragen an Ihr Konto vorzutäuschen. Deshalb empfehlen wir, Ihr Auth Secret zu schützen und ausschließlich in Ihrem Backend zu speichern. Verwenden Sie dafür ein Secret-Management-System Ihrer Wahl. Beispiele sind Vault⁠, AWS Secrets Manager⁠, GCP Secret Manager⁠ und Kubernetes Secrets⁠. Je nach gewählter Backend-Plattform kommen jedoch noch viele weitere Lösungen infrage.

In welcher Reihenfolge müssen die Schlüssel im Body stehen?

Sie können die Schlüssel im Body in beliebiger Reihenfolge anordnen. Wichtig ist jedoch, dass diese Reihenfolge bei der Signaturerzeugung konsistent bleibt. Der erzeugte Hash hängt vom Inhalt des JSON ab. Eine andere Reihenfolge erzeugt einen anderen Hash, wodurch Ihre Anfrage abgelehnt wird.