Page Comparison

...

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.

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​

Utiliser Vous pouvez par exemple utiliser curl pour récupérer un jeton d'accès sur le fournisseur d'identité (IdP) :

...

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 :

export KEY=$(curl -s https://##CONSENT_MANAGER_SERVER##/keys' -H 'Authorization: Bearer ##JETON##' --data-raw '{"name":"##KEY_NAME","scope":"OWNER"}' | jq -r .key)

...

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...).

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.

...

{
  "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 :

...

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.

TX_URI=https://<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.

...

{
   "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.

...

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​

TX=`curl -v --header "CM_KEY: ${KEY}" \
            --header "Authorization: ${TOKEN}" \
            --header "Accept: application/json" \
            https://<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 :

...