Authentification Azure Active Directory

Aperçu

Cette section contient les instructions sur la configuration de l'authentification déléguée de WorkflowGen avec le point de terminaison (« endpoint ») v1 de l'API d'authentification Azure AD ou avec Microsoft Identity Provider (Plateforme d"identités Microsoft) v2.0. Elle contient également des instructions sur la configuration d'une instance de WorkflowGen en fonctionnement qui utilise Azure pour l'authentification des utilisateurs.

Dans les instructions, remplacez <workflowgen url> par le domaine et le chemin de votre instance de WorkflowGen; par exemple, localhost/wfgen ou www.macompagnie.com/wfgen.

Prérequis

• Assurez-vous d'avoir une copie de WorkflowGen sous licence installée et en fonctionnement sur un serveur. Vous devez être un administrateur WorkflowGen.

• Assurez-vous d'avoir l'accès d'administrateur Azure AD pour pouvoir configurer Azure AD.

• Assurez-vous d'avoir approvisionné un utilisateur Azure AD existant depuis lequel vous pourrez vous authentifier à WorkflowGen et que cet utilisateur a les permissions administratives. Ceci est important car une fois que vous aurez activé la délégation, vous devrez toujours pouvoir gérer l'application.

• Le mode de chiffrement AES et sa clé sont requis pour que l'authentification fonctionne.

Configuration d'Active Directory

La configuration d'Azure AD se fait dans deux parties. D'abord, vous devez inscrire l'application Web WorkflowGen et l'associer à votre instance de WorkflowGen; ensuite, vous devez inscrire l'API GraphQL de WorkflowGen pour pouvoir inscrire des applications personnalisées pour y accéder.

Étape 1 : Créez une nouvelle inscription d'application pour WorkflowGen

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

2. Cliquez sur Nouvelle inscription et entrez les propriétés :

   • Nom : WorkflowGen Web app

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

   • URI de redirection :

     • Type : Web

     • Valeur : https://<workflowgen url>/auth/callback

     ✏️ Note : En fonction du contexte, vous devez choisir la bonne option pour votre cas d'utilisation pour la valeur Types de comptes pris en charge. 📌 Exemple : https://macompagnie.com/wfgen/auth/callback

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

Vous devriez maintenant voir la page d'aperçu de l'application WorkflowGen inscrite.

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

Vous devez maintenant générer une clé secrète client pour utiliser dans le module d'authentification de WorkflowGen.

1. Cliquez sur Certificats & secrets.

2. Dans la section Secrets client, ajoutez une nouvelle clé.

   • DESCRIPTION : secret, ou quelque chose de semblable pour rappeler que ceci est la clé secrète client.

   • EXPIRE : Choisissez Jamais.

   • VALEUR : Une valeur avec une entropie suffisante pour être impossible à deviner.

3. Cliquez sur Enregistrer. La valeur que vous avez entrée sera maintenant cryptée.

4. Copiez la valeur générée car vous ne pourrez plus la rechercher par la suite.

Étape 3 : Ajoutez un URI de redirection

Pour que la communication entre WorkflowGen et Azure fonctionne, vous devez ajouter un autre URI de redirection autorisé à l'application Web WorkflowGen Web app enregistrée.

1. Cliquez sur Authentification.

2. Dans la section URI de redirection, entrez les informations suivantes :

   • Type : Web

   • URI de redirection : https://<workflowgen url>/auth/logout/return 📌 Exemple : https://macompagnie.com/wfgen/auth/logout/return ✏️ Note : Vous devriez également voirhttps://<workflowgen url>/auth/callback dans cette liste.

3. Cliquez sur Enregistrer en haut de la section.

Étape 4 : Créez une nouvelle inscription d'application pour l'API GraphQL de WorkflowGen

Pour exposer l'API GraphQL, vous devez ajouter une nouvelle application qui la représentera. Pour ce faire :

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

2. Cliquez sur Nouvelle inscription et renseignez le formulaire des propriétés :

   • Nom : WorkflowGen GraphQL

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

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

Vous avez maintenant correctement enregistré l'API GraphQL dans Azure AD.

Étape 5 : Exposez l'API dans l'inscription d'application de l'API WorkflowGen GraphQL

1. Cliquez sur Exposer une API.

2. À droite de URI ID d'application, cliquez sur Définir et entrez l'URI https://<workflowgen url>/graphql. 📌 Exemple : https://macompagnie.com/wfgen/graphql

3. Cliquez sur Ajouter une étendue et entrez les informations suivantes :

   • Nom de l'étendue : defaut

   • Qui peut accepter ? : Administrateurs et utilisateurs

   • Nom d'affichage du consentement d'administrateur : Accès par défaut à l'API WorkflowGen GraphQL

   • Description du consentement d'administrateur : Permet à l'application d'accéder à l'API WorkflowGen GraphQL

   • Nom d'affichage du consentement de l'utilisateur :

     Accès par défaut à l'API WorkflowGen GraphQL

   • Description du consentement de l'utilisateur : Permet à l'application d'accéder à l'API WorkflowGen GraphQL

4. Cliquez sur Ajouter une étendue.

5. Cliquez sur Enregistrer.

Depuis octobre 2021, Azure AD nécessite l'utilisation d'un schéma par défaut ou d'un domaine vérifié pour l'URL AppId sur l'application à locataire unique (voir la documentation Microsoft ici pour plus d'informations).

La documentation Microsoft sur la façon d'ajouter et de vérifier un domaine personnalisé est disponible ici.

Étape 6 : Accordez l'accès à WorkflowGen

1. Dans la page d'inscription de l'application WorkflowGen Web app, cliquez sur Autorisations de l'API.

2. Cliquez sur Ajouter une autorisation, puis cliquez sur Mes API.

3. Cliquez sur WorkflowGen GraphQL API dans la liste.

4. Cliquez sur Autorisations déléguées et cochez defaut.

5. Cliquez sur Ajouter des autorisations.

Vérifiez les inscriptions

Vous devriez maintenant avoir toutes les informations dont vous aurez besoin pour configurer WorkflowGen pour déléguer l'authentification à Azure AD. Voici un résumé :

• Un ID client. Ceci est l'ID de l'application WorkflowGen inscrite dans Azure. Vous pouvez l'ID sur la page d'aperçu de l'application.

• Une clé secrète client. Ceci est la clé secrète générée antérieurement.

• Une audience. Ceci est la propriété URI ID d'application dans la section Exposer une API.

• Le point de terminaison des métadonnées. Cette URL est liée à votre annuaire Azure. Pour la trouver :

  1. Naviguez à la section des propriétés de l'annuaire.

  2. Copiez la valeur Tenant ID.

  3. Le point de terminaison est formulé comme suit :

     Pour Azure v1 :

     https://login.microsoftonline.com/<Tenant ID>/.well-known/openid-configuration

     Pour Microsoft Identity Platform v2.0 :

     https://login.microsoftonline.com/<Tenant ID>/v2.0/.well-known/openid-configuration

Vous devriez maintenant avoir toutes les informations requises pour lier votre instance de WorkflowGen à Azure AD.

Configuration de WorkflowGen

Vous devez maintenant configurer WorkflowGen pour déléguer l'authentification à Azure AD.

Étape 1 : Ajoutez les valeurs Azure AD au web.config de WorkflowGen

1. Ouvrez le fichier web.config de WorkflowGen et ajoutez les propriétés suivantes sous <appSettings>: Pour Azure v1 :

   <!-- Azure v1 auth -->
   <add key="ApplicationSecurityAuthProvider" value="azure-v1"/>
   <add key="ApplicationSecurityAuthClientId" value="<CLIENT ID>" />
   <add key="ApplicationSecurityAuthClientSecret" value="<CLIENT SECRET>" />
   <add key="ApplicationSecurityAuthMetadataUrl" value="<METADATA URL>" />
   <add key="ApplicationSecurityAuthCheckSessionUrl" value="<CHECK SESSION URL>" />
   <add key="ApplicationSecurityAuthAppIdClaim" value="appid" />
   <add key="ApplicationSecurityAuthUsernameClaim" value="upn" />
   <add key="ApplicationSecurityAuthClockTolerance" value="60" />
   <add key="ApplicationSecurityAuthSessionRefreshEnableIFrame" value="Y"/>

   Pour Microsoft Identity Platform v2.0 :

   <!-- Microsoft Identity Platform v2 -->
   <add key="ApplicationSecurityAuthProvider" value="ms-identity-v2"/>
   <add key="ApplicationSecurityAuthClientId" value="<CLIENT ID>" />
   <add key="ApplicationSecurityAuthClientSecret" value="<CLIENT SECRET>" />
   <add key="ApplicationSecurityAuthMetadataUrl" value="<METADATA URL>" />
   <add key="ApplicationSecurityAuthAppIdClaim" value="appid" />
   <add key="ApplicationSecurityAuthUsernameClaim" value="preferred_username" />
   <add key="ApplicationSecurityAuthAccessTokenUsernameClaim" value="upn" />
   <add key="ApplicationSecurityAuthClockTolerance" value="60" />
   <add key="ApplicationSecurityAuthSessionRefreshEnableIFrame" value="Y"/>

   ✏️ Note : Check session iFrame n'est pas supporté dans Microsoft Identity Platform v2.

2. Remplacez <CLIENT ID> par l'ID de l'application.

3. Remplacez <CLIENT SECRET> par la clé secrète de l'application inscrite WorkflowGen générée dans Azure.

4. Remplacez <METADATA URL> par l'URL que vous avez formulée antérieurement depuis la valeur Tenant ID de votre annuaire Azure AD.

5. Remplacez <CHECK SESSION URL> par la valeur de la propriété check_session_iframe de la point de terminaison des métadonnées. (Voir le tableau ci-dessous pour plus d'informations sur cette propriété.)

   📌 Exemple de requête Linux / macOS :

   curl "<METADATA URL>" | python -m json.tool

   ✏️ Note : Enlevez | python -m json.tool si vous n'avez pas Python; ceci est pour l'impression automatique (« pretty printing »).

   📌 Exemple de requête Windows PowerShell : Invoke-RestMethod -Uri "<METADATA URL>" -Method GET | ConvertTo-JSON

Tableau des options web.config

Option	Description
ApplicationSecurityAuthProvider	Le nom du fournisseur d'identité supporté par WorkflowGen. À présent, seulement Azure Active Directory, Microsoft Identity Platform v2.0, Auth0, AD FS et Okta sont supportés. Valeur : azure-v1, ms-identity-v2,auth0, adfs, ou okta
ApplicationSecurityAuthClientId	Chaque fournisseur d'identité génère un code qui identifie uniquement votre application. Dans ce cas, cette valeur est le code qui identifie uniquement l'application Web WorkflowGen dans Azure Active Directory, Auth0, AD FS ou Okta.
ApplicationSecurityAuthClientSecret	Comme pour l'ID client, cette valeur est aussi générée par le fournisseur d'identité, mais est plutôt comme un mot de passe d'utilisateur. Il est important de le garder secret parce qu'un logiciel malveillant ayant accès pourrait agir au nom de l'application. Cette valeur doit être générée explicitement dans Azure Active Directory.
ApplicationSecurityAuthMetadataUrl	Le point de terminaison fourni par le fournisseur d'identité qui supporte le standard OpenID Connect Discovery. Il permet à WorkflowGen de récupérer des informations publiques sur votre domaine Azure Active Directory, sans lequel vous devrez effectuer beaucoup plus de configurations dans le fichier web.config.
ApplicationSecurityAuthAppIdClaim	Le nom de la revendication contenu dans le jeton d'accès obtenu du fournisseur d'identité qui identifie uniquement un client non-interactif. Il est utilisé seulement si vous avez une application machine-à-machine qui doit accéder à l'API GraphQL. Pour le configurer, voir la section Configuration d'Azure Active Directory pour les applications monopages. ✏️ Note : Il est recommandé de garder la valeur par défaut.
ApplicationSecurityAuthUsernameClaim	Le nom de la revendication contenue dans le jeton d'accès qui identifie l'utilisateur dans WorkflowGen. Il est utilisé par WorkflowGen pour générer un jeton de session ainsi que par l'API GraphQL en récupérant un jeton d'accès. ✏️ Note : Il est recommandé de garder la valeur par défaut.
ApplicationSecurityAuthAccessTokenUsernameClaim	Cette valeur est utilisée par l'API GraphQL lors de la réception d'un jeton d'accès. ✏️ Note : Il est recommandé de garder la valeur par défaut.
ApplicationSecurityAuthClockTolerance	Cette valeur est utilisée lors de la vérification d'un jeton dans WorkflowGen. Il est essentiellement pour gérer des différences mineures entre les horloges des serveurs. ✏️ Note : Il est recommandé de garder la valeur par défaut.
ApplicationSecurityAuthSessionRefreshEnableIFrame	Lorsqu'elle est activée (Y), cette option active la fonctionnalité d'auto-rafraîchissement de session à l'aide d'un <iframe> invisible. Cela permet aux utilisateurs d'entrer leurs mots de passe moins souvent en actualisant leur session en arrière-plan pendant qu'ils travaillent. ✏️ Note : Cette option est uniquement disponible lorsque WorkflowGen est configuré avec l'authentification OIDC.

WorkflowGen est maintenant lié à Azure AD et réciproquement. La dernière étape est de configurer quelques options pour finaliser le « câblage interne ».

Étape 2 : Ajoutez des valeurs de sécurité pour la génération de session

Pour générer un jeton de session, vous devez ajouter quelques configurations au fichier web.config.

1. Ouvrez le fichier web.config de WorkflowGen et ajouter la propriété suivante sous <appSettings> :

    <!-- Auth -->
    <add key="ApplicationSecurityAuthSessionTokenSigningSecret" value="<SECRET>" />

2. Remplacez <SECRET> par une valeur qui ne peut pas être devinée, comme un UUID.

Le secret sera seulement accessible dans votre instance de WorkflowGen, donc lors de la génération du jeton de session, WorkflowGen le signera avec ce secret afin de vérifier la validité de tous les jetons qui seront envoyés.

Étape 3 : Activez la délégation d'authentification

Vous devez maintenant activer la délégation en remplaçant le système d'authentification dans IIS et faire pointer les modules de WorkflowGen au module d'authentification correct.

Configurez IIS

1. Dans Gestionnaire IIS, cliquez sur l'application WorkflowGen dans l'arborescence.

2. Cliquez sur le bouton Authentification.

3. Activez Authentification anonyme et désactivez toutes les autres authentifications.

4. Répétez ces étapes pour toutes les sous-applications.

Ajoutez des propriétés aux fichiers web.config de certains modules

Certains modules doivent faire vérifier leur authentification par le module d'authentification spécial Advantys.Security.JWTAuthenticationModule WorkflowGen, tandis que certains autres modules ne le doivent pas parce qu'ils sont soit publics ou ne font pas partie du système d'authentification global.

1. Ajoutez la propriété suivante au fichier web.config de WorkflowGen :

   <?xml version="1.0" encoding="UTF-8"?>
   <configuration>
    <system.webServer>
        <modules>
            <add name="ApplicationSecurityAuthenticationModule" type="Advantys.Security.Http.JWTAuthenticationModule" />
        </modules>
    </system.webServer>
   </configuration>

2. Si vous avez développé des formulaires Web personnalisés avec leurs propres dossiers \bin, vous devez copier les assemblies .NET et les bibliothèques de dépendances suivants de \wfgen\bin dans le dossier \bin de chaque formulaire Web personnalisé (\wfgen\wfapps\webforms\bin) :

   • Advantys.My.dll

   • Advantys.Security.dll

   • Newtonsoft.Json.dll

   • jose-jwt.dll

Vous devriez maintenant avoir une instance de WorkflowGen en fonctionnement avec l'authentification déléguée à Azure AD via le protocole OpenID Connect. Assurez-vous d'avoir approvisionné vos utilisateurs à WorkflowGen afin qu'ils puissent accéder à WorkflowGen.

Appel des APIs tierces avec le jeton d'accès

• Cette méthode est uniquement supportée avec Microsoft Identity Platform v2.0 (ms-identity-v2).

• Si le portail utilisateur ou le module d'administration de WorkflowGen est affiché sans le menu d'en-tête principal, cette fonctionnalité ne fonctionnera pas. Par exemple, ce scénario peut se produire lorsque la page d'accueil du portail utilisateur ou un formulaire de suivi de demande est affiché dans une iFrame dans une solution externe.

• Le module GraphiQL (/wfgen/graphql) ne supporte pas la gestion de session lorsqu'il est affiché dans un navigateur.

Par défaut, le seul destinataire du jeton d'accès est l'API GraphQL. Cela signifie qu'il ne peut être utilisé que pour envoyer des requêtes à cette API uniquement. Pour appeler vos propres APIs, vous devrez suivre les étapes suivantes dans votre portail Azure, puis modifier le fichier web.config de WorkflowGen.

Dans votre portail Azure :

Étape 1 : Ajoutez une nouvelle inscription d'application qui représente vos APIs

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

2. Cliquez sur Nouvelle inscription et renseignez le formulaire des propriétés :

   • Nom : Mes API

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

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

Étape 2 : Exposez vos APIs dans l'inscription

1. Cliquez sur Exposer une API.

2. À droite de URI ID d'application, cliquez sur Définir et entrez l'URI api://my-apis.

3. Cliquez sur Ajouter une étendue et entrez les informations suivantes :

   • Nom de l'étendue : wfgen-graphql-full-access

   • Qui peut accepter ? : Administrateurs et utilisateurs

   • Nom d'affichage du consentement administrateur : Accès complet à l'API WorkflowGen GraphQL

   • Description du consentement administrateur : Permet à l'application d'accéder à l'API WorkflowGen GraphQL.

   • Nom d'affichage du consentement de l'utilisateur : Accès complet à l'API WorkflowGen GraphQL

   • Description du consentement de l'utilisateur :

     Permet à l'application d'accéder à l'API WorkflowGen GraphQL.

4. Cliquez sur Ajouter une étendue.

5. Ajoutez toute autre étendue qui semble nécessaire pour vos autres APIs.

6. Cliquez sur Enregistrer.

Étape 3 : Ajoutez un rôle d'application

1. Cliquez sur Manifeste.

2. Recherchez la propriété JSON appRoles et ajoutez l'objet JSON suivant au tableau JSON :

   {
     "allowedMemberTypes": [
       "Application"
     ],
     "description": "Allows the application to get access to WorkflowGen's GraphQL API.",
     "displayName": "wfgen-graphql-full-access-role",
     "id": "<NEW ID>",
     "isEnabled": true,
     "lang": null,
     "origin": "Application",
     "value": "wfgen-graphql-full-access-role"
   }

   ✏️ Note : Remplacez<NEW ID> par la valeur générée par la commande PowerShell[guid]::NewGuid().ToString().

3. Cliquez sur Enregistrer.

Étape 4 : Accordez à WorkflowGen l'accès à l'application Mes API

1. Accédez à la page d'inscription de votre application WorkflowGen.

2. Cliquez sur API autorisées, puis cliquez sur Ajouter une autorisation.

3. Cliquez sur Mes API, puis choisissez Mes API dans la liste.

4. Cliquez sur Autorisation déléguées et cochez wfgen-graphql-full-access.

5. Cliquez sur Ajouter des autorisations.

Étape 5 (facultatif) : Accordez l'accès à vos applications automatisées (flux d'informations d'identification du client)

Pour chacune de vos applications :

1. Accédez à la page d'inscription de l'application.

2. Cliquez sur Autorisations configurées, puis cliquez sur Ajouter une autorisation

3. Cliquez sur Mes API, puis sélectionnez Mes API dans la liste.

4. Cliquez sur Autorisations de l'application et cochez wfgen-graphql-full-access-role.

5. Cliquez sur Ajouter des autorisations.

Dans le fichier web.config de WorkflowGen :

Ouvrez le fichier web.config de WorkflowGen, ajoutez les paramètres d'application suivantes, puis enregistrez le fichier :

<add key="ApplicationSecurityAuthAudience" value="api://my-apis"/>
<add key="ApplicationSecurityAuthAdditionalScopes" value="api://my-apis/wfgen-graphql-full-access" />
<add key="ApplicationSecurityAuthGraphQLScope" value="wfgen-graphql-full-access" />
<add key="ApplicationSecurityAuthGraphQLAppRole" value="wfgen-graphql-full-access-role" />

Vous devez également définir les étendues supplémentaires (ApplicationSecurityAuthAdditionalScopes) faisant référence à d'autres APIs que vous avez définies lors de l'étape 3 des étapes effectuées dans le portail Azure. Les étendues doivent être séparées par une virgule.

Informations supplémentaires

Support des services SOAP

WorkflowGen supporte seulement les requêtes à l'API SOAP en utilisant les méthodes d'authentification classiques. Si vous devez toujours utiliser cette API, vous devez effectuer quelques étapes additionnelles pour la configurer correctement. Pour ce faire :

1. Créez un nouvel annuaire WorkflowGen séparé pour les utilisateurs de l'API SOAP.

2. Approvisionnez-le avec des utilisateurs et des groupes au besoin.

3. Dans Gestionnaire IIS, cochez la méthode d'authentification De base pour l'application \ws\wfgen.

4. Dans le fichier web.config (situé dans \Inetpub\wwwroot\wfgen), ajoutez le suivant sous <location path="ws" inheritInChildApplications="false"> :

   <system.webServer>
       <modules>
           <remove name="ApplicationSecurityAuthenticationModule" />
       </modules>
   </system.webServer>

À propos de la gestion de session

Azure Active Directory supporte la Gestion de session Open ID Connect, un standard de « extension draft », en plus du standard principal de OpenID Connect. Ce standard définit les règles pour gérer la session SSO du fournisseur depuis le client. Par exemple, si un utilisateur se déconnecte de sa session Azure AD depuis n'importe quel appareil, un client Web régulier recevra un message qui lui permettra d'enlever la session locale de cet utilisateur. WorkflowGen supporte cette fonctionnalité quand l'authentification déléguée est activée avec Azure AD.

Options configurables

Le tableau ci-dessous liste toutes les options configurables dans WorkflowGen que vous pouvez utiliser pour personnaliser votre expérience d'authentification; elles se trouvent dans le fichier web.config de WorkflowGen.

Option	Description
ApplicationSecurityAuthSessionTokenCookie	Le nom du cookie de session généré par le module d'authentification. Valeur par défaut : wfgen_token ✏️ Note : Ceci est utile quand vous avez de multiples instances de WorkflowGen en fonctionnement auxquelles vous voulez accéder lorsque vous y êtes authentifié en même temps.
ApplicationSecurityAuthSessionTimeOut	La durée de la session en secondes. Sa valeur par défaut est le temps d'expiration du jeton d'ID reçu du fournisseur. Valeur par défaut : la valeur d'expiration (« exp value » du jeton Azure ID
ApplicationSecurityAuthMobileSessionTimeOut	La durée de la session en secondes lorsqu'elle est demandée par des appareils mobiles sur le point de terminaison de jeton. Valeur par défaut : 7200 secondes

Limitations courantes

• Si le portail utilisateur ou le module d'administration de WorkflowGen est affiché sans le menu de l'en-tête principale, cette fonctionnalité pourrait ne pas fonctionner. Par exemple, ce scénario pourrait se produire lorsque la page d'accueil du portail ou un formulaire de suivi de demande est affiché dans une iFrame dans une solution externe.

• Le module GraphiQL (/wfgen/graphql) ne supporte pas la gestion de session lorsqu'il est affiché dans un navigateur.