Prenly Remote Authority API

L'objectif de ce document est d'expliquer :

1. ...comment l'écosystème Prenly permet de gérer l'authentification et l'autorisation des utilisateurs en utilisant une infrastructure technique appartenant à l'éditeur ou à un tiers.

2. ...comment une implémentation technique peut être faite en construisant une modeste API résiduelle qui suit la spécification "Prenly Remote authority API".

Contact

Veuillez nous contacter par courriel à l'adresse hello@prenly.com ou par téléphone au +46-31-3884740 pour toute question ou problème concernant cette API.

Définitions

L'authentification est le processus qui consiste à vérifier l'identité de quelqu'un ou de quelque chose, c'est-à-dire à s'assurer qu'il est bien celui qu'il prétend être, avant de lui accorder l'accès à des données protégées. Normalement, cela se fait en fournissant certaines informations d'identification, telles qu'un nom d'utilisateur et un mot de passe. Si les informations d'identification correspondent à un enregistrement stocké, l'utilisateur est "vérifié" (authentifié) en appliquant le principe selon lequel l'utilisateur connaissait quelque chose que seul le "véritable" utilisateur connaîtrait.

L'autorisation est le processus qui consiste à déterminer les ressources auxquelles un utilisateur a accès, c'est-à-dire les données auxquelles l'utilisateur est autorisé à accéder et ce qu'il peut ou ne peut pas faire. Pour Prenly, cela signifie déterminer les publications que l'utilisateur peut voir et ouvrir pour les lire.

Une API( interface de programme d'application)est un ensemble de routines, de protocoles et d'outils permettant de gérer l'interaction entre différents systèmes ou parties de systèmes, et dicte la communication entre les systèmes.

Dans Prenly, une autorité est une implémentation technique qui détermine comment l'authentification et l'autorisation sont gérées par une application Prenly dans le backend Prenly.

Introduction à l'API

L'API Prenly Remote Authority permet de remplacer la gestion de l'autorisation et/ou de l'authentification par Prenly en implémentant des points de terminaison API qui suivent une spécification API, permettant à un client Prenly d'authentifier et d'autoriser en fonction de son système, de ses exigences et de ses besoins.

Fondamentalement, cela permet à l'autorité de l'application Prenly d'autoriser et/ou d'authentifier les utilisateurs lorsqu'ils interagissent avec l'application Prenly, c'est-à-dire lorsqu'ils lisent des publications dans une application, par l'intermédiaire de l'API de l'autorité distante de Prenly.

L'autorité de Prenly servira de médiateur pour les demandes d'authentification et d'autorisation entre les utilisateurs et Prenly lorsqu'aucune communication directe n'est autorisée entre l'utilisateur et la mise en œuvre de l'API. Au lieu de cela, l'implémentation de l'API informe l'autorité de Prenly de la manière d'agir sur les demandes d'authentification et d'autorisation des utilisateurs.

Implémentation de votre API

Comprendre comment l'utilisateur utilise l'application Prenly

Les applications Prenly

Prenly fournit à l'utilisateur final des applications qui sont principalement utilisées pour lire des publications et des articles. L'application est soit une application mobile native sur la plateforme Android ou iOS, soit notre lecteur électronique basé sur le web. Ces deux types d'applications offrent une expérience utilisateur similaire.

L'application peut contenir des publications publiques, accessibles à tous, ainsi que du contenu protégé, qui nécessite une certaine forme d'autorisation pour être consommé. Pour les applications natives, il est également possible de permettre à tous les utilisateurs non connectés de consommer certaines publications gratuitement avant de devoir se connecter.

Navigation dans l'application

Lorsqu'un utilisateur utilise l'application, il peut normalement voir la page d'accueil qui contient des composants affichant les publications publiées. Les publications publiques peuvent être ouvertes et lues en sélectionnant la publication. Toutefois, lorsque l'utilisateur tente d'ouvrir une publication protégée, l'application lui demande de se connecter(authentification).

Après la connexion, Prenly détermine si la publication demandée peut être lue par l'utilisateur(autorisation). Si c'est le cas, la publication est ouverte et prête à être utilisée. Si l'utilisateur n'a pas accès à la lecture, il en est informé dans l'application. Le contenu protégé ne sera pas affiché, mais l'utilisateur sera toujours connecté.

Dans certains cas, une application demandera à l'utilisateur de se connecter pour consulter certaines publications, en particulier lorsque toutes les publications publiées ne peuvent pas être consultées par n'importe qui. Par exemple, les publications disponibles via un abonnement où d'autres publications publiées qui ne sont pas souscrites doivent être cachées.

Configuration d'un environnement API

Confiance pour les requêtes Prenly

Prenly envoie une clé secrète prédéfinie dans toutes les demandes d'authentification et d'autorisation. Cette clé n'est connue que de Prenly et de votre système. Vous devez vérifier que la clé fournie correspond à la clé attendue pour toutes les demandes d'API.

Vous pouvez également ouvrir vos points d'accès à l'API à certaines adresses IP seulement pour plus de sécurité. Contactez-nous pour obtenir une liste mise à jour des adresses IP que Prenly utilisera dans les requêtes si vous souhaitez cette sécurité supplémentaire.

Cryptage du trafic

Nous vous recommandons vivement de ne pas autoriser de trafic HTTP non crypté vers votre API. Utilisez HTTPS !

Permettre un comportement de type REST

Les demandes préalables sont actuellement effectuées à l'aide de HTTP POST, mais l'API ne devrait pas être limitée à l'utilisation de n'importe quelle méthode HTTP pour l'expansion future des points finaux. Veuillez vous référer à la spécification actuelle de l'API pour plus d'informations, car c'est la spécification de l'API qui a le dernier mot en ce qui concerne les écarts par rapport à cette documentation.

Dans les réponses de l'API, les codes d'état HTTP sont utilisés pour informer Prenly du résultat. Vous devez être en mesure de répondre avec différents codes d'état HTTP, à la fois pour les requêtes réussies et pour les erreurs de données, les erreurs d'exécution et les erreurs de serveur inattendues.

Les paramètres de la demande sont actuellement envoyés sous forme de JSON dans le corps de la demande.

Tous les points d'extrémité répondent actuellement avec JSON dans le corps de la réponse.

Se familiariser avec OpenAPI 3.0

La spécification de l'API est documentée dans un fichier yaml conformément à la norme OpenAPI 3.0 (anciennement Swagger) et spécifie les aspects techniques et les exigences de l'API et de chaque point de terminaison, y compris tous les objets de données de demande et de réponse.

La documentation générée automatiquement est disponible à l'adresse https://apidoc.prenly.com/remote-api/ et le fichier de spécification est disponible à l'adresse https://apidoc.prenly.com/remote-api/spec/v1.3-specification.yaml.

N'hésitez pas à faire une copie du fichier de spécification et à le modifier en fonction de vos points d'accès à l'API (URL), car la spécification générée automatiquement contient des points d'accès génériques à titre de référence. Avec ce fichier, vous pouvez facilement créer un environnement de test avec des outils prêts à l'emploi disponibles à l'adresse https://openapi.tools/ (voir la section "Testing").

Pour en savoir plus sur OpenAPI, y compris sur la spécification, consultez le site https://www.openapis.org/.

Création du point final d'authentification

Consultez la spécification de l'API à l'adresse https://apidoc.prenly.com/remote-api/ pour connaître les points de terminaison d'authentification. Vous pouvez choisir l'URL du point final comme vous le souhaitez, mais le point final doit respecter la spécification de l'API.

Paramètres de la requête

Les paramètres de la demande font partie de la demande en tant que JSON et sont envoyés par Prenly pour chaque demande.

Réponse en cas de succès

Une connexion réussie doit répondre par un code de statut HTTP 200 et une réponse JSON avec l'identifiant unique de l'utilisateur qui a été authentifié.

Réponse en cas d'échec

Les échecs connus dus aux paramètres de demande spécifiés doivent faire l'objet d'une réponse avec l'un des codes d'état HTTP 401, 403 ou 412, comme indiqué dans la documentation de l'API. Ces erreurs doivent contenir une réponse JSON qui suit le modèle de données Error qui se trouve au bas de https://apidoc.prenly.com/remote-api/.

Vous pouvez choisir de fournir soit une erreur, soit un objet JSON vide. Actuellement, seule la propriété "message" est requise si vous fournissez une erreur. Cependant, il est recommandé de fournir également une propriété "code".

Nous vous recommandons vivement de donner à la propriété "message" une valeur en anglais qui représente l'erreur d'une manière ou d'une autre. Si votre logiciel dispose de codes internes, il est conseillé de les utiliser ici au cas où un débogage mutuel serait nécessaire à l'avenir. N'incluez pas de données personnelles qui ne sont pas nécessaires, par exemple des noms personnels ! Les identifiants uniques sont suffisants pour le dépannage.

Ces informations ne sont jamais montrées à l'utilisateur final mais peuvent être enregistrées dans Prenly pour simplifier le dépannage.

Création du point d'accès pour l'autorisation

Voir la spécification de l'API à l'adresse https://apidoc.prenly.com/remote-api/ pour les points de terminaison d'autorisation. Vous pouvez choisir l'URL du point final comme vous le souhaitez, mais le point final doit respecter la spécification de l'API.

Paramètres de la demande

Les paramètres de requête font partie de la requête en tant que JSON et sont envoyés par Prenly pour chaque requête.

Réponse en cas de succès

Une récupération réussie des informations sur l'utilisateur doit répondre par un code de statut HTTP 200 et une réponse JSON conforme au modèle de données UserSummary décrit dans la spécification.

Les champs de cet objet de données sont expliqués au bas de https://apidoc.prenly.com/remote-api/.

A quoi servent les propriétés

La seule propriété qui ne peut actuellement pas être laissée vide est "uid". Les autres propriétés peuvent être omises, mais nous recommandons de définir une propriété "productCodes" pour mieux contrôler si Prenly doit accorder un accès en lecture aux publications ou non. Actuellement, Prenly traitera une propriété "productCodes" manquante comme une liste vide.

Réponse en cas d'échec

Les erreurs connues résultant des paramètres de demande spécifiés doivent faire l'objet d'une réponse avec l'un des codes d'état HTTP 403, 404 ou 412, comme indiqué dans la documentation de l'API. Ces erreurs doivent contenir une réponse JSON qui suit le modèle de données Error décrit ci-dessus.

Tests

Il est important de tester votre implémentation pour les points finaux d'authentification et d'autorisation. Voir https://docs.google .com/document/d/1UxmvDs7_Z0GwGbwCHXr4Ojpb9HaZif1nJ8YRMmztzeo/ pour plus d'informations sur la manière de tester vos points de terminaison.

Que se passe-t-il dans Prenly ?

Lorsque l'utilisateur se connecte (authentification + autorisation)

Lorsque l'utilisateur demande à se connecter et soumet le formulaire de connexion, les données de connexion sont envoyées à l'autorité Prenly (cryptées avec SSL). À partir de là, l'autorité gère l'utilisation de ces informations d'identification pour authentifier l'utilisateur. Pour l'API de l'autorité distante, cela signifie que les informations d'identification sont envoyées au point de connexion distant comme spécifié.

Prenly traitera la réponse de l'API et gérera les demandes d'authentification réussies et non réussies où l'utilisateur verra une erreur en fonction du code d'état HTTP de la réponse d'erreur. Voir ci-dessous pour plus d'informations.

Si l'authentification a réussi...

Une connexion réussie déclenche une demande d'autorisation distincte au point de terminaison de l'API d'autorisation pour récupérer les informations de l'utilisateur, qui sont mises en cache dans Prenly pour une durée limitée.

L'application indiquera également que quelqu'un est connecté, par son nom ou son adresse électronique, en fonction des données d'utilisateur renvoyées dans les informations d'identification de l'utilisateur.

Si les données de connexion sont incorrectes...

Si la demande a techniquement abouti, mais que les données d'identification sont incorrectes, l'autorité Prenly en informera l'application et un message indiquant que les données d'identification sont incorrectes sera présenté à l'utilisateur.

Si quelque chose a échoué...

D'autres erreurs basées sur le client ou le serveur, ou des erreurs de réseau, seront détectées et enregistrées par Prenly. L'application recevra un message d'erreur approprié qui sera présenté à l'utilisateur.

Au fur et à mesure que l'utilisateur poursuit sa lecture

Mise en cache pour les demandes répétées

La mise en cache des données de réponse d'une autorisation réussie (les informations de l'utilisateur) élimine le besoin de requêtes répétées à l'API distante pour récupérer les données de l'utilisateur qui changent rarement. Chaque client Prenly peut choisir le délai d'expiration du cache. Nous recommandons de le fixer à 30 minutes, le délai minimum autorisé étant de 20 minutes.

Ré-autorisation

Prenly utilisera le résultat mis en cache pour chaque demande d'autorisation tant que le cache n'a pas expiré. Si le cache a expiré, Prenly déclenchera une nouvelle demande d'autorisation au point de terminaison d'autorisation dans l'API distante. Les données de l'utilisateur, telles que la disponibilité du produit, ainsi que les données mises en cache seront alors mises à jour.

Traitement des erreurs

Si une erreur de serveur (code HTTP 5xx) se produit lorsque la réautorisation est déclenchée, le délai d'expiration du cache est prolongé de cinq minutes. Prenly procède ainsi pour éviter que les utilisateurs ne soient déconnectés en raison d'erreurs temporaires du réseau ou du serveur ; l'utilisateur continue à lire comme si rien ne s'était passé et, après cinq minutes, une nouvelle tentative de réautorisation est effectuée. Ce comportement dure aussi longtemps que le problème de serveur persiste. Prenly enregistrera ces problèmes techniques et tentera de joindre le client si cela se produit.

Mise en service

Lorsque vous pensez que l'API est prête à être mise en service (vous avez fini de développer et de tester votre mise en œuvre), contactez-nous pour prendre les dernières mesures.

Prenly vous demandera des informations pour configurer votre implémentation dans Prenly. Ces informations seront évaluées et si tout est en ordre, votre implémentation pourra être utilisée dans Prenly pour les applications e-paper sélectionnées par Prenly.

Configuration de Prenly

Avant que votre implémentation d'API à distance puisse être utilisée dans Prenly, vous devez fournir :

- la clé secrète que vous avez choisie pour les points de terminaison d'authentification et d'autorisation

- Les points d'accès à l'API que vous avez choisis

- Une liste de produits pour lesquels l'accès en lecture est autorisé et pour lesquels le titre Prenly est connu (seuls les produits connus de Prenly dans la liste des codes de produits du point d'accès d'autorisation peuvent autoriser l'accès en lecture).

- Le délai d'expiration que vous préférez pour le cache

- Une URL où un nouvel utilisateur peut créer un compte

- Une URL où un utilisateur peut supprimer son compte

- Une URL où un utilisateur peut réinitialiser son mot de passe (s'il a oublié son mot de passe).

- Nous vous recommandons de fournir également une URL permettant à un utilisateur autorisé, sans code produit connu au préalable, d'activer un produit (par exemple, d'acheter un abonnement).

- Les informations d'identification de l'utilisateur (nom d'utilisateur et mot de passe) pour l'utilisateur test, lorsque l'utilisateur est partagé par Textalk, Apple et Google (si vous avez des applications natives) où au moins un code produit doit rester actif tant que l'API à distance est utilisée par l'autorité Prenly pour votre e-paper.