Remote API

Der Zweck dieses Dokuments ist es zu erklären:

1. ...wie das Prenly-Ökosystem die Benutzerauthentifizierung und -autorisierung durch eine technische Infrastruktur ermöglicht, die dem Herausgeber oder einer dritten Partei gehört.

2. ...wie eine technische Implementierung durch den Aufbau einer bescheidenen Rest-API erfolgen kann, die der "Prenly Remote authority API" Spezifikation folgt.

Kontakt

Bitte kontaktieren Sie uns per E-Mail unter hello@prenly.com oder per Telefon unter +46-31-3884740 bei Fragen oder Problemen bezüglich dieser API.

Definitionen

Authentifizierung ist der Prozess, bei dem die Identität einer Person oder einer Sache überprüft wird, d. h. ob sie diejenige ist, die sie vorgibt zu sein, bevor der Zugriff auf geschützte Daten gewährt wird. Normalerweise erfolgt dies durch die Angabe von Anmeldedaten wie Benutzername und Passwort. Wenn die Anmeldedaten mit einem gespeicherten Datensatz übereinstimmen, wird der Benutzer "verifiziert" (authentifiziert), indem der Grundsatz angewendet wird, dass der Benutzer etwas weiß, was nur der "echte" Benutzer wissen kann.

Autorisierung ist der Prozess, bei dem entschieden wird, auf welche Ressourcen ein Benutzer Zugriff hat, d.h. auf welche Daten der Benutzer zugreifen darf und auf welche nicht. Für Prenly bedeutet dies, dass festgelegt wird, welche Veröffentlichungen der Benutzer sehen und zum Lesen öffnen kann.

Eine API(Application Program Interface) ist eine Reihe von Routinen, Protokollen und Werkzeugen, die die Interaktion zwischen verschiedenen Systemen oder Teilen von Systemen regeln und die Kommunikation von System zu System vorgeben.

In Prenly ist eine Autorität eine technische Implementierung, die entscheidet, wie Authentifizierung und Autorisierung durch eine Prenly-Anwendung innerhalb des Prenly-Backends gehandhabt werden.

Einführung

Die Prenly Remote Authority API bietet die Möglichkeit, Prenlys Autorisierungs- und/oder Authentifizierungshandling zu ersetzen, indem API-Endpunkte implementiert werden, die einer API-Spezifikation folgen, die es einem Prenly-Kunden ermöglicht, sich nach seinem System, seinen Anforderungen und Bedürfnissen zu authentifizieren und zu autorisieren.

Im Kern ermöglicht dies der Behörde der Prenly-Anwendung, Benutzer zu autorisieren und/oder zu authentifizieren, wenn sie mit der Prenly-Anwendung interagieren, d.h. wenn sie Publikationen innerhalb einer App lesen, und zwar über die API der Prenly-Fernbehörde.

Die Prenly Behörde vermittelt Authentifizierungs- und Autorisierungsanfragen zwischen Nutzern und Prenly, wobei keine direkte Kommunikation zwischen Nutzern und API-Implementierung erlaubt ist. Stattdessen teilt die API-Implementierung der Prenly-Behörde mit, wie sie auf die Authentifizierungs- und Autorisierungsanfragen der Benutzer reagieren soll.

Implementieren Sie Ihre API

Verstehen, wie der Benutzer die Prenly-Anwendung nutzt

Prenly-Anwendungen

Prenly stellt dem Endnutzer Anwendungen zur Verfügung, die hauptsächlich zum Lesen von Publikationen und Artikeln verwendet werden. Bei der Anwendung handelt es sich entweder um eine native mobile App auf der Android- oder iOS-Plattform oder um unseren responsiven webbasierten E-Reader. Diese beiden Anwendungstypen bieten ein ähnliches Benutzererlebnis.

Die Anwendung kann sowohl veröffentlichte Publikationen enthalten, die für jedermann zugänglich sind, als auch geschützte Inhalte, für deren Nutzung eine bestimmte Art von Genehmigung erforderlich ist. Bei nativen Anwendungen ist es auch möglich, dass jeder nicht angemeldete Benutzer einige Publikationen kostenlos konsumieren kann, bevor eine Anmeldung erforderlich ist.

Navigation in der Anwendung

Bei der Nutzung der Anwendung sieht der Benutzer normalerweise die Startseite mit den Komponenten, die die veröffentlichten Publikationen anzeigen. Öffentliche Publikationen können durch Auswahl der Publikation geöffnet und gelesen werden. Wenn der Benutzer jedoch versucht, eine geschützte Publikation zu öffnen, fordert die Anwendung den Benutzer auf, sich anzumelden(Authentifizierung).

Nach dem Einloggen entscheidet Prenly, ob die angeforderte Publikation für den Benutzer lesbar ist(Autorisierung). Wenn ja, wird die Publikation geöffnet und kann konsumiert werden. Wenn der Nutzer keine Leseberechtigung hat, wird er in der App benachrichtigt. Der geschützte Inhalt wird nicht angezeigt, aber der Benutzer ist weiterhin angemeldet.

In manchen Fällen erfordert eine Anwendung, dass der Benutzer sich anmeldet, um bestimmte Veröffentlichungen anzuzeigen, insbesondere wenn nicht alle veröffentlichten Veröffentlichungen von jedermann eingesehen werden können. Dies gilt insbesondere dann, wenn nicht alle veröffentlichten Publikationen für jedermann sichtbar sind, z. B. bei Publikationen, die über ein Abonnement zugänglich sind und bei denen andere, nicht abonnierte Veröffentlichungen ausgeblendet werden sollen.

Einrichten einer API-Umgebung

Vertrauen in Prenly-Anfragen

Prenly sendet einen vordefinierten geheimen Schlüssel in allen Authentifizierungs- und Autorisierungsanfragen. Der Schlüssel ist nur Prenly und Ihrem System bekannt. Sie sollten überprüfen, ob der bereitgestellte Schlüssel mit dem erwarteten Schlüssel für alle API-Anfragen übereinstimmt.

Sie können Ihre API-Endpunkte auch nur für bestimmte IP-Adressen öffnen, um zusätzliche Sicherheit zu gewährleisten. Bitte kontaktieren Sie uns, um eine aktuelle Liste der IPs zu erhalten, die Prenly bei Anfragen verwendet, wenn Sie diese zusätzliche Sicherheit wünschen.

Verschlüsseln Sie den Datenverkehr

Wir empfehlen dringend, jeglichen unverschlüsselten HTTP-Verkehr zu Ihrer API zu verbieten. Verwenden Sie HTTPS!

Erlauben Sie ein REST-ähnliches Verhalten

Vorläufige Anfragen werden derzeit mit HTTP POST gestellt, aber die API sollte nicht auf die Verwendung beliebiger HTTP-Methoden für zukünftige Endpunkt-Erweiterungen beschränkt sein. Weitere Einzelheiten finden Sie in der aktuellen API-Spezifikation, da diese das letzte Wort hat, wenn es zu Unstimmigkeiten mit dieser Dokumentation kommt.

In API-Antworten werden HTTP-Statuscodes verwendet, um Prenly über das Ergebnis zu informieren. Sie müssen in der Lage sein, mit verschiedenen HTTP-Statuscodes zu antworten, sowohl für erfolgreiche Anfragen als auch für Datenfehler, Laufzeitfehler und unerwartete Serverfehler.

Anfrageparameter werden derzeit als JSON im Anfragekörper übergeben.

Alle Endpunkte antworten derzeit mit JSON im Response-Body.

Machen Sie sich mit OpenAPI 3.0 vertraut

Die API-Spezifikation ist in einer yaml-Datei gemäß dem OpenAPI 3.0-Standard (ehemals Swagger) dokumentiert, in der die technischen Aspekte und Anforderungen der API und jedes Endpunkts, einschließlich aller Anfrage- und Antwortdatenobjekte, angegeben sind.

Die automatisch generierte Dokumentation finden Sie unter https://apidoc.prenly.com/remote-api/ und die Spezifikationsdatei unter https://apidoc.prenly.com/remote-api/spec/v1.3-specification.yaml.

Es steht Ihnen frei, eine Kopie der Spezifikationsdatei zu erstellen und sie an Ihre API-Endpunkte (URLs) anzupassen, da die automatisch generierte Spezifikation allgemeine benannte Endpunkte als Referenz enthält. Mit dieser Datei können Sie leicht eine Testumgebung mit vorgefertigten Tools aufbauen, die unter https://openapi.tools/ zur Verfügung stehen (siehe Abschnitt "Testen").

Lesen Sie mehr über OpenAPI, einschließlich der Spezifikation, unter https://www.openapis.org/.

Erstellen Sie den Authentifizierungsendpunkt

Siehe die API-Spezifikation unter https://apidoc.prenly.com/remote-api/ für den/die Authentifizierungsendpunkt(e). Sie können die Endpunkt-URL genau so wählen, wie Sie möchten; der Endpunkt muss jedoch der API-Spezifikation entsprechen.

Anforderungsparameter

Die Anforderungsparameter sind Teil des Anforderungskörpers als JSON und werden von Prenly für jede Anforderung gesendet.

Antwort bei Erfolg

Eine erfolgreiche Anmeldung muss mit dem HTTP-Statuscode 200 und einer JSON-Antwort mit der eindeutigen Kennung des Benutzers, der authentifiziert wurde, beantwortet werden.

Antwort im Fehlerfall

Bekannte Fehler, die von den gegebenen Anfrageparametern abhängen, müssen mit einem der HTTP-Statuscodes 401, 403 oder 412 antworten, wie in der API-Dokumentation angegeben. Diese Fehler müssen eine JSON-Antwort enthalten, die dem Datenmodell Error folgt, das Sie am Ende von https://apidoc.prenly.com/remote-api/ finden .

Sie können wählen, ob Sie einen Fehler oder ein leeres JSON-Objekt bereitstellen möchten. Derzeit ist nur die Eigenschaft "message" erforderlich, wenn Sie einen Fehler übermitteln. Es wird jedoch empfohlen, auch eine "Code"-Eigenschaft anzugeben.

Es wird dringend empfohlen, einen Wert für die Eigenschaft "message" in englischer Sprache anzugeben, der den Fehler auf irgendeine Weise darstellt. Wenn Ihre Software über interne Codes verfügt, ist es sinnvoll, diese hier zu verwenden, wenn später eine gegenseitige Fehlersuche erforderlich ist. Geben Sie keine persönlichen Daten an, die nicht benötigt werden, wie z. B. persönliche Namen! Eindeutige IDs sind für die Fehlersuche ausreichend.

Diese Informationen werden dem Endbenutzer nie angezeigt, können aber in Prenly protokolliert werden, um die Fehlersuche zu vereinfachen.

Erstellen Sie den Autorisierungsendpunkt

Siehe die API-Spezifikation unter https://apidoc.prenly.com/remote-api/ für den/die Autorisierungsendpunkt(e). Sie können die Endpunkt-URL genau so wählen, wie Sie es wünschen; der Endpunkt muss jedoch der API-Spezifikation entsprechen.

Anforderungsparameter

Anforderungsparameter sind Teil des Anforderungskörpers als JSON und werden von Prenly für jede Anforderung gesendet.

Antwort bei Erfolg

Ein erfolgreicher Abruf der Benutzerinformationen muss mit dem HTTP-Statuscode 200 und einer JSON-Antwort entsprechend dem UserSummary-Datenmodell, wie in der Spezifikation beschrieben, beantwortet werden.

Die Felder in diesem Datenobjekt werden am Ende von https://apidoc.prenly.com/remote-api/ erläutert .

Welche Eigenschaften werden verwendet, um

Die einzige Eigenschaft, die derzeit nicht leer gelassen werden kann, ist "uid". Die anderen Eigenschaften können weggelassen werden, es wird jedoch empfohlen, eine "productCodes"-Eigenschaft anzugeben, um besser kontrollieren zu können, ob Prenly Leserechte für Publikationen gewähren soll oder nicht. Derzeit behandelt Prenly eine fehlende "productCodes"-Eigenschaft als leere Liste.

Antwort bei Fehlern

Bekannte Fehler, die von den gegebenen Anfrageparametern abhängen, müssen mit einem der HTTP-Statuscodes 403, 404 oder 412 antworten, wie in der API-Dokumentation angegeben. Diese Fehler müssen eine JSON-Antwort enthalten, die dem oben beschriebenen Fehlerdatenmodell entspricht.

Testen

Es ist wichtig, dass Sie Ihre Implementierung für die Authentifizierungs- und Autorisierungsendpunkte testen. Unter https://docs.google.com/document/d/1UxmvDs7_Z0GwGbwCHXr4Ojpb9HaZif1nJ8YRMmztzeo/ finden Sie weitere Informationen zum Testen Ihrer Endpunkte.

Was passiert in Prenly?

Wenn sich der Benutzer anmeldet (Authentifizierung + Autorisierung)

Wenn der Benutzer die Anmeldung anfordert und das Anmeldeformular abschickt, werden die Anmeldedaten an die Prenly Autorität gesendet (verschlüsselt mit SSL). Von dort aus kümmert sich die Behörde um die Verwendung dieser Anmeldeinformationen zur Authentifizierung des Benutzers. Für die API der entfernten Behörde bedeutet dies, dass die Anmeldeinformationen gemäß der Spezifikation an den entfernten Endpunkt gesendet werden.

Prenly verarbeitet die API-Antwort und behandelt sowohl erfolgreiche als auch fehlgeschlagene Authentifizierungsanfragen, bei denen der Benutzer je nach dem HTTP-Statuscode der Fehlermeldung einen Fehler sieht. Siehe unten für weitere Details.

Wenn die Authentifizierung erfolgreich war...

Eine erfolgreiche Anmeldung löst eine separate Autorisierungsanfrage an den Remote-API-Endpunkt für die Autorisierung aus, um die Informationen des Benutzers abzurufen, die in Prenly für eine begrenzte Zeit zwischengespeichert werden.

Die Anwendung zeigt auch an, dass jemand eingeloggt ist, mit Namen oder E-Mail, je nachdem, welche Benutzerdaten in den Benutzerinformationen zurückgegeben wurden.

Hinweis: Wenn die unmittelbare Autorisierungsanfrage direkt nach der erfolgreichen Authentifizierungsanfrage mit HTTP 401 antwortet, wertet Prenly dies als Implementierungsfehler, meldet den Benutzer ab und informiert ihn darüber, dass die Anmeldedaten falsch waren. Um dies zu vermeiden, wird empfohlen, das im UserIdentification-Schema vorgesehene Token-Konzept zu verwenden, falls Sie die Möglichkeit zur Fernabmeldung des Benutzers unterstützen möchten.

Wenn die Anmeldedaten falsch waren...

Wenn die Anfrage technisch erfolgreich war, aber die Anmeldedaten falsch waren, benachrichtigt die Prenly-Behörde die Anwendung und der Benutzer erhält eine Meldung über die falschen Anmeldedaten.

Wenn etwas fehlgeschlagen ist...

Andere client- oder serverbasierte Fehler oder Netzwerkfehler werden von Prenly abgefangen und protokolliert. Die Anwendung wird mit einer geeigneten Fehlermeldung bedient, die dem Benutzer präsentiert wird.

Wenn der Benutzer weiterliest

Caching für wiederholte Anfragen

Durch das Zwischenspeichern der Antwortdaten auf eine erfolgreiche Autorisierung (die Informationen des Benutzers) werden wiederholte Anfragen an die Remote-API zum Abrufen von Benutzerdaten, die nur selten geändert werden, überflüssig. Jeder Prenly-Kunde kann die Cache-Ablaufzeit wählen, wir empfehlen die Einstellung von 30 Minuten, wobei die minimal zulässige Cache-Ablaufzeit 20 Minuten beträgt.

Neu-Autorisierung

Prenly verwendet das im Cache gespeicherte Ergebnis für jede Autorisierungsanfrage, solange der Cache noch nicht abgelaufen ist. Wenn der Cache abgelaufen ist, löst Prenly eine neue Autorisierungsanfrage an den Autorisierungsendpunkt in der Remote-API aus. Dadurch werden die Daten des Benutzers, z. B. die Produktverfügbarkeit, sowie die im Cache gespeicherten Daten aktualisiert.

Behandlung von Fehlern

Tritt beim Auslösen der erneuten Autorisierung ein Serverfehler (5xx HTTP-Code) auf, wird die Cache-Ablaufzeit um fünf Minuten verlängert. Prenly tut dies, um zu vermeiden, dass Benutzer wegen vorübergehender Netzwerk- oder Serverfehler abgemeldet werden; der Benutzer liest weiter, als ob nichts passiert wäre, und nach fünf Minuten wird ein neuer Versuch zur erneuten Autorisierung unternommen. Dieses Verhalten bleibt so lange bestehen, wie das Serverproblem anhält. Prenly wird solche technischen Probleme protokollieren und versuchen, den Kunden zu erreichen, wenn dies geschieht.

In Betrieb gehen

Wenn Sie der Meinung sind, dass die API bereit ist, live zu gehen (Sie haben Ihre Implementierung fertig entwickelt und getestet), kontaktieren Sie uns, um die letzten Schritte einzuleiten.

Prenly wird Informationen von Ihnen benötigen, um Ihre Implementierung in Prenly einzurichten. Die Informationen werden ausgewertet und wenn alles in Ordnung ist, kann Ihre Implementierung in Prenly für die von Ihnen gewählten E-Paper Prenly-Anwendungen verwendet werden.

Einrichten von Prenly

Bevor Ihre Implementierung der Remote-API in Prenly verwendet werden kann, müssen Sie diese bereitstellen:

- den von Ihnen gewählten geheimen Schlüssel für die Authentifizierungs- und Autorisierungsendpunkte

- Die von Ihnen gewählten API-Endpunkte

- Eine Liste von Produkten, die Leseberechtigungen gewähren sollen und für die Prenly einen Titel hat (nur Prenly-bekannte Produkte innerhalb der Produktcode-Liste des Autorisierungs-Endpunkts können Leseberechtigungen gewähren)

- Ihre gewünschte Cache-Ablaufzeit

- Eine URL, unter der ein neuer Benutzer ein Konto erstellen kann

- Eine URL, unter der ein Benutzer sein Konto löschen kann

- Eine URL, unter der ein Benutzer sein Passwort zurücksetzen kann (falls er sein Passwort vergessen hat)

- Wir empfehlen, dass Sie auch eine URL angeben, unter der ein autorisierter Benutzer ohne im Voraus bekannte Produktcodes ein Produkt aktivieren kann (d. h. ein Abonnement erwerben kann)

- Benutzerdaten (Benutzername und Kennwort) für den Testbenutzer, wobei der Benutzer von Textalk, Apple und Google (wenn Sie native Anwendungen haben) gemeinsam genutzt wird und mindestens ein Produktcode aktiv bleiben muss, solange die Remote-API von der Prenly-Behörde Ihres E-Papers verwendet wird