API dell'autorità remota di Prenly

Lo scopo di questo documento è quello di spiegare:

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

2. ...come sia possibile realizzare un'implementazione tecnica costruendo una modesta API residuale 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, cioè se è chi dice di essere, prima che venga concesso l'accesso a dati protetti. Normalmente, ciò avviene fornendo determinate 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 che determina a quali risorse un utente ha accesso, cioè a quali dati l'utente è autorizzato ad accedere e cosa può o non può fare. Per Prenly, ciò significa determinare quali pubblicazioni l'utente può vedere e aprire per leggere.

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

In Prenly, un'autorità è un'implementazione tecnica che determina il modo in cui l'autenticazione e l'autorizzazione sono gestite da un'applicazione Prenly nel backend Prenly.

Introduzione all'API

L'API Prenly Remote Authority offre la possibilità di sostituire la gestione dell'autorizzazione e/o dell'autenticazione da parte di Prenly implementando endpoint API che seguono una specifica API, consentendo a un 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 quando interagiscono con l'applicazione Prenly, ad esempio quando leggono le pubblicazioni in un'applicazione, tramite l'API Prenly Remote Authority.

L'autorità Prenly medierà le richieste di autenticazione e autorizzazione tra gli utenti e Prenly, laddove non è consentita la comunicazione diretta tra l'utente 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.

Implementazione dell'API

Capire come l'utente utilizza l'applicazione Prenly

Applicazioni Prenly

Prenly fornisce all'utente finale applicazioni utilizzate principalmente per leggere pubblicazioni e articoli. L'applicazione può essere un'applicazione mobile nativa su piattaforma Android o iOS o 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 una qualche forma di autorizzazione per essere consumati. Per le applicazioni native, è anche possibile consentire a tutti gli utenti non loggati di consumare gratuitamente alcune pubblicazioni prima che venga richiesto il login.

Navigazione nell'applicazione

Quando un utente utilizza l'applicazione, di solito vede la home page che contiene componenti che mostrano 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 determina se la pubblicazione richiesta è leggibile per quell'utente(autorizzazione). In caso affermativo, la pubblicazione viene aperta e pronta all'uso. Se l'utente non ha accesso alla lettura, viene avvisato nell'app. Il contenuto protetto non verrà visualizzato, 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 visualizzate da chiunque. Ad esempio, le pubblicazioni disponibili tramite un abbonamento, dove altre pubblicazioni pubblicate che non sono state sottoscritte devono essere nascoste.

Configurazione di un ambiente API

Fiducia per le richieste 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.

È inoltre possibile aprire gli endpoint API solo a determinati indirizzi IP per una maggiore sicurezza. Contattateci per ottenere un elenco aggiornato degli indirizzi IP che Prenly utilizzerà nelle richieste se desiderate questa ulteriore sicurezza.

Crittografare il traffico

Vi consigliamo vivamente di non consentire il traffico HTTP non criptato verso la vostra API. Utilizzare HTTPS!

Consentire un comportamento simile a REST

Le richieste prenly sono attualmente effettuate tramite HTTP POST, ma l'API non dovrebbe essere limitata all'uso di qualsiasi metodo HTTP per la futura espansione degli endpoint. Per ulteriori informazioni, consultare la specifica API attuale, che ha l'ultima parola su qualsiasi deviazione dalla presente documentazione.

Nelle risposte dell'API, i codici di stato HTTP sono utilizzati per informare Prenly del 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 inviati come JSON nel corpo della richiesta.

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

Familiarizzare con OpenAPI 3.0

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

La documentazione generata automaticamente è disponibile 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 agli endpoint (URL) dell'API, poiché le specifiche generate automaticamente contengono endpoint generici di riferimento. Con questo file, si può facilmente costruire un ambiente di test con gli strumenti già pronti disponibili su https://openapi.tools/ (vedere la sezione "Test").

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/. L'URL dell'endpoint può essere scelto a piacere, ma deve essere conforme alle specifiche API.

Parametri della richiesta

I parametri della richiesta fanno parte 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'identificativo univoco dell'utente che è stato autenticato.

Risposta in caso di fallimento

Ai fallimenti noti dovuti ai parametri di richiesta specificati si deve rispondere con uno dei codici di stato HTTP 401, 403 o 412, come specificato nella documentazione dell'API. Questi errori devono contenere una risposta JSON che segue il modello di dati Error che si trova in fondo a https://apidoc.prenly.com/remote-api/.

Si può scegliere di fornire un Erroreo un oggetto JSON vuoto. Attualmente, solo la proprietà "message" è richiesta se si fornisce un Errore. Tuttavia, si consiglia di fornire anche la proprietà "code".

Si consiglia vivamente di impostare un valore per la proprietà "message" in inglese, che rappresenti in qualche modo l'errore. Se il software dispone di codici interni di qualsiasi tipo, è consigliabile utilizzarli qui, nel caso in cui sia necessario un futuro debug reciproco. Non includere dati personali non necessari, ad esempio nomi di persone! 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 per l'autorizzazione

Per gli endpoint di autorizzazione, consultare le specifiche API all'indirizzo https://apidoc.prenly.com/remote-api/. Si può scegliere l'URL dell'endpoint come si vuole, ma l'endpoint deve seguire le specifiche API.

Parametri della richiesta

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

Risposta in caso di successo

Se le informazioni sull'utente vengono recuperate con successo, si deve rispondere con il codice di stato HTTP 200 e con una risposta JSON conforme al modello di dati UserSummary 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, ma si consiglia di impostare la proprietà "productCodes" per controllare meglio se Prenly deve concedere o meno l'accesso in lettura alle pubblicazioni. Attualmente, Prenly tratta una proprietà "productCodes" mancante come un elenco vuoto.

Risposta in caso di fallimento

Agli errori noti derivanti dai parametri di richiesta specificati si deve rispondere con uno dei codici di stato HTTP 403, 404 o 412, come specificato nella documentazione dell'API. Questi errori devono contenere una risposta JSON che segue il modello di dati Error, come descritto sopra.

Test

È importante testare l'implementazione degli endpoint di autenticazione e autorizzazione. Vedere https://docs.google .com/document/d/1UxmvDs7_Z0GwGbwCHXr4Ojpb9HaZif1nJ8YRMmztzeo/ per ulteriori informazioni su come testare gli endpoint.

Cosa succede in Prenly?

Quando l'utente accede (autenticazione + autorizzazione)

Quando l'utente richiede l'accesso e invia il modulo di login, i dati di accesso vengono inviati all'autorità Prenly (crittografati con SSL). Da qui, l'autorità gestisce come utilizzare queste credenziali per autenticare l'utente. Per l'API Remote authority, ciò significa che le credenziali vengono inviate al punto di connessione remoto, come specificato.

Prenly elaborerà la risposta dell'API e gestirà sia le richieste di autenticazione riuscite che quelle non riuscite, dove l'utente vedrà un errore a seconda del codice di stato HTTP della risposta di errore. Per ulteriori informazioni, vedere di seguito.

Se l'autenticazione è riuscita...

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

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

Se i dati di accesso non sono corretti...

Se la richiesta è tecnicamente andata a buon fine, ma le credenziali non erano corrette, l'autorità Prenly informerà l'applicazione e all'utente verrà presentato un messaggio sulle credenziali non corrette.

Se qualcosa non è andato a buon fine...

Altri errori del client o del server o errori di rete vengono rilevati e registrati da Prenly. L'applicazione riceverà un messaggio di errore appropriato che verrà presentato all'utente.

Mentre l'utente continua a leggere

Caching per le richieste ripetute

La memorizzazione nella cache dei dati di risposta di un'autorizzazione andata a buon fine (le informazioni dell'utente) elimina la necessità di ripetere le richieste all'API remota per recuperare i dati dell'utente che cambiano raramente. Ogni cliente Prenly può scegliere il tempo di scadenza della cache; si consiglia di impostare 30 minuti, mentre il tempo minimo di scadenza della cache 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 degli errori

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 a causa di errori temporanei della rete o del server; l'utente continua a leggere come se nulla fosse, e dopo cinque minuti viene 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 è in ordine, la vostra implementazione potrà essere utilizzata in Prenly per le applicazioni e-paper Prenly selezionate.

Configurazione di Prenly

Prima che la vostra implementazione 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 a cui concedere l'accesso in lettura e per i quali il titolo Prenly (solo i prodotti noti a Prenly nell'elenco dei codici prodotto dall'endpoint di autorizzazione possono concedere l'accesso in lettura)

- Il tempo di scadenza preferito per la cache

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

- Un URL dove un utente può cancellare il proprio account

- Un URL in cui l'utente può reimpostare la propria password (se l'ha dimenticata).

- Si consiglia di fornire anche un URL in cui un utente autorizzato, senza codici prodotto precedentemente noti, 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 per il vostro e-paper