Authentification
Authentification
Trois types d’authentification HTTP sont possibles via les Web Services : Basic, via un token Bearer, en OAuth2.
Authentification Basic
L’authentification Basic transmet login:password encodé en Base64 au serveur.
Il faut ajouter un header Authorization à la requête HTTP avec la valeur “Basic” espace la valeur en Base64.
Par exemple, si le login est “user” et le mot de passe “toto”, la valeur encodée en Base64 de user:toto est dXNlcjp0b3Rv. La valeur du Header Authorization sera donc : Authorization: Basic dXNlcjp0b3Rv.
Il faut également ajouter un header X-API-KEY à la requête HTTP avec l’api key récupéré sur le Hub.
Pour plus d’informations sur l’api key, voir la section API Key → dans le menu.
Authentification Bearer
L’authentification Bearer utilise un token qui permet au serveur d’identifier l’utilisateur.
Pour récupérer un token Bearer, il faut effectuer une requête HTTP GET à l’adresse https://<yellowbox_url>/ws/authentication avec le header Authorization décrit dans le paragraphe précédent. Si l’authentification est validée, YellowBox renvoie un token sous forme de texte.
Pour utiliser ce token sur les prochains appels de web services, il suffit de rajouter le header Authorization avec la valeur “Bearer” espace le token. La valeur du header Authorization pourrait donc être par exemple : Authorization: Bearer eyJhbGciOiJIUzI1NiJ8.eyJpc3MiOiJhdXRoMCJ9.s69x7Mmu4JqwmdxiK6sesALO8tcedbFsKEEITUxw9ho.
La durée de validité d’un token est de 5 minutes depuis le dernier appel d’un web service.
Il faut également ajouter un header X-API-KEY à la requête HTTP avec l’api key récupéré sur le Hub.
Pour plus d’informations sur l’api key, voir la section API Key → dans le menu.
Authentification via Swagger
Il est possible d’utiliser les web services de YellowBox directement depuis la documentation Swagger. Pour ce faire, il faut cliquer sur le bouton Authorize présent à droite. Une fenêtre s’ouvre où il suffit de renseigner le login et mot de passe à utiliser et de cliquer sur le bouton Authorize. Swagger créé ainsi une authentification Basic et rajoute pour chaque appel de web service, annoté avec un cadenas sur la droite, le header Authorization avec la bonne valeur.
Pour tester un web service, il faut cliquer sur le bouton Try it out et renseigner les paramètres ou body de la requête puis cliquer sur le bouton Execute.
La réponse apparaît alors en dessous.
Authentification via Postman
Postman permet de gérer plusieurs types d’authentification dont Basic et Bearer. Pour ce faire, il faut aller dans l’onglet Authorization puis sélectionner le type d’authentification voulu dans le sélecteur (Basic Auth ou Bearer Token) et de renseigner les champs en fonction du type choisi.
Un clic sur le bouton Preview Request permet d’ajouter automatiquement le header Authorization et de prévisualiser sa valeur en fonction du type.
Il faut également ajouter un header X-API-KEY à la requête HTTP avec l’api key récupéré sur le Hub.
Pour plus d’informations sur l’api key, voir la section API Key → dans le menu.
Il faut noter que l’utilisation de l’authentification Bearer permet d’optimiser les temps de connexion.
Initialisation de l’authentification en OAuth2
Dans le cas ou Yellowbox est paramétré en type d’authentification OAuth2, les appels aux webservices doivent être en OAuth2 également.
Faire un appel à https://<yellowbox_url>/apps/oauth2/microsoft/getAuthorizeUrlAction.do?type=webservice
Il faut ensuite s’authentifier à l’aide de l’URL retournée. Pour cela, ouvrir cette URL en utilisant un navigateur Internet.
Une fois l’authentification effectuée on récupère un access token, c’est cet access_token qui sera utilisé pour tous les appels de webservices.
Lors d’un appel web service on ajoute le header authorization avec en valeur Bearer (à noter l’espace après Bearer) et le token que l’on vient de récupérer. Idem qu’une authentification Bearer mais avec l’access_token obtenu.
Il faut également ajouter un header X-API-KEY à la requête HTTP avec l’api key récupéré sur le Hub.
Pour plus d’informations sur l’api key, voir la section API Key → dans le menu.
Important
Afin d’assurer le bon fonctionnement, il est nécessaire au préalable de définir les authorisations d’authentification de Microsoft avec l’URL de votre YellowBox.
A travers le paramétrage de Microsoft, rajouter l’url suivante dans les URLs de redirection :
https://<yellowbox_url>/ws/authentication/callback
Si vous rencontrez l’erreur suivante :
Une documentation sur l’authentification via Office365 est disponible.