Configuration d'Azure Active Directory pour les scripts côté serveur

Aperçu

Dans certains cas, vous voudrez effectuer une tâche spécifique qui peut être automatisée mais qui doit pouvoir accéder à l'API GraphQL de WorkflowGen; ce cas d'usage est souvent sous forme d'un script ou d'une application côté serveur (p.ex. : background service, daemon, curl , Postman, etc...). Pour ceci, OAuth2 fournit un type d'octroi appelé Client Credentials (informations d'identification du client) qui échange tout simplement un ID client et une clé secrète client pour un jeton d'accès. Il n'y a aucun jeton ID car ceci ne fait pas partie du standard OpenID Connect et aucun utilisateur n'est impliqué.

Cette section fournit des instructions sur la façon de configurer Azure AD pour qu'un script ou une application côté serveur ait accès à l'API WorkflowGen GraphQL. Tout d'abord, vous devez inscrire une nouvelle application Web dans Azure AD; ensuite, vous devrez configurer une nouvelle application dans votre serveur Web WorkflowGen.

Prérequis

  • Assurez-vous d'avoir une copie de WorkflowGen sous licence installée et en fonctionnement sur un serveur Web IIS en mode de connexion sécurisé HTTPS.

  • Assurez-vous d'avoir un accès administratif à WorkflowGen.

  • Assurez-vous d'avoir un accès administratif à Azure Active Directory pour pouvoir le configurer correctement.

  • Assurez-vous d'avoir bien configuré l'authentification déléguée à Azure AD sur votre instance de WorkflowGen en suivant les instructions dans la section Authentification Azure Active Directory.

  • Assurez-vous d'avoir configuré avec succès l'authentification déléguée à Azure AD sur votre instance WorkflowGen en suivant les instructions de la section Authentification Azure Active Directory avec l'application WorkflowGen GraphQL API également enregistrée.

Configuration d'Azure Active Directory

Étape 1 : Inscrivez une nouvelle application Web

  1. Dans le portail Azure, cliquez sur Inscriptions d'applications dans la section Azure Active Directory.

  2. Cliquez sur Nouvelle inscription, puis saisissez les propriétés :

    • Nom : Nom de votre script, service ou application

    • Types de comptes pris en charge : Comptes dans cet annuaire d'organisation uniquement (Locataire unique)

      ✏️ Note : Selon le contexte, vous devez choisir la bonne option pour votre cas d'utilisation pour la valeur du type de compte supporté.

    • URI de redirection : Laissez ce champ vide

  3. Cliquez sur S'inscrire en bas de la page.

Vous avez maintenant inscrit avec succès votre application dans Azure Active Directory.

Étape 2 : Accordez l'accès à l'API GraphQL WorkflowGen

  1. Cliquez sur API autorisées.

  2. Dans la section Autorisations configurées, cliquez sur Ajouter une autorisation.

  3. Cliquez sur Mes API, puis sélectionnez l'application WorkflowGen GraphQL API dans la liste.

  4. Cliquez sur Autorisations déléguées, puis cochez defaut dans la colonne Autorisation.

  5. Cliquez sur Ajouter des autorisations.

  6. Dans la page API autorisées, cliquez sur Accorder un consentement administrateur pour <votre nom de locataire>, puis cliquez sur Oui.

Étape 3 : Générez une clé secrète client pour l'application

  1. Dans le menu de l'inscription de l'application, cliquez sur Certificats & secrets.

  2. Dans la section Secrets client, cliquez sur Nouveau secret client.

    • Description : Mon secret, ou quelque chose qui l'identifie comme clé secrète client

    • Date d'expiration : Choisissez 24 moi ou la période d'expiration souhaité.

  3. Cliquez sur Ajouter.

  4. La clé secrète client générée automatiquement est maintenant affichée dans la colonne Valeur. Copiez la valeur de la clé secrète client et enregistrez-la dans un endroit sûr, car vous ne pourrez plus la récupérer par la suite.

Depuis la dernière mise à jour du portail Azure, il n'est plus possible de définir des clés secrètes client pour qu'elles n'expirent jamais. Vous devrez régénérer manuellement une nouvelle clé secrète client tous les deux ans (si l'option 24 months a été sélectionnée) avant qu'elle n'expire. Ensuite, mettez à jour la clé secrète client utilisée par l'instance WorkflowGen dans son fichier de configuration Web.

Vérifiez l'inscription

Voici un aperçu des informations dont vous aurez besoin :

  • Un ID client : Ceci est l'ID d'application (client) dans la section d'aperçu de votre inscription d'application.

  • Une clé secrète client : Ceci est la valeur que vous avez générée dans la section Certificates & secrets.

  • Un ID locataire : Ceci est l'ID de répertoire (locataire) dans la section d'aperçu de votre inscription d'application.

  • Une étendue : L'étendue de l'application WorkflowGen GraphQL API dans la section Exposer une API. ✏️ Note : Vous devez ajouter un point (.) avant le nom de l'étendue defaut dans l'URL lors de la transmission de l'étendue en tant que paramètre dans la demande pour récupérer le jeton d'accès (p.ex. : https://<url workflowgen>/graphql/.default). Voir le paramètre scope dans l'exemple cURL.

Vous avez maintenant enregistré avec succès votre script ou application côté serveur dans Azure AD.

Configuration de WorkflowGen

Comme pour l'approvisionnement des utilisateurs, WorkflowGen a besoin de savoir quelle application accède à l'API GraphQL. Par conséquent, vous devez enregistrer l'application dans WorkflowGen, qui se compose de votre script ou application côté serveur.

Inscrivez une nouvelle application

  1. Dans la page Applications du module d'administration WorkflowGen, cliquez sur Nouvelle application.

  2. Renseignez le formulaire :

    • Nom : Mon application serveur

    • Description : Une description qui identifie clairement votre script, service ou application

    • Type : Client non interactif

    • Nom d'utilisateur d'impersonnification : Tout nom d'utilisateur WorkflowGen ayant l'accès requis à l'API GraphQL

    • ID client : L'ID client que vous avez récupéré précédemment lors de l'inscription de votre application dans Azure AD

    • Actif : Cochez cette case

  3. Cliquez sur Save.

Votre application devrait maintenant apparaître dans la liste des applications WorkflowGen.

Vous devriez maintenant avoir les composants nécessaires en place pour effectuer des demandes d'API GraphQL avec votre script ou application côté serveur en transmettant le jeton d'accès qui a été précédemment récupéré à partir du point de terminaison du jeton Azure OAuth2 à l'aide du flux d'octroi des informations d'identification du client.

Utilisation du jeton d'accès

Pour que votre script ou application côté serveur envoie des requêtes à l'API WorkflowGen GraphQL, vous devez d'abord obtenir un jeton d'accès à partir de votre point de terminaison de jeton Azure OAuth2. Voici des exemples de la façon d'obtenir un jeton d'accès pour votre application et de faire une demande à l'API GraphQL.

Récupérer le jeton d'accès d'Azure pour votre application

Requête cURL

curl --location --request POST 'https://login.microsoftonline.com/<Tenant ID>/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<Client ID>' \
--data-urlencode 'client_secret=<Client Secret>' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=https://<workflowgen url>/graphql/.default'

Il est suggéré d'utiliser l'URL du point de terminaison du jeton OAuth2 v2.0 (p.ex. : https://login.microsoftonline.com/<Tenant ID>/oauth2/v2.0/token), qui fonctionne à la fois pour les fournisseurs Microsoft Identity Platform v2.0 et Azure v1.

Vous devez également ajouter un point (.) avant le nom de l'étendue par défaut dans l'URL lors de la transmission de l'étendue en tant que paramètre dans la demande de récupération du jeton d'accès (p.ex. : https://macompagnie.com/wfgen/graphql/.default). Voir le paramètre scope dans l'exemple cURL ci-dessus.

Si vous avez configuré la section Appel des APIs tierces avec le jeton d'accès, la valeur du paramètre scope doit être api://my-apis/.default au lieu de https://<url workflowgen>/graphql/.default.

Réponse JSON

{
"token_type": "Bearer",
"expires_in": 3599,
"ext_expires_in": 3599,
"access_token": "<access token>"
}

Pour inspecter le contenu du jeton d'accès, vous pouvez copier et coller la valeur de la chaîne <access token> dans le site Web jwt.io. Le jeton d'accès est un JSON Web Token.

Par défaut, le jeton d'accès expire dans 3599 secondes, soit environ une heure.

Requête de l'API GraphQL avec le jeton d'accès

Requête cURL pour obtenir le nom d'utilisateur du visionneur de WorkflowGen

curl --location --request POST 'https://mycompany.com/wfgen/graphql' \
--header 'Authorization: Bearer <access token>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'query={
viewer {
userName
}
}'

Réponse JSON de l'API GraphQL

{
"data": {
"viewer": {
"userName": "[email protected]"
}
}
}

Pour plus d'informations sur le flux d'octroi des informations d'identification du client OAuth 2.0 d'Azure et des exemples supplémentaires, voir le guide Plateforme d’identités Microsoft et flux d’informations d’identification du client OAuth 2.0.