Een RESTful-technisch profiel definiëren in een aangepast Azure Active Directory B2C-beleid

Artikel
01/22/2024

Notitie

In Azure Active Directory B2C is aangepast beleid voornamelijk bedoeld om met complexe scenario's om te gaan. Voor de meeste scenario's wordt aangeraden ingebouwde gebruikersstromen te gebruiken. Als u dit nog niet hebt gedaan, vindt u meer informatie over aangepast beleid in het starterspakket in Aan de slag met aangepaste beleidsregels in Active Directory B2C.

Azure Active Directory B2C (Azure AD B2C) biedt ondersteuning voor het integreren van uw eigen RESTful-service. Azure AD B2C verzendt gegevens naar de RESTful-service in een verzameling invoerclaims en ontvangt gegevens terug in een verzameling uitvoerclaims. Zie REST API-claimsuitwisselingen integreren in uw aangepaste Azure AD B2C-beleid voor meer informatie.

Protocol

Het kenmerk Naam van het element Protocol moet worden ingesteld op Proprietary. Het handlerkenmerk moet de volledig gekwalificeerde naam bevatten van de protocolhandlerassembly die wordt gebruikt door Azure AD B2C: Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null.

In het volgende voorbeeld ziet u een RESTful-technisch profiel:

<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" />
  ...

Invoerclaims

Het element InputClaims bevat een lijst met claims die naar de REST API moeten worden verzonden . U kunt ook de naam van uw claim toewijzen aan de naam die is gedefinieerd in de REST API. In het volgende voorbeeld ziet u de toewijzing tussen uw beleid en de REST API. De givenName-claim wordt als firstName naar de REST API verzonden, terwijl de achternaam wordt verzonden als lastName. De e-mailclaim wordt ingesteld zoals is.

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

Het element InputClaimsTransformations kan een verzameling InputClaimsTransformation-elementen bevatten die worden gebruikt om de invoerclaims te wijzigen of nieuwe elementen te genereren voordat ze naar de REST API worden verzonden.

Een JSON-nettolading verzenden

Met het technische profiel van de REST API kunt u een complexe JSON-nettolading verzenden naar een eindpunt.

Een complexe JSON-nettolading verzenden:

Bouw uw JSON-nettolading met de generateJson-claimtransformatie .
In het technische profiel van de REST API:
1. Voeg een transformatie van invoerclaims toe met een verwijzing naar de GenerateJson claimtransformatie.
2. SendClaimsIn De optie metagegevens instellen opbody
3. Stel de ClaimUsedForRequestPayload optie voor metagegevens in op de naam van de claim die de JSON-nettolading bevat.
4. Voeg in de invoerclaim een verwijzing toe naar de invoerclaim die de JSON-nettolading bevat.

In het volgende voorbeeld TechnicalProfile wordt een verificatie-e-mail verzonden met behulp van een e-mailservice van derden (in dit geval 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>

Uitvoerclaims

Het element OutputClaims bevat een lijst met claims die worden geretourneerd door de REST API. Mogelijk moet u de naam van de claim die in uw beleid is gedefinieerd, toewijzen aan de naam die is gedefinieerd in de REST API. U kunt ook claims opnemen die niet worden geretourneerd door de REST API, zolang u het DefaultValue kenmerk instelt.

Het element OutputClaimsTransformations kan een verzameling OutputClaimsTransformation-elementen bevatten die worden gebruikt om uitvoerclaims te wijzigen of nieuwe te genereren.

In het volgende voorbeeld ziet u de claim die wordt geretourneerd door de REST API:

De MembershipId-claim die is toegewezen aan de naam van de loyaltyNumber-claim .

Het technische profiel retourneert ook claims die niet worden geretourneerd door de id-provider:

De loyaltyNumberIsNew-claim die een standaardwaarde heeft ingesteld op true.

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

Metagegevens

Kenmerk	Vereist	Beschrijving
ServiceUrl	Ja	De URL van het REST API-eindpunt.
AuthenticationType	Ja	Het type verificatie dat wordt uitgevoerd door de RESTful-claimprovider. Mogelijke waarden: `None`, `Basic`, `Bearer`, , of `ApiKeyHeaderClientCertificate`. De `None` waarde geeft aan dat de REST API anoniem is. De `Basic` waarde geeft aan dat de REST API is beveiligd met HTTP-basisverificatie. Alleen geverifieerde gebruikers, waaronder Azure AD B2C, hebben toegang tot uw API. De `ClientCertificate` waarde (aanbevolen) geeft aan dat de REST API de toegang beperkt met behulp van clientcertificaatverificatie. Alleen services met de juiste certificaten, bijvoorbeeld Azure AD B2C, hebben toegang tot uw API. De `Bearer` waarde geeft aan dat de REST API de toegang beperkt met behulp van client OAuth2 Bearer-token. De `ApiKeyHeader` waarde geeft aan dat de REST API is beveiligd met DE HTTP-header van de API-sleutel, zoals x-functions-key.
AllowInsecureAuthInProduction	Nee	Hiermee wordt aangegeven of de `AuthenticationType` waarde kan worden ingesteld `none` op in de productieomgeving (`DeploymentMode` van de TrustFrameworkPolicy is ingesteld `Production`op , of niet opgegeven). Mogelijke waarden: waar of onwaar (standaard).
SendClaimsIn	Nee	Hiermee geeft u op hoe de invoerclaims worden verzonden naar de RESTful-claimprovider. Mogelijke waarden: `Body` (standaard), `Form`, of `UrlHeaderQueryString`. De `Body` waarde is de invoerclaim die wordt verzonden in de aanvraagbody in JSON-indeling. De `Form` waarde is de invoerclaim die wordt verzonden in de aanvraagbody in een door ampersand '&' gescheiden sleutelwaardenotatie. De `Header` waarde is de invoerclaim die wordt verzonden in de aanvraagheader. De `Url` waarde is de invoerclaim die wordt verzonden in de URL, `https://api.example.com/{claim1}/{claim2}?{claim3}={claim4}`bijvoorbeeld. Het hostnaamgedeelte van de URL mag geen claims bevatten. De `QueryString` waarde is de invoerclaim die wordt verzonden in de querytekenreeks van de aanvraag. De HTTP-woorden die door elk worden aangeroepen, zijn als volgt: `Body`:VERZENDEN `Form`:VERZENDEN `Header`:TOEVOEGEN `Url`:TOEVOEGEN `QueryString`:TOEVOEGEN
ClaimsFormat	Nee	Momenteel niet in gebruik, kan worden genegeerd.
ClaimUsedForRequestPayload	Nee	Naam van een tekenreeksclaim die de nettolading bevat die naar de REST API moet worden verzonden.
Foutopsporingsmodus	Nee	Hiermee wordt het technische profiel uitgevoerd in de foutopsporingsmodus. Mogelijke waarden: `true` of `false` (standaard). In de foutopsporingsmodus kan de REST API meer informatie retourneren. Zie de sectie Foutbericht retourneren .
IncludeClaimResolvingInClaimsHandling	Nee	Geeft voor de invoer- en uitvoerclaims aan of claimsoplossing is opgenomen in het technische profiel. Mogelijke waarden: `true` of `false` (standaard). Als u een claimsresolver wilt gebruiken in het technische profiel, stel dit in op `true`.
ResolveJsonPathsInJsonTokens	Nee	Geeft aan of het technische profiel JSON-paden oplost. Mogelijke waarden: `true` of `false` (standaard). Gebruik deze metagegevens om gegevens te lezen uit een geneste JSON-element. Stel in een OutputClaim het `PartnerClaimType` JSON-padelement in dat u wilt uitvoeren. Bijvoorbeeld: `firstName.localized`, of `data[0].to[0].email`.
UseClaimAsBearerToken	Nee	De naam van de claim die het bearer-token bevat.

Foutafhandeling

De volgende metagegevens kunnen worden gebruikt om de foutberichten te configureren die worden weergegeven bij REST API-fout. De foutberichten kunnen worden gelokaliseerd.

Kenmerk	Vereist	Beschrijving
DefaultUserMessageIfRequestFailed	Nee	Een standaard aangepast foutbericht voor alle REST API-uitzonderingen.
UserMessageIfCircuitOpen	Nee	Foutbericht wanneer de REST API niet bereikbaar is. Als dit niet is opgegeven, wordt de DefaultUserMessageIfRequestFailed geretourneerd.
UserMessageIfDnsResolutionFailed	Nee	Foutbericht voor de uitzondering voor DNS-omzetting. Als dit niet is opgegeven, wordt de DefaultUserMessageIfRequestFailed geretourneerd.
UserMessageIfRequestTimeout	Nee	Foutbericht wanneer er een time-out optreedt voor de verbinding. Als dit niet is opgegeven, wordt de DefaultUserMessageIfRequestFailed geretourneerd.

Cryptografische sleutels

Als het type verificatie is ingesteld op None, wordt het element CryptographicKeys niet gebruikt.

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

Als het type verificatie is ingesteld op Basic, bevat het element CryptographicKeys de volgende kenmerken:

Kenmerk	Vereist	Beschrijving
BasicAuthenticationUsername	Ja	De gebruikersnaam die wordt gebruikt om te verifiëren.
BasicAuthenticationPassword	Ja	Het wachtwoord dat wordt gebruikt om te verifiëren.

In het volgende voorbeeld ziet u een technisch profiel met basisverificatie:

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

Als het type verificatie is ingesteld op ClientCertificate, bevat het element CryptographicKeys het volgende kenmerk:

Kenmerk	Vereist	Beschrijving
ClientCertificate	Ja	Het X509-certificaat (RSA-sleutelset) dat moet worden gebruikt voor verificatie.

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

Als het type verificatie is ingesteld op Bearer, bevat het element CryptographicKeys het volgende kenmerk:

Kenmerk	Vereist	Beschrijving
BearerAuthenticationToken	Nee	Het OAuth 2.0 Bearer-token.

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

Als het type verificatie is ingesteld op ApiKeyHeader, bevat het element CryptographicKeys het volgende kenmerk:

Kenmerk	Vereist	Beschrijving
De naam van de HTTP-header, zoals `x-functions-key`, of `x-api-key`.	Ja	De sleutel die wordt gebruikt voor verificatie.

Notitie

Op dit moment ondersteunt Azure AD B2C slechts één HTTP-header voor verificatie. Als voor uw RESTful-aanroep meerdere headers zijn vereist, zoals een client-id en clientgeheimwaarde, moet u de aanvraag op een bepaalde manier proxyen.

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

Foutbericht over validatie retourneren

Uw REST API moet mogelijk een foutbericht retourneren, zoals 'De gebruiker is niet gevonden in het CRM-systeem'. Als er een fout optreedt, moet de REST API een HTTP 4xx-foutbericht retourneren, zoals 400 (ongeldige aanvraag) of 409-antwoordstatuscode (conflict). De hoofdtekst van het antwoord bevat een foutbericht dat is opgemaakt in 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"
}

Kenmerk	Vereist	Beschrijving
version	Ja	Uw REST API-versie. Bijvoorbeeld: 1.0.1
status	Ja	Een HTTP-antwoordstatuscodes zoals getal en moet 409 zijn. Uw REST-service kan een HTTP 4XX-statuscode retourneren, maar de waarde van de `status` opgeslagen antwoordtekst in de JSON-indeling moet zijn `409`.
code	Nee	Een foutcode van de RESTful-eindpuntprovider, die wordt weergegeven wanneer `DebugMode` deze is ingeschakeld.
requestId	Nee	Een aanvraag-id van de RESTful-eindpuntprovider, die wordt weergegeven wanneer `DebugMode` deze is ingeschakeld.
userMessage	Ja	Er wordt een foutbericht weergegeven aan de gebruiker.
developerMessage	Nee	De uitgebreide beschrijving van het probleem en hoe u dit kunt oplossen, wat wordt weergegeven wanneer `DebugMode` dit is ingeschakeld.
moreInfo	Nee	Een URI die verwijst naar aanvullende informatie, die wordt weergegeven wanneer `DebugMode` deze is ingeschakeld.

In het volgende voorbeeld ziet u een C#-klasse die een foutbericht retourneert:

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; }
}

Volgende stappen

Zie de volgende artikelen voor voorbeelden van het gebruik van een RESTful-technisch profiel: