Prenly Remote Authority API

Formålet med dette dokument er at forklare:

1. ...hvordan Prenly-økosystemet gør det muligt at administrere godkendelse og autorisation af brugere ved hjælp af en teknisk infrastruktur, der ejes af udgiveren eller en tredjepart.

2. ...hvordan en teknisk implementering kan udføres ved at bygge en beskeden rest-API, der følger "Prenly Remote authority API"-specifikationen.

Kontakt

Kontakt os venligst via e-mail på hello@prenly.com eller via telefon på +46-31-3884740 for spørgsmål eller problemer vedrørende denne API.

Definitioner

Autentificering er processen med at verificere identiteten af nogen eller noget, dvs. om de er dem, de hævder at være, før der gives adgang til beskyttede data. Normalt gøres dette ved at give visse legitimationsoplysninger, f.eks. et brugernavn og en adgangskode. Idet legitimationsoplysningerne matcher en lagret post, bliver brugeren "verificeret" (autentificeret) ved at anvende princippet om, at brugeren vidste noget, som kun den "rigtige" bruger ville vide.

Autorisation er processen med at bestemme, hvilke ressourcer en bruger har adgang til, dvs. hvilke data brugeren er autoriseret til at få adgang til, og hvad brugeren må eller ikke må gøre. For Prenly betyder det, at det bestemmes, hvilke publikationer brugeren kan se og åbne for at læse.

En API(Application Program Interface)er et sæt rutiner, protokoller og værktøjer til at styre interaktionen mellem forskellige systemer eller dele af systemer og dikterer kommunikationen mellem systemer.

I Prenly er en autoritet en teknisk implementering, der bestemmer, hvordan autentificering og autorisation håndteres af en Prenly-applikation i Prenly-backend.

Introduktion til

Prenly Remote Authority API giver mulighed for at erstatte Prenlys styring af autorisation og/eller godkendelse ved at implementere API-slutpunkter, der følger en API-specifikation, så en Prenly-kunde kan godkende og autorisere baseret på deres system, krav og behov.

Grundlæggende giver dette Prenly-applikationsmyndigheden mulighed for at autorisere og/eller godkende brugere, når de interagerer med Prenly-applikationen, dvs. når de læser publikationer i en app, ved hjælp af Prenly Remote Authority API.

Prenly-myndigheden vil formidle godkendelses- og autorisationsanmodninger mellem brugere og Prenly, hvor ingen direkte kommunikation er tilladt mellem bruger og API-implementering. I stedet informerer API-implementeringen Prenly-myndigheden om, hvordan den skal handle på brugernes godkendelses- og autorisationsanmodninger.

Implementering af din API

Forstå, hvordan brugeren anvender Prenly-applikationen

Prenly-applikationer

Prenly forsyner slutbrugeren med applikationer, der primært bruges til at læse publikationer og artikler. Applikationen er enten en indbygget mobilapp på Android- eller iOS-platformen eller vores responsive webbaserede e-læser. Disse to applikationstyper tilbyder en lignende brugeroplevelse.

Applikationen kan indeholde publicerede publikationer, der er offentlige for alle, samt beskyttet indhold, der kræver en eller anden form for godkendelse for at blive brugt. For native apps er det også muligt at give alle ikke-indloggede brugere mulighed for at bruge visse publikationer gratis, før der kræves login.

Navigering i applikationen

Når en bruger anvender applikationen, kan han eller hun normalt se startsiden, som indeholder komponenter, der viser offentliggjorte publikationer. Offentlige publikationer kan åbnes og læses ved at vælge publikationen. Men når brugeren forsøger at åbne en beskyttet publikation, vil applikationen kræve, at brugeren logger ind(autentificering).

Efter login afgør Prenly, om den ønskede publikation kan læses af den pågældende bruger(autorisation). Hvis det er tilfældet, åbnes publikationen og er klar til brug. Hvis brugeren ikke har læseadgang, får brugeren besked i appen. Det beskyttede indhold vil ikke blive vist, men brugeren vil stadig være logget ind.

I nogle tilfælde vil en applikation kræve, at brugeren logger ind for at se visse publikationer, især når ikke alle offentliggjorte publikationer kan ses af alle. For eksempel publikationer, der er tilgængelige via et abonnement, hvor andre publicerede publikationer, der ikke abonneres på, skal skjules.

Konfiguration af et API-miljø

Tillid til Prenly-anmodninger

Prenly sender en foruddefineret hemmelig nøgle i alle godkendelses- og autorisationsanmodninger. Nøglen er kun kendt af Prenly og dit system. Du bør kontrollere, at den angivne nøgle matcher den forventede nøgle for alle API-anmodninger.

Du kan også åbne dine API-slutpunkter for kun visse IP-adresser for at opnå ekstra sikkerhed. Kontakt os for at få en opdateret liste over IP-adresser, som Prenly vil bruge i anmodninger, hvis du ønsker denne ekstra sikkerhed.

Krypter trafikken

Vi anbefaler på det kraftigste, at du ikke tillader ukrypteret HTTP-trafik til din API. Brug HTTPS!

Tillad en REST-lignende adfærd

Foreløbige anmodninger foretages i øjeblikket ved hjælp af HTTP POST, men API'en bør ikke være begrænset til at bruge nogen HTTP-metoder til fremtidig udvidelse af slutpunkter. Se den aktuelle API-specifikation for at få flere oplysninger, da API-specifikationen har det sidste ord i eventuelle afvigelser fra denne dokumentation.

I API-svar bruges HTTP-statuskoder til at informere Prenly om resultatet. Du skal være i stand til at svare med forskellige HTTP-statuskoder, både for vellykkede anmodninger og for datafejl, runtime-fejl og uventede serverfejl.

Anmodningsparametre sendes i øjeblikket som JSON i anmodningskroppen.

Alle slutpunkter svarer i øjeblikket med JSON i svarteksten.

Sæt dig ind i OpenAPI 3.0

API-specifikationen er dokumenteret i en yaml-fil i henhold til OpenAPI 3.0-standarden (tidligere Swagger) og specificerer de tekniske aspekter og krav til API'en og hvert slutpunkt, herunder alle anmodnings- og svardataobjekter.

Automatisk genereret dokumentation er tilgængelig på https://apidoc.prenly.com/remote-api/, og specifikationsfilen er tilgængelig på https://apidoc.prenly.com/remote-api/spec/v1.3-specification.yaml.

Du er velkommen til at lave en kopi af specifikationsfilen og ændre den til dine API-slutpunkter (URL'er), da den autogenererede specifikation indeholder generiske navngivne slutpunkter til reference. Med denne fil kan du nemt opbygge et testmiljø med færdige værktøjer, der er tilgængelige på https://openapi.tools/ (se afsnittet "Test").

Læs mere om OpenAPI, herunder specifikationen, på https://www.openapis.org/.

Opbygning af godkendelsesslutpunktet

Se API-specifikationen på https://apidoc.prenly.com/remote-api/ for godkendelsesslutpunkterne. Du kan vælge slutpunktets URL, som du vil, men slutpunktet skal følge API-specifikationen.

Anmodningsparametre

Anmodningsparametre er en del af anmodningen som JSON og sendes af Prenly for hver anmodning.

Svar på succes

Et vellykket login skal svare med HTTP-statuskode 200 og et JSON-svar med den unikke identifikator for den bruger, der blev godkendt.

Svar på fejl

Kendte fejl på grund af de angivne anmodningsparametre skal besvares med en af HTTP-statuskoderne 401, 403 eller 412 som angivet i API-dokumentationen. Disse fejl skal indeholde et JSON-svar, der følger Error-datamodellen, som findes nederst på https://apidoc.prenly.com/remote-api/.

Du kan vælge at levere enten en Erroreller et tomt JSON-objekt. I øjeblikket er det kun "message"-egenskaben, der kræves, hvis du leverer en Error. Det anbefales dog også at angive en "code"-egenskab.

Vi anbefaler på det kraftigste, at du angiver en værdi for "message"-egenskaben på engelsk, som repræsenterer fejlen på en eller anden måde. Hvis din software har nogen form for interne koder, er det tilrådeligt at bruge dem her, hvis der i fremtiden bliver brug for gensidig fejlfinding. Medtag ikke personlige data, som ikke er nødvendige, f.eks. personlige navne! Unikke ID'er er gode nok til fejlfinding.

Disse oplysninger vises aldrig til slutbrugeren, men kan logges i Prenly for at forenkle fejlsøgningen.

Opbygning af slutpunkt for autorisation

Se API-specifikationen på https://apidoc.prenly.com/remote-api/ for autorisationsslutpunkterne. Du kan vælge slutpunktets URL, som du vil, men slutpunktet skal følge API-specifikationen.

Anmodningsparametre

Anmodningsparametre er en del af anmodningen som JSON og sendes af Prenly for hver anmodning.

Svar ved succes

En vellykket hentning af brugeroplysningerne skal svare med HTTP-statuskode 200 og et JSON-svar i henhold til UserSummary-datamodellen, der er beskrevet i specifikationen.

Felterne i dette dataobjekt er forklaret nederst på https://apidoc.prenly.com/remote-api/.

Hvad egenskaber bruges til

Den eneste egenskab, der i øjeblikket ikke kan efterlades tom, er "uid". De andre egenskaber kan udelades, men vi anbefaler at indstille en "productCodes"-egenskab for bedre at kunne kontrollere, om Prenly skal give læseadgang til publikationer eller ej. I øjeblikket vil Prenly behandle en manglende "productCodes"-egenskab som en tom liste.

Svar i tilfælde af fejl

Kendte fejl som følge af de angivne anmodningsparametre skal besvares med en af HTTP-statuskoderne 403, 404 eller 412 som angivet i API-dokumentationen. Disse fejl skal indeholde et JSON-svar, der følger Error-datamodellen som beskrevet ovenfor.

Testning

Det er vigtigt at teste din implementering af slutpunkterne for godkendelse og autorisation. Se https://docs.google .com/document/d/1UxmvDs7_Z0GwGbwCHXr4Ojpb9HaZif1nJ8YRMmztzeo/ for at få flere oplysninger om, hvordan du tester dine endpoints.

Hvad sker der i Prenly?

Når brugeren logger ind (autentificering + autorisation)

Når brugeren anmoder om at logge ind og sender loginformularen, sendes loginoplysningerne til Prenly-autoriteten (krypteret med SSL). Derfra styrer myndigheden, hvordan disse oplysninger skal bruges til at godkende brugeren. For API'en Remote authority betyder det, at legitimationsoplysningerne sendes til fjernforbindelsespunktet som angivet.

Prenly behandler API-svaret og håndterer både vellykkede og mislykkede autentificeringsanmodninger, hvor brugeren vil se en fejl afhængigt af HTTP-statuskoden i fejlsvaret. Se nedenfor for mere information.

Hvis autentificeringen var vellykket...

Et vellykket login udløser en separat autorisationsanmodning til Authorisation API endpoint for at hente brugerens oplysninger, som cachelagres i Prenly i en begrænset periode.

Applikationen vil også vise, at nogen er logget ind med navn eller e-mail baseret på de brugerdata, der blev returneret i brugeroplysningerne.

Hvis login-oplysningerne var forkerte...

Hvis anmodningen teknisk set var vellykket, men legitimationsoplysningerne var forkerte, giver Prenly-autoriteten besked til applikationen, og brugeren får en besked om forkerte legitimationsoplysninger.

Hvis noget mislykkedes...

Andre klient- eller serverbaserede fejl eller netværksfejl vil blive fanget og logget af Prenly. Programmet modtager en passende fejlmeddelelse, som præsenteres for brugeren.

Mens brugeren fortsætter med at læse

Caching til gentagne anmodninger

Caching af svardataene fra en vellykket autorisation (brugerens oplysninger) eliminerer behovet for gentagne anmodninger til den eksterne API for at hente brugerdata, der sjældent ændres. Hver Prenly-kunde kan vælge cache-udløbstiden, vi anbefaler at indstille 30 minutter, hvor den mindste tilladte cache-udløbstid er 20 minutter.

Genautorisation

Prenly vil bruge det cachelagrede resultat for hver autorisationsanmodning, så længe cachen ikke er udløbet. Hvis cachen er udløbet, udløser Prenly en ny autorisationsanmodning til autorisationsendepunktet i den eksterne API. Dette vil opdatere brugerens data, såsom produkttilgængelighed, samt de cachelagrede data.

Håndtering af fejl

Hvis der opstår en serverfejl (5xx HTTP-kode), når genautorisation udløses, forlænges cache-udløbstiden med fem minutter. Prenly gør dette for at undgå, at brugere bliver logget ud på grund af midlertidige netværks- eller serverfejl; brugeren fortsætter med at læse, som om intet var hændt, og efter fem minutter foretages et nyt forsøg på genautorisation. Denne adfærd varer, så længe serverproblemet varer ved. Prenly vil logge sådanne tekniske problemer og forsøge at få fat i kunden, hvis det sker.

At gå live

Når du mener, at API'en er klar til at gå live (du er færdig med at udvikle og teste din implementering), skal du kontakte os for at tage de sidste skridt.

Prenly har brug for oplysninger fra dig for at kunne konfigurere din implementering i Prenly. Oplysningerne vil blive evalueret, og hvis alt er i orden, kan din implementering bruges i Prenly til dine udvalgte Prenly e-papir-applikationer.

Konfiguration af Prenly

Før din eksterne API-implementering kan bruges i Prenly, skal du angive:

- Din valgte hemmelige nøgle til godkendelses- og autorisationsslutpunkterne

- Dine valgte API-slutpunkter

- En liste over produkter, der skal gives læseadgang til, og som Prenly-titlen (kun Prenly-kendte produkter på produktkodelisten fra godkendelsesslutpunktet kan give læseadgang)

- Din foretrukne udløbstid for cachen

- En URL, hvor en ny bruger kan oprette en konto

- En URL, hvor en bruger kan slette sin konto

- En URL, hvor en bruger kan nulstille sin adgangskode (hvis de har glemt deres adgangskode)

- Vi anbefaler, at du også angiver en URL, hvor en autoriseret bruger uden tidligere kendte produktkoder kan aktivere et produkt (f.eks. købe et abonnement).

- Brugeroplysninger (brugernavn og adgangskode) for testbrugeren, hvor brugeren deles af Textalk, Apple og Google (hvis du har indbyggede apps), hvor mindst én produktkode skal forblive aktiv, så længe den eksterne API bruges af Prenly-autoriteten til din e-paper.