RESTful műszaki profil definiálása egyéni Azure Active Directory B2C-szabályzatban

Cikk
01/22/2024

Feljegyzés

Az Azure Active Directory B2C-ben az egyéni szabályzatok elsősorban összetett helyzetek kezelésére szolgálnak. A legtöbb forgatókönyv esetében javasoljuk, hogy beépített felhasználói folyamatokat használjon. Ha még nem tette meg, ismerkedjen meg az egyéni szabályzatok kezdőcsomagjával az Egyéni szabályzatok használatának első lépései az Active Directory B2C-ben.

Az Azure Active Directory B2C (Azure AD B2C) támogatja a saját RESTful szolgáltatás integrálását. Az Azure AD B2C adatokat küld a RESTful szolgáltatásnak egy bemeneti jogcímcsoportban, és adatokat fogad vissza egy kimeneti jogcímgyűjteményben. További információ: REST API-jogcímcserék integrálása az Azure AD B2C egyéni szabályzatában.

Protokoll

A Protokoll elem névattribútumát a következőre kell állítani Proprietary: . A kezelő attribútumnak tartalmaznia kell az Azure AD B2C által használt protokollkezelő-szerelvény teljes nevét: Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null.

Az alábbi példa egy RESTful technikai profilt mutat be:

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

Bemeneti jogcímek

Az InputClaims elem a REST API-nak küldendő jogcímek listáját tartalmazza. A jogcím nevét a REST API-ban meghatározott névre is megfeleltetheti. Az alábbi példa a szabályzat és a REST API közötti leképezést mutatja be. A givenName jogcímet a rendszer firstName néven küldi el a REST API-nak, míg a vezetéknevet vezetéknévként. Az e-mail-jogcím a következőképpen van beállítva.

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

Az InputClaimsTransformations elem tartalmazhat Olyan InputClaimsTransformation elemek gyűjteményét, amelyek a bemeneti jogcímek módosítására vagy újak létrehozására szolgálnak a REST API-ba való küldés előtt.

JSON-hasznos adatok küldése

A REST API technikai profilja lehetővé teszi, hogy összetett JSON-hasznos adatokat küldjön egy végpontnak.

Összetett JSON-hasznos adat küldése:

Hozza létre A JSON hasznos adatait a GenerateJson-jogcímek átalakításával.
A REST API technikai profiljában:
1. Adjon hozzá egy bemeneti jogcímátalakítást a jogcímátalakításra GenerateJson való hivatkozással.
2. SendClaimsIn A metaadatok beállításának beállításabody
3. Állítsa a ClaimUsedForRequestPayload metaadat-beállítást a JSON hasznos adatokat tartalmazó jogcím nevére.
4. A bemeneti jogcímben adjon hozzá egy hivatkozást a JSON hasznos adatait tartalmazó bemeneti jogcímhez.

Az alábbi példa TechnicalProfile egy ellenőrző e-mailt küld egy külső levelezőszolgáltatás (ebben az esetben a SendGrid) használatával.

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

Kimeneti jogcímek

Az OutputClaims elem a REST API által visszaadott jogcímek listáját tartalmazza. Előfordulhat, hogy le kell képeznie a szabályzatban meghatározott jogcím nevét a REST API-ban meghatározott névre. Olyan jogcímeket is megadhat, amelyeket a REST API nem ad vissza, feltéve, hogy beállítja az DefaultValue attribútumot.

A OutputClaimsTransformations elem olyan OutputClaimsTransformation elemek gyűjteményét tartalmazhatja, amelyek a kimeneti jogcímek módosítására vagy újak létrehozására szolgálnak.

Az alábbi példa a REST API által visszaadott jogcímet mutatja be:

A loyaltyNumber jogcím nevére leképezett MembershipId jogcím.

A technikai profil olyan jogcímeket is visszaad, amelyeket az identitásszolgáltató nem ad vissza:

A loyaltyNumberIsNew jogcím, amelynek alapértelmezett értéke a truekövetkező.

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

Metaadatok

Attribútum	Kötelező	Leírás
ServiceUrl	Igen	A REST API-végpont URL-címe.
AuthenticationType	Igen	A RESTful jogcímszolgáltató által végzett hitelesítés típusa. Lehetséges értékek: `None`, `Basic`, `Bearer`, `ClientCertificate`vagy `ApiKeyHeader`. Az `None` érték azt jelzi, hogy a REST API névtelen. Az `Basic` érték azt jelzi, hogy a REST API-t alapszintű HTTP-hitelesítés védi. Az API-hoz csak ellenőrzött felhasználók férhetnek hozzá, beleértve az Azure AD B2C-t is. Az `ClientCertificate` (ajánlott) érték azt jelzi, hogy a REST API ügyféltanúsítvány-hitelesítéssel korlátozza a hozzáférést. Csak azok a szolgáltatások férhetnek hozzá az API-hoz, amelyek rendelkeznek a megfelelő tanúsítványokkal, például az Azure AD B2C-vel. Az `Bearer` érték azt jelzi, hogy a REST API korlátozza a hozzáférést az ügyfél OAuth2 Tulajdonos jogkivonatával. Az `ApiKeyHeader` érték azt jelzi, hogy a REST API-t API-kulcs HTTP-fejléce, például x-functions-key védi.
AllowInsecureAuthInProduction	Nem	Azt jelzi, hogy az `AuthenticationType` éles környezetben (az TrustFrameworkPolicy értéke`Production`, vagy nincs megadva) éles környezetben`DeploymentMode` állítható-e `none` be. Lehetséges értékek: igaz vagy hamis (alapértelmezett).
SendClaimsIn	Nem	Meghatározza, hogy a bemeneti jogcímek hogyan legyenek elküldve a RESTful jogcímszolgáltatónak. Lehetséges értékek: `Body` (alapértelmezett), `Form`vagy `HeaderUrl` `QueryString`. Az `Body` érték a kérelem törzsében JSON formátumban küldött bemeneti jogcím. Az `Form` érték az a bemeneti jogcím, amelyet a kérelem törzse és "&" elválasztott kulcsérték formátumban küld el. Az `Header` érték a kérelem fejlécében küldött bemeneti jogcím. Az `Url` érték az URL-címben küldött bemeneti jogcím, `https://api.example.com/{claim1}/{claim2}?{claim3}={claim4}`például. Az URL gazdagépnév része nem tartalmazhat jogcímeket. Az `QueryString` érték a kérelem lekérdezési sztringjében küldött bemeneti jogcím. Az egyes http-parancsok a következők: `Body`:POST `Form`:POST `Header`:KAP `Url`:KAP `QueryString`:KAP
Jogcímforma	Nem	Jelenleg nincs használatban, figyelmen kívül hagyható.
ClaimUsedForRequestPayload	Nem	A REST API-nak küldendő hasznos adatokat tartalmazó karakterlánc-jogcím neve.
Hibakeresési mód	Nem	Hibakeresési módban futtatja a műszaki profilt. Lehetséges értékek: `true`vagy `false` (alapértelmezett). Hibakeresési módban a REST API további információkat adhat vissza. Lásd a Visszatérési hibaüzenet szakaszt .
IncludeClaimResolvingInClaimsHandling	Nem	A bemeneti és kimeneti jogcímek esetében meghatározza, hogy a jogcímfeloldás szerepel-e a műszaki profilban. Lehetséges értékek: `true`vagy `false` (alapértelmezett). Ha egy jogcímfeloldót szeretne használni a műszaki profilban, állítsa be a következőre `true`: .
ResolveJsonPathsInJsonTokens	Nem	Azt jelzi, hogy a műszaki profil feloldja-e a JSON-útvonalakat. Lehetséges értékek: `true`vagy `false` (alapértelmezett). Ezzel a metaadatokkal adatokat olvashat beágyazott JSON-elemből. Az OutputClaim fájlban állítsa be a `PartnerClaimType` kimenethez használni kívánt JSON-elérési elemet. Például: `firstName.localized`, vagy `data[0].to[0].email`.
UseClaimAsBearerToken	Nem	A tulajdonosi jogkivonatot tartalmazó jogcím neve.

Hibakezelés

A REST API-hiba esetén megjelenő hibaüzenetek konfigurálásához az alábbi metaadatok használhatók. A hibaüzenetek honosíthatók.

Attribútum	Kötelező	Leírás
DefaultUserMessageIfRequestFailed	Nem	Az összes REST API-kivétel alapértelmezett testreszabott hibaüzenete.
UserMessageIfCircuitOpen	Nem	Hibaüzenet, ha a REST API nem érhető el. Ha nincs megadva, a DefaultUserMessageIfRequestFailed függvény lesz visszaadva.
UserMessageIfDnsResolutionFailed	Nem	A DNS-feloldási kivétel hibaüzenete. Ha nincs megadva, a DefaultUserMessageIfRequestFailed függvény lesz visszaadva.
UserMessageIfRequestTimeout	Nem	A kapcsolat időtúllépése esetén hibaüzenet jelenik meg. Ha nincs megadva, a DefaultUserMessageIfRequestFailed függvény lesz visszaadva.

Titkosítási kulcsok

Ha a hitelesítés típusa be van állítva None, a CryptographicKeys elem nem lesz használva.

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

Ha a hitelesítés típusa be van állítva Basic, a CryptographicKeys elem a következő attribútumokat tartalmazza:

Attribútum	Kötelező	Leírás
BasicAuthenticationUsername	Igen	A hitelesítéshez használt felhasználónév.
BasicAuthenticationPassword	Igen	A hitelesítéshez használt jelszó.

Az alábbi példa egy alapszintű hitelesítéssel rendelkező műszaki profilt mutat be:

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

Ha a hitelesítés típusa be van állítva ClientCertificate, a CryptographicKeys elem a következő attribútumot tartalmazza:

Attribútum	Kötelező	Leírás
ClientCertificate	Igen	A hitelesítéshez használni kívánt X509-tanúsítvány (RSA-kulcskészlet).

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

Ha a hitelesítés típusa be van állítva Bearer, a CryptographicKeys elem a következő attribútumot tartalmazza:

Attribútum	Kötelező	Leírás
BearerAuthenticationToken	Nem	Az OAuth 2.0 tulajdonosi jogkivonata.

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

Ha a hitelesítés típusa be van állítva ApiKeyHeader, a CryptographicKeys elem a következő attribútumot tartalmazza:

Attribútum	Kötelező	Leírás
A HTTP-fejléc neve, például `x-functions-key`: vagy `x-api-key`.	Igen	A hitelesítéshez használt kulcs.

Feljegyzés

Az Azure AD B2C jelenleg csak egy HTTP-fejlécet támogat a hitelesítéshez. Ha a RESTful-híváshoz több fejlécre van szükség, például ügyfélazonosítóra és titkos ügyfélkódra, a kérést valamilyen módon kell proxyznia.

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

Érvényesítési hibaüzenet visszaadása

Előfordulhat, hogy a REST API-nak hibaüzenetet kell visszaadnia, például: "A felhasználó nem található a CRM rendszerben". Hiba esetén a REST API-nak HTTP 4xx hibaüzenetet kell visszaadnia, például 400-as (hibás kérés) vagy 409-es (ütközési) válaszállapot-kódot. A válasz törzse JSON formátumban formázott hibaüzenetet tartalmaz:

{
  "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"
}

Attribútum	Kötelező	Leírás
Verzió	Igen	A REST API-verzió. Például: 1.0.1
status	Igen	A HTTP-válasz állapotkódjaihoz hasonló számnak kell lennie, és 409-esnek kell lennie. A REST-szolgáltatás http 4XX állapotkódot adhat vissza, de a `status` JSON-formátumú válasz törzsében megadott értéknek meg kell lennie `409`.
code	Nem	Hibakód a RESTful végpontszolgáltatótól, amely akkor jelenik meg, ha `DebugMode` engedélyezve van.
requestId	Nem	A RESTful végpontszolgáltató kérésazonosítója, amely akkor jelenik meg, ha `DebugMode` engedélyezve van.
userMessage	Igen	A felhasználó számára megjelenő hibaüzenet.
developerMessage	Nem	A probléma részletes leírása és kijavítása, amely akkor jelenik meg, ha `DebugMode` engedélyezve van.
moreInfo	Nem	Egy URI, amely további információkra mutat, amelyek akkor jelennek meg, ha `DebugMode` engedélyezve van.

Az alábbi példában egy C# osztály látható, amely hibaüzenetet ad vissza:

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

Következő lépések

A RESTful technikai profil használatára az alábbi cikkekben talál példákat:

Megosztás a következőn keresztül: