Conseils d'utilisation de l'API
Quelques conseils pour utiliser au mieux notre API.
Contenu de cette documentation :
La documentation de l’API
La documentation est accessible aux adresses suivantes :
backend core : https://core.fairandsmart.com/swagger-ui/
backend data : https://data-fr01.fairandsmart.com/swagger-ui/
backend timestamp : https://tsa.fairandsmart.com/swagger-ui/
Mise en place d’un compte technique pour l’utilisation de l’API
Si dans l’absolu il est possible d’utiliser n’importe quel compte ayant accès à l’organisation pour faire des appels à l’API, il est préférable de créer un compte technique dédié à cet usage.
Cette pratique permet d’une part de mitiger le risque de l’utilisation du compte d’un collaborateur qui peut être amener à ne plus avoir accès à l’application - changement de poste, départ de l’entreprise - mais aussi de configurer les rôles au plus fin de manière à restreindre les opérations possibles au strict minimum.
La première étape est de définir un rôle spécifique et lui attribuer uniquement les opérations dont il aura besoin, par exemple Générer un lien de collecte de consentement et Évaluer le statut d'un consentement avec une requête.
La seconde étape est d’inviter cet utilisateur technique : pour cela suivre la procédure d’invitation d’un collaborateur en précisant qu’il doit bénéficier uniquement du rôle nouvellement créé.
Puis procéder à l’onboarding du compte technique de manière standard.
Authentification des accès
L’accès à l’API se fait via un jeton d’acces (access_token) via auprès du serveur d’authentification OAuth2 https://auth.fairandsmart.com/ . Ce jeton est obtenu après deux appels :
un premier pour obtenir un refresh_token à longue durée de vie (30 jours) mais qui ne sert qu'à récupérer des access_token ;
un second pour obtenir un access_token à courte durée de vie (5 minutes) qui lui ne sert qu'à requêter notre API ;
Exemple de cinématique (il vous faudra un environnement linux équipé de curl et jq pour le faire fonctionner) :
# récupération d'un refresh_token
export REFRESH_TOKEN=$(/usr/bin/curl --fail --silent \
https://auth.fairandsmart.com/auth/realms/FairAndSmart/protocol/openid-connect/token \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode username=MY_USERNAME \
--data-urlencode password=MY_PASSWORD \
--data-urlencode grant_type=password \
--data-urlencode client_id=fsorg \
| jq -r '.refresh_token')
# récupération d'un access_token
export ACCESS_TOKEN=$(/usr/bin/curl --fail --silent \
https://auth.fairandsmart.com/auth/realms/FairAndSmart/protocol/openid-connect/token \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode "refresh_token=${REFRESH_TOKEN}" \
--data-urlencode "client_id=fsorg" \
| jq -r '.access_token')A la fin des appels, l’environnement contient deux variables : REFRESH_TOKEN (validité 30 jours) pour récupérer d’autres access_token, et ACCESS_TOKEN (validité 5 minutes) pour interroger l’API.
Il est conseillé de conserver une copie du refresh_token pour éviter d’avoir à ouvrir une nouvelle session à chaque appel REST, et le renouveler uniquement si nécessaire.
Bien qu’il soit possible d’obtenir un access_token dès le premier appel, il est conseillé de prendre l’habitude de passer par le mécanisme refresh_token → access_token pour éviter d’avoir à ouvrir une nouvelle session à chaque appel REST, et le renouveler uniquement si nécessaire.
Ce fonctionnement permet en outre de pouvoir modifier le mot de passe du compte utilisé pour récupérer refresh et access token de manière asynchrone, et de ne pas se couper l’accès à l’API le temps de propager le changement de production de le code de votre applicatif.
Choix d’un User ID lors de la génération d’un formulaire de consentement
Un User ID doit être passé aux appels de génération des endpoints de collecte de consentement (https://core.fairandsmart.com/swagger-ui/). Dans la mesure où cet identifiant figure en clair dans le registre de consentements, sa définition doit présenter des garanties appropriées.
Ainsi nous recommandons d'éviter de choisir un User ID permettant d’identifier directement un utilisateur, en utilisant un pivot qui nécessite l’accès à votre SI pour être résolu.
En particulier l’utilisation des noms-prénoms, adresses email, n° SS ou même d’une version obfusquée réversible tel que l'encodage en base64 de ces attributs sont à éviter.
Pour aller plus loin