Häufig gestellte Fragen

1. Welche API-Authentifizierungsmethode unterstützt Monotype Fonts?

Monotype Fonts unterstützt zwei Authentifizierungsmethoden für APIs:

Typ Client Credentials Grant

Anwendungsfall: Diese Methode ist ideal für Benutzer*innen, die sich im Namen eines Unternehmens anmelden.

Funktionsweise: Bei dieser Methode authentifiziert sich das Unternehmen über seine eigene Client-ID und ein eigenes Secret. Sie wird hauptsächlich für die M2M-Kommunikation (Machine-to-Machine) verwendet, bei der keine Interaktion von Benutzer*innen erforderlich ist.

Sicherheit: Diese Methode ermöglicht Servern die sichere Authentifizierung und gewährleistet, dass nur vertrauenswürdige Parteien auf bestimmte Ressourcen zugreifen können.

**Typ Authorization Code Grant mit Umleitungs-URL**

Anwendungsfall: Diese Methode wird eingesetzt, wenn sich Endbenutzer*innen über die API anmelden müssen.

Funktionsweise: In diesem Szenario werden Benutzer*innen an die Callback-URL-Seite umgeleitet. (Hierbei handelt es sich um die Umleitungs-URL, die Benutzer*innen vorab angegeben haben). Nach der erfolgreichen Authentifizierung leitet Auth0 Benutzer*innen zurück zur Anwendung – mit einem Autorisierungscode, der dann gegen ein Zugriffstoken eingetauscht wird.

Sicherheit: Dank der Umleitungs-URL schafft dieser Flow eine zusätzliche Sicherheitsebene und gewährleistet, dass das Zugriffstoken nicht im Browser einsehbar ist.

2. Was ist ein Grant-Typ? Wie verwende ich Grant-Typen für APIs?

Grant-Typen (oder Flows) sind Methoden, über die Anwendungen Zugriffstoken erhalten. So können Sie einer anderen Partei eingeschränkten Zugriff auf Ihre Ressourcen gewähren, ohne hierbei Anmeldedaten preiszugeben. Das Protokoll OAuth 2.0 unterstützt verschiedene Grant-Typen für verschiedene Zugriffsarten. Monotype Fonts unterstützt die folgenden Grant-Typen:

authorization_code

Der Authorization Code Flow (wie in OAuth 2.0 RFC 6749, Abschnitt 4.1 definiert) umfasst den Eintausch eines Autorisierungscodes gegen ein Zugriffstoken. Dieser Flow kann nur für vertrauliche Anwendungen wie Regular Web Applications eingesetzt werden, da die Authentifizierungsmethoden der Anwendung an diesem Austausch beteiligt sind und dabei geschützt werden müssen. Der Autorisierungscode wird über den API-Endpoint /oauth/authorize abgerufen. Hierzu fragt er die Client-ID und die Umleitungs-URL ab. Nach erfolgreicher Ausführung erhalten Benutzer*innen einen Autorisierungscode, der ihrer Umleitungs-URL angehängt wird.

client_credentials

Beim Client Credentials Flow (wie in OAuth 2.0 RFC 6749, Abschnitt 4.4 definiert) tauscht eine Anwendung ihre Anmeldedaten, wie z. B. eine Client-ID und ein Client Secret, gegen ein Zugriffstoken ein.

Dieser Flow eignet sich am besten für M2M-Anwendungen (Machine-to-Machine), wie z. B. CLIs, Daemons oder Backend-Services, da das System keine Benutzer*innen, sondern eine Anwendung authentifizieren und autorisieren muss.

refresh_token

Aktualisierungstoken (oder Refresh Tokens) werden verwendet, um ein neues Zugriffs- und/oder ID-Token für Benutzer*innen anzufordern, ohne dass sie sich hierfür erneut anmelden müssen.

In der Regel sollten Sie ein neues Zugriffstoken anfordern, bevor das vorherige abläuft (um Serviceunterbrechungen zu vermeiden), jedoch nicht bei jedem API-Aufruf.

3. Was ist eine Umleitungs-URI? Wann und wie wird eine Umleitungs-URI verwendet?

Eine Umleitungs-URI (Uniform Resource Identifier) ist eine wichtige Komponente sicherer Anwendungsflows, insbesondere beim Einsatz des Typs Authorization Code Grant. Sie erfüllt zwei wichtige Zwecke:

Sicherheit

Über die Umleitungs-URI bezieht Ihre Anwendung den Autorisierungscode vom Anwendungsserver. Sie wird vorab auf diesem Server registriert, um schädliche Umleitungen zu verhindern. Sie gewährleistet, dass der vertrauliche Autorisierungscode sicher an den richtigen Ort gesendet wird.

User Experience

Nachdem sich Benutzer*innen bei einer Anwendung anmelden oder sie autorisieren, müssen sie nahtlos zu dieser Anwendung zurückgesendet werden. Die Umleitungs-URI vereinfacht diesen Vorgang, indem sie dem Authentifizierungsserver die URL mitteilt, an die Benutzer*innen umgeleitet werden sollen, nachdem der Authentifizierungsprozess abgeschlossen wurde.

Verwendung

Registrierung: Benutzer*innen geben zum Zeitpunkt der Registrierung eine Umleitungs-URI an. Monotype Fonts registriert diese URI auf dem Authentifizierungsserver, während die entsprechende Anwendung eingerichtet wird.

Anmeldungsflow: Die Anwendung fügt diese URI der Authentifizierungsanfrage hinzu, die an den Authentifizierungsserver gesendet wird. Um den Autorisierungscode abzurufen, verwenden Sie den API-Endpoint (/oauth/authorize), der die Client-ID und die Umleitungs-URL in der Payload abfragt. (Client-ID und Client Secret werden Benutzer*innen im Rahmen des Onboarding-Prozesses bereitgestellt.)

Beispiel:

curl --location 'https://api.monotype.com/v2/oauth/authorize?client_id=client_id&redirect_uri=redirect_uri'

Empfangen des Autorisierungscodes: Nachdem sich Benutzer*innen authentifiziert haben, leitet der Autorisierungsserver sie zu den vorab registrierten URIs um und fügt hierbei den Autorisierungscode zu den Abfrageparametern der Umleitungs-URI hinzu.

Fragen zu spezifischen Szenarien

4. Ich habe ein gültiges Zugriffstoken, aber kann einige APIs nicht ausführen. Woran liegt das?

Jede Kundenanwendung auf unserem Autorisierungsserver verfügt über individuelle Berechtigungen, die wir auch als „Bereiche“ bezeichnen. Diese Bereiche definieren, wie umfassend Ihre Anwendung auf unsere API-Funktionen zugreifen kann. Allgemeine Bereiche umfassen read:font:metadata, read:font:data und create:webfonts:kit. Stellen Sie sicher, dass das Zugriffstoken Ihrer Anwendung alle Bereiche umfasst, die Sie für die gewünschten API-Funktionen benötigen (verwenden Sie hierzu https://jwt.io/).

5. Was sind Client-ID und Client Secret? Wie verwende ich sie?

Client-ID und Client Secret sind Anmeldedaten, über die eine Anwendung bei einem OAuth-2.0-Autorisierungsserver authentifiziert werden. Sie ähneln Benutzername und Passwort, jedoch bestätigen hiermit nicht Benutzer*innen ihre Identität, sondern registrierte Anwendungen. Client-ID und Client Secret werden generiert, wenn eine neue Kundenanwendung auf unserem OAuth-Server registriert wird.

Client-ID

Die Client-ID ist eine eindeutige Kennung, die Ihrer Anwendung während des Registrierungsprozesses zugewiesen wird. Sie dient als Anmeldeinformation, die Ihre Anwendung eindeutig identifiziert, wenn sie mit dem Authentifizierungsserver interagiert. Die Client-ID spielt eine wichtige Rolle bei der Authentifizierung, da der Authentifizierungsserver hierüber eingehende Authentifizierungsanfragen der jeweiligen Anwendung zuordnen kann. Die Client-ID wird verwendet, um die Ordnungsmäßigkeit von Authentifizierungsanfragen zu überprüfen, damit die Authentifizierung von Benutzer*innen nur für autorisierte Anwendungen zugänglich sind. Die Client-ID wird oftmals in Verbindung mit einem Client Secret eingesetzt, um die Sicherheit des Authentifizierungsflows zu steigern.

Client Secret

Das Client Secret (Client-Geheimnis) ist eine Anmeldeinformation, die nur Ihrer Anwendung und dem Authentifizierungsserver bekannt ist. In Verbindung mit der Client-ID entsteht so eine zusätzliche Sicherheitsebene im Authentifizierungsprozess. Das Client Secret wird während des Authentifizierungsflows eingesetzt, um Ihre Anwendung zu authentifizieren, wenn sie beim Authentifizierungsserver Zugriffstoken anfordert. So wird gewährleistet, dass nur registrierte und autorisierte Anwendungen mit dem richtigen Client Secret Zugriffstoken erhalten und Benutzer*innen authentifizieren können. Um die Sicherheit des Authentifizierungsprozesses zu wahren, muss das Client Secret unbedingt geheim gehalten werden und darf niemals in clientseitigem Code oder öffentlichen Repositorys offengelegt werden.

6. Was sind Zugriffstoken und Aktualisierungstoken?

Zugriffstoken und Aktualisierungstoken sind zwei Arten von Token, die verwendet werden, um Benutzersitzungen und API-Zugriff in sicheren Anwendungen zu verwalten.

Das Zugriffstoken ist ein JSON Web Token (JWT), das vom Autorisierungsserver ausgegeben wird, um Zugriff auf Ihre API zu gewähren. Es handelt sich hierbei um eine zeitlich begrenzte Anmeldeinformation, die in der Regel 24 Stunden lang gültig ist. So werden sichere und authentifizierte Interaktionen zwischen Ihrer Anwendung und der API gewährleistet.

Auch das Aktualisierungstoken ist ein JSON Web Token (JWT), das von Auth0 generiert wird. Es spielt eine entscheidende Rolle beim kontinuierlichen Zugriff auf Ihre API. Dieses Token bleibt ein Jahr lang gültig und dient als sichere Methode, um ein neues Zugriffstoken anzufordern, wenn das aktuelle abläuft. Es kann nur einmal verwendet werden. Daraufhin wird gemeinsam mit dem aktualisierten Zugriffstoken auch ein neues Aktualisierungstoken ausgegeben. Es empfiehlt sich, das aktuelle Aktualisierungstoken sicher in Ihren Systemen zu speichern, um ein nahtloses und sicheres Tokenmanagement zu gewährleisten.

7. Wie kann ich mit einem Aktualisierungstoken ein Zugriffstoken generieren?

Das Aktualisierungstoken kann zur Erneuerung des Zugriffstoken verwendet werden, wenn das aktuelle Zugriffstoken in Kürze abläuft oder bereits abgelaufen ist. Um das Token neu zu generieren, senden Sie eine POST-Anfrage an den Endpoint /oauth/token in der Authentication API – verwenden Sie dabei grant_type=refresh_token. Die Funktion des Aktualisierungstokens gilt nur für grant_type=authorization_code.

Unten finden Sie einen curl-Beispielcode:

curl --request POST \
  --url 'https://{apiGatewayHost}/v2/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --header 'Authorization: Basic {base64Encode(clientId:clientSecret)}' \
  --data grant_type=refresh_token&refresh_token={token}

8. Was ist ein JWT?

Ein JWT (oder JSON Web Token) ist eine schnelle und unabhängige Methode für den sicheren Informationsaustausch zwischen Parteien mithilfe von JSON-Objekten. JWTs werden für Authentifizierung, Autorisierung und Informationsaustausch verwendet. Ihre Vertrauenswürdigkeit garantieren digitale Signaturen, wodurch die Integrität und Echtzeit der übertragenen Daten sichergestellt wird.

9. Brauche ich für jeden API-Aufruf ein neues Zugriffstoken?

Nein. Im Idealfall erstellen wir nicht für jeden API-Aufruf ein neues JWT. Stattdessen erstellen wir einen Codeausschnitt, der erkennt, wann das Token abläuft, und dann mithilfe des Aktualisierungstokens ein neues Token generiert. Der unten stehende curl-Beispielcode zeigt, wie Sie aus einem Aktualisierungstoken ein neues Zugriffstoken generieren können.

Hinweis: Wir generieren Aktualisierungstoken nur für grant_type=authorization_code.

curl --request POST \
  --url 'https://{apiGatewayHost}/v2/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --header 'Authorization: Basic {base64Encode(clientId:clientSecret)}' \
  --data grant_type=refresh_token&refresh_token={token}

10. Wie gewährleiste ich nahtlosen Zugriff auf die API, selbst wenn das Token abläuft?

Lesen Sie sich hierzu bitte die Antwort auf Frage 9 durch. Wenn wir ein Zugriffstoken generieren, enthält die Antwort-Payload ein Feld namens expires_at. Bei der Integration von APIs können wir in Abhängigkeit von diesem Feld ein neues Token generieren, wenn das alte (in Kürze) abläuft.

11. Warum erhalte ich die Fehlermeldung „The provided token does not have correct permissions to access this resource“?

Wenn Sie mit Ihrem Zugriffstoken an Grenzen stoßen, verfügt es möglicherweise nicht über die nötigen Berechtigungen (oder „Bereiche“), um auf bestimmte Funktionen oder Daten zuzugreifen. So können Sie das Problem lösen:

Überprüfen Sie die Berechtigungen Ihres Zugriffstokens:

Zugriffstoken umfassen Bereiche, die Ihre Berechtigungen definieren. Sie können die Berechtigungen Ihres Tokens einsehen, um herauszufinden, welche Aktionen Sie ausführen können.

Wie überprüfe ich Berechtigungen?

Besuchen Sie jwt.io, ein vertrauenswürdiges Tool zur Decodierung von JSON Web Tokens (JWTs).
Geben Sie Ihr Zugriffstoken in den Decoder ein. Daraufhin werden Ihnen die decodierten Tokeninformationen angezeigt, darunter auch die verschiedenen Berechtigungen.

Berechtigungsbeispiele:

Ihr Token kann beispielsweise Berechtigungen wie read:font:data, read:font:pair, read:font:preview und read:font:similar enthalten.

Nächste Schritte:

Wenn erforderliche Berechtigungen fehlen, können Sie ein aktualisiertes Token mit den richtigen Bereichen anfordern.
Wenn Sie sich nicht sicher sind, welche Berechtigungen Sie brauchen oder wie Sie zusätzliche Berechtigungen anfordern können, wenden Sie sich bitte an unser Supportteam.

12. Welchen Zweck erfüllt die GUID in Fehlermeldungen?

Die GUID im Feld Instance dient als eindeutige Kennung, die den exakten Fehlerstack sowie Details innerhalb unseres Systems identifiziert. Wenn Sie diese GUID beim Melden von Fehlern angeben, können wir Ihnen effektivere und gezieltere Unterstützung bei etwaigen Problemen bieten.

Hinweis: Geben Sie diese Kennung bei einer Support-Anfrage an, um eine schnellere und präzisere Lösung zu ermöglichen.

Eine Liste allgemeiner Fehlercodes finden Sie hier: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status

13. Was ist die Durchsatzbegrenzung? Wieso erhalte ich bei API-Aufrufen eine Fehlermeldung hinsichtlich der Durchsatzbegrenzung?

Die Durchsatzbegrenzung ist ein Grenzwert, der die maximale Anzahl von API-Aufrufen definiert, die innerhalb eines bestimmten Zeitraums gesendet werden können. Wenn Sie diesen Grenzwert überschreiten, erhalten Sie eine entsprechende Fehlermeldung. Diese Fehlermeldung bedeutet, dass die Anzahl der API-Aufrufe, die im festgelegten Zeitraum über Ihr Konto gesendet wurden, das Limit überschritten hat, das laut unserer Richtlinie zulässig ist.

14. Warum erhalte ich beim Fontimport die Fehlermeldung „Sorry, the functionality is not supported with client credentials. Please request for user specific token with authorization_code grant type“?

Die Fontimport-Funktion steht nur Benutzer*innen mit bestimmten Token zur Verfügung (Zugriffstoken, die über grant_type = Authorization_code generiert werden). Ein Zugriffstoken mit grant_type=client_credentials verfügt nicht über die nötige Berechtigung (den Bereich), um auf die Fontdownload-API zuzugreifen.

15. Warum erhalte ich bei Fonts in meiner Bibliothek die Fehlermeldung „Sorry, the functionality is not supported with client credentials. Please request for user specific token with authorization_code grant type“?

Die Bibliotheks-API-Funktion steht nur Benutzer*innen mit bestimmten Token zur Verfügung (Zugriffstoken, die über grant_type=authorization_code generiert werden). Ein Zugriffstoken mit grant_type=client_credentials verfügt nicht über die nötige Berechtigung (den Bereich), um auf die API zuzugreifen.

16. Kann ich Fonts auf meinem CDN hosten und dieses CDN für die Produktionsumgebung verwenden?

Sie sollten davon absehen, Ihr Content Delivery Network (CDN) zu verwenden – das gilt insbesondere für öffentliche CDNs. Wir empfehlen, das CDN von Monotype zu verwenden, um Fontdateien abzurufen und in der Produktionsumgebung zu verwenden.

17. Ist es möglich, serverseitiges Caching zu implementieren, um auf effiziente Weise Fontdateien zu hosten und bei Kundenanfragen bereitzustellen?

Zwar kann serverseitiges Caching verschiedene Verbesserungen bei der Inhaltsbereitstellung bewirken, doch wir raten davon ab, es zum Hosten und Verteilen von Fontdateien zu verwenden. Wir empfehlen stattdessen das CDN (Content Delivery Network) von Monotype, das die Effizienz der Fontbereitstellung steigert und dabei zusätzliche Sicherheit bietet. Mit dem Einsatz des Monotype CDN gewährleisten Sie, dass Fontdateien stets im Einklang mit den Best Practices der Branche bereitgestellt werden. Ob diese Empfehlung in Ihrem individuellen Fall zutrifft, hängt jedoch von den spezifischen Bedingungen Ihres Vertrags ab. Wenden Sie sich gern an unser Business Team, um mehr über einen maßgeschneiderten Ansatz zu erfahren oder die Einhaltung Ihrer vertraglichen Verpflichtungen zu gewährleisten.