OAuth2

Prenly supporte OAuth2 avec ou sans l'extension OpenID Connect (OIDC) tant que le serveur d'autorisation suit la spécification OAuth2 RFC 6749. Vous aurez probablement besoin d'un serveur d'autorisation qui supporte OIDC.

Prenly ne prend en charge que l'autorisation Code d'autorisation.

Le client que Prenly utilisera dans le flux OAuth2 est l'autorité d'application de l'e-paper (une implémentation technique qui décide comment l'authentification et l'autorisation sont gérées par l'application de l'e-paper dans le backend de Prenly).

Prenly devra connaître quelques éléments pour pouvoir agir en tant que client pour le flux d'autorisation :

- Facultatif*. L'émetteur choisi.
Ceci n'est obligatoire que si vous souhaitez utiliser l'extension OpenID Connect ID token claim.

- Obligatoire. L'identifiant du client que vous voulez que l'autorité Prenly utilise.

- Obligatoire. Le secret du client que l'autorité Prenly doit utiliser lors de l'échange de l'autorisation fournie contre un jeton d'accès lors de l'authentification de l'autorité Prenly (le client).

- Facultatif. Portée. Vous pouvez choisir de faire en sorte que Prenly utilise une liste de champs d'application séparés par des espaces, définissant l'autorisation du jeton délivré. Le(s) champ(s) d'application sera(ont) utilisé(s) avec le point final d'autorisation.

- Facultatif. État. Prenly prend en charge la génération d'un état dans la demande d'autorisation. Vous pouvez choisir de laisser Prenly générer un état ou de faire en sorte que l'autorité l'ignore.

- Obligatoire. Point d'arrivée de l'autorisation. L'autorité Prenly dirigera l'agent utilisateur vers ce point d'accès pour initier le flux d'autorisation avec le serveur d'autorisation en connectant l'utilisateur pour obtenir l'octroi du code d'autorisation.

- Obligatoire. Point d'accès au jeton. L'autorité Prenly essaiera d'échanger le code d'autorisation de l'utilisateur contre un jeton d'accès ou, si votre serveur d'autorisation le prend en charge (ce qui est fortement recommandé), d'échanger le jeton de rafraîchissement de l'utilisateur contre un nouveau jeton d'accès.

Méthode d'authentification. Par défaut, Prenly utilise la méthode d'authentification client de l'OIDC client_secret_basic lors de l'authentification avec le point de terminaison du serveur d'autorisation. Prenly prend également en charge la méthode d'authentification client client_secret_post. Veuillez informer Prenly si vous avez besoin de cette dernière, sinon la méthode d'authentification par défaut sera utilisée.

- Recommandé. Une URL externe pour déconnecter l'utilisateur. L'autorité Prenly utilisera l'agent utilisateur sélectionné par l'utilisateur actuel pour déconnecter l'utilisateur à distance sur le serveur d'autorisation.
Prenly est capable d'utiliser des caractères génériques dans l'URL lors de la création de la demande d'autorisation pour déconnecter l'utilisateur en fournissant ce qui suit :

◦ L'identifiant du client;
◦ L'URI de retour de la déconnexion ;
◦ L'URI d'erreur de déconnexion ;

Veuillez noter que l'état ne peut pas être utilisé.
Un exemple de paramètre de requête URI de retour est "post_logout_redirect_uri".

Actuellement, seule la méthode HTTP GET est prise en charge pour l'URL de déconnexion.

Identifiant de l'utilisateur

L'autorité Prenly devra savoir comment extraire l'identifiant unique de l'utilisateur après que celui-ci a été autorisé avec succès par le serveur d'autorisation.

Cet identifiant unique, si vous utilisez l'API de l'autorité Prenly à distance, est le paramètre de requête `uid` lors de la demande d'informations sur le résumé de l'utilisateur.

Vous pouvez choisir l'une des méthodes suivantes :

- A partir d'une propriété dans la réponse du point de terminaison du jeton JSON. Si vous choisissez cette méthode, vous devez nous informer du nom de la propriété que vous avez choisie et qui contient l'identifiant de l'utilisateur.

- À partir de la réclamation OpenID Connect "sub" dans le jeton d'identification signé (tel que renvoyé par la propriété "id_token" de la réponse au jeton).
Pour pouvoir extraire l'identifiant de l'utilisateur, vous devez également fournir :

◦ Requis. L'URL externe vers les clés publiques pour valider les jetons d'identification. Cette URL doit contenir un jeu de clés Web JSON conforme aux normes JWT, qui peut être appelé JKU ou JWKS.
◦ Facultatif. Le nom de la propriété dans la réponse des données utilisateur qui contient un numéro de client.

- À partir de la réponse de propriété "sub" d'un point de terminaison UserInfo.
Pour utiliser cette méthode, vous devez également fournir :

◦ Obligatoire. L'URL du point de terminaison UserInfo. Le point de terminaison est utilisé pour obtenir des informations de base sur l'utilisateur en utilisant le jeton d'accès de l'utilisateur pour autoriser la demande.
◦ Facultatif. Le nom de la propriété dans la réponse de données d'utilisateur qui contient un numéro de client.

Serveur de ressources

Vous pouvez choisir un serveur de ressources que Prenly prend en charge ou vous êtes libre de nous contacter à l'adresse hello@prenly.com pour faire une demande à Prenly de prendre en charge votre serveur de ressources spécifique en tant que tâche d'intégration, que Prenly pourrait prendre en charge sur la base d'une tâche de développement payée.

Prenly supporte l'API Prenly Remote authority à partir de la version 1.4 comme serveur de ressources. Voir nos informations générales sur l'API Prenly Remote authority pour le concept de cette API. Pour mettre en œuvre l'API Prenly Remote authority en tant que serveur de ressources, veuillez consulter la spécification de l'API pour le point de terminaison /oauth2/getUser.

La "ressource" que Prenly demande au serveur de ressources est une liste de produits d'abonnement associés à l'utilisateur. Les produits, sous la forme d'un code produit, indiquent le statut de l'abonnement de l'utilisateur, chaque code étant configuré pour accorder un accès en lecture aux publications dans votre application e-paper.

Pour accorder l'accès en lecture correct en fonction du produit d'abonnement, vous devez également indiquer à Prenly les publications auxquelles le code produit autorise l'accès en lecture. Tout produit inconnu sera ignoré.

Vous n'avez peut-être pas besoin d'un serveur de ressources dédié...

Prenly peut se passer d'un serveur de ressources traditionnel si votre point de terminaison UserInfo est capable d'exposer le statut d'abonnement du propriétaire de la ressource - l'utilisateur.

Si votre point d'accès UserInfo en est capable, tout ce que vous aurez à fournir est la réclamation (nom de la propriété) dans les données JSON de la réponse du point d'accès UserInfo.

La valeur de la demande doit être une liste JSON (tableau) de chaînes de caractères. Chaque élément de la liste représente un code de produit d'abonnement.

Fournir des informations

Lorsque vous disposez de toutes les informations requises, veuillez contacter le service clientèle de Prenly à l'adresse hello@prenly.com. L'équipe configurera alors l'autorité Prenly de l'application e-paper choisie pour qu'elle utilise OAuth2 pour vous.