Prenly Remote Authority API

Der Zweck dieses Dokuments ist es zu erklären:

1. ...wie das Prenly-Ökosystem es ermöglicht, die Authentifizierung und Autorisierung von Nutzern über eine technische Infrastruktur zu verwalten, die dem Herausgeber oder einem Dritten gehört.

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

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 der Überprüfung der Identität einer Person oder Sache, d. h. ob sie diejenige ist, die sie vorgibt zu sein, bevor der Zugriff auf geschützte Daten gewährt wird. Normalerweise geschieht dies durch die Angabe bestimmter Anmeldeinformationen, z. B. eines Benutzernamens und eines Passworts. Wenn die Anmeldedaten mit einem gespeicherten Datensatz übereinstimmen, wird der Benutzer "verifiziert" (authentifiziert), indem das Prinzip angewendet wird, dass der Benutzer etwas weiß, was nur der "echte" Benutzer wissen kann.

Beider Autorisierung wird festgelegt, auf welche Ressourcen ein Benutzer Zugriff hat, d. h. auf welche Daten der Benutzer zugreifen darf und was er tun darf und was 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 ein Satz von Routinen, Protokollen und Werkzeugen, die die Interaktion zwischen verschiedenen Systemen oder Teilen von Systemen regeln und die Kommunikation zwischen Systemen vorgeben.

In Prenly ist eine Autorität eine technische Implementierung, die festlegt, wie Authentifizierung und Autorisierung durch eine Prenly Anwendung im Prenly Backend gehandhabt werden.

Einführung in die

Die Prenly Remote Authority API bietet die Möglichkeit, das Autorisierungs- und/oder Authentifizierungsmanagement von Prenly zu ersetzen, indem API-Endpunkte implementiert werden, die einer API-Spezifikation folgen, die es einem Prenly-Kunden ermöglicht, auf der Grundlage seines Systems, seiner Anforderungen und Bedürfnisse zu authentifizieren und zu autorisieren.

Grundsätzlich erlaubt dies der Prenly-Anwendungsbehörde, Benutzer zu autorisieren und/oder zu authentifizieren, wenn sie mit der Prenly-Anwendung interagieren, d.h. wenn sie Publikationen in einer App lesen, und zwar über die Prenly Remote Authority API.

Die Prenly Behörde vermittelt Authentifizierungs- und Autorisierungsanfragen zwischen Nutzern und Prenly, wobei keine direkte Kommunikation zwischen Nutzer 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 Ihrer API

Verstehen, wie der Nutzer 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 alle zugänglich sind, als auch geschützte Inhalte, für deren Nutzung eine bestimmte Form der Autorisierung erforderlich ist. Bei nativen Anwendungen ist es auch möglich, allen nicht angemeldeten Nutzern zu erlauben, bestimmte Publikationen kostenlos zu konsumieren, bevor eine Anmeldung erforderlich ist.

Navigieren in der Anwendung

Wenn ein Nutzer die Anwendung verwendet, sieht er normalerweise die Startseite, die Komponenten enthält, die veröffentlichte 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, verlangt die Anwendung, dass sich der Benutzer anmeldet(Authentifizierung).

Nach der Anmeldung stellt Prenly fest, ob die angeforderte Publikation für diesen Benutzer lesbar ist(Autorisierung). Ist dies der Fall, wird die Publikation geöffnet und steht zur Nutzung bereit. Wenn der Nutzer keine Leseberechtigung hat, wird er in der App darauf hingewiesen. Der geschützte Inhalt wird nicht angezeigt, aber der Benutzer ist weiterhin angemeldet.

In manchen Fällen verlangt eine Anwendung, dass der Nutzer sich anmeldet, um bestimmte Publikationen zu sehen, insbesondere wenn nicht alle veröffentlichten Publikationen von jedermann eingesehen werden können. Dies gilt insbesondere dann, wenn nicht alle veröffentlichten Publikationen für jedermann einsehbar sind, z. B. bei Publikationen, die über ein Abonnement verfügbar sind und bei denen andere veröffentlichte Publikationen, die nicht abonniert sind, ausgeblendet werden sollen.

Konfigurieren einer API-Umgebung

Vertrauen für 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 bei allen API-Anfragen überprüfen, ob der bereitgestellte Schlüssel mit dem erwarteten Schlüssel übereinstimmt.

Für zusätzliche Sicherheit können Sie Ihre API-Endpunkte auch nur für bestimmte IP-Adressen öffnen. Setzen Sie sich mit uns in Verbindung, um eine aktualisierte Liste der IP-Adressen zu erhalten, die Prenly bei Anfragen verwendet, wenn Sie diese zusätzliche Sicherheit wünschen.

Verschlüsseln Sie den Datenverkehr

Wir empfehlen dringend, dass Sie keinen unverschlüsselten HTTP-Verkehr zu Ihrer API zulassen. 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 Informationen finden Sie in der aktuellen API-Spezifikation, da die API-Spezifikation bei Abweichungen von dieser Dokumentation das letzte Wort hat.

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

Alle Endpunkte antworten derzeit mit JSON im Antwortkörper.

Machen Sie sich mit OpenAPI 3.0 vertraut

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

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 erstellen, die unter https://openapi.tools/ verfügbar sind (siehe Abschnitt "Testen").

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

Erstellen des Authentifizierungsendpunkts

In der API-Spezifikation unter https://apidoc.prenly.com/remote-api/ finden Sie die Authentifizierungsendpunkte. Sie können die Endpunkt-URL frei wählen, aber der Endpunkt muss der API-Spezifikation entsprechen.

Anforderungsparameter

Anforderungsparameter sind Teil der Anforderung 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 bei Misserfolg

Bekannte Fehler, die auf die angegebenen Anfrageparameter zurückzuführen sind, müssen mit einem der HTTP-Statuscodes 401, 403 oder 412 beantwortet werden, wie in der API-Dokumentation angegeben. Diese Fehler müssen eine JSON-Antwort enthalten, die dem Datenmodell "Error" entspricht, das am Ende von https://apidoc.prenly.com/remote-api/ zu finden ist .

Sie können entweder einen Fehleroder ein leeres JSON-Objekt bereitstellen. 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, für die Eigenschaft "message" einen Wert in englischer Sprache festzulegen, der den Fehler in irgendeiner Weise darstellt. Wenn Ihre Software über interne Codes verfügt, ist es ratsam, diese hier zu verwenden, falls später eine gegenseitige Fehlersuche erforderlich ist. Geben Sie keine persönlichen Daten an, die nicht benötigt werden, z. B. Personennamen! 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 erleichtern.

Erstellung des Endpunkts für die Autorisierung

Siehe die API-Spezifikation unter https://apidoc.prenly.com/remote-api/ für die Autorisierungsendpunkte. Sie können die Endpunkt-URL nach Belieben wählen, aber der Endpunkt muss der API-Spezifikation entsprechen.

Anfrageparameter

Die Anfrageparameter sind Teil der Anfrage als JSON und werden von Prenly für jede Anfrage gesendet.

Antwort bei Erfolg

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

Die Felder dieses Datenobjekts werden am Ende von https://apidoc.prenly.com/remote-api/ erläutert.

Wofür die Eigenschaften verwendet werden

Die einzige Eigenschaft, die derzeit nicht leer gelassen werden kann, ist "uid". Die anderen Eigenschaften können weggelassen werden, aber wir empfehlen, eine "productCodes"-Eigenschaft zu setzen, um besser kontrollieren zu können, ob Prenly Lesezugriff auf Publikationen gewähren soll oder nicht. Derzeit behandelt Prenly eine fehlende "productCodes"-Eigenschaft als leere Liste.

Antwort im Fehlerfall

Bekannte Fehler, die sich aus den angegebenen Anfrageparametern ergeben, müssen mit einem der HTTP-Statuscodes 403, 404 oder 412 beantwortet werden, wie in der API-Dokumentation angegeben. Diese Fehler müssen eine JSON-Antwort enthalten, die dem oben beschriebenen Error-Datenmodell 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 sich anmelden möchte und das Anmeldeformular abschickt, werden die Anmeldedaten an die Prenly-Behörde gesendet (verschlüsselt mit SSL). Von dort aus verwaltet die Behörde, wie diese Anmeldedaten zur Authentifizierung des Benutzers zu verwenden sind. Für die API der entfernten Behörde bedeutet dies, dass die Anmeldedaten wie angegeben an den entfernten Verbindungspunkt gesendet werden.

Prenly verarbeitet die API-Antwort und bearbeitet sowohl erfolgreiche als auch erfolglose Authentifizierungsanfragen, bei denen der Benutzer je nach HTTP-Statuscode der Fehlerantwort einen Fehler sieht. Siehe unten für weitere Informationen.

Wenn die Authentifizierung erfolgreich war...

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

Die Anwendung zeigt auch an, dass jemand eingeloggt ist, und zwar durch den Namen oder die E-Mail, je nachdem, welche Benutzerdaten in den Anmeldedaten zurückgegeben wurden.

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 erhält eine entsprechende Fehlermeldung, die dem Benutzer angezeigt wird.

Wenn der Benutzer weiterliest

Caching für wiederholte Anfragen

Durch das Zwischenspeichern der Antwortdaten einer erfolgreichen Autorisierung (die Informationen des Benutzers) entfällt die Notwendigkeit wiederholter Anfragen an die Remote-API, um Benutzerdaten abzurufen, die sich selten ändern. 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.

Erneute 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 (HTTP-Code 5xx) auf, wird die Cache-Verfallszeit um fünf Minuten verlängert. Prenly tut dies, um zu vermeiden, dass Benutzer aufgrund von vorübergehenden Netzwerk- oder Serverfehlern 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 hält so lange an, wie das Serverproblem anhält. Prenly wird solche technischen Probleme protokollieren und versuchen, den Kunden zu erreichen, wenn dies der Fall ist.

In Betrieb gehen

Wenn Sie der Meinung sind, dass die API bereit ist, live zu gehen (Sie haben die Entwicklung und das Testen Ihrer Implementierung abgeschlossen), kontaktieren Sie uns, um die letzten Schritte einzuleiten.

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

Prenly konfigurieren

Bevor Ihre Remote-API-Implementierung 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 Lesezugriff gewähren sollen und für die der Prenly-Titel (nur Prenly-bekannte Produkte in der Produktcodeliste vom Autorisierungsendpunkt können Lesezugriff gewähren)

- Ihre bevorzugte Ablaufzeit für den Cache

- 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 es vergessen hat)

- Wir empfehlen, dass Sie auch eine URL angeben, unter der ein autorisierter Benutzer ohne zuvor bekannte Produktcodes ein Produkt aktivieren kann (z. B. ein Abonnement erwerben)

- 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 für Ihr E-Paper verwendet wird