Apprendre à utiliser l'API Right Consents pour les opérations de base :
Comprendre les concepts et les ressources de base de l'API
Créer une transaction de consentement
Suivre le flux de travail de la transaction
Utiliser curl pour effectuer des appels API de base pour un scénario simple de collecte de consentement
Dans ce guide, vous découvrirez les concepts de base et les ressources de l'API. Nous utiliserons certains modèles d'éléments de consentement existants pour créer une transaction et suivre le déroulement de la transaction en utilisant uniquement des appels à l'APILe 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.
Table of Contents |
---|
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.
Info |
---|
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 jeton intégrétoken.
Dans ce guide, nous allons initier une transaction en tant qu'utilisateur administrateur et laisser le sujet cible 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
Utiliser Vous pouvez par exemple utiliser curl pour récupérer un jeton d'accès sur le fournisseur d'identité (IdP) :
Code Block |
---|
TOKEN="Bearer "+`curl -v -d "client_id=cmclient" -d "username=demo@demo.com<user>" -d "password=demo42<password>" -d "grant_type=password" httphttps://localhost:4285<serveur d'auth>/auth/realms/RightConsentsFairAndSmart/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.
Pour générer une clé API, allez dans le backoffice dans la section "Intégration" et la sous-section "Sécurité" et créez une nouvelle clé API avec un champ d'application "Propriétaire". La clé n'est visible que lors de la génération, n'hésitez pas à la stocker quelque part.
Vous pouvez créer une variable bash permettant à la commande suivante d'aboutir Voir https://fairandsmart.atlassian.net/wiki/spaces/BDC/pages/edit-v2/2594603023#Gestion pour la génération.
La clé peut être générée à partir d’un appel à l’API :
Code Block |
---|
export KEY="<PUT THE GENERATED KEY HERE>"$(curl -s https://##CONSENT_MANAGER_SERVER##/keys' -H 'Authorization: Bearer ##JETON##' --data-raw '{"name":"##KEY_NAME","scope":"OWNER"}' | jq -r .key) |
Note |
---|
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...).
Info |
---|
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.
Code Block | ||
---|---|---|
| ||
{ "subject": "testuser@demo.com", "layoutData": { "type":"layout", "elements":["processing.001"], "orientation":"VERTICAL", "info":"information.001" } } |
Info |
---|
Ce contexte utilise des éléments déjà créés dans le guide du premier formulaire de consentement : information.001, traitement.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 :
Code Block |
---|
TX=`curl -v --header "Content-Type: application/json" \ --header "CM_KEY: ${KEY}" \ --header "Authorization: ${TOKEN}" \ --request POST \ --data '{"subject":"testuser@demo.com","layoutData":{"type":"layout","elements":["processing.001"],"orientation":"VERTICAL","info":"information.001"}}' \ httphttps://localhost:4287<consent-manager>/consents` && TX_ID=`echo $TX | jq -r .id` && TX_TOKEN=`echo $TX | jq -r .token` |
...
Le cycle de vie de la transaction suit 6 états : CRÉÉCREATED, SOUMISSUBMITTED, ENGAGÉCOMMITTED, ANNULÉ, DÉLAI D'ATTENTE, RETOUR EN ARRIÈRECANCELLED, TIMEOUT, ROLLBACK. Après la création, la transaction se trouve dans l'état CREATED.
...
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.
Code Block |
---|
TX_URI=httphttps://localhost:4287<consent-manager>/consents/${TX_ID}?t=${TX_TOKEN} |
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.
Code Block |
---|
TX=`curl -v --header "CM_KEY: ${KEY}" \ --header "Authorization: ${TOKEN}" \ --header "Accept: application/json" \ httphttps://localhost:4287<consent-manager>/consents/${TX_ID}` |
Voici une version abrégée de la transaction qui s'est déroulée juste après la création :
Code Block | ||
---|---|---|
| ||
{ "id":"P6f1JU6LjKoUwR5QBEYPgf", "subject":"usertest", "state":"CREATED", "token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJQNmYxSlU2TGpLb1V3UjVRQkVZUGdmIiwiZXhwIjoxNjYwOTMwMzMyfQ.0pGomVcjvGGWshhovRpCKjP6BVOt2K6-W6QXLCVlwsA", "task":"http://localhost:4287/consents/P6f1JU6LjKoUwR5QBEYPgf/submit", "breed":"http://localhost:4287/consents/P6f1JU6LjKoUwR5QBEYPgf/child" } |
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.
...
Code Block |
---|
FORM_VALUES='{"info":["element/information/'`echo ${TX_FORM} | jq -r '.info.entry.key'`/`echo ${TX_FORM} | jq -r '.info.serial'`'"],"element/processing/'`echo ${TX_FORM} | jq -r '.elements[0].entry.key'`/`echo ${TX_FORM} | jq -r '.elements[0].serial'`'":["accepted"]}' && SUBMIT_JSON=`curl -v --header "CM_KEY: ${KEY}" \ --header "Authorization: Bearer ${TOKEN}" \ --header "Content-Type: application/json" \ --header "Accept: application/json" \ --request POST \ --data ${FORM_VALUES} \ ${TX_TASK}?t=${TX_TOKEN}` |
Obtenir à nouveau la représentation de la transaction
Code Block |
---|
TX=`curl -v --header "CM_KEY: ${KEY}" \ --header "Authorization: ${TOKEN}" \ --header "Accept: application/json" \ httphttps://localhost:4287<consent-manager>/consents/${TX_ID}` && echo ${TX} |
...
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 :
...