Ajouter un connecteur d’API à un workflow d’utilisateur

Article
02/05/2024

Pour utiliser un connecteur d’API, vous devez d’abord créer le connecteur d’API, puis l’activer dans un workflow utilisateur.

Important

À partir du 12 juillet 2021, si les clients B2B de Microsoft Entra configurent de nouvelles intégrations Google pour une utilisation avec l’inscription en libre-service pour leurs applications métier ou personnalisées, l’authentification avec les identités Google ne fonctionnera pas tant que les authentifications ne seront pas déplacées vers les vues web du système. Plus d’informations
À partir du 30 septembre 30, 2021, Google déprécie la prise en charge de la connexion aux vues web intégrée. Si vos applications authentifient les utilisateurs avec une vue web incorporée et que vous utilisez la Fédération des services Google avec Azure AD B2C ou Microsoft Entra B2B pour des invitations utilisateur externes ou une inscription en libre-service, les utilisateurs de Google Gmail ne pourront pas s’authentifier. Plus d’informations

Créer un connecteur d'API

Conseil

Les étapes de cet article peuvent varier légèrement en fonction du portail à partir duquel vous démarrez.

Connectez-vous au Centre d’administration de Microsoft Entra en tant qu’Administrateur de l’utilisateur.
Accédez à Identité>Identités externes>Vue d’ensemble.
Sélectionnez All API connectors (Tous les connecteurs d’API), puis New API connector (Nouveau connecteur d’API).
Indiquez un nom d’affichage pour l’appel. Par exemple, Vérifier l’état d’approbation.
Indiquez l’URL du point de terminaison pour l’appel d’API.
Choisissez le Type d'authentification et configurez les informations d'authentification pour appeler votre API. Découvrez comment sécuriser votre connecteur d’API.
Sélectionnez Enregistrer.

Demande envoyée à votre API

Un connecteur d’API est matérialisé en tant que requête HTTP POST, en envoyant les attributs utilisateur (« revendications ») en tant que paires clé-valeur dans un corps JSON. Les attributs sont sérialisés de la même façon que les propriétés utilisateur Microsoft Graph.

Exemple de requête

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

Seules les propriétés utilisateur et les attributs personnalisés répertoriés dans l’expérience Identités>Identités externes>Vue d’ensemble>Attributs utilisateur personnalisés peuvent être envoyés dans la demande.

Des attributs personnalisés au format extension_<extensions-app-id>_AttributeName existent dans le répertoire. Votre API doit s’attendre à recevoir des revendications dans ce même format sérialisé. Pour plus d’informations sur les attributs personnalisés, consultez définir des attributs personnalisés pour les flux d’inscription en libre-service.

En outre, les revendications sont généralement envoyées dans toutes les requêtes :

Paramètres régionaux de l’interface utilisateur (« ui_locales ») – Paramètres régionaux d’un utilisateur final comme configurés sur son appareil. Cela peut être utilisé par votre API pour retourner des réponses internationalisées.

Adresse e-mail ('e-mail') ou identités ('identités') : ces revendications peuvent être utilisées par votre API pour identifier l’utilisateur final qui s’authentifie auprès de l’application.

Important

Si une revendication n’a pas de valeur au moment où le point de terminaison de l’API est appelé, la revendication n’est pas envoyée à l’API. Votre API doit être conçue pour vérifier et gérer explicitement le cas où une revendication ne figure pas dans la requête.

Activer le connecteur d’API dans un workflow utilisateur

Procédez comme suit pour ajouter un connecteur d’API à un workflow d’utilisateur d’inscription en libre-service.

Connectez-vous au Centre d’administration de Microsoft Entra en tant qu’Administrateur de l’utilisateur.
Accédez à Identité>Identités externes>Vue d’ensemble.
Sélectionnez Flux d’utilisateurs, puis sélectionnez le flux utilisateur auquel vous souhaitez ajouter le connecteur d’API.
Sélectionnez Connecteurs d’API, puis sélectionnez les points de terminaison d’API que vous souhaitez appeler aux étapes suivantes dans le workflow d’utilisateur :
- Après la fédération avec un fournisseur d’identité lors de l’inscription
- Avant de créer l’utilisateur
Sélectionnez Enregistrer.

Un connecteur API à cette étape du processus d’inscription est invoqué immédiatement après que l’utilisateur s’authentifie auprès d’un fournisseur d’identité (comme Google, Facebook et Microsoft Entra ID). Cette étape précède la page de collection d’attributs, qui est le formulaire présenté à l’utilisateur pour collecter des attributs utilisateur.

Exemple de demande envoyée à l’API à cette étape

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "lastName":"Smith",
 "ui_locales":"en-US"
}

Les revendications exactes envoyées à l’API dépendent des informations fournies par le fournisseur d’identité. « email » est toujours envoyé.

Types de réponses attendus de l’API Web à cette étape

Lorsque l’API web reçoit une requête HTTP de Microsoft Entra ID lors d’un flux utilisateur, elle peut renvoyer les réponses suivantes :

Réponse de continuation
Réponse de blocage

Réponse de continuation

Une réponse de continuation indique que le flux de l’utilisateur doit passer à l’étape suivante : la page de collecte d’attribut.

Dans une réponse de continuation, l’API peut renvoyer des revendications. Si une revendication est retournée par l’API, la revendication effectue les opérations suivantes :

Renseigne le champ d’entrée dans la page de collections d’attributs.

Consultez un exemple de réponse de continuation.

Réponse de blocage

Une réponse de blocage quitte le workflow de l’utilisateur. Il peut être intentionnellement émis par l’API pour arrêter la continuation du workflow de l’utilisateur en affichant une page de blocage à l’utilisateur. La page de blocage affiche les userMessage fournies par l’API.

Consultez un exemple de réponse de blocage.

avant la création de l’utilisateur

Un connecteur d’API à cette étape du processus d’inscription est appelé après la page de collection d’attributs, si elle est inclue. Cette étape est toujours appelée avant qu’un compte d’utilisateur ne soit créé dans Microsoft Entra ID.

Exemple de demande envoyée à l’API à cette étape

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

Les revendications exactes envoyées à l’API dépendent des informations collectées auprès de l’utilisateur ou fournies par le fournisseur d’identité.

Types de réponses attendus de l’API Web à cette étape

Lorsque l’API web reçoit une requête HTTP de Microsoft Entra ID lors d’un flux utilisateur, elle peut renvoyer les réponses suivantes :

Réponse de continuation
Réponse de blocage
Réponse de validation

Réponse de continuation

Une réponse de continuation indique que le flux de l’utilisateur doit passer à l’étape suivante : créer l’utilisateur dans le répertoire.

Dans une réponse de continuation, l’API peut renvoyer des revendications. Si une revendication est retournée par l’API, la revendication effectue les opérations suivantes :

Remplace toute valeur qui a déjà été attribuée à la revendication à partir de la page de collection d’attributs.

Consultez un exemple de réponse de continuation.

Réponse de blocage

Consultez un exemple de réponse de blocage.

Validation-réponse d’erreur

Lorsque l’API répond avec une réponse d’erreur de validation, le workflow de l’utilisateur reste sur la page de collection d’attributs et une userMessage est présenté à l’utilisateur. L’utilisateur peut ensuite modifier et renvoyer le formulaire. Ce type de réponse peut être utilisé pour la validation d’entrée.

Consultez un exemple de réponse d’erreur de validation.

Exemples de réponses

Exemple de réponse de continuation

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "Continue",
    "postalCode": "12349", // return claim
    "extension_<extensions-app-id>_CustomAttribute": "value" // return claim
}

Paramètre	Type	Requise	Description
version	Chaîne	Oui	Version de votre API.
action	String	Oui	La valeur doit être `Continue`.
<builtInUserAttribute>	<attribute-type>	Non	Les valeurs peuvent être stockées dans le répertoire si elles sont sélectionnées en tant que Revendication à recevoir dans la configuration du connecteur d’API et Attributs utilisateur pour un workflow utilisateur. Les valeurs peuvent être renvoyées dans le jeton si elles sont sélectionnées en tant que Revendication d’application.
<extension_{extensions-app-id}_CustomAttribute>	<attribute-type>	Non	La revendication n’a pas besoin de contenir `_<extensions-app-id>_`, elle est facultative. Les valeurs retournées peuvent remplacer des valeurs collectées à partir d’un utilisateur.

Exemple de réponse de blocage

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "There was an error with your request. Please try again or contact support.",
}

Paramètre	Type	Requise	Description
version	Chaîne	Oui	Version de votre API.
action	String	Oui	La valeur doit être `ShowBlockPage`
userMessage	String	Oui	Message à afficher à l’utilisateur.

Expérience de l’utilisateur final avec une réponse de blocage

Voici un exemple d’image de l’expérience de l’utilisateur final après qu’une API a retourné une réponse de blocage.

Exemple de réponse d’erreur de validation

HTTP/1.1 400 Bad Request
Content-type: application/json

{
    "version": "1.0.0",
    "status": 400,
    "action": "ValidationError",
    "userMessage": "Please enter a valid Postal Code.",
}

Paramètre	Type	Requise	Description
version	Chaîne	Oui	Version de votre API.
action	String	Oui	La valeur doit être `ValidationError`.
status	Entier / Chaîne	Oui	La valeur doit être `400`, ou `"400"` pour une réponse ValidationError.
userMessage	String	Oui	Message à afficher à l’utilisateur.

Notes

Le code d’état HTTP doit être « 400 » en plus de la valeur « Status » dans le corps de la réponse.

Expérience de l’utilisateur final avec une réponse d’erreur de validation

Voici un exemple d’image de l’expérience de l’utilisateur final après qu’une API a retourné une réponse de blocage.

Meilleures pratiques et résolution des problèmes

Utilisation des fonctions cloud serverless

Les fonctions serverless, comme les déclencheurs HTTP dans Azure Functions, fournissent une façon de créer des points de terminaison d’API à utiliser avec le connecteur d’API. Vous pouvez utiliser la fonction cloud serverless pour, par exemple, effectuer une logique de validation et limiter les inscriptions à des domaines de courrier spécifiques. La fonction cloud serverless peut également appeler et invoquer d’autres API web, magasins de données et d’autres services cloud dans le cade de scénarios plus complexes.

Meilleures pratiques

Assurez-vous que :

Votre API suit les contrats de demande et de réponse d’API comme indiqué ci-dessus.
L’URL du point de terminaison du connecteur d’API pointe vers le point de terminaison d’API approprié.
Votre API recherche explicitement les valeurs null des revendications reçues dont elle dépend.
Votre API implémente une méthode d’authentification décrite dans Sécuriser votre connecteur d’API.
Votre API répond aussi rapidement que possible pour garantir une expérience utilisateur fluide.
- Microsoft Entra ID attend un maximum de 20 secondes pour recevoir une réponse. Si aucune réponse n’est reçue, le service effectue une tentative supplémentaire pour appeler votre API.
- Si vous utilisez une fonction serverless ou un service web scalable, utilisez un plan d’hébergement qui conserve l’API dans un état « de veille » ou « dynamique » en production. Pour Azure Functions, nous vous recommandons d’utiliser au minimum le plan Premium.
Assurez la haute disponibilité de votre API.
Analysez et optimisez les performances des API en aval, des bases de données ou d’autres dépendances de votre API.
Vos points de terminaison doivent respecter les exigences du protocole TLS Microsoft Entra et de sécurité de chiffrement. Pour plus d’informations, consultez Configuration requise pour TLS et les suites de chiffrement.

Utiliser la journalisation

En général, il est judicieux d’utiliser les outils de journalisation activés par votre service API Web, comme Application Insights, pour surveiller votre API en cas de codes d’erreur inattendus, d’exceptions et de performances médiocres.

Analysez les codes d’état HTTP autres que HTTP 200 ou 400.
Un code d’état HTTP 401 ou 403 indique généralement un problème avec votre authentification. Vérifiez la couche d’authentification de votre API et la configuration correspondante dans le connecteur d’API.
Si nécessaire, utilisez des niveaux de journalisation plus agressifs (par exemple, « trace » ou « debug ») lors du développement.
Surveillez votre API en cas de temps de réponse longs.

Étapes suivantes

Découvrez comment ajouter un système d’approbation personnalisé à l’inscription en libre-service
Lancez-vous avec nos exemples de démarrage rapide.

Ajouter un connecteur d’API à un workflow d’utilisateur

Créer un connecteur d'API

Demande envoyée à votre API

Activer le connecteur d’API dans un workflow utilisateur

Après la fédération avec un fournisseur d’identité lors de l’inscription

Exemple de demande envoyée à l’API à cette étape

Types de réponses attendus de l’API Web à cette étape

Réponse de continuation

Réponse de blocage

avant la création de l’utilisateur

Exemple de demande envoyée à l’API à cette étape

Types de réponses attendus de l’API Web à cette étape

Réponse de continuation

Réponse de blocage

Validation-réponse d’erreur

Exemples de réponses

Exemple de réponse de continuation

Exemple de réponse de blocage

Exemple de réponse d’erreur de validation

Meilleures pratiques et résolution des problèmes

Utilisation des fonctions cloud serverless

Meilleures pratiques

Utiliser la journalisation

Étapes suivantes

Ressources supplémentaires