À propos des connecteurs d’API dans Azure AD B2C

Important

À compter du 1er mai 2025, Azure AD B2C ne sera plus disponible pour les nouveaux clients. Pour plus d’informations, consultez notre FAQ.

Avant de commencer, utilisez le sélecteur Choisir un type de stratégie en haut de cette page pour choisir le type de stratégie que vous configurez. Azure Active Directory B2C offre deux possibilités pour définir la façon dont les utilisateurs interagissent avec vos applications : via des flux utilisateurs prédéfinis ou via des stratégies personnalisées entièrement configurables. La procédure donnée dans cet article est différente pour chaque méthode.

Aperçu

En tant qu’administrateur informatique ou développeur, vous pouvez utiliser des connecteurs d’API pour intégrer vos flux d’utilisateurs d’inscription à des API REST pour personnaliser l’expérience d’inscription et l’intégrer à des systèmes externes. Par exemple, avec les connecteurs d’API, vous pouvez :

Valider des données d’entrée utilisateur. Validez par rapport à des données utilisateur incorrectes ou non valides. Par exemple, vous pouvez valider les données fournies par l’utilisateur par rapport à des données existantes dans une banque de données externe ou une liste de valeurs autorisées. En cas d’invalidité, vous pouvez demander à un utilisateur de fournir des données valides ou empêcher l’utilisateur de continuer le processus d’inscription.
Vérifiez l’identité de l’utilisateur. Utilisez un service de vérification d’identité ou des sources de données d’identité externes pour ajouter un niveau de sécurité supplémentaire aux décisions de création de compte.
Intégrer à un flux de travail d’approbation personnalisé. Connectez-vous à un système d’approbation personnalisé pour gérer et limiter la création de comptes.
Augmentez les jetons avec des attributs provenant de sources externes. Enrichir les jetons avec des attributs utilisateur provenant de sources externes à Azure AD B2C, tels que des systèmes cloud, des magasins d’utilisateurs personnalisés, des systèmes d’autorisation personnalisés, des services d’identité hérités, etc.
Remplacer des attributs utilisateur. Reformatez ou attribuez une valeur à un attribut collecté auprès de l’utilisateur. Par exemple, si un utilisateur entre le prénom entier en lettres minuscules ou majuscules, vous pouvez modifier sa mise en forme en utilisant une majuscule uniquement pour la première lettre.
Exécuter une logique métier personnalisée. Vous pouvez déclencher des événements en aval dans vos systèmes ce cloud pour envoyer des notifications Push, mettre à jour des bases de données d’entreprise, gérer des autorisations, auditer des bases de données et effectuer d’autres actions personnalisées.

Un connecteur d’API fournit à Azure AD B2C les informations nécessaires pour appeler le point de terminaison de l’API en définissant l’URL et l’authentification du point de terminaison HTTP pour l’appel d’API. Une fois que vous avez configuré un connecteur d’API, vous pouvez l’activer pour une étape spécifique dans un flux utilisateur. Lorsqu’un utilisateur atteint cette étape dans le flux d’inscription, le connecteur d’API est appelé et matérialisé en tant que requête HTTP POST à votre API, en envoyant des informations utilisateur (« revendications ») en tant que paires clé-valeur dans un corps JSON. La réponse d’API peut affecter l’exécution du flux utilisateur. Par exemple, la réponse de l’API peut empêcher un utilisateur de s’inscrire, demander à l’utilisateur de réentérer des informations ou remplacer les attributs utilisateur.

Où activer un connecteur d’API dans un flux utilisateur

Il existe trois emplacements dans un flux utilisateur où vous pouvez activer un connecteur d’API :

Après la fédération avec un fournisseur d’identité lors de l’inscription (s’applique uniquement aux expériences d’inscription)
Avant de créer l’utilisateur , s’applique uniquement aux expériences d’inscription
Avant d’envoyer le jeton (aperçu) - s’applique aux inscriptions et aux connexions

Un connecteur d’API à cette étape du processus d’inscription est appelé immédiatement après l’authentification de l’utilisateur 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. Cette étape n’est pas appelée si un utilisateur s’inscrit auprès d’un compte local. Voici quelques exemples de scénarios de connecteur d’API que vous pouvez activer à cette étape :

Utilisez l’adresse e-mail ou l’identité fédérée que l’utilisateur a fournie pour rechercher des revendications dans un système existant. Retournez ces revendications à partir du système existant, complétez la page de collection d’attributs, puis rendez-les disponibles pour un retour dans le jeton.
Implémentez une liste d’autorisation ou de refus en fonction de l’identité sociale.

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éé. Voici quelques exemples de scénarios que vous pouvez activer à cette étape au cours de l’inscription :

Validez les données d’entrée utilisateur et demandez à un utilisateur de renvoyer des données.
Bloquer l’inscription utilisateur en fonction des données entrées par l’utilisateur.
Vérifier l’identité de l’utilisateur.
Interrogez les systèmes externes pour obtenir des données existantes sur l'utilisateur afin de les renvoyer dans le jeton d'application ou de les stocker dans Microsoft Entra ID.

Avant d’envoyer le jeton (aperçu)

Remarque

Cette fonctionnalité est en préversion publique.

Un connecteur d’API à cette étape du processus d’inscription ou de connexion est appelé avant l’émission d’un jeton. Voici des exemples de scénarios que vous pouvez activer à cette étape :

Enrichissement du jeton avec des attributs relatifs à l’utilisateur provenant de sources différentes du répertoire, y compris les systèmes d’identité hérités, les systèmes RH, les magasins d’utilisateurs externes et bien plus encore.
Enrichissement du jeton avec des attributs de groupe ou de rôle que vous stockez et gérez dans votre propre système d’autorisation.
Application de transformations ou manipulations de revendications à des valeurs de revendications dans le répertoire.

Identity Experience Framework, qui sous-tend Azure Active Directory B2C (Azure AD B2C), peut s’intégrer aux API RESTful dans un parcours utilisateur. Cet article explique comment créer un parcours utilisateur qui interagit avec un service RESTful à l’aide d’un profil technique RESTful.

À l’aide d’Azure AD B2C, vous pouvez ajouter votre propre logique métier à un parcours utilisateur en appelant votre propre service RESTful. Identity Experience Framework peut envoyer et recevoir des données de votre service RESTful pour échanger des revendications. Par exemple, vous pouvez :

Utilisez la source de données d’identité externe pour valider les données d’entrée utilisateur. Par exemple, vous pouvez vérifier que l’adresse e-mail fournie par l’utilisateur existe dans la base de données de votre client et, si ce n’est pas le cas, présenter une erreur. Vous pouvez également considérer les connecteurs d’API comme un moyen de prendre en charge les webhooks sortants, car l’appel est effectué lorsqu’un événement se produit, par exemple, une inscription.
Traitez des revendications. Si un utilisateur entre son prénom en minuscules ou en majuscules, votre API REST peut mettre en forme le nom avec uniquement la première lettre majuscule et la renvoyer à Azure AD B2C. Toutefois, lors de l’utilisation d’une stratégie personnalisée, ClaimsTransformations est préférable à l’appel d’une API RESTful.
Enrichir dynamiquement les données utilisateur en s’intégrant davantage aux applications métier de l’entreprise. Votre service RESTful peut recevoir l’adresse e-mail de l’utilisateur, interroger la base de données du client et renvoyer le numéro de fidélité de l’utilisateur à Azure AD B2C. Ensuite, les revendications de retour peuvent être stockées dans le compte Microsoft Entra de l’utilisateur, évaluées dans les étapes d’orchestration suivantes ou incluses dans le jeton d’accès.
Exécuter une logique métier personnalisée. Vous pouvez envoyer des notifications Push, mettre à jour des bases de données d’entreprise, exécuter un processus de migration utilisateur, gérer les autorisations, auditer des bases de données et effectuer d’autres flux de travail.

Diagramme d’un échange de revendications de service RESTful

Remarque

Les requêtes HTTP peuvent être annulées s’il existe une réponse lente ou inexistante du service RESTful à Azure AD B2C. Le délai d’expiration par défaut est de 10 secondes pour les stratégies personnalisées et 5 secondes pour les flux utilisateur. Le nombre de nouvelles tentatives par défaut est un (ce qui signifie qu’il y a 2 tentatives au total).

Appel d’un service RESTful

Cette interaction inclut un échange de revendications d’informations entre les revendications de l’API REST et Azure AD B2C. Vous pouvez concevoir l’intégration avec les services RESTful de la manière suivante :

Profil technique de validation. L’appel au service RESTful se produit à l’intérieur d’un profil technique de validation du profil technique autodéclaré spécifié ou d’un contrôle d’affichage de vérification d’un contrôle d’affichage. Le profil technique de validation valide les données fournies par l’utilisateur avant que le parcours utilisateur avance. Avec le profil technique de validation, vous pouvez :
- Envoyez des revendications à votre API REST.
- Validez les revendications et lèvez des messages d’erreur personnalisés qui sont affichés à l’utilisateur.
- Renvoyez les revendications de l’API REST aux étapes d’orchestration suivantes.
Échange de revendications. Un échange direct de revendications peut être configuré en appelant un profil technique d’API REST directement à partir d’une étape d’orchestration d’un parcours utilisateur. Cette définition est limitée à :
- Envoyez des revendications à votre API REST.
- Validez les revendications et levez des messages d’erreur personnalisés qui sont retournés à l’application.
- Renvoyez les revendications de l’API REST aux étapes d’orchestration suivantes.

Vous pouvez ajouter un appel d’API REST à n’importe quelle étape du parcours utilisateur défini par une stratégie personnalisée. Par exemple, vous pouvez appeler une API REST :

Lors de la connexion, juste avant qu’Azure AD B2C valide les informations d’identification.
Immédiatement après la connexion.
Avant qu’Azure AD B2C ne crée un compte dans l’annuaire.
Une fois qu’Azure AD B2C a créé un compte dans le répertoire.
Avant qu’Azure AD B2C émet un jeton d’accès.

Envoi de données

Dans le profil technique RESTful, l’élément InputClaims contient une liste de revendications à envoyer à votre service RESTful. Vous pouvez mapper le nom de votre revendication au nom défini dans le service RESTful, définir une valeur par défaut et utiliser des résolveurs de revendications.

Vous pouvez configurer la façon dont les revendications d’entrée sont envoyées au fournisseur de revendications RESTful à l’aide de l’attribut SendClaimsIn. Les valeurs possibles sont les suivantes :

Body, envoyé dans le corps de la requête HTTP POST au format JSON.
Formulaire, envoyé dans le corps de la requête HTTP POST dans un format de valeur de clé séparée par l’ampersand '&'.
Header, envoyé dans l’en-tête de requête HTTP GET.
QueryString, envoyé dans la chaîne de requête HTTP GET.

Lorsque l’option Body est configurée, le profil technique de l’API REST vous permet d’envoyer une charge utile JSON complexe à un point de terminaison. Pour plus d’informations, consultez Envoyer une charge utile JSON.

Réception de données

L’élément OutputClaims du profil technique RESTful contient une liste de revendications retournées par l’API REST. Vous devrez peut-être mapper le nom de la revendication définie dans votre stratégie au nom défini dans l’API REST. Vous pouvez également inclure des revendications qui ne sont pas retournées par le fournisseur d’identité de l’API REST, tant que vous définissez l’attribut DefaultValue.

Les revendications de sortie analysées par le fournisseur de revendications RESTful s’attendent toujours à analyser une réponse de corps JSON plate, par exemple :

{
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "loyaltyNumber":  1234
}

Les assertions de sortie doivent ressembler à l'exemple de code XML suivant :

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
  <OutputClaim ClaimTypeReferenceId="email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" />
</OutputClaims>

Traitement des valeurs Null

Une valeur Null dans une base de données est utilisée lorsque la valeur d’une colonne est inconnue ou manquante. N’incluez pas de clés JSON avec une null valeur. Dans l’exemple suivant, l’e-mail retourne la valeur null.

{
  "name": "Emily Smith",
  "email": null,
  "loyaltyNumber":  1234
}

Lorsqu’un élément a la valeur Null, effectuez les opérations suivantes :

Omettez la paire clé-valeur du json.
Retourne une valeur qui correspond au type de données de revendication Azure AD B2C. Par exemple, pour un string type de données, retournez une chaîne ""vide. Pour un integer type de données, retournez une valeur 0zéro. Pour un dateTime type de données, retournez une valeur 0001-01-01T00:00:00.0000000Zminimale .

L’exemple suivant montre comment gérer une valeur Null. L’e-mail est omis dans le JSON :

{
  "name": "Emily Smith",
  "loyaltyNumber":  1234
}

Analyser un corps JSON imbriqué

Pour analyser une réponse de corps JSON imbriquée, définissez les métadonnées ResolveJsonPathsInJsonTokens sur true. Dans la revendication de sortie, définissez PartnerClaimType sur l’élément de chemin d’accès JSON que vous souhaitez générer.

"contacts": [
  {
    "id": "MAINCONTACT_1",
    "person": {
      "name": "Emily Smith",
      "loyaltyNumber":  1234,
      "emails": [
        {
          "id": "EMAIL_1",
          "type": "WORK",
          "email": "email@domain.com"
        }
      ]
    }
  }
],

Les spécifications de sortie doivent être conformes à l'extrait de code XML suivant :

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="contacts[0].person.name" />
  <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="contacts[0].person.emails[0].email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="contacts[0].person.loyaltyNumber" />
</OutputClaims>

Localiser l’API REST

Dans un profil technique RESTful, vous pouvez envoyer la langue/les paramètres régionaux de la session actuelle et, si nécessaire, déclencher un message d’erreur localisé. À l’aide du programme de résolution de revendications, vous pouvez envoyer une revendication contextuelle, telle que la langue de l’utilisateur. L’exemple suivant montre un profil technique RESTful illustrant ce scénario.

<TechnicalProfile Id="REST-ValidateUserData">
  <DisplayName>Validate user input data</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app.azurewebsites.net/api/identity</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="IncludeClaimResolvingInClaimsHandling">true</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="userLanguage" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="email" PartnerClaimType="emailAddress" />
  </InputClaims>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

Gestion des messages d’erreur

Votre API REST peut avoir besoin de renvoyer un message d’erreur, tel que « L’utilisateur n’a pas été trouvé dans le système CRM ». Si une erreur se produit, l’API REST doit retourner un message d’erreur HTTP 409 (code d’état de la réponse en conflit). Pour plus d’informations, consultez le profil technique RESTful.

Ce comportement ne peut être obtenu qu’en appelant un profil technique d’API REST à partir d’un profil technique de validation. Laisser l’utilisateur corriger les données de la page et réexécuter la validation lors de l’envoi de la page.

Si vous référencez un profil technique d’API REST directement à partir d’un parcours utilisateur, l’utilisateur est redirigé vers l’application de partie de confiance avec le message d’erreur approprié.

Développement de votre API REST

Votre API REST peut être développée sur n’importe quelle plateforme et écrite dans n’importe quel langage de programmation, tant qu’elle est sécurisée et peut envoyer et recevoir des revendications au format JSON.

La demande adressée à votre service d’API REST provient de serveurs Azure AD B2C. Le service d’API REST doit être publié sur un point de terminaison HTTPS accessible publiquement. L’appel d’API REST arrive à partir d’une adresse IP du centre de données Azure.

Vous pouvez utiliser des fonctions cloud serverless, telles que des déclencheurs HTTP dans Azure Functions pour faciliter le développement.

Vous devez concevoir votre service d’API REST et ses composants sous-jacents (tels que la base de données et le système de fichiers) à haute disponibilité.

Important

Vos points de terminaison doivent respecter les exigences de sécurité Azure AD B2C. Les versions et les chiffrements TLS plus anciens sont déconseillés. Pour plus d’informations, consultez la configuration requise pour azure AD B2C TLS et la suite de chiffrement.

Étapes suivantes

Découvrez comment ajouter un connecteur d’API pour modifier les expériences d’inscription
Découvrez comment ajouter un connecteur d’API pour enrichir des jetons avec des revendications externes
Découvrez comment sécuriser votre connecteur d’API
Bien démarrer avec nos exemples

Consultez les articles suivants pour obtenir des exemples d’utilisation d’un profil technique RESTful :

Découvrez comment créer une résilience lors de l’interfaçage avec des processus externes
Découvrez comment créer la résilience par le biais des meilleures pratiques pour les développeurs.

Rétroaction

Cette page a-t-elle été utile ?

Last updated on 2025-05-06