Prenly Remote Authority API

Formålet med dette dokumentet er å forklare:

1. ...hvordan Prenly-økosystemet gjør det mulig å håndtere brukerautentisering og autorisasjon ved hjelp av en teknisk infrastruktur som eies av utgiveren eller en tredjepart.

2. ...hvordan en teknisk implementering kan gjøres ved å bygge et beskjedent rest-API som følger "Prenly Remote authority API"-spesifikasjonen.

Kontakt

Ta kontakt med oss på e-post hello@prenly.com eller på telefon +46-31-3884740 hvis du har spørsmål eller problemer med dette API-et.

Definisjoner

Autentisering er prosessen med å verifisere identiteten til noen eller noe, for eksempel om de er den de utgir seg for å være, før de gis tilgang til beskyttede data. Normalt gjøres dette ved å oppgi legitimasjon, for eksempel et brukernavn og et passord. Gitt at legitimasjonen stemmer overens med en lagret oppføring, blir brukeren "verifisert" (autentisert) ved å anvende prinsippet om at brukeren visste noe som bare den "ekte" brukeren ville vite.

Autorisasjon er prosessen som bestemmer hvilke ressurser en bruker har tilgang til, dvs. hvilke data brukeren har tillatelse til å få tilgang til, som i hva brukeren kan eller ikke kan gjøre. For Prenly betyr dette å bestemme hvilke publikasjoner brukeren kan se og åpne for å lese.

Et API(Application Program Interface)er et sett med rutiner, protokoller og verktøy som håndterer samspillet mellom ulike systemer eller deler av systemer, og som styrer kommunikasjonen mellom systemene.

I Prenly er en autoritet en teknisk implementering som bestemmer hvordan autentisering og autorisasjon skal håndteres av en Prenly-applikasjon i Prenlys backend.

Introduksjon

Prenly Remote Authority API introduserer muligheten til å erstatte Prenlys autorisasjons- og/eller autentiseringshåndtering ved å implementere API-sluttpunkter som følger en API-spesifikasjon, noe som gjør det mulig for en Prenly-kunde å autentisere og autorisere etter eget system, krav og behov.

I utgangspunktet gjør dette det mulig for Prenly-applikasjonens autoritet å autorisere og/eller autentisere brukere når de samhandler med Prenly-applikasjonen, f.eks. når de leser publikasjoner i en app, ved hjelp av Prenly Remote Authority API.

Prenly-autoriteten vil formidle autentiserings- og autorisasjonsforespørsler mellom brukere og Prenly der ingen direkte kommunikasjon er tillatt mellom brukere og API-implementering. I stedet informerer API-implementeringen Prenly-autoriteten om hvordan den skal reagere på brukernes autentiserings- og autorisasjonsforespørsler.

Implementer API-et ditt

Forstå hvordan brukeren bruker Prenly-applikasjonen

Prenly-applikasjoner

Prenly betjener sluttbrukeren med applikasjoner som hovedsakelig brukes til å lese publikasjoner og artikler. Applikasjonen er enten en innebygd mobilapp på Android- eller iOS-plattformen, eller vår responsive nettbaserte e-leser. Disse to applikasjonstypene tilbyr en lignende brukeropplevelse.

Applikasjonen kan inneholde publiserte publikasjoner som er offentlige for alle, samt beskyttet innhold som krever en eller annen form for tillatelse for å kunne brukes. For native-apper er det også mulig å la alle brukere som ikke er innlogget, få tilgang til noen publikasjoner gratis før innlogging kreves.

Navigere i applikasjonen

Når en bruker bruker applikasjonen, kan han eller hun normalt se startsiden som inneholder komponenter som viser publiserte publikasjoner. Offentlige publikasjoner kan åpnes og leses ved å velge publikasjonen. Men når brukeren prøver å åpne en beskyttet publikasjon, vil applikasjonen kreve at brukeren logger på(autentisering).

Etter pålogging avgjør Prenly om den forespurte publikasjonen kan leses av den aktuelle brukeren(autorisasjon). Hvis det er tilfelle, åpnes publikasjonen og er klar til å brukes. Hvis brukeren ikke har lesetilgang, vil brukeren bli varslet i appen. Det beskyttede innholdet vises ikke, men brukeren vil fortsatt være innlogget.

I noen tilfeller vil en applikasjon kreve at brukeren logger inn for å vise visse publikasjoner, spesielt når ikke alle publiserte publikasjoner kan ses av hvem som helst. For eksempel publikasjoner som er tilgjengelige via et abonnement, der andre publiserte publikasjoner som ikke er tilgjengelige via abonnement, skal være skjult.

Sette opp et API-miljø

Tillit til Prenly-forespørsler

Prenly sender en forhåndsdefinert hemmelig nøkkel i alle autentiserings- og autorisasjonsforespørsler. Nøkkelen er kun kjent av Prenly og systemet ditt. Du bør kontrollere at den oppgitte nøkkelen samsvarer med den forventede nøkkelen for alle API-forespørsler.

Du kan også åpne API-sluttpunktene dine kun for visse IP-adresser for ekstra sikkerhet. Kontakt oss for å få en oppdatert liste over IP-adresser som Prenly vil bruke i forespørsler hvis du ønsker denne ekstra sikkerheten.

Krypter trafikken

Vi anbefaler på det sterkeste å ikke tillate ukryptert HTTP-trafikk til API-et ditt. Bruk HTTPS!

Tillat en REST-aktig oppførsel

Foreløpig gjøres forespørsler med HTTP POST, men API-et bør ikke være begrenset til å bruke noen HTTP-metoder for fremtidig utvidelse av endepunkter. Se den gjeldende API-spesifikasjonen for mer informasjon, ettersom API-spesifikasjonen har det siste ordet når det gjelder eventuelle avvik fra denne dokumentasjonen.

I API-svar brukes HTTP-statuskoder til å informere Prenly om resultatet. Du må kunne svare med forskjellige HTTP-statuskoder, både for vellykkede forespørsler og for datafeil, kjøretidsfeil og uventede serverfeil.

For øyeblikket sendes forespørselsparametere som JSON i forespørselsteksten.

Alle endepunkter svarer for øyeblikket med JSON i svarteksten.

Bli kjent med OpenAPI 3.0

API-spesifikasjonen er dokumentert i en yaml-fil i henhold til OpenAPI 3.0-standarden (tidligere Swagger), som angir de tekniske aspektene og kravene til API-et og hvert endepunkt, inkludert alle dataobjekter for forespørsler og svar.

Autogenerert dokumentasjon finnes på https://apidoc.prenly.com/remote-api/, og spesifikasjonsfilen er tilgjengelig på https://apidoc.prenly.com/remote-api/spec/v1.3-specification.yaml.

Du kan gjerne ta en kopi av spesifikasjonsfilen og endre den til dine API-endepunkter (URL-er), ettersom den autogenererte spesifikasjonen inneholder generiske navngitte endepunkter som referanse. Med denne filen kan du enkelt bygge opp et testmiljø med ferdige verktøy som du finner på https://openapi.tools/ (se avsnittet "Testing").

Les mer om OpenAPI, inkludert spesifikasjonen, på https://www.openapis.org/.

Bygg endepunktet for autentisering

Se API-spesifikasjonen på https://apidoc.prenly.com/remote-api/ for endepunkt(er) for autentisering. Du kan velge endepunktets URL akkurat som du ønsker, men endepunktet må følge API-spesifikasjonen.

Forespørselsparametere

Forespørselsparametere er en del av forespørselsteksten som JSON og sendes av Prenly for hver forespørsel.

Svar ved suksess

En vellykket pålogging må svare med HTTP-statuskode 200 og et JSON-svar med den unike identifikatoren til brukeren som ble autentisert.

Svar på feil

Kjente feil som avhenger av de gitte forespørselsparameterne, må svare med en av HTTP-statuskodene 401, 403 eller 412 som angitt i API-dokumentasjonen. Disse feilene må inneholde et JSON-svar som følger Error-datamodellen, som du finner spesifisert nederst på https://apidoc.prenly.com/remote-api/.

Du kan velge å levere enten en Erroreller et tomt JSON-objekt. For øyeblikket er det bare "message"-egenskapen som kreves hvis du oppgir en Error. Det anbefales imidlertid at du også oppgir en "code"-egenskap.

Vi anbefaler på det sterkeste at du oppgir en "message"-egenskapsverdi på engelsk som representerer feilen på en eller annen måte. Hvis programvaren din har interne koder, er det hensiktsmessig å bruke dem her hvis det er behov for gjensidig feilsøking i fremtiden. Ikke legg inn personopplysninger som ikke er nødvendige, for eksempel personnavn! Unike ID-er er gode nok til feilsøking.

Denne informasjonen vises aldri til sluttbrukeren, men kan logges i Prenly for å forenkle feilsøking.

Bygg autorisasjonsendepunktet

Se API-spesifikasjonen på https://apidoc.prenly.com/remote-api/ for autorisasjonsendepunkt(er). Du kan velge endepunktets URL-adresse akkurat som du vil, men endepunktet må følge API-spesifikasjonen.

Forespørselsparametere

Forespørselsparametere er en del av forespørselsteksten som JSON og sendes av Prenly for hver forespørsel.

Svar ved suksess

En vellykket henting av brukerinformasjonen må svare med HTTP-statuskode 200 og et JSON-svar i henhold til UserSummary-datamodellen som beskrevet i spesifikasjonen.

Feltene i dette dataobjektet er forklart nederst på https://apidoc.prenly.com/remote-api/.

Hvilke egenskaper brukes til

Den eneste egenskapen som for øyeblikket ikke kan utelates, er "uid". De andre egenskapene kan utelates, men vi anbefaler at du angir en "productCodes"-egenskap for å få bedre kontroll over om Prenly skal gi lesetillatelse til publikasjoner eller ikke. For øyeblikket behandler Prenly en manglende "productCodes"-egenskap som en tom liste.

Svar ved feil

Kjente feil som avhenger av de gitte forespørselsparameterne, må svare med en av HTTP-statuskodene 403, 404 eller 412 som spesifisert i API-dokumentasjonen. Disse feilene må inkludere et JSON-svar som følger Error-datamodellen som beskrevet ovenfor.

Testing

Det er viktig å teste implementeringen av endepunktene for autentisering og autorisasjon. Se https://docs.google .com/document/d/1UxmvDs7_Z0GwGbwCHXr4Ojpb9HaZif1nJ8YRMmztzeo/ for mer informasjon om testing av endepunktene.

Hva skjer i Prenly?

Når brukeren logger på (autentisering + autorisasjon)

Når brukeren ber om å logge på og sender inn påloggingsskjemaet, sendes legitimasjonen til Prenlys autoritet (kryptert med SSL). Derfra håndterer autoriteten hvordan legitimasjonen skal brukes til å autentisere brukeren. For API-et for ekstern autoritet betyr dette at legitimasjonen sendes til det eksterne endepunktet i henhold til spesifikasjonen.

Prenly behandler API-svaret og håndterer både vellykkede og mislykkede autentiseringsforespørsler, der brukeren vil se en feilmelding avhengig av HTTP-statuskoden for feilsvaret. Se nedenfor for mer informasjon.

Hvis autentiseringen lykkes...

En vellykket pålogging vil utløse en separat autorisasjonsforespørsel til det eksterne API-endepunktet for autorisasjon for å hente brukerens informasjon, som bufres i Prenly i en begrenset periode.

Applikasjonen vil også gjenspeile at noen er innlogget, med navn eller e-post, basert på hvilke brukerdata som ble returnert i brukerinformasjonen.

Hvis påloggingsinformasjonen var feil...

Hvis forespørselen teknisk sett var vellykket, men påloggingsinformasjonen var feil, vil Prenly-autoriteten varsle applikasjonen, og brukeren vil få en melding om feil påloggingsinformasjon.

Hvis noe mislyktes...

Andre klient- eller serverbaserte feil, eller nettverksfeil, fanges opp og logges av Prenly. Applikasjonen får en passende feilmelding som presenteres for brukeren.

Når brukeren fortsetter å lese

Caching for gjentatte forespørsler

Caching av vellykkede autorisasjonssvardata (brukerens informasjon) eliminerer behovet for gjentatte forespørsler til det eksterne API-et for å hente brukerdata som sjelden endres. Hver Prenly-kunde kan velge utløpstid for hurtigbufferen, og vi anbefaler å sette den til 30 minutter, der den minste tillatte utløpstiden er 20 minutter.

Autorisering på nytt

Prenly bruker det hurtigbufrede resultatet for hver autorisasjonsforespørsel så lenge hurtigbufferen ikke har utløpt. Hvis hurtigbufferen har utløpt, vil Prenly utløse en ny autorisasjonsforespørsel til autorisasjonsendepunktet i det eksterne API-et. Dette oppdaterer brukerens data, for eksempel produkttilgjengelighet, i tillegg til de hurtigbufrede dataene.

Feilhåndtering

Hvis det oppstår en serverfeil (5xx HTTP-kode) når ny autorisasjon utløses, forlenges utløpstiden for hurtigbufferen med fem minutter. Prenly gjør dette for å unngå at brukere logges ut på grunn av midlertidige nettverks- eller serverfeil. Brukeren fortsetter å lese som om ingenting har skjedd, og etter fem minutter gjøres det et nytt forsøk på reautorisering. Denne oppførselen varer så lenge serverproblemet vedvarer. Prenly logger slike tekniske problemer og prøver å få tak i kunden hvis dette skjer.

Går live

Når du tror at API-et er klart til å tas i bruk (du er ferdig med å utvikle og teste implementeringen), kan du kontakte oss for å ta de siste stegene.

Prenly vil kreve informasjon fra deg for å sette opp implementeringen i Prenly. Informasjonen vil bli evaluert, og hvis alt er i orden, kan implementeringen din brukes i Prenly for de e-paper Prenly-applikasjonene du har valgt.

Sette opp Prenly

Før implementeringen din av det eksterne API-et kan brukes i Prenly, må du oppgi dette:

- Den hemmelige nøkkelen du har valgt for autentiserings- og autorisasjonsendepunktene

- API-endepunktene du har valgt

- En liste over produkter som skal gi lesetillatelser og som Prenly-tittelen skal gjelde for (bare Prenly-kjente produkter i produktkodelisten fra autorisasjonsendepunktet kan gi lesetillatelse)

- Ønsket utløpstid for hurtigbufferen

- En URL-adresse der en ny bruker kan opprette en konto

- En URL der en bruker kan slette kontoen sin

- En URL der en bruker kan tilbakestille passordet sitt (i tilfelle de har glemt passordet sitt)

- Vi anbefaler at du også oppgir en URL-adresse der en autorisert bruker uten forhåndskjente produktkoder kan aktivere et produkt (f.eks. kjøpe et abonnement)

- Brukerinformasjon (brukernavn og passord) for testbrukeren, der brukeren deles av Textalk, Apple og Google (hvis du har egne apper), der minst én produktkode må være aktiv så lenge det eksterne API-et brukes av Prenly-autoriteten til e-papiret ditt