# Configuration de Microsoft Entra ID pour les scripts côté serveur

{% hint style="warning" %}
Azure Active Directory (Azure AD) a été renommé **Microsoft Entra ID (ME-ID)**. Bien que la documentation WorkflowGen ait été mise à jour pour refléter ce changement de nom, les paramètres de l'application WorkflowGen font toujours référence à Azure AD (par exemple, connecteur d'annuaire `Azure AD SCIM v2`).

De même, certains éléments de configuration ME-ID dans le portail Azure ont été renommés et / ou déplacés. La documentation WorkflowGen a été mise à jour en conséquence, mais il se peut qu'elle ne soit toujours pas tout à fait exacte à cet égard. Consultez la documentation [Microsoft Entra ID](https://learn.microsoft.com/fr-fr/entra/identity/) pour plus d'informations.
{% endhint %}

## 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 Microsoft Entra ID (ME-ID) 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 ME-ID; 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 à ME-ID pour pouvoir le configurer correctement.
* Assurez-vous d'avoir configuré avec succès l'authentification déléguée à ME-ID sur votre instance WorkflowGen en suivant les instructions de la section [Authentification Microsoft Entra ID](https://docs.workflowgen.com/azure-fr/9.0/authentification-azure-active-directory) avec l'application `WorkflowGen GraphQL API` également enregistrée.

## Configuration de Microsoft Entra ID

### Étape 1 : Inscrivez une nouvelle application Web

1. Dans le portail Azure, cliquez sur **Inscriptions d'applications** dans la section **Services Azure**.<br>
2. Cliquez sur **Nouvelle inscription**, puis entrez les propriétés :
   * **Nom** **:** `Nom de votre script, service ou application`&#x20;
   * **Types de comptes pris en charge :** `Comptes dans cet annuaire d'organisation uniquement (Default Directory 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<br>
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 **Afficher les autorisation de l'API**.<br>
2. Dans la section **Autorisations configurées**, cliquez sur **Ajouter une autorisation**.<br>
3. Cliquez sur **Mes API**, puis sélectionnez l'application `WorkflowGen GraphQL API` dans la liste.<br>
4. Cliquez sur **Autorisations déléguées**, puis cochez `defaut` dans la colonne **Autorisation**. <br>
5. Cliquez sur **Ajouter des autorisations**.<br>
6. Dans la page **API autorisées**, cliquez sur **Accorder un consentement d'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**.<br>
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 **730 jours (24 mois)** ou la période d'expiration souhaitée.<br>
3. Cliquez sur **Ajouter**.<br>
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.

{% hint style="warning" %}
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 **730 jours (24 mois)** 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.
{% endhint %}

### 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**.&#x20;
* 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](#recuperer-le-jeton-dacces-dazure-pour-votre-application).&#x20;

Vous avez maintenant enregistré avec succès votre script ou application côté serveur dans Microsoft Entra ID.

## 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**.<br>
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<br>
3. Cliquez sur **Enregistrer**.

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

{% hint style="success" %}
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 ME-ID OAuth2 à l'aide du **flux d'octroi des informations d'identification du client**.
{% endhint %}

## 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 ME-ID 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 de ME-ID pour votre application

#### Requête cURL

```bash
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://<url workflowgen>/graphql/.default'

```

{% hint style="info" %}
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**.
{% endhint %}

{% hint style="info" %}
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.
{% endhint %}

{% hint style="warning" %}
Si vous avez configuré la section [Appel des APIs tierces avec le jeton d'accès](https://docs.workflowgen.com/azure-fr/9.0/authentification-azure-active-directory#appel-des-apis-tierces-avec-le-jeton-dacces), la valeur du paramètre `scope` doit être `api://my-apis/.default` au lieu de `https://<url workflowgen>/graphql/.default`.
{% endhint %}

#### Réponse JSON

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

{% hint style="info" %}
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](https://jwt.io). Le jeton d'accès est un **JSON Web Token**.&#x20;

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

### 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

```bash
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

```javascript
{
    "data": {
        "viewer": {
            "userName": "firstname.lastname@mycompany.com"
        }
    }
}
```

{% hint style="info" %}
Pour plus d'informations sur le **flux d'octroi des informations d'identification du client OAuth 2.0** et des exemples supplémentaires, voir le guide [Plateforme d’identités Microsoft et flux d’informations d’identification du client OAuth 2.0](https://docs.microsoft.com/fr-fr/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow).
{% endhint %}