Prenly Remote Authority API

Formålet med dette dokument er at forklare:

1. ...hvordan Prenly-økosystemet gør det muligt at håndtere brugergodkendelse og -autorisation via en teknisk infrastruktur, der ejes af udgiveren eller en tredjepart.

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

Kontakt

Kontakt os 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 en proces, hvor man verificerer en persons eller et objekts identitet, dvs. om vedkommende er den, han eller hun udgiver sig for at være, før der gives adgang til beskyttede data. Normalt sker dette ved at give nogle legitimationsoplysninger, f.eks. et brugernavn og en adgangskode. Når 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 beslutte, hvilke ressourcer en bruger har adgang til, dvs. hvilke data brugeren har tilladelse til at få adgang til, som i hvad brugeren må eller ikke må gøre. For Prenly er det at bestemme, 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 håndtere interaktionen mellem forskellige systemer eller dele af systemer, som dikterer system-til-system-kommunikation.

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

Introduktion til Prenly

Prenly Remote Authority API introducerer muligheden for at erstatte Prenlys autorisations- og/eller godkendelseshåndtering ved at implementere API-slutpunkter, der følger en API-specifikation, som gør det muligt for en Prenly-kunde at autentificere og autorisere efter deres system, krav og behov.

Kernen i dette er, at Prenly-applikationens autoritet kan 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 brugere og API-implementering. I stedet informerer API-implementeringen Prenly-myndigheden om, hvordan den skal reagere på brugernes godkendelses- og autorisationsanmodninger.

Implementer din API

Forstå, hvordan brugeren bruger Prenly-applikationen

Prenly-applikationer

Prenly betjener slutbrugeren med applikationer, der hovedsageligt 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, som er offentlige for alle, samt beskyttet indhold, som kræver en eller anden form for tilladelse for at blive brugt. For native apps er det også muligt at give alle ikke-indloggede brugere mulighed for at bruge nogle publikationer gratis, før der kræves login.

Navigering i applikationen

Ved at bruge applikationen kan en bruger 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, så den er klar til at blive brugt. 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 vise visse publikationer, især når ikke alle offentliggjorte publikationer kan ses af hvem som helst. For eksempel publikationer, der er tilgængelige via et abonnement, hvor andre ikke-abonnementsudgivne publikationer skal være skjult.

Opsætning 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 bestemte 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 kraftigt, at du ikke tillader ukrypteret HTTP-trafik til din API. Brug HTTPS!

Tillad en REST-agtig adfærd

Foreløbige anmodninger foretages i øjeblikket med 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 flere detaljer, da API-specifikationen har det sidste ord i eventuelle uoverensstemmelser med denne dokumentation.

I API-svar bruges HTTP-statuskoder til at informere Prenly om resultatet. Du skal kunne 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.

Bliv fortrolig med OpenAPI 3.0

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

Automatisk genereret dokumentation findes 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 som reference. Med denne fil kan du nemt opbygge et testmiljø med de færdige værktøjer, der findes på https://openapi.tools/ (se afsnittet "Testing").

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

Byg godkendelsesslutpunktet

Se API-specifikationen på https://apidoc.prenly.com/remote-api/ for godkendelsens slutpunkt(er). Du kan vælge slutpunktets URL, præcis som du ønsker, men slutpunktet skal følge API-specifikationen.

Anmodningsparametre

Anmodningsparametre er en del af anmodningsteksten 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, der afhænger af de givne anmodningsparametre, skal svare 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 du kan finde specificeret i bunden af https://apidoc.prenly.com/remote-api/.

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

Vi anbefaler stærkt, at du angiver en "message"-egenskabsværdi på engelsk, som repræsenterer fejlen på en eller anden måde. Hvis din software har en eller anden form for interne koder, er det hensigtsmæssigt at bruge dem her, hvis det bliver nødvendigt med gensidig fejlfinding i fremtiden. Medtag ikke personlige data, som ikke er nødvendige, f.eks. personnavne! Unikke ID'er er gode nok til fejlfinding.

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

Byg autorisationsslutpunktet

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

Anmodningsparametre

Anmodningsparametre er en del af anmodningsteksten 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 som 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 du angiver en "productCodes"-egenskab for bedre at kunne kontrollere, om Prenly skal give læsetilladelse til publikationer eller ej. I øjeblikket vil Prenly behandle en manglende "productCodes"-egenskab som en tom liste.

Svar på fejl

Kendte fejl, der afhænger af de givne anmodningsparametre, skal svare med en af HTTP-statuskoderne 403, 404 eller 412 som specificeret 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 test af dine endpoints.

Hvad sker der i Prenly?

Når brugeren logger ind (godkendelse + autorisation)

Når brugeren anmoder om at logge ind og sender loginformularen, sendes legitimationsoplysningerne til Prenlys autoritet (krypteret med SSL). Derfra håndterer myndigheden, hvordan disse legitimationsoplysninger skal bruges til at godkende brugeren. For API'en Remote authority betyder det, at legitimationsoplysningerne sendes til det eksterne slutpunkt i henhold til specifikationen.

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

Hvis godkendelsen lykkedes...

Et vellykket login udløser en separat autorisationsanmodning til det eksterne API-endepunkt for autorisation for at hente brugerens oplysninger, som cachelagres i Prenly i en begrænset periode.

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

Hvis legitimationsoplysningerne 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 fanges og logges af Prenly. Applikationen får en passende fejlmeddelelse, som præsenteres for brugeren.

Når brugeren fortsætter med at læse

Caching til gentagne anmodninger

Caching af vellykkede autorisationsresponsdata (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øbstid, vi anbefaler at indstille 30 minutter, hvor den mindste tilladte cache-udløbstid er 20 minutter.

Genautorisation

Prenly bruger det cachelagrede resultat til 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 konfigurere din implementering i Prenly. Oplysningerne vil blive evalueret, og hvis alt er i orden, kan din implementering bruges i Prenly til dine valgte Prenly-applikationer til e-papir.

Opsætning af Prenly

Før din implementering af den eksterne API 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 give læseadgang, og som Prenly-titlen gælder for (kun Prenly-kendte produkter på listen over produktkoder fra godkendelsesslutpunktet kan give læseadgang)

- Din ønskede 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 forud 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 native apps), hvor mindst én produktkode skal forblive aktiv, så længe fjern-API'en bruges af din e-papirs Prenly-autoritet.