Prise en main de l'API
- Nicolas Rueff
Le backend Right Consents est disponible sous la forme d'une API REST. La documentation complète de l'API est générée par le backend lui-même à l'aide des normes swagger et OpenAPI. Elle est servie par le backend lui-même et est toujours synchronisée avec la version en cours.
L'API de consentement est plus ou moins similaire à un paiement en ligne : un utilisateur privilégié crée la transaction et la transmet au client. Il n'est pas obligatoire d'avoir un client authentifié pour effectuer la transaction.
Accès à l'interface utilisateur de l'API REST
Si vous avez suivi le guide de démarrage rapide, vous devriez pouvoir accéder à l'interface locale de la documentation de l'API. Si vous avez une instance spécifique de Right Consents, il vous suffit d'adapter l'URL avec le nom de domaine ou l'adresse IP de votre instance.
Le fichier swagger correspondant est disponible à l'adresse https://<consent-manager>/swagger-ui.
Authentification
Les consentements de droit définissent cinq rôles d'application : administrateur, opérateur, utilisateur, transaction ou anonyme. Pour obtenir un rôle, les appels à l'API doivent être authentifiés. Right Consents prend en charge 3 schémas d'authentification différents : jeton OIDC, API KEY et token.
Dans ce guide, nous allons initier une transaction en tant qu'utilisateur administrateur et laisser le sujet suivre le flux de travail de la transaction en utilisant des jetons intégrés. Vous pouvez utiliser un jeton OIDC ou une clé API pour accéder à l'API.
Recevoir un jeton d'accès
Vous pouvez par exemple utiliser curl pour récupérer un jeton d'accès sur le fournisseur d'identité (IdP) :
TOKEN="Bearer "+`curl -v -d "client_id=cmclient" -d "username=<user>" -d "password=<password>" -d "grant_type=password" https://<serveur d'auth>/auth/realms/FairAndSmart/protocol/openid-connect/token | jq -r '.access_token'`Le jeton d'accès a une durée de validité courte (5mn) et vous devrez le renouveler au cours du guide, il vous suffira de rejouer cette demande lorsque vous en aurez besoin.
Générer une clé API
Au lieu de récupérer un jeton OIDC auprès de l'IdP, vous pouvez générer une clé à partir du backoffice et utiliser cette clé directement dans un en-tête de requête spécifique. La clé API n'expirera jamais et a un rôle spécifique qui n'est pas administrateur et vous pouvez révoquer la clé si vous pensez qu'elle a été corrompue ou divulguée.
Voir Clés d'API | Gestion pour la génération.
La clé peut être générée à partir d’un appel à l’API :
export KEY=$(curl -s https://##CONSENT_MANAGER_SERVER##/keys' -H 'Authorization: Bearer ##JETON##' --data-raw '{"name":"##KEY_NAME","scope":"OWNER"}' | jq -r .key)Sachez que l'utilisation d'une clé API n'est pas aussi sûre qu'un jeton OIDC et que vous ne devez l'utiliser que dans les appels HTTPS à l'API, et ne jamais l'envoyer à un code côté client.
Créer une transaction
La transaction est créée par un administrateur ou un opérateur API pour un sujet particulier. La création de la transaction doit être effectuée côté serveur pour garantir que l'accès de l'administrateur à l'API ne soit pas divulgué dans le code du client et pour garantir les meilleures capacités du scénario d'intégration. Une fois créée, l'URL de la transaction doit être transmise au sujet ciblé par le canal souhaité (courriel, redirection web...).
Il est possible pour un simple utilisateur de créer une transaction pour lui-même. Cela permet un déploiement côté client mais implique d'avoir un schéma d'authentification unifié et une application client compatible Ajax. Cette intégration sera détaillée dans d'autres guides.
Définir un contexte de consentement
Pour créer une transaction de consentement, nous devons envoyer un contexte de consentement (sujet, présentation et configuration) à l'API. Le contexte peut être conçu à l'aide du concepteur de formulaires du backoffice, puis adapté à votre cas d'utilisation de l'intégration ; si vous êtes familiarisé avec son format, vous pouvez également en générer un à partir de zéro.
Voici le contexte de consentement le plus simple possible avec une configuration complète par défaut.
{
"subject": "testuser@demo.com",
"layoutData": {
"type":"layout",
"elements":["processing.001"],
"orientation":"VERTICAL",
"info":"information.001"
}
}Créer la transaction
Utilisez le jeton précédemment récupéré pour créer la transaction pour l'objet cible : testuser@demo.com en envoyant la charge utile du contexte à la ressource "consents" de l'API :
La réponse contiendra la représentation de la transaction créée dans son corps. Cette représentation contient l'identifiant de la transaction et le jeton de transaction pour l'autorisation. La réponse contient également un en-tête "Location" avec l'URI de la ressource déjà formaté.
Le cycle de vie de la transaction suit 6 états : CREATED, SUBMITTED, COMMITTED, CANCELLED, TIMEOUT, ROLLBACK. Après la création, la transaction se trouve dans l'état CREATED.
Après la création, c'est au sujet cible d'interagir avec l'API. L'API prend en charge deux modes d'interaction : HTML et JSON.
En mode HTML, le client est supposé être un navigateur et tout est fait pour simplifier les interactions avec l'API grâce à des redirections et à un rendu HTML automatiques. Ce mode est conçu pour être intégré dans un site web ou une application existante avec des vues web en utilisant des IFrame ou des redirections web.
En mode JSON, les principes REST sont appliqués et la représentation des transactions de consentement est générée. Tout le rendu du formulaire de consentement et de la représentation de la transaction doit être mis en œuvre manuellement du côté du client.
Dans les prochaines étapes, nous allons explorer les deux modes.
Compléter le flux de travail de la transaction (mode HTML)
En HTML, vous devez utiliser l'URI de la transaction renvoyée dans l'en-tête "Location" ou construire l'URI de la transaction à partir de la représentation de la ressource renvoyée. Lorsque le mimetype text/html est requis par l'API, un simple appel à la ressource racine de la transaction effectuera la redirection nécessaire vers la prochaine tâche humaine du flux de travail à accomplir.
Ouvrez la vue HTML de la transaction de consentement
Il est très facile de suivre le déroulement de la transaction en mode HTML. Il suffit d'ouvrir l'URI de la transaction dans un navigateur :
L'API est pilotée par le navigateur pour suivre les étapes du flux de travail. À l'état final et sans url de rappel spécifiée, le sujet reste sur la représentation de la transaction. En fonction de la configuration, cette vue permet de créer une nouvelle transaction basée sur celle-ci pour modifier le consentement, récupérer le reçu du consentement ou fermer la fenêtre.
Compléter le flux de travail de la transaction (mode JSON)
Obtenir la représentation de la transaction
Pour obtenir la représentation de la transaction, il suffit d'effectuer un GET sur la ressource de la transaction.
Voici une version abrégée de la transaction qui s'est déroulée juste après la création :
Obtenir le formulaire de consentement et soumettre les valeurs
Lorsque la transaction est dans l'état CREATED, l'étape suivante est submit : la soumission du consentement. L'appel à l'url du champ "task" produira le formulaire nécessaire à la soumission du consentement et inclura un lien de soumission avec un nouveau jeton si nécessaire.
Vous pouvez construire l'URI de la tâche humaine suivante en obtenant le champ de la tâche et le jeton de la transaction :
Vous pouvez maintenant appeler la représentation de la tâche de soumission qui renverra la représentation du formulaire de consentement :
Le formulaire de consentement contient de nombreuses informations qui sont utilisées dans le rendu HTML. En JSON, vous devez faire tout ce qu'il faut pour afficher les informations et les options du formulaire. Vous devez également construire les choix de consentement dans un format adapté à l'API, une carte d'identifiants d'éléments et de réponses aux choix :
Obtenir à nouveau la représentation de la transaction
Notez que la transaction est maintenant dans l'état COMMITTED.
En fonction de la configuration du contexte, une étape de validation peut également être nécessaire en envoyant un code par courrier électronique ou par SMS au sujet afin de vérifier une nouvelle fois son identité.
Code de prise en main
Retrouvez un projet de prise en main de ces concepts ici :