Prenly Remote Authority API

Lo scopo di questo documento è quello di spiegare

1. ...come l'ecosistema Prenly permetta di gestire l'autenticazione e l'autorizzazione degli utenti da un'infrastruttura tecnica di proprietà dell'editore o di una terza parte.

2. ...come si può realizzare un'implementazione tecnica costruendo una modesta API a riposo che segua le specifiche "Prenly Remote authority API".

Contatto

Per domande o problemi relativi a questa API, si prega di contattarci via e-mail all'indirizzo hello@prenly.com o telefonicamente al numero +46-31-3884740.

Definizioni

L'autenticazione è il processo di verifica dell'identità di una persona o di qualcosa, ossia se è chi dice di essere, prima di concedere l'accesso a dati protetti. Normalmente viene effettuata fornendo alcune credenziali, come un nome utente e una password. Se le credenziali corrispondono a un record memorizzato, l'utente viene "verificato" (autenticato) applicando il principio che l'utente conosce qualcosa che solo l'utente "reale" può conoscere.

L'autorizzazione è il processo di decisione delle risorse a cui l'utente ha accesso, cioè dei dati a cui l'utente ha il permesso di accedere, cioè di ciò che l'utente può o non può fare. Per Prenly si tratta di determinare quali pubblicazioni l'utente può vedere e aprire per leggerle.

Un'API(Application Program Interface) è un insieme di routine, protocolli e strumenti per gestire l'interazione tra diversi sistemi o parti di sistemi, stabilendo la comunicazione tra sistemi.

In Prenly, un'autorità è un'implementazione tecnica che decide come l'autenticazione e l'autorizzazione vengono gestite da un'applicazione Prenly all'interno del backend di Prenly.

Introduzione

L'API Prenly Remote authority introduce la possibilità di sostituire la gestione dell'autorizzazione e/o dell'autenticazione di Prenly implementando endpoint API che seguono una specifica API, che consente al cliente Prenly di autenticare e autorizzare in base al proprio sistema, ai propri requisiti e alle proprie esigenze.

In sostanza, ciò consente all'autorità dell'applicazione Prenly di autorizzare e/o autenticare gli utenti nel momento in cui si impegnano con l'applicazione Prenly, ad esempio quando leggono le pubblicazioni all'interno di un'applicazione, tramite proxy dell'API dell'autorità remota Prenly.

L'autorità di Prenly medierà le richieste di autenticazione e autorizzazione tra gli utenti e Prenly, dove non è consentita la comunicazione diretta tra gli utenti e l'implementazione dell'API. Invece, l'implementazione dell'API informa l'autorità Prenly su come agire in base alle richieste di autenticazione e autorizzazione degli utenti.

Implementare l'API

Capire come l'utente consuma l'applicazione Prenly

Applicazioni Prenly

Prenly serve l'utente finale con applicazioni utilizzate principalmente per leggere pubblicazioni e articoli. L'applicazione può essere un'applicazione mobile nativa su piattaforma Android o iOS, oppure il nostro e-reader responsive basato sul web. Questi due tipi di applicazione offrono un'esperienza utente simile.

L'applicazione può contenere pubblicazioni pubbliche e accessibili a tutti, ma anche contenuti protetti che richiedono un certo tipo di autorizzazione per essere consumati. Per le applicazioni native, è anche possibile consentire a qualsiasi utente non loggato di consumare gratuitamente alcune pubblicazioni prima che venga richiesto il login.

Navigazione nell'applicazione

Utilizzando l'applicazione, l'utente può normalmente vedere la pagina iniziale contenente i componenti che visualizzano le pubblicazioni pubblicate. Le pubblicazioni pubbliche possono essere aperte e lette selezionando la pubblicazione. Tuttavia, quando l'utente tenta di aprire una pubblicazione protetta, l'applicazione richiede all'utente di effettuare il login(autenticazione).

Dopo l'accesso, Prenly deciderà se la pubblicazione richiesta è leggibile per quell'utente(autorizzazione). In caso affermativo, la pubblicazione verrà aperta, pronta per essere consumata. Se l'utente non ha accesso alla lettura, viene avvisato all'interno dell'applicazione. Il contenuto protetto non verrà mostrato, ma l'utente continuerà a essere connesso.

In alcuni casi, un'applicazione richiederà all'utente di effettuare il login per visualizzare alcune pubblicazioni, soprattutto quando non tutte le pubblicazioni pubblicate possono essere viste da chiunque. Ad esempio, le pubblicazioni accessibili tramite una sottoscrizione, mentre le altre pubblicazioni non sottoscritte dovrebbero essere nascoste.

Impostazione di un ambiente API

Fiducia nelle richieste di Prenly

Prenly invia una chiave segreta predefinita in tutte le richieste di autenticazione e autorizzazione. La chiave è nota solo a Prenly e al vostro sistema. È necessario verificare che la chiave fornita corrisponda a quella prevista per tutte le richieste API.

Potete anche aprire i vostri endpoint API solo per alcuni indirizzi IP per una maggiore sicurezza. Contattateci per avere un elenco aggiornato degli IP che Prenly utilizzerà nelle richieste se desiderate questa sicurezza aggiuntiva.

Crittografare il traffico

Raccomandiamo vivamente di non consentire il traffico HTTP non crittografato verso la vostra API. Utilizzare HTTPS!

Consentire un comportamento RESTish

Le richieste prenly sono attualmente effettuate con HTTP POST, ma l'API non dovrebbe essere limitata all'uso di qualsiasi metodo HTTP per l'espansione futura degli endpoint. Per maggiori dettagli, consultare le attuali specifiche dell'API, che hanno l'ultima parola su eventuali discrepanze con la presente documentazione.

Nelle risposte dell'API, i codici di stato HTTP sono utilizzati per informare Prenly sul risultato. È necessario essere in grado di rispondere con diversi codici di stato HTTP, sia per le richieste andate a buon fine che per gli errori di dati, gli errori di runtime e gli errori inattesi del server.

I parametri della richiesta sono attualmente passati come JSON nel corpo della richiesta.

Tutti gli endpoint rispondono attualmente con JSON nel corpo della risposta.

Conoscere OpenAPI 3.0

Le specifiche dell'API sono documentate in un file yaml secondo lo standard OpenAPI 3.0 (ex Swagger), che illustra gli aspetti tecnici e i requisiti dell'API e di ciascun endpoint, compresi tutti gli oggetti di dati di richiesta e di risposta.

La documentazione generata automaticamente è fornita all'indirizzo https://apidoc.prenly.com/remote-api/ e il file delle specifiche è disponibile all'indirizzo https://apidoc.prenly.com/remote-api/spec/v1.3-specification.yaml.

È possibile fare una copia del file delle specifiche e modificarlo in base ai propri endpoint API (URL), poiché le specifiche generate automaticamente contengono endpoint generici come riferimento. Con questo file, è possibile creare facilmente un ambiente di test con gli strumenti già pronti forniti da https://openapi.tools/ (vedere la sezione "Testing").

Per saperne di più su OpenAPI, comprese le specifiche, consultare https://www.openapis.org/.

Creare l'endpoint di autenticazione

Per gli endpoint di autenticazione, consultare le specifiche dell'API all'indirizzo https://apidoc.prenly.com/remote-api/. È possibile scegliere l'URL dell'endpoint esattamente come si desidera; tuttavia, l'endpoint deve seguire le specifiche API.

Parametri della richiesta

I parametri della richiesta fanno parte del corpo della richiesta come JSON e vengono inviati da Prenly per ogni richiesta.

Risposta in caso di successo

Un login riuscito deve rispondere con il codice di stato HTTP 200 e una risposta JSON con l'identificatore univoco dell'utente che è stato autenticato.

Risposta in caso di fallimento

Gli errori noti che dipendono dai parametri di richiesta forniti devono rispondere con uno dei codici di stato HTTP 401, 403 o 412, come specificato nella documentazione dell'API. Questi errori devono includere una risposta JSON che segua il modello di dati Error, che si può trovare specificato in fondo a https://apidoc.prenly.com/remote-api/.

È possibile scegliere se fornire un Erroreo un oggetto JSON vuoto. Attualmente, se si fornisce un errore, è richiesta solo la proprietà "message". Tuttavia, si consiglia di fornire anche la proprietà "code".

Si consiglia vivamente di fornire un valore della proprietà "message" in inglese, che rappresenti in qualche modo l'errore. Se il software dispone di un qualche tipo di codice interno, è opportuno utilizzarlo in questo caso se è necessaria una futura risoluzione reciproca dei problemi. Non includere dati personali non necessari, come ad esempio i nomi personali! Gli ID univoci sono sufficienti per la risoluzione dei problemi.

Queste informazioni non vengono mai mostrate all'utente finale, ma possono essere registrate in Prenly per semplificare la risoluzione dei problemi.

Creare l'endpoint di autorizzazione

Consultare le specifiche API all'indirizzo https://apidoc.prenly.com/remote-api/ per gli endpoint di autorizzazione. È possibile scegliere l'URL dell'endpoint esattamente come si desidera; tuttavia, l'endpoint deve seguire le specifiche API.

Parametri della richiesta

I parametri della richiesta fanno parte del corpo della richiesta come JSON e vengono inviati da Prenly per ogni richiesta.

Risposta in caso di successo

Una richiesta di informazioni sull'utente andata a buon fine deve rispondere con il codice di stato HTTP 200 e una risposta JSON conforme al modello di dati UserSummary, come descritto nelle specifiche.

I campi di questo oggetto dati sono spiegati in fondo a https://apidoc.prenly.com/remote-api/.

A cosa servono le proprietà

L'unica proprietà che attualmente non può essere lasciata vuota è "uid". Le altre proprietà possono essere omesse, tuttavia si consiglia di specificare una proprietà "productCodes" per controllare meglio se Prenly deve o non deve concedere il permesso di lettura alle pubblicazioni. Attualmente, Prenly tratta una proprietà "productCodes" mancante come un elenco vuoto.

Risposta in caso di fallimento

Gli errori noti che dipendono dai parametri di richiesta forniti, devono rispondere con uno dei codici di stato HTTP 403, 404 o 412, come specificato nella documentazione dell'API. Questi errori devono includere una risposta JSON che segua il modello di dati Error, come descritto sopra.

Test

È importante testare l'implementazione degli endpoint di autenticazione e autorizzazione. Fare riferimento a https://docs.google.com/document/d/1UxmvDs7_Z0GwGbwCHXr4Ojpb9HaZif1nJ8YRMmztzeo/ per ulteriori informazioni sulla verifica degli endpoint.

Cosa succede in Prenly?

Quando l'utente accede (autenticazione + autorizzazione)

Quando l'utente chiede di accedere e invia il modulo di login, le credenziali vengono inviate all'autorità di Prenly (crittografate con SSL). Da lì, l'autorità gestisce l'uso di queste credenziali per autenticare l'utente. Per l'API Remote authority, ciò significa che le credenziali vengono inviate all'endpoint remoto secondo le specifiche.

Prenly elaborerà la risposta dell'API e gestirà sia le richieste di autenticazione riuscite che quelle fallite, dove l'utente vedrà un errore a seconda del codice di stato HTTP della risposta fallita. Vedere di seguito per maggiori dettagli.

Se l'autenticazione è riuscita...

Un login riuscito attiva una richiesta di autorizzazione separata all'endpoint API remoto di autorizzazione per recuperare le informazioni dell'utente, che vengono memorizzate nella cache di Prenly per un periodo di tempo limitato.

L'applicazione rifletterà anche che qualcuno ha effettuato l'accesso, con il nome o l'e-mail, in base ai dati dell'utente restituiti nelle informazioni dell'utente.

Se le credenziali sono sbagliate...

Se la richiesta è tecnicamente riuscita, ma le credenziali erano sbagliate, l'autorità Prenly lo comunicherà all'applicazione e all'utente verrà presentato un messaggio sulle credenziali sbagliate.

Se qualcosa non è andato a buon fine...

Altri errori client o server, o errori di rete, vengono catturati e registrati da Prenly. L'applicazione riceverà un messaggio di errore adeguato da presentare all'utente.

Quando l'utente continua a leggere

Caching per le richieste ripetute

La memorizzazione nella cache dei dati di risposta dell'autorizzazione (le informazioni dell'utente) elimina la necessità di ripetere le richieste all'API remota per recuperare i dati dell'utente che raramente vengono modificati. Ogni cliente Prenly può scegliere il tempo di scadenza della cache; si consiglia di impostare 30 minuti, mentre il tempo di scadenza minimo consentito è di 20 minuti.

Riautorizzazione

Prenly utilizzerà il risultato della cache per ogni richiesta di autorizzazione, purché la cache non sia scaduta. Se la cache è scaduta, Prenly attiva una nuova richiesta di autorizzazione all'endpoint di autorizzazione dell'API remota. Questo aggiornerà i dati dell'utente, come la disponibilità dei prodotti, oltre ai dati memorizzati nella cache.

Gestione dei fallimenti

Se si verifica un errore del server (codice HTTP 5xx) quando viene attivata la ri-autorizzazione, il tempo di scadenza della cache viene prolungato di cinque minuti. Prenly agisce in questo modo per evitare che gli utenti vengano disconnessi per errori temporanei della rete o del server; l'utente continuerà a leggere come se nulla fosse e dopo cinque minuti verrà effettuato un nuovo tentativo di riautorizzazione. Questo comportamento dura fino a quando il problema del server persiste. Prenly registrerà tali problemi tecnici e cercherà di contattare il cliente in caso di problemi.

Andare in onda

Quando ritenete che l'API sia pronta per essere messa in funzione (avete finito di sviluppare e testare la vostra implementazione), contattateci per compiere gli ultimi passi.

Prenly vi chiederà informazioni per configurare la vostra implementazione in Prenly. Le informazioni saranno valutate e, se tutto è a posto, la vostra implementazione potrà essere utilizzata in Prenly per le applicazioni e-paper Prenly da voi scelte.

Impostazione di Prenly

Prima che la vostra implementazione dell'API remota possa essere utilizzata in Prenly, dovete fornire:

- La chiave segreta scelta per gli endpoint di autenticazione e autorizzazione.

- Gli endpoint API scelti

- Un elenco di prodotti che devono concedere autorizzazioni di lettura e per i quali Prenly ha un titolo (solo i prodotti conosciuti da Prenly all'interno dell'elenco dei codici prodotto dell'endpoint di autorizzazione possono concedere autorizzazioni di lettura).

- Il tempo di scadenza della cache desiderato

- Un URL in cui un nuovo utente può creare un account

- Un URL in cui un utente può cancellare il proprio account

- Un URL in cui l'utente può reimpostare la propria password (nel caso in cui l'abbia dimenticata).

- Si consiglia di fornire anche un URL in cui un utente autorizzato, senza codici prodotto conosciuti in precedenza, possa attivare un prodotto (ad esempio, acquistare un abbonamento).

- credenziali utente (nome utente e password) per l'utente di prova, dove l'utente è condiviso da Textalk, Apple e Google (se avete applicazioni native) dove almeno un codice prodotto deve rimanere attivo finché l'API remota è utilizzata dall'autorità Prenly del vostro e-paper