API for ekstern autoritet

Formålet med dette dokumentet er å forklare:

1. ...hvordan Prenly-økosystemet gjør det mulig å administrere autentisering og autorisering av brukere 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

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

Definisjoner

Autentisering er prosessen med å verifisere identiteten til noen eller noe, dvs. om de er den de utgir seg for å være, før det gis tilgang til beskyttede data. Normalt gjøres dette ved å oppgi visse legitimasjonsopplysninger, 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 med å bestemme hvilke ressurser en bruker har tilgang til, dvs. hvilke data brukeren har tilgang til, og 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 styrer samspillet mellom ulike systemer eller deler av systemer, og som dikterer kommunikasjonen mellom systemene.

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

Introduksjon til

Prenly Remote Authority API gir muligheten til å erstatte Prenlys administrasjon av autorisasjon og/eller autentisering ved å implementere API-sluttpunkter som følger en API-spesifikasjon, slik at en Prenly-kunde kan autentisere og autorisere basert på sitt system, sine krav og behov.

I utgangspunktet gjør dette det mulig for Prenly-applikasjonsmyndigheten å 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 bruker og API-implementering. I stedet informerer API-implementeringen Prenly-autoriteten om hvordan den skal reagere på brukernes autentiserings- og autorisasjonsforespørsler.

Implementering av API-et ditt

Forstå hvordan brukeren bruker Prenly-applikasjonen

Prenly-applikasjoner

Prenly tilbyr sluttbrukeren 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 autorisasjon for å kunne konsumeres. For native-apper er det også mulig å la alle brukere som ikke er innlogget, få gratis tilgang til visse publikasjoner før innlogging kreves.

Navigering 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. Når brukeren prøver å åpne en beskyttet publikasjon, vil applikasjonen imidlertid kreve at brukeren logger inn(autentisering).

Etter innlogging avgjør Prenly om den forespurte publikasjonen kan leses av brukeren(autorisasjon). Hvis dette er tilfelle, åpnes publikasjonen og er klar til bruk. Hvis brukeren ikke har lesetilgang, blir brukeren 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 å se visse publikasjoner, spesielt når ikke alle publiserte publikasjoner kan ses av alle. For eksempel publikasjoner som er tilgjengelige via et abonnement, der andre publiserte publikasjoner som det ikke abonneres på, skal være skjult.

Konfigurere et API-miljø

Tillit for Prenly-forespørsler

Prenly sender en forhåndsdefinert hemmelig nøkkel i alle autentiserings- og autorisasjonsforespørsler. Nøkkelen er bare 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 for bare 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 at du ikke tillater ukryptert HTTP-trafikk til API-et ditt. Bruk HTTPS!

Tillat en REST-lignende oppførsel

Foreløpige forespørsler gjøres for øyeblikket ved hjelp av 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 ulike HTTP-statuskoder, både for vellykkede forespørsler og for datafeil, kjøretidsfeil og uventede serverfeil.

Forespørselsparametere sendes for øyeblikket som JSON i forespørselsteksten.

Alle endepunkter svarer for øyeblikket med JSON i svarteksten.

Gjør deg kjent med OpenAPI 3.0

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

Autogenerert dokumentasjon er tilgjengelig 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 lage 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 et testmiljø med ferdige verktøy som er tilgjengelige på https://openapi.tools/ (se avsnittet "Testing").

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

Bygge endepunktet for autentisering

Se API-spesifikasjonen på https://apidoc.prenly.com/remote-api/ for endepunktene for autentisering. Du kan velge endepunktets URL som du vil, men endepunktet må følge API-spesifikasjonen.

Forespørselsparametere

Forespørselsparametere er en del av forespørselen 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 på grunn av de angitte forespørselsparameterne må besvares 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 nederst på https://apidoc.prenly.com/remote-api/.

Du kan velge å oppgi 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 angir en verdi for "message"-egenskapen på engelsk som representerer feilen på en eller annen måte. Hvis programvaren din har noen form for interne koder, er det lurt å bruke dem her i tilfelle det blir behov for gjensidig feilsøking i fremtiden. Ikke legg inn personopplysninger som ikke er nødvendige, f.eks. personnavn! Unike ID-er er godt nok for feilsøking.

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

Bygge endepunkt for autorisasjon

Se API-spesifikasjonen på https://apidoc.prenly.com/remote-api/ for autorisasjonsendepunktene. Du kan velge sluttpunktets URL som du vil, men sluttpunktet må følge API-spesifikasjonen.

Forespørselsparametere

Forespørselsparametere er en del av forespørselen 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 er beskrevet i spesifikasjonen.

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

Hva egenskapene brukes til

Den eneste egenskapen som for øyeblikket ikke kan stå tom, 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 lesetilgang til publikasjoner eller ikke. For øyeblikket behandler Prenly en manglende "productCodes"-egenskap som en tom liste.

Svar i tilfelle feil

Kjente feil som skyldes de angitte forespørselsparameterne, må besvares med en av HTTP-statuskodene 403, 404 eller 412 som angitt i API-dokumentasjonen. Disse feilene må inneholde et JSON-svar som følger Error-datamodellen som beskrevet ovenfor.

Testing

Det er viktig å teste implementasjonen for endepunktene for autentisering og autorisasjon. Se https://docs.google .com/document/d/1UxmvDs7_Z0GwGbwCHXr4Ojpb9HaZif1nJ8YRMmztzeo/ for mer informasjon om hvordan du tester endepunktene dine.

Hva skjer i Prenly?

Når brukeren logger inn (autentisering + autorisasjon)

Når brukeren ber om å logge på og sender inn påloggingsskjemaet, sendes påloggingsopplysningene til Prenly-autoriteten (kryptert med SSL). Derfra administrerer autoriteten hvordan disse opplysningene skal brukes til å autentisere brukeren. For API-et for ekstern autoritet betyr dette at legitimasjonen sendes til det eksterne tilkoblingspunktet som angitt.

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

Hvis autentiseringen var vellykket...

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

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

Hvis påloggingsopplysningene 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, vil bli fanget opp og logget av Prenly. Programmet mottar en passende feilmelding som presenteres for brukeren.

Mens brukeren fortsetter å lese

Caching for gjentatte forespørsler

Caching av svardataene fra en vellykket autorisasjon (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øpstiden for hurtigbufferen, og vi anbefaler at den settes til 30 minutter, med en minste tillatt utløpstid på 20 minutter.

Ny autorisasjon

Prenly bruker det hurtigbufrede resultatet for hver autorisasjonsforespørsel så lenge hurtigbufferen ikke er utløpt. Hvis hurtigbufferen er 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.

Håndtering av feil

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å ny autorisasjon. Denne oppførselen varer så lenge serverproblemet vedvarer. Prenly logger slike tekniske problemer og forsøker å få tak i kunden hvis dette skjer.

Gå live

Når du mener 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 å konfigurere implementeringen i Prenly. Informasjonen vil bli evaluert, og hvis alt er i orden, kan implementeringen din brukes i Prenly for de utvalgte Prenly e-papirapplikasjonene dine.

Konfigurere Prenly

Før den eksterne API-implementeringen din kan brukes i Prenly, må du oppgi følgende:

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

- API-endepunktene du har valgt

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

- Din foretrukne utløpstid for hurtigbufferen

- En URL 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 (hvis de har glemt passordet sitt)

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

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