Prenly Remote authority API

Le but de ce document est d'expliquer :

1. ...comment l'éco-système Prenly permet à l'authentification et à l'autorisation de l'utilisateur d'être gérée par une infrastructure technique appartenant à l'éditeur ou à une tierce partie.

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

Contact

Veuillez nous contacter par courrier électronique à 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 d'autoriser l'accès à des données protégées. Normalement, cela se fait en fournissant des 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écider à quelles ressources un utilisateur a accès, c'est-à-dire à quelles données l'utilisateur a la permission d'accéder, c'est-à-dire ce que l'utilisateur peut ou ne peut pas faire. Pour Prenly, il s'agit de 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, dictant la communication de système à système.

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

Introduction

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

Au fond, cela permet à l'autorité de l'application Prenly d'autoriser et/ou d'authentifier les utilisateurs lorsqu'ils s'engagent 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, aucune communication directe n'étant autorisée entre les utilisateurs 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émentez votre API

Comprendre comment l'utilisateur consomme l'application Prenly

Les applications Prenly

Prenly propose à l'utilisateur final des applications 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 autorisation pour être consommé. Pour les applications natives, il est également possible de permettre à tout utilisateur non connecté de consommer gratuitement certaines publications avant de devoir se connecter.

Navigation dans l'application

En utilisant l'application, un utilisateur peut normalement voir la page d'accueil contenant des composants affichant des publications publiées. Les publications publiques peuvent être ouvertes et lues en sélectionnant la publication. Mais 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écidera si la publication demandée peut être lue par l'utilisateur(autorisation). Si c'est le cas, la publication sera ouverte, prête à être consommée. Si l'utilisateur n'a pas accès à la lecture, il en sera 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 afficher certaines publications, en particulier lorsque toutes les publications publiées ne peuvent pas être vues par n'importe qui. Par exemple, les publications accessibles par le biais d'un abonnement, alors que d'autres publications publiées sans abonnement doivent être cachées.

Configurer un environnement API

Confiance dans 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 requêtes API.

Vous pouvez également ouvrir vos points d'accès à l'API à certaines adresses IP seulement pour plus de sécurité. Veuillez nous contacter pour obtenir une liste actualisée des adresses IP que Prenly utilisera dans les requêtes si vous souhaitez bénéficier de cette sécurité supplémentaire.

Cryptage du trafic

Nous vous recommandons vivement d'interdire tout trafic HTTP non crypté vers votre API. Utilisez HTTPS !

Permettre un comportement RESTish

Les demandes préalables sont actuellement effectuées avec HTTP POST, mais l'API ne doit pas être limitée à l'utilisation de n'importe quelle méthode HTTP en vue d'une expansion future des points finaux. Veuillez consulter la spécification actuelle de l'API pour plus de détails, car c'est la spécification de l'API qui a le dernier mot en cas de divergence avec la présente 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, pour les requêtes réussies ainsi que 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 transmis sous forme de JSON dans le corps de la demande.

Tous les points de terminaison répondent actuellement avec du 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), indiquant 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 fournie à 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 fournis à 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/.

Construire le point final d'authentification

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

Paramètres de la demande

Les paramètres de la demande font partie du corps 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 erreurs connues qui dépendent des paramètres de demande donnés doivent répondre avec l'un des codes d'état HTTP 401, 403 ou 412 comme spécifié dans la documentation de l'API. Ces erreurs doivent inclure une réponse JSON suivant le modèle de données Error que vous pouvez trouver spécifié 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. Il est toutefois recommandé de fournir également une propriété "code".

Nous vous recommandons vivement de fournir une valeur de propriété "message" en anglais qui représente l'erreur d'une manière ou d'une autre. Si votre logiciel dispose de codes internes, il convient de les utiliser ici si un dépannage mutuel s'avère nécessaire à l'avenir. N'incluez pas de données personnelles inutiles, telles que des noms de personnes ! Les identifiants uniques suffisent 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.

Construire le point final d'autorisation

Consultez la spécification de l'API à l'adresse https://apidoc.prenly.com/remote-api/ pour connaître le(s) point(s) de terminaison de l'autorisation. Vous pouvez choisir l'URL du point final exactement comme vous le souhaitez ; cependant, le point final doit respecter la spécification de l'API.

Paramètres de la demande

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

Réponse en cas de succès

Une récupération réussie des informations sur l'utilisateur doit répondre par un code d'état HTTP 200 et une réponse JSON conforme au modèle de données UserSummary tel que 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/.

Quelles sont les propriétés utilisées ?

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 vous recommandons de spécifier une propriété "productCodes" pour mieux contrôler si Prenly doit ou non accorder l'autorisation de lecture aux publications. Actuellement, Prenly traitera une propriété "productCodes" manquante comme une liste vide.

Réponse en cas d'échec

Les erreurs connues qui dépendent des paramètres de demande donnés, doivent répondre avec l'un des codes d'état HTTP 403, 404 ou 412 comme spécifié dans la documentation de l'API. Ces erreurs doivent inclure une réponse JSON suivant 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. Consultez le site https://docs.google.com/document/d/1UxmvDs7_Z0GwGbwCHXr4Ojpb9HaZif1nJ8YRMmztzeo/ pour plus d'informations sur le test de vos points d'accès.

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 informations d'identification sont envoyées à l'autorité de Prenly (cryptées avec SSL). A 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 terminaison distant conformément à la spécification.

Prenly traitera la réponse de l'API et s'occupera des demandes d'authentification réussies et échouées où l'utilisateur verra une erreur en fonction du code d'état HTTP de la réponse d'échec. Voir ci-dessous pour plus de détails.

Si l'authentification a réussi...

Une connexion réussie déclenchera une demande d'autorisation séparée vers le point de terminaison de l'API d'autorisation à distance 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 s'est connecté, avec son nom ou son adresse électronique, en fonction des données d'utilisateur renvoyées dans les informations sur l'utilisateur.

Si les informations d'identification sont erronées...

Si la demande a techniquement abouti, mais que les informations d'identification sont erronées, l'autorité Prenly en informera l'application et un message indiquant que les informations d'identification sont erronées 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, sont détectées et enregistrées par Prenly. L'application recevra un message d'erreur approprié à présenter à l'utilisateur.

Lorsque l'utilisateur continue à lire

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

La mise en cache des données d'une réponse d'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 sont rarement modifiées. 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éclenche 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é des produits, seront alors mises à jour, de même que les données mises en cache.

Gestion des échecs

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 continuera à lire comme si de rien n'était et, au bout de cinq minutes, une nouvelle tentative de réautorisation sera 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 implémentation), contactez-nous pour prendre les dernières mesures.

Prenly vous demandera des informations pour mettre en place votre implémentation dans Prenly. Ces informations seront évaluées et, si tout est conforme, votre implémentation pourra être utilisée dans Prenly pour les applications e-paper Prenly de votre choix.

Configuration de Prenly

Avant que votre implémentation de l'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 des autorisations de lecture doivent être accordées et pour lesquels Prenly est un titre (seuls les produits connus de Prenly dans la liste des codes de produits du point d'accès d'autorisation peuvent accorder des autorisations de lecture).

- Le délai d'expiration du cache que vous souhaitez

- 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 (au cas où il l'aurait oublié).

- Nous vous recommandons de fournir également une URL où un utilisateur autorisé sans code produit connu à l'avance peut activer un produit (c'est-à-dire 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 de votre e-paper.