Definování technického profilu RESTful ve vlastních zásadách Azure Active Directory B2C

Článek
01/22/2024

Poznámka:

V Azure Active Directory B2C jsou vlastní zásady navržené především pro řešení složitých scénářů. Ve většině scénářů doporučujeme používat integrované toky uživatelů. Pokud jste to neudělali, přečtěte si informace o úvodním balíčku vlastních zásad v tématu Začínáme s vlastními zásadami ve službě Active Directory B2C.

Azure Active Directory B2C (Azure AD B2C) poskytuje podporu pro integraci vlastní služby RESTful. Azure AD B2C odesílá data do služby RESTful ve vstupní kolekci deklarací identity a přijímá data zpět ve výstupní kolekci deklarací. Další informace najdete v tématu Integrace výměn deklarací identity rozhraní REST API ve vlastních zásadách Azure AD B2C.

Protokol

Atribut Name elementu Protocol musí být nastaven na Proprietary. Atribut obslužné rutiny musí obsahovat plně kvalifikovaný název sestavení obslužné rutiny protokolu, které používá Azure AD B2C: Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null.

Následující příklad ukazuje technický profil 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" />
  ...

Vstupní deklarace identity

Element InputClaims obsahuje seznam deklarací identity, které se mají odeslat do rozhraní REST API. Můžete také namapovat název deklarace identity na název definovaný v rozhraní REST API. Následující příklad ukazuje mapování mezi zásadami a rozhraním REST API. Deklarace givenName je odeslána do rozhraní REST API jako firstName, zatímco příjmení je odesláno jako příjmení. Deklarace e-mailu je nastavená tak, jak je.

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

Element InputClaimsTransformations může obsahovat kolekci elementů InputClaimsTransformation, které se používají k úpravě vstupních deklarací identity nebo generování nových před odesláním do rozhraní REST API.

Odeslání datové části JSON

Technický profil rozhraní REST API umožňuje odeslat komplexní datovou část JSON do koncového bodu.

Odeslání komplexní datové části JSON:

Sestavte datovou část JSON pomocí transformace deklarací identity GenerateJson .
V technickém profilu rozhraní REST API:
1. Přidejte vstupní transformaci deklarací identity s odkazem na GenerateJson transformaci deklarací identity.
2. SendClaimsIn Nastavení možnosti metadat nabody
3. ClaimUsedForRequestPayload Nastavte možnost metadat na název deklarace identity obsahující datovou část JSON.
4. Do vstupní deklarace identity přidejte odkaz na vstupní deklaraci identity obsahující datovou část JSON.

Následující příklad TechnicalProfile odešle ověřovací e-mail pomocí e-mailové služby třetí strany (v tomto případě 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>

Výstupní deklarace identity

Element OutputClaims obsahuje seznam deklarací identity vrácených rozhraním REST API. Možná budete muset namapovat název deklarace identity definované ve vaší zásadě na název definovaný v rozhraní REST API. Můžete také zahrnout deklarace identity, které nevrací rozhraní REST API, pokud nastavíte DefaultValue atribut.

OutputClaimsTransformations element může obsahovat kolekci OutputClaimsTransformation elementů, které slouží k úpravě výstupních deklarací identity nebo generování nových.

Následující příklad ukazuje deklaraci identity vrácenou rozhraním REST API:

Deklarace Id členství , která je namapovaná na název deklarace typu loyaltyNumber .

Technický profil také vrací deklarace identity, které nevrací zprostředkovatel identity:

Deklarace loyaltyNumberIsNew , která má výchozí hodnotu nastavenou na true.

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

Metadata

Atribut	Požadováno	Popis
ServiceUrl	Ano	Adresa URL koncového bodu rozhraní REST API.
Authenticationtype	Ano	Typ ověřování prováděné zprostředkovatelem deklarací identity RESTful. Možné hodnoty: `None`, `Basic`, `Bearer`, `ClientCertificate`nebo `ApiKeyHeader`. Hodnota `None` označuje, že rozhraní REST API je anonymní. Hodnota `Basic` označuje, že rozhraní REST API je zabezpečené pomocí základního ověřování HTTP. K vašemu rozhraní API mají přístup jenom ověření uživatelé, včetně Azure AD B2C. Hodnota `ClientCertificate` (doporučená) označuje, že rozhraní REST API omezuje přístup pomocí ověřování klientským certifikátem. K vašemu rozhraní API mají přístup jenom služby, které mají odpovídající certifikáty, například Azure AD B2C. Hodnota `Bearer` označuje, že rozhraní REST API omezuje přístup pomocí nosné tokenu klienta OAuth2. Hodnota `ApiKeyHeader` označuje, že rozhraní REST API je zabezpečené pomocí hlavičky HTTP klíče rozhraní API, například x-functions-key.
AllowInsecureAuthInProduction	No	Určuje, zda `AuthenticationType` lze nastavit na `none` hodnotu v produkčním prostředí (`DeploymentMode`hodnota TrustFrameworkPolicy je nastavena na `Production`hodnotu , nebo není určena). Možné hodnoty: true nebo false (výchozí).
SendClaimsIn	No	Určuje, jak se vstupní deklarace identity odesílají zprostředkovateli deklarací RESTful. Možné hodnoty: `Body` (výchozí), `Form`, `Header`nebo `UrlQueryString`. Hodnota `Body` je vstupní deklarace identity, která se odešle v textu požadavku ve formátu JSON. Hodnota `Form` je vstupní deklarace identity, která se odešle v textu požadavku ve formátu hodnoty klíče odděleného ampersandem '&'. Hodnota `Header` je vstupní deklarace identity, která je odeslána v hlavičce požadavku. Hodnota `Url` je vstupní deklarace identity, která je odeslána v adrese URL, `https://api.example.com/{claim1}/{claim2}?{claim3}={claim4}`například . Část názvu hostitele adresy URL nemůže obsahovat deklarace identity. Hodnota `QueryString` je vstupní deklarace identity, která je odeslána v řetězci dotazu požadavku. Slovesa HTTP vyvolaná jednotlivými příkazy jsou následující: `Body`:PŘÍSPĚVEK `Form`:PŘÍSPĚVEK `Header`:DOSTAT `Url`:DOSTAT `QueryString`:DOSTAT
ClaimsFormat	No	Aktuálně se nepoužívá, je možné ho ignorovat.
ClaimUsedForRequestPayload	No	Název deklarace identity řetězce, která obsahuje datovou část, která se má odeslat do rozhraní REST API.
DebugMode	No	Spustí technický profil v režimu ladění. Možné hodnoty: `true`nebo `false` (výchozí). V režimu ladění může rozhraní REST API vrátit další informace. Podívejte se na část Návratová chybová zpráva .
IncludeClaimResolvingInClaimsHandling	No	U vstupních a výstupních deklarací identity určuje, jestli je řešení deklarací identity součástí technického profilu. Možné hodnoty: `true`nebo `false` (výchozí). Pokud chcete použít překladač deklarací identity v technickém profilu, nastavte ho na `true`hodnotu .
ResolveJsonPathsInJsonTokens	No	Určuje, jestli technický profil překládá cesty JSON. Možné hodnoty: `true`nebo `false` (výchozí). Tato metadata slouží ke čtení dat z vnořeného elementu JSON. V outputClaim nastavte `PartnerClaimType` na element cesty JSON, který chcete vytvořit výstup. Příklad: `firstName.localized`nebo `data[0].to[0].email`.
UseClaimAsBearerToken	No	Název deklarace identity, která obsahuje nosný token.

Zpracování chyb

Následující metadata lze použít ke konfiguraci chybových zpráv zobrazených při selhání rozhraní REST API. Chybové zprávy lze lokalizovat.

Atribut	Požadováno	Popis
DefaultUserMessageIfRequestFailed	No	Výchozí přizpůsobená chybová zpráva pro všechny výjimky rozhraní REST API.
UserMessageIfCircuitOpen	No	Chybová zpráva, když rozhraní REST API není dostupné. Pokud není zadáno, vrátí se defaultUserMessageIfRequestFailed.
UserMessageIfDnsResolutionFailed	No	Chybová zpráva výjimky překladu DNS Pokud není zadáno, vrátí se defaultUserMessageIfRequestFailed.
UserMessageIfRequestTimeout	No	Chybová zpráva při vypršení časového limitu připojení Pokud není zadáno, vrátí se defaultUserMessageIfRequestFailed.

Kryptografické klíče

Pokud je typ ověřování nastaven na None, CryptographicKeys element se nepoužívá.

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

Pokud je typ ověřování nastaven na Basic, element CryptographicKeys obsahuje následující atributy:

Atribut	Požadováno	Popis
BasicAuthenticationUsername	Ano	Uživatelské jméno, které se používá k ověření.
BasicAuthenticationPassword	Ano	Heslo, které se používá k ověření.

Následující příklad ukazuje technický profil se základním ověřováním:

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

Pokud je typ ověřování nastaven ClientCertificatena , element CryptographicKeys obsahuje následující atribut:

Atribut	Požadováno	Popis
ClientCertificate	Ano	Certifikát X509 (sada klíčů RSA), který se má použít k ověření.

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

Pokud je typ ověřování nastaven Bearerna , element CryptographicKeys obsahuje následující atribut:

Atribut	Požadováno	Popis
BearerAuthenticationToken	No	Nosný token 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>

Pokud je typ ověřování nastaven ApiKeyHeaderna , element CryptographicKeys obsahuje následující atribut:

Atribut	Požadováno	Popis
Název hlavičky HTTP, například `x-functions-key`, nebo `x-api-key`.	Ano	Klíč, který se používá k ověření.

Poznámka:

V tuto chvíli Azure AD B2C podporuje pouze jednu hlavičku HTTP pro ověřování. Pokud volání RESTful vyžaduje více hlaviček, jako je ID klienta a hodnota tajného klíče klienta, budete muset požadavek nějakým způsobem zprostředkovat.

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

Chybová zpráva o vrácení ověření

Vaše rozhraní REST API může potřebovat vrátit chybovou zprávu, například Uživatel nebyl v systému CRM nalezen. Pokud dojde k chybě, rozhraní REST API by mělo vrátit chybovou zprávu HTTP 4xx, například 400 (chybný požadavek) nebo stavový kód odpovědi 409 (konflikt). Text odpovědi obsahuje chybovou zprávu formátovanou ve formátu 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"
}

Atribut	Požadováno	Popis
version	Ano	Vaše verze rozhraní REST API. Příklad: 1.0.1
stav	Ano	Stavové kódy odpovědi HTTP a musí být 409. Služba REST může vrátit stavový kód HTTP 4XX, ale hodnota `status` souboru v textu odpovědi ve formátu JSON musí být `409`.
code	No	Kód chyby od poskytovatele koncového bodu RESTful, který se zobrazí, když `DebugMode` je povolený.
requestId	No	Identifikátor požadavku od poskytovatele koncového bodu RESTful, který se zobrazí, když `DebugMode` je povolený.
userMessage	Ano	Chybová zpráva, která se uživateli zobrazí.
developerMessage	No	Podrobný popis problému a jeho oprava, která se zobrazí, když `DebugMode` je povolená.
moreInfo	No	Identifikátor URI, který odkazuje na další informace, které se zobrazí, když `DebugMode` je povoleno.

Následující příklad ukazuje třídu C#, která vrací chybovou zprávu:

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

Další kroky

Příklady použití technického profilu RESTful najdete v následujících článcích: