Définir un profil technique RESTful dans une stratégie personnalisée Azure Active Directory 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.

Remarque

Dans Active Directory B2C, les stratégies personnalisées sont principalement conçues pour gérer des scénarios complexes. Pour la plupart des scénarios, nous vous recommandons de recourir à des flux d’utilisateurs intégrés. Si vous ne l’avez pas fait, découvrez le Pack de démarrage de stratégie personnalisée dans Prise en main des stratégies personnalisées dans Active Directory B2C.

Azure Active Directory B2C (Azure AD B2C) prend en charge l’intégration de votre propre service RESTful. Azure AD B2C envoie des données au service RESTful dans une collection de revendications d’entrée et reçoit des données dans une collection de revendications de sortie. Pour plus d’informations, consultez Intégrer des échanges de revendications d’API REST dans votre stratégie personnalisée Azure AD B2C.

Protocole

L’attribut Name de l’élément Protocol doit être défini sur Proprietary. L’attribut du gestionnaire doit contenir le nom complet de l’assembly de gestionnaire de protocole utilisé par Azure AD B2C : Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null.

L’exemple suivant montre un profil technique RESTful :

<TechnicalProfile Id="REST-UserMembershipValidator">
  <DisplayName>Validate user input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  ...

Revendications d’entrée

L’élément InputClaims contient une liste de revendications à envoyer à l’API REST. Vous pouvez également mapper le nom de votre revendication au nom défini dans l’API REST. L’exemple suivant montre le mappage entre votre stratégie et l’API REST. La revendication givenName est envoyée à l’API REST en tant que firstName, tandis que le nom de famille est envoyé en tant que lastName. La revendication d’e-mail est définie comme c’est le cas.

<InputClaims>
  <InputClaim ClaimTypeReferenceId="email" />
  <InputClaim ClaimTypeReferenceId="givenName" PartnerClaimType="firstName" />
  <InputClaim ClaimTypeReferenceId="surname" PartnerClaimType="lastName" />
</InputClaims>

L’élément InputClaimsTransformations peut contenir une collection d’éléments InputClaimsTransformation utilisés pour modifier les revendications d’entrée ou en générer de nouvelles avant l’envoi à l’API REST.

Envoyer une charge utile JSON

Le profil technique de l’API REST vous permet d’envoyer une charge utile JSON complexe à un point de terminaison.

Pour envoyer une charge utile JSON complexe :

1. Générez votre charge utile JSON avec la transformation de revendications GenerateJson .
2. Dans le profil technique de l’API REST :
   1. Ajoutez une transformation de revendications d’entrée avec une référence à la GenerateJson transformation de revendications.
   2. Définir l’option de métadonnées sur SendClaimsInbody
   3. Définissez l’option ClaimUsedForRequestPayload de métadonnées sur le nom de la revendication contenant la charge utile JSON.
   4. Dans la revendication d’entrée, ajoutez une référence à la revendication d’entrée contenant la charge utile JSON.

L’exemple TechnicalProfile suivant envoie un e-mail de vérification à l’aide d’un service de messagerie tiers (dans ce cas, SendGrid).

<TechnicalProfile Id="SendGrid">
  <DisplayName>Use SendGrid's email API to send the code to the user</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://api.sendgrid.com/v3/mail/send</Item>
    <Item Key="AuthenticationType">Bearer</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="ClaimUsedForRequestPayload">sendGridReqBody</Item>
    <Item Key="DefaultUserMessageIfRequestFailed">Cannot process your request right now, please try again later.</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BearerAuthenticationToken" StorageReferenceId="B2C_1A_SendGridApiKey" />
  </CryptographicKeys>
  <InputClaimsTransformations>
    <InputClaimsTransformation ReferenceId="GenerateSendGridRequestBody" />
  </InputClaimsTransformations>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="sendGridReqBody" />
  </InputClaims>
</TechnicalProfile>

Revendications de sortie

L’élément OutputClaims 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 l’API REST, tant que vous définissez l’attribut DefaultValue .

L’élément OutputClaimsTransformations peut contenir une collection d’éléments OutputClaimsTransformation qui sont utilisés pour modifier les revendications de sortie ou en générer de nouvelles.

L’exemple suivant montre la revendication retournée par l’API REST :

• Revendication MembershipId mappée au nom de la revendication loyaltyNumber .

Le profil technique retourne également des revendications qui ne sont pas retournées par le fournisseur d’identité :

• La revendication loyaltyNumberIsNew qui a une valeur par défaut définie sur true.

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="MembershipId" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumberIsNew" DefaultValue="true" />
</OutputClaims>

Métadonnées

Caractéristique	Obligatoire	Descriptif
ServiceUrl	Oui	URL du point de terminaison de l’API REST.
Type d'authentification	Oui	Type d’authentification effectuée par le fournisseur de revendications RESTful. Valeurs possibles : None, , BasicBearer, ClientCertificate, ou ApiKeyHeader. La None valeur indique que l’API REST est anonyme. La Basic valeur indique que l’API REST est sécurisée avec l’authentification HTTP de base. Seuls les utilisateurs vérifiés, y compris Azure AD B2C, peuvent accéder à votre API. La ClientCertificate valeur (recommandée) indique que l’API REST limite l’accès à l’aide de l’authentification par certificat client. Seuls les services disposant des certificats appropriés, par exemple Azure AD B2C, peuvent accéder à votre API. La Bearer valeur indique que l’API REST limite l’accès à l’aide du jeton du porteur OAuth2 client. La ApiKeyHeader valeur indique que l’API REST est sécurisée avec l’en-tête HTTP de clé API, tel que x-functions-key.
AllowInsecureAuthInProduction	Non	Indique si la AuthenticationType valeur peut être définie none dans l’environnement de production (DeploymentMode de TrustFrameworkPolicy est définie Productionsur , ou non spécifiée). Valeurs possibles : true ou false (valeur par défaut).
SendClaimsIn	Non	Spécifie la façon dont les revendications d’entrée sont envoyées au fournisseur de revendications RESTful. Valeurs possibles : Body (par défaut), Form, HeaderUrlou QueryString. La Body valeur est la revendication d’entrée envoyée dans le corps de la requête au format JSON. La Form valeur est la revendication d’entrée qui est envoyée dans le corps de la requête dans un format de valeur de clé séparée par '&' ampersand. La Header valeur est la revendication d’entrée envoyée dans l’en-tête de requête. La Url valeur est la revendication d’entrée envoyée dans l’URL, par exemple https://api.example.com/{claim1}/{claim2}?{claim3}={claim4}. La partie nom d’hôte de l’URL ne peut pas contenir de revendications. La QueryString valeur est la revendication d’entrée envoyée dans la chaîne de requête de requête. Les verbes HTTP appelés par chacun sont les suivants : Body:PUBLIER Form:PUBLIER Header:AVOIR Url:AVOIR QueryString:AVOIR
Format des réclamations	Non	Non utilisé actuellement, peut être ignoré.
ClaimUsedForRequestPayload	Non	Nom d’une revendication de chaîne qui contient la charge utile à envoyer à l’API REST.
DebugMode	Non	Exécute le profil technique en mode débogage. Valeurs possibles : true ou false (par défaut). En mode débogage, l’API REST peut retourner plus d’informations. Consultez la section Retour du message d’erreur .
InclureRéclamationRésoudreInClaimsHandling	Non	Pour les revendications d’entrée et de sortie, spécifie si la résolution des revendications est incluse dans le profil technique. Valeurs possibles : true ou false (par défaut). Si vous souhaitez utiliser un programme de résolution des revendications dans le profil technique, définissez cette valeur sur true.
ResolveJsonPathsInJsonTokens	Non	Indique si le profil technique résout les chemins JSON. Valeurs possibles : true ou false (par défaut). Utilisez ces métadonnées pour lire des données à partir d’un élément JSON imbriqué. Dans un OutputClaim, définissez l’élément PartnerClaimType de chemin d’accès JSON que vous souhaitez générer. Par exemple : firstName.localized ou data[0].to[0].email.
UseClaimAsBearerToken	Non	Nom de la revendication qui contient le jeton du porteur.

Gestion des erreurs

Les métadonnées suivantes peuvent être utilisées pour configurer les messages d’erreur affichés lors de l’échec de l’API REST. Les messages d’erreur peuvent être localisés.

Caractéristique	Obligatoire	Descriptif
DefaultUserMessageIfRequestFailed	Non	Message d’erreur personnalisé par défaut pour toutes les exceptions d’API REST.
UserMessageIfCircuitOpen	Non	Message d’erreur lorsque l’API REST n’est pas accessible. S’il n’est pas spécifié, DefaultUserMessageIfRequestFailed est retourné.
UserMessageIfDnsResolutionFailed	Non	Message d’erreur pour l’exception de résolution DNS. S’il n’est pas spécifié, DefaultUserMessageIfRequestFailed est retourné.
UserMessageIfRequestTimeout	Non	Message d’erreur lorsque la connexion est expirée. S’il n’est pas spécifié, DefaultUserMessageIfRequestFailed est retourné.

Clés de chiffrement

Si le type d’authentification est défini Nonesur , l’élément CryptographicKeys n’est pas utilisé.

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</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-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
</TechnicalProfile>

Si le type d’authentification est défini Basicsur , l’élément CryptographicKeys contient les attributs suivants :

Caractéristique	Obligatoire	Descriptif
BasicAuthenticationNom d’utilisateur	Oui	Nom d’utilisateur utilisé pour l’authentification.
BasicAuthenticationPassword	Oui	Mot de passe utilisé pour l’authentification.

L’exemple suivant montre un profil technique avec l’authentification de base :

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</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-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">Basic</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BasicAuthenticationUsername" StorageReferenceId="B2C_1A_B2cRestClientId" />
    <Key Id="BasicAuthenticationPassword" StorageReferenceId="B2C_1A_B2cRestClientSecret" />
  </CryptographicKeys>
</TechnicalProfile>

Si le type d’authentification est défini ClientCertificatesur , l’élément CryptographicKeys contient l’attribut suivant :

Caractéristique	Obligatoire	Descriptif
ClientCertificate	Oui	Certificat X509 (jeu de clés RSA) à utiliser pour l’authentification.

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</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-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">ClientCertificate</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="ClientCertificate" StorageReferenceId="B2C_1A_B2cRestClientCertificate" />
  </CryptographicKeys>
</TechnicalProfile>

Si le type d’authentification est défini Bearersur , l’élément CryptographicKeys contient l’attribut suivant :

Caractéristique	Obligatoire	Descriptif
BearerAuthenticationToken	Non	Jeton du porteur OAuth 2.0.

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</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-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">Bearer</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BearerAuthenticationToken" StorageReferenceId="B2C_1A_B2cRestClientAccessToken" />
  </CryptographicKeys>
</TechnicalProfile>

Si le type d’authentification est défini ApiKeyHeadersur , l’élément CryptographicKeys contient l’attribut suivant :

Caractéristique	Obligatoire	Descriptif
Nom de l’en-tête HTTP, tel que x-functions-key, ou x-api-key.	Oui	Clé utilisée pour l’authentification.

Remarque

À ce stade, Azure AD B2C ne prend en charge qu’un seul en-tête HTTP pour l’authentification. Si votre appel RESTful nécessite plusieurs en-têtes, tels qu’un ID client et une valeur de clé secrète client, vous devrez proxyr la requête d’une certaine manière.

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</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-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">ApiKeyHeader</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="x-functions-key" StorageReferenceId="B2C_1A_RestApiKey" />
  </CryptographicKeys>
</TechnicalProfile>

Retour d’un message d’erreur de validation

Votre API REST peut avoir besoin de renvoyer un message d’erreur, par exemple « 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 4xx, tel que 400 (requête incorrecte) ou 409 (conflit). Le corps de la réponse contient un message d’erreur mis en forme au format JSON :

{
  "version": "1.0.0",
  "status": 409,
  "code": "API12345",
  "requestId": "50f0bd91-2ff4-4b8f-828f-00f170519ddb",
  "userMessage": "Message for the user",
  "developerMessage": "Verbose description of problem and how to fix it.",
  "moreInfo": "https://restapi/error/API12345/moreinfo"
}

Caractéristique	Obligatoire	Descriptif
Version	Oui	Version de votre API REST. Par exemple : 1.0.1
statut	Oui	Un numéro de type code d’état de réponse HTTP et doit être 409. Votre service REST peut retourner un code d’état HTTP 4XX, mais la valeur du corps de status réponse au format JSON doit être 409.
code	Non	Code d’erreur du fournisseur de points de terminaison RESTful, qui s’affiche lorsqu’il DebugMode est activé.
requestId	Non	Identificateur de demande du fournisseur de point de terminaison RESTful, qui s’affiche quand DebugMode il est activé.
message utilisateur	Oui	Message d’erreur affiché à l’utilisateur.
developerMessage	Non	Description détaillée du problème et comment la résoudre, qui s’affiche quand DebugMode elle est activée.
plus d’infos	Non	URI qui pointe vers des informations supplémentaires, qui s’affiche quand DebugMode elle est activée.

L’exemple suivant montre une classe C# qui retourne un message d’erreur :

public class ResponseContent
{
  public string Version { get; set; }
  public int Status { get; set; }
  public string Code { get; set; }
  public string UserMessage { get; set; }
  public string DeveloperMessage { get; set; }
  public string RequestId { get; set; }
  public string MoreInfo { get; set; }
}

Étapes suivantes

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

• Intégrer des échanges de revendications d’API REST dans votre stratégie personnalisée Azure AD B2C
• Procédure pas à pas : ajouter un connecteur d’API à un flux d’utilisateur d’inscription
• Procédure pas à pas : ajouter des échanges de revendications d’API REST à des stratégies personnalisées dans Azure Active Directory B2C
• Sécuriser vos services d’API REST