Prenly Remote Authority API

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

1. ...miten Prenly-ekosysteemin avulla voidaan hallita käyttäjien todentamista ja valtuuttamista käyttämällä kustantajan tai kolmannen osapuolen omistamaa teknistä infrastruktuuria.

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

Yhteystiedot

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

Todentaminen on prosessi, jossa jonkun tai jonkin henkilön henkilöllisyys tarkistetaan, eli varmistetaan, että henkilö on se, joka hän väittää olevansa, ennen kuin pääsy suojattuihin tietoihin myönnetään. Tavallisesti tämä tapahtuu antamalla tietyt tunnistetiedot, 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 jotakin sellaista, jonka vain "oikea" käyttäjä voi tietää.

Valtuuttaminen on prosessi, jossa määritetään, mihin resursseihin käyttäjällä on pääsy, eli mihin tietoihin käyttäjällä on oikeus päästä ja 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 hallitaan eri järjestelmien tai järjestelmien osien välistä vuorovaikutusta ja määrätään järjestelmien välinen viestintä.

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

Johdanto

Prenly Remote Authority API tarjoaa mahdollisuuden korvata Prenlyn valtuuttamisen ja/tai todennuksen hallinta toteuttamalla API-päätepisteitä, jotka noudattavat API-määrittelyä ja joiden avulla Prenly-asiakas voi todentaa ja valtuuttaa järjestelmänsä, vaatimustensa ja tarpeidensa mukaisesti.

Periaatteessa tämä mahdollistaa sen, että Prenly-sovellusviranomainen voi valtuuttaa ja/tai todentaa käyttäjät, kun he ovat vuorovaikutuksessa 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äjän 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 tarjoaa loppukäyttäjälle sovelluksia, joita käytetään pääasiassa julkaisujen ja artikkelien lukemiseen. Sovellus on joko natiivi mobiilisovellus Android- tai iOS-alustalla tai responsiivinen verkkopohjainen 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 käyttäminen edellyttää jonkinlaista lupaa. Natiivisovelluksissa on myös mahdollista antaa kaikille kirjautumattomille käyttäjille mahdollisuus käyttää tiettyjä julkaisuja ilmaiseksi ennen kuin kirjautuminen vaaditaan.

Navigointi sovelluksessa

Kun käyttäjä käyttää sovellusta, hän näkee yleensä etusivun, joka sisältää julkaistuja julkaisuja näyttäviä komponentteja. Julkiset julkaisut voidaan avata ja lukea valitsemalla julkaisu. Kun käyttäjä kuitenkin yrittää avata suojatun julkaisun, sovellus vaatii käyttäjää kirjautumaan sisään(todennus).

Kirjautumisen jälkeen Prenly määrittää, onko pyydetty julkaisu kyseisen käyttäjän luettavissa(valtuutus). Jos näin on, julkaisu avataan ja on valmis käytettäväksi. Jos käyttäjällä ei ole lukuoikeutta, käyttäjälle ilmoitetaan siitä 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 tarkastelemiseksi, erityisesti silloin, kun kaikki julkaistut julkaisut eivät ole kenen tahansa tarkasteltavissa. Esimerkiksi tilauksen kautta saatavilla olevat julkaisut, joissa muut julkaistut julkaisut, joita ei ole tilattu, pitäisi piilottaa.

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

Luottamus ennakkotietopyyntö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 on tarkistettava, että toimitettu avain vastaa odotettua avainta kaikissa API-pyynnöissä.

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

Salaa liikenne

Suosittelemme voimakkaasti, ettet salli salaamatonta HTTP-liikennettä API-sovellukseesi. Käytä HTTPS:ää!

Salli REST-tyyppinen 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 tämän dokumentaation poikkeamien suhteen.

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

Pyyntöparametrit lähetetää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 yaml-tiedostossa OpenAPI 3.0 -standardin (entinen Swagger) mukaisesti, ja siinä määritellään API:n ja kunkin päätepisteen tekniset näkökohdat ja vaatimukset, mukaan lukien kaikki pyynnön ja vastauksen dataobjektit.

Automaattisesti luotu dokumentaatio on saatavilla osoitteessa https://apidoc.prenly.com/remote-api/ ja määrittelytiedosto osoitteessa https://apidoc.prenly.com/remote-api/spec/v1.3-specification.yaml.

Voit vapaasti kopioida määrittelytiedoston ja muokata sitä API-päätepisteidesi (URL-osoitteiden) mukaan, sillä automaattisesti luotu määrittely sisältää yleisiä nimettyjä päätepisteitä viitteeksi. Tämän tiedoston avulla voit helposti rakentaa testiympäristön valmiiden työkalujen avulla, jotka ovat saatavilla osoitteessa 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äätteiden osalta. Voit valita päätepisteen URL-osoitteen haluamallasi tavalla, mutta päätepisteen on oltava API-määrittelyn mukainen.

Pyynnön parametrit

Pyyntöparametrit ovat osa pyyntöä 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 tunnistautuneen käyttäjän yksilöllinen tunniste.

Vastaus epäonnistumisen yhteydessä

Tunnettuihin epäonnistumisiin, jotka johtuvat määritetyistä pyyntöparametreista, on vastattava jollakin HTTP-tilakoodilla 401, 403 tai 412 API-asiakirjoissa määritellyllä tavalla. Näiden virheiden on sisällettävä JSON-vastaus, joka noudattaa Error-tietomallia, joka löytyy osoitteesta https://apidoc.prenly.com/remote-api/.

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

Suosittelemme, että asetat "message"-ominaisuudelle englanninkielisen arvon, joka kuvaa virhettä jollakin tavalla. Jos ohjelmistossasi on jonkinlaisia sisäisiä koodeja, on suositeltavaa käyttää niitä tässä, jos tulevaisuudessa tarvitaan keskinäistä virheenkorjausta. Älä sisällytä henkilökohtaisia tietoja, joita ei tarvita, esim. henkilökohtaisia nimiä! 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.

Päätepisteen rakentaminen valtuutusta varten

Katso API-määrittely osoitteessa https://apidoc.prenly.com/remote-api/ valtuutuspäätteiden osalta. Voit valita päätepisteen URL-osoitteen haluamallasi tavalla, mutta päätepisteen on oltava API-määrittelyn mukainen.

Pyynnön parametrit

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

Vastaus onnistumisen yhteydessä

Onnistuneeseen käyttäjätietojen hakemiseen 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 "productCodes"-ominaisuuden asettamista, jotta voidaan paremmin valvoa, antaako Prenly julkaisuille lukuoikeuden vai ei. Tällä hetkellä Prenly käsittelee puuttuvaa "productCodes"-ominaisuutta tyhjänä luettelona.

Vastaus epäonnistumisen sattuessa

Määritetyistä pyyntöparametreista johtuviin tunnettuihin virheisiin 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. Katso https://docs.google .com/document/d/1UxmvDs7_Z0GwGbwCHXr4Ojpb9HaZif1nJ8YRMmztzeo/ lisätietoja päätepisteiden testaamisesta.

Mitä Prenlyssä tapahtuu?

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

Kun käyttäjä pyytää kirjautumista ja lähettää kirjautumislomakkeen, kirjautumistiedot lähetetään Prenly-viranomaiselle (SSL-salauksella salattuna). Sieltä viranomainen hallinnoi, 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 määritettyyn etäyhteyspisteeseen.

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

Jos todennus onnistui...

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

Sovellus näyttää 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 kirjautumistiedot olivat virheelliset...

Jos pyyntö onnistui teknisesti, mutta kirjautumistiedot olivat virheelliset, Prenly-viranomainen ilmoittaa asiasta sovellukselle ja käyttäjälle esitetään viesti virheellisistä kirjautumistiedoista.

Jos jokin epäonnistui...

Prenly havaitsee ja kirjaa muut asiakas- tai palvelinpohjaiset virheet tai verkkovirheet. Sovellus saa asianmukaisen virheilmoituksen, joka esitetään käyttäjälle.

Kun käyttäjä jatkaa lukemista

Välimuistitallennus toistuvia pyyntöjä varten

Onnistuneen valtuutuksen vastaustietojen (käyttäjän tietojen) välimuistiin tallentaminen poistaa tarpeen tehdä toistuvia pyyntöjä etä-API:lle harvoin muuttuvien käyttäjätietojen hakemista varten. Kukin Prenly-asiakas voi valita välimuistin vanhentumisajan, suosittelemme 30 minuutin asetusta, ja välimuistin pienin sallittu 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.

Virheiden käsittely

Jos palvelinvirhe (5xx HTTP-koodi) ilmenee, kun valtuutuksen uusiminen käynnistetään, välimuistin voimassaoloaikaa 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 olisi tapahtunut, ja viiden minuutin kuluttua tehdään uusi uudelleenlupausyritys. Tämä toimintatapa 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 käyttöönotettavaksi (olet saanut toteutuksen kehittämisen ja testauksen valmiiksi), ota meihin yhteyttä viimeisten vaiheiden toteuttamiseksi.

Prenly tarvitsee sinulta tietoja, jotta voit määrittää toteutuksesi Prenlyssä. Tiedot arvioidaan, ja jos kaikki on kunnossa, toteutustasi voidaan käyttää Prenlyssä valitsemissasi Prenlyn e-paperisovelluksissa.

Prenlyn konfigurointi

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

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

- valitsemasi API-päätepisteet

- Luettelo tuotteista, joille myönnetään lukuoikeus ja joiden Prenly-otsikko (vain valtuutuspäätepisteen tuotekoodiluettelossa olevat Prenly-tunnetut tuotteet voivat myöntää lukuoikeuden).

- haluamasi välimuistin vanhentumisaika

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

- URL-osoite, josta 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 aiemmin tunnettuja tuotekoodeja, voi aktivoida tuotteen (esim. ostaa tilauksen).

- Testikäyttäjän käyttäjätunnukset (käyttäjätunnus ja salasana), kun käyttäjä on jaettu Textalkin, Applen ja Googlen kanssa (jos käytössäsi on natiivisovelluksia), kun vähintään yhden tuotekoodin on pysyttävä aktiivisena niin kauan kuin Prenly-viranomainen käyttää etäkäyttöliittymää sähköisen lehden API:ta.