Prenly Remote authority API

Tämän asiakirjan tarkoituksena on selittää:

1. ...miten Prenly-ekosysteemi mahdollistaa sen, että käyttäjän todennus ja valtuutus voidaan hoitaa kustantajan tai kolmannen osapuolen omistaman teknisen infrastruktuurin avulla.

2. ...miten tekninen toteutus voidaan tehdä rakentamalla vaatimaton lepo-API, joka noudattaa "Prenly Remote authority API" -eritelmää.

Ota yhteyttä osoitteeseen

Ota meihin yhteyttä sähköpostitse osoitteeseen hello@prenly.com tai puhelimitse numeroon +46-31-3884740, jos sinulla on tätä APIa koskevia kysymyksiä tai ongelmia.

Määritelmät

Tunnistaminen on prosessi, jossa jonkun tai jonkin asian henkilöllisyys tarkistetaan, eli tarkistetaan, onko henkilö se, joka hän sanoo olevansa, ennen kuin hänelle myönnetään pääsy suojattuihin tietoihin. Tavallisesti tämä tapahtuu antamalla joitakin tunnistetietoja, kuten käyttäjätunnus ja salasana. Koska tunnistetiedot vastaavat tallennettua tietuetta, käyttäjä "todennetaan" (autentikoidaan) soveltamalla periaatetta, jonka mukaan käyttäjä tiesi jotain, minkä vain "oikea" käyttäjä voi tietää.

Valtuutus on prosessi, jossa päätetään, mihin resursseihin käyttäjällä on pääsy, eli mihin tietoihin käyttäjällä on lupa päästä, eli mitä käyttäjä saa tehdä ja mitä ei. Prenlyssä tämä tarkoittaa sen määrittämistä, mitä julkaisuja käyttäjä voi nähdä ja avata luettavaksi.

API(Application Program Interface) on joukko rutiineja, protokollia ja työkaluja, joilla hoidetaan eri järjestelmien tai niiden osien välistä vuorovaikutusta ja määrätään järjestelmien välinen viestintä.

Prenlyssä viranomainen on tekninen toteutus, joka päättää, miten Prenly-sovellus käsittelee todennusta ja valtuutusta Prenlyn taustajärjestelmässä.

Johdanto

Prenly Remote authority API esittelee mahdollisuuden korvata Prenlyn auktorisointi- ja/tai todennuskäsittely toteuttamalla API-päätepisteet, jotka noudattavat API-määrittelyä, jonka avulla Prenly-asiakas voi todentaa ja auktorisoida järjestelmänsä, vaatimustensa ja tarpeidensa mukaan.

Pohjimmiltaan tämä mahdollistaa sen, että Prenly-sovelluksen viranomainen voi valtuuttaa ja/tai todentaa käyttäjät, kun he ovat tekemisissä Prenly-sovelluksen kanssa, eli kun he lukevat julkaisuja sovelluksessa, Prenly Remote authority API:n välityksellä.

Prenly-viranomainen välittää todennus- ja valtuutuspyyntöjä käyttäjien ja Prenlyn välillä silloin, kun käyttäjien ja API-toteutuksen välillä ei sallita suoraa viestintää. Sen sijaan API-toteutus ilmoittaa Prenly-viranomaiselle, miten käyttäjien todennus- ja valtuutuspyyntöjen perusteella toimitaan.

API:n toteuttaminen

Ymmärrä, miten käyttäjä käyttää Prenly-sovellusta.

Prenly-sovellukset

Prenly palvelee loppukäyttäjää sovelluksilla, joita käytetään pääasiassa julkaisujen ja artikkelien lukemiseen. Sovellus on joko natiivi mobiilisovellus Android- tai iOS-alustalla tai responsiivinen web-pohjainen e-lukijamme. Nämä kaksi sovellustyyppiä tarjoavat samanlaisen käyttökokemuksen.

Sovellus voi sisältää julkaistuja julkaisuja, jotka ovat julkisia kaikille, sekä suojattua sisältöä, jonka kuluttamiseen tarvitaan jonkinlainen lupa. Natiivisovelluksissa on myös mahdollista antaa kirjautumattomien käyttäjien käyttää joitakin julkaisuja ilmaiseksi ennen kuin kirjautuminen vaaditaan.

Navigointi sovelluksessa

Käyttäjä näkee sovellusta käyttäessään yleensä aloitussivun, joka sisältää julkaistuja julkaisuja näyttäviä komponentteja. Julkiset julkaisut voidaan avata ja lukea valitsemalla julkaisu. Mutta kun käyttäjä yrittää avata suojatun julkaisun, sovellus vaatii käyttäjää kirjautumaan sisään(todennus).

Kirjautumisen jälkeen Prenly päättää, onko pyydetty julkaisu kyseisen käyttäjän luettavissa(valtuutus). Jos vastaus on myönteinen, julkaisu avataan, ja se on valmis käytettäväksi. Jos käyttäjällä ei ole lukuoikeutta, käyttäjälle ilmoitetaan asiasta sovelluksessa. Suojattua sisältöä ei näytetä, mutta käyttäjä on silti kirjautunut sisään.

Joissakin tapauksissa sovellus vaatii käyttäjältä kirjautumista tiettyjen julkaisujen näyttämiseksi, varsinkin kun kaikki julkaistut julkaisut eivät ole kenen tahansa nähtävissä. Esimerkiksi julkaisut, joihin on pääsy tilauksen kautta, kun muut julkaistut julkaisut, joihin ei ole tehty tilausta, on piilotettava.

API-ympäristön määrittäminen

Luottamus Prenly-pyyntöihin

Prenly lähettää ennalta määritellyn salaisen avaimen kaikissa todennus- ja valtuutuspyynnöissä. Avain on vain Prenlyn ja sinun järjestelmäsi tiedossa. Sinun tulisi tarkistaa, että toimitettu avain vastaa odotettua avainta kaikissa API-pyynnöissä.

Voit myös avata API-päätepisteesi vain tietyille IP-osoitteille lisäturvallisuuden vuoksi. Ota meihin yhteyttä saadaksesi ajantasaisen luettelon IP-osoitteista, joita Prenly käyttää pyynnöissä, jos haluat tämän lisäturvan.

Salaa liikenne

Suosittelemme voimakkaasti salaamattoman HTTP-liikenteen kieltämistä API-rajapintaasi. Käytä HTTPS:ää!

Salli REST-käyttäytyminen

Prenly-pyynnöt tehdään tällä hetkellä HTTP POST -menetelmällä, mutta API:ta ei pitäisi rajoittaa käyttämään mitään HTTP-menetelmiä tulevaa päätepisteen laajentamista varten. Katso lisätietoja nykyisestä API-määrittelystä, sillä API-määrittelyllä on lopullinen sananvalta mahdollisissa ristiriidoissa tämän dokumentaation kanssa.

API-vastauksissa käytetään HTTP-tilakoodeja, joilla Prenlylle ilmoitetaan tuloksesta. Sinun on pystyttävä vastaamaan eri HTTP-tilakoodeilla onnistuneista pyynnöistä sekä tietovirheistä, suoritusaikavirheistä ja odottamattomista palvelimen virheistä.

Pyyntöparametrit välitetään tällä hetkellä JSON-muodossa pyynnön rungossa.

Kaikki päätepisteet vastaavat tällä hetkellä JSON-muodossa vastausrungossa.

Tutustu OpenAPI 3.0:aan.

API-määrittely on dokumentoitu OpenAPI 3.0 -standardin (entinen Swagger) mukaisessa yaml-tiedostossa, jossa ilmoitetaan API:n ja kunkin päätepisteen tekniset näkökohdat ja vaatimukset, mukaan lukien kaikki pyyntö- ja vastausdatakohteet.

Automaattisesti luotu dokumentaatio löytyy osoitteesta https://apidoc.prenly.com/remote-api/ ja määrittelytiedosto osoitteesta https://apidoc.prenly.com/remote-api/spec/v1.3-specification.yaml.

Voit vapaasti kopioida määrittelytiedoston ja muokata sitä API-päätepisteidesi (URL-osoitteiden) mukaiseksi, sillä automaattisesti luotu määrittely sisältää viitteenä yleisiä nimettyjä päätepisteitä. Tämän tiedoston avulla voit helposti rakentaa testausympäristön valmiiden työkalujen avulla, jotka löytyvät osoitteesta https://openapi.tools/ (katso kohta "Testaus").

Lue lisää OpenAPI:stä ja sen määrittelystä osoitteessa https://www.openapis.org/.

Autentikoinnin päätepisteen rakentaminen

Katso API-spesifikaatio osoitteessa https://apidoc.prenly.com/remote-api/ todennuspäätepisteen (-pisteiden) osalta. Voit valita päätepisteen URL-osoitteen juuri haluamallasi tavalla; päätepisteen on kuitenkin oltava API-määrittelyn mukainen.

Pyyntöparametrit

Pyyntöparametrit ovat osa pyynnön runkoa JSON-muodossa, ja Prenly lähettää ne jokaisen pyynnön yhteydessä.

Vastaus onnistumisen yhteydessä

Onnistuneeseen kirjautumiseen on vastattava HTTP-tilakoodilla 200 ja JSON-vastauksella, jossa on todennetun käyttäjän yksilöllinen tunniste.

Vastaus epäonnistumisen yhteydessä

Tunnettuihin virheisiin, jotka riippuvat annetuista pyyntöparametreista, on vastattava jollakin HTTP-tilakoodilla 401, 403 tai 412 API-asiakirjoissa määritellyllä tavalla. Näihin virheisiin on sisällytettävä JSON-vastaus, joka noudattaa Error-tietomallia, joka on määritetty osoitteessa https://apidoc.prenly.com/remote-api/.

Voit valita joko Error- tai tyhjän JSON-olion. Tällä hetkellä vain "message"-ominaisuus vaaditaan, jos annetaan Error. On kuitenkin suositeltavaa antaa myös "code"-ominaisuus.

Suosittelemme, että annat englanninkielisen "message"-ominaisuuden arvon, joka kuvaa virhettä jollakin tavalla. Jos ohjelmistossasi on jonkinlaisia sisäisiä koodeja, niitä kannattaa käyttää tässä, jos tulevaisuudessa tarvitaan keskinäistä vianmääritystä. Älä sisällä henkilötietoja, joita ei tarvita, kuten henkilönnimiä! Yksilölliset tunnukset riittävät vianmääritykseen.

Näitä tietoja ei koskaan näytetä loppukäyttäjälle, mutta ne voidaan kirjata Prenlyyn vianmäärityksen helpottamiseksi.

Rakenna valtuutuksen päätepiste

Katso valtuutuspäätepiste(t) API-määrittelystä osoitteessa https://apidoc.prenly.com/remote-api/. Voit valita päätepisteen URL-osoitteen täsmälleen haluamallasi tavalla; päätepisteen on kuitenkin noudatettava API-määrittelyä.

Pyyntöparametrit

Pyyntöparametrit ovat osa pyyntörunkoa JSON-muodossa, ja Prenly lähettää ne jokaisen pyynnön yhteydessä.

Vastaus onnistumisen yhteydessä

Onnistuneeseen käyttäjätietojen hakuun on vastattava HTTP-tilakoodilla 200 ja JSON-vastauksella, joka on eritelmässä kuvatun UserSummary-tietomallin mukainen.

Tämän tieto-objektin kentät selitetään https://apidoc.prenly.com/remote-api/-sivun alaosassa .

Mitä ominaisuuksia käytetään

Ainoa ominaisuus, jota ei tällä hetkellä voi jättää tyhjäksi, on "uid". Muut ominaisuudet voidaan jättää pois, mutta suosittelemme kuitenkin, että määrittelet "productCodes"-ominaisuuden, jotta voit hallita paremmin, pitäisikö Prenlyn antaa tai olla antamatta lukuoikeuksia julkaisuille. Tällä hetkellä Prenly käsittelee puuttuvaa "productCodes"-ominaisuutta tyhjänä luettelona.

Vastaus epäonnistumiseen

Tunnettuihin virheisiin, jotka riippuvat annetuista pyyntöparametreista, on vastattava jollakin HTTP-tilakoodilla 403, 404 tai 412 API-asiakirjoissa määritellyllä tavalla. Näiden virheiden on sisällettävä JSON-vastaus, joka noudattaa edellä kuvattua Error-tietomallia.

Testaus

On tärkeää testata todennus- ja valtuutuspisteiden toteutusta. Lisätietoja päätepisteiden testaamisesta on osoitteessa https://docs.google.com/document/d/1UxmvDs7_Z0GwGbwCHXr4Ojpb9HaZif1nJ8YRMmztzeo/.

Mitä tapahtuu Prenlyssä?

Kun käyttäjä kirjautuu sisään (todennus + valtuutus).

Kun käyttäjä pyytää kirjautumista ja lähettää kirjautumislomakkeen, tunnistetiedot lähetetään Prenlyn auktoriteetille (SSL:llä salattuna). Sieltä käsin viranomainen huolehtii siitä, miten näitä tunnistetietoja käytetään käyttäjän todentamiseen. Etäviranomaisen API:n osalta tämä tarkoittaa, että valtuustiedot lähetetään etäpäätteeseen eritelmän mukaisesti.

Prenly käsittelee API-vastauksen ja käsittelee sekä onnistuneet että epäonnistuneet todennuspyynnöt, jolloin käyttäjä näkee virheilmoituksen vastauksen HTTP-tilakoodista riippuen. Katso lisätietoja jäljempänä.

Jos todennus onnistui...

Onnistunut sisäänkirjautuminen käynnistää erillisen valtuutuspyynnön valtuutuksen etä-API-päätepisteeseen käyttäjän tietojen noutamiseksi, jotka tallennetaan välimuistiin Prenlyyn rajoitetuksi ajaksi.

Sovellus ilmoittaa myös, että joku on kirjautunut sisään, nimellä tai sähköpostilla sen perusteella, mitä käyttäjätietoja käyttäjätiedoissa palautettiin.

Jos tunnistetiedot olivat väärät...

Jos pyyntö onnistui teknisesti, mutta tunnistetiedot olivat väärät, Prenly-viranomainen ilmoittaa asiasta sovellukselle ja käyttäjälle annetaan viesti vääristä tunnistetiedoista.

Jos jokin epäonnistui...

Prenly havaitsee ja kirjaa muut asiakas- tai palvelinpohjaiset virheet tai verkkovirheet. Sovellukselle annetaan käyttäjälle sopiva virheilmoitus.

Kun käyttäjä jatkaa lukemista

Välimuistitallennus toistuvia pyyntöjä varten

Onnistuneen valtuutusvastauksen tietojen (käyttäjän tietojen) välimuistiin tallentaminen poistaa tarpeen tehdä toistuvia pyyntöjä etä-API:lle harvoin muuttuvien käyttäjätietojen noutamiseksi. Kukin Prenly-asiakas voi valita välimuistin vanhentumisajan, suosittelemme asettamaan 30 minuuttia, jolloin pienin sallittu välimuistin vanhentumisaika on 20 minuuttia.

Uudelleenvaltuutus

Prenly käyttää välimuistissa olevaa tulosta jokaisessa valtuutuspyynnössä niin kauan kuin välimuisti ei ole vanhentunut. Jos välimuisti on vanhentunut, Prenly käynnistää uuden valtuutuspyynnön etä-API:n valtuutuspäätepisteeseen. Tämä päivittää käyttäjän tiedot, kuten tuotteen saatavuuden, sekä välimuistissa olevat tiedot.

Epäonnistumisen käsittely

Jos palvelinvirhe (5xx HTTP-koodi) tapahtuu, kun valtuutuksen uudelleenlataus käynnistetään, välimuistin vanhentumisaikaa pidennetään viidellä minuutilla. Prenly tekee näin, jotta käyttäjät eivät kirjautuisi ulos tilapäisten verkko- tai palvelinvirheiden vuoksi; käyttäjä jatkaa lukemista ikään kuin mitään ei tapahtuisi, ja viiden minuutin kuluttua tehdään uusi uudelleenlupausyritys. Tämä toiminta jatkuu niin kauan kuin palvelinongelma jatkuu. Prenly kirjaa tällaiset tekniset ongelmat ja yrittää tavoittaa asiakkaan, jos näin tapahtuu.

Käyttöönotto

Kun olet sitä mieltä, että API on valmis siirtymään käyttökuntoon (olet saanut toteutuksen kehittämisen ja testaamisen valmiiksi), ota meihin yhteyttä viimeisten vaiheiden toteuttamiseksi.

Prenly tarvitsee sinulta tietoja, jotta voit perustaa toteutuksesi Prenlyyn. Tiedot arvioidaan, ja jos kaikki on kunnossa, toteutustasi voidaan käyttää Prenlyssä valitsemissasi e-paperin Prenly-sovelluksissa.

Prenlyn käyttöönotto

Ennen kuin etä-API:n toteutustasi voidaan käyttää Prenlyssä, sinun on annettava seuraavat tiedot:

- Valitsemasi salainen avain todennus- ja valtuutuspäätteille.

- valitsemasi API-päätepisteet

- Luettelo tuotteista, joille pitäisi myöntää lukuoikeudet ja joiden Prenly-otsikko (vain valtuutuspäätepisteen tuotekoodiluettelossa olevat Prenly-tunnetut tuotteet voivat myöntää lukuoikeudet).

- haluamasi välimuistin vanhentumisaika

- URL-osoite, jossa uusi käyttäjä voi luoda tilin.

- URL-osoite, jossa käyttäjä voi poistaa tilinsä

- URL-osoite, jossa käyttäjä voi palauttaa salasanansa (jos hän on unohtanut salasanansa).

- Suosittelemme, että annat myös URL-osoitteen, jossa valtuutettu käyttäjä, jolla ei ole mitään ennalta tunnettuja tuotekoodeja, voi aktivoida tuotteen (esim. ostaa tilauksen).

- Testikäyttäjän käyttäjätunnukset (käyttäjätunnus ja salasana), joissa käyttäjä on jaettu Textalkin, Applen ja Googlen kanssa (jos sinulla on natiivisovelluksia), joissa vähintään yhden tuotekoodin on pysyttävä aktiivisena niin kauan kuin sähköisen lehden Prenly-valtuutettu käyttää etä-API:tä.