Definiowanie profilu technicznego RESTful w zasadach niestandardowych usługi Azure Active Directory B2C

Artykuł
01/22/2024

Uwaga

W usłudze Azure Active Directory B2C zasady niestandardowe są przeznaczone głównie do rozwiązywania złożonych scenariuszy. W przypadku większości scenariuszy zalecamy używanie wbudowanych przepływów użytkownika. Jeśli nie zostało to zrobione, dowiedz się więcej o niestandardowym pakiecie startowym zasad w temacie Wprowadzenie do zasad niestandardowych w usłudze Active Directory B2C.

Usługa Azure Active Directory B2C (Azure AD B2C) zapewnia obsługę integracji własnej usługi RESTful. Usługa Azure AD B2C wysyła dane do usługi RESTful w kolekcji oświadczeń wejściowych i odbiera dane z powrotem w kolekcji oświadczeń wyjściowych. Aby uzyskać więcej informacji, zobacz Integrowanie wymiany oświadczeń interfejsu API REST w zasadach niestandardowych usługi Azure AD B2C.

Protokół

Atrybut Name elementu Protocol musi być ustawiony na Proprietary. Atrybut programu obsługi musi zawierać w pełni kwalifikowaną nazwę zestawu obsługi protokołu, który jest używany przez usługę Azure AD B2C: Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null.

W poniższym przykładzie przedstawiono profil techniczny 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" />
  ...

Oświadczenia wejściowe

Element InputClaims zawiera listę oświadczeń wysyłanych do interfejsu API REST. Możesz również zamapować nazwę oświadczenia na nazwę zdefiniowaną w interfejsie API REST. W poniższym przykładzie pokazano mapowanie między zasadami a interfejsem API REST. Oświadczenie givenName jest wysyłane do interfejsu API REST jako firstName, podczas gdy nazwisko jest wysyłane jako lastName. Oświadczenie e-mail jest ustawione w następujący sposób.

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

Element InputClaimsTransformations może zawierać kolekcję elementów InputClaimsTransformation , które są używane do modyfikowania oświadczeń wejściowych lub generowania nowych przed wysłaniem do interfejsu API REST.

Wysyłanie ładunku JSON

Profil techniczny interfejsu API REST umożliwia wysyłanie złożonego ładunku JSON do punktu końcowego.

Aby wysłać złożony ładunek JSON:

Skompiluj ładunek JSON za pomocą przekształcenia oświadczeń GenerateJson .
W profilu technicznym interfejsu API REST:
1. Dodaj transformację oświadczeń wejściowych z odwołaniem do GenerateJson przekształcenia oświadczeń.
2. SendClaimsIn Ustaw opcję metadanych nabody
3. ClaimUsedForRequestPayload Ustaw opcję metadanych na nazwę oświadczenia zawierającego ładunek JSON.
4. W oświadczeniu wejściowym dodaj odwołanie do oświadczenia wejściowego zawierającego ładunek JSON.

Poniższy przykład TechnicalProfile wysyła weryfikacyjną wiadomość e-mail przy użyciu usługi poczty e-mail innej firmy (w tym przypadku usługi 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>

Oświadczenia wyjściowe

Element OutputClaims zawiera listę oświadczeń zwracanych przez interfejs API REST. Może być konieczne zamapowania nazwy oświadczenia zdefiniowanego w zasadach na nazwę zdefiniowaną w interfejsie API REST. Można również uwzględnić oświadczenia, które nie są zwracane przez interfejs API REST, o ile ustawisz DefaultValue atrybut.

Element OutputClaimsTransformations może zawierać kolekcję elementów OutputClaimsTransformation , które są używane do modyfikowania oświadczeń wyjściowych lub generowania nowych.

W poniższym przykładzie pokazano oświadczenie zwrócone przez interfejs API REST:

Oświadczenie MembershipId , które jest mapowane na nazwę oświadczenia loyaltyNumber .

Profil techniczny zwraca również oświadczenia, które nie są zwracane przez dostawcę tożsamości:

The loyaltyNumberIsNew claim that has a default value set to true.

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

Metadane

Atrybut	Wymagania	opis
ServiceUrl	Tak	Adres URL punktu końcowego interfejsu API REST.
Authenticationtype	Tak	Typ uwierzytelniania wykonywanego przez dostawcę oświadczeń RESTful. Możliwe wartości: `None`, , `BearerBasic`, `ClientCertificate`lub `ApiKeyHeader`. Wartość `None` wskazuje, że interfejs API REST jest anonimowy. Wartość `Basic` wskazuje, że interfejs API REST jest zabezpieczony przy użyciu uwierzytelniania podstawowego HTTP. Tylko zweryfikowani użytkownicy, w tym usługa Azure AD B2C, mogą uzyskiwać dostęp do interfejsu API. Wartość (zalecana `ClientCertificate` ) wskazuje, że interfejs API REST ogranicza dostęp przy użyciu uwierzytelniania certyfikatu klienta. Tylko usługi z odpowiednimi certyfikatami, na przykład Azure AD B2C, mogą uzyskiwać dostęp do interfejsu API. Wartość `Bearer` wskazuje, że interfejs API REST ogranicza dostęp przy użyciu tokenu elementu nośnego OAuth2 klienta. Wartość `ApiKeyHeader` wskazuje, że interfejs API REST jest zabezpieczony za pomocą nagłówka HTTP klucza interfejsu API, takiego jak x-functions-key.
AllowInsecureAuthInProduction	Nie.	Wskazuje, czy `AuthenticationType` parametr można ustawić na `none` wartość w środowisku produkcyjnym (`DeploymentMode` w obiekcie TrustFrameworkPolicy ustawiono wartość `Production`, czy nie określono). Możliwe wartości: prawda lub fałsz (wartość domyślna).
SendClaimsIn	Nie.	Określa sposób wysyłania oświadczeń wejściowych do dostawcy oświadczeń RESTful. Możliwe wartości: `Body` (wartość domyślna), `Form`, `HeaderUrl` lub `QueryString`. Wartość `Body` to oświadczenie wejściowe wysyłane w treści żądania w formacie JSON. Wartość `Form` to oświadczenie wejściowe, które jest wysyłane w treści żądania w formacie wartości klucza i "&". Wartość `Header` to oświadczenie wejściowe wysyłane w nagłówku żądania. Wartość `Url` to oświadczenie wejściowe, które jest wysyłane w adresie URL, na przykład `https://api.example.com/{claim1}/{claim2}?{claim3}={claim4}`. Część nazwy hosta adresu URL nie może zawierać oświadczeń. Wartość `QueryString` to oświadczenie wejściowe wysyłane w ciągu zapytania żądania. Czasowniki HTTP wywoływane przez poszczególne są następujące: `Body`:POST `Form`:POST `Header`:POBIERZ `Url`:POBIERZ `QueryString`:POBIERZ
ClaimsFormat	Nie.	Obecnie nie można go zignorować.
ClaimUsedForRequestPayload	Nie.	Nazwa oświadczenia ciągu zawierającego ładunek do wysłania do interfejsu API REST.
Debugmode	Nie.	Uruchamia profil techniczny w trybie debugowania. Możliwe wartości: `true`lub `false` (wartość domyślna). W trybie debugowania interfejs API REST może zwrócić więcej informacji. Zobacz sekcję Zwracany komunikat o błędzie.
IncludeClaimResolvingInClaimsHandling	Nie.	W przypadku oświadczeń wejściowych i wyjściowych określa, czy rozwiązanie oświadczeń jest zawarte w profilu technicznym. Możliwe wartości: `true`lub `false` (wartość domyślna). Jeśli chcesz użyć funkcji rozpoznawania oświadczeń w profilu technicznym, ustaw tę opcję na `true`wartość .
ResolveJsonPathsInJsonTokens	Nie.	Wskazuje, czy profil techniczny rozpoznaje ścieżki JSON. Możliwe wartości: `true`lub `false` (wartość domyślna). Te metadane służą do odczytywania danych z zagnieżdżonego elementu JSON. W elemecie OutputClaim ustaw `PartnerClaimType` element ścieżki JSON, który chcesz wyświetlić. Na przykład: `firstName.localized`, lub `data[0].to[0].email`.
UseClaimAsBearerToken	Nie.	Nazwa oświadczenia zawierającego token elementu nośnego.

Obsługa błędów

Następujące metadane mogą służyć do konfigurowania komunikatów o błędach wyświetlanych po niepowodzeniu interfejsu API REST. Komunikaty o błędach mogą być zlokalizowane.

Atrybut	Wymagania	opis
DefaultUserMessageIfRequestFailed	Nie.	Domyślny dostosowany komunikat o błędzie dla wszystkich wyjątków interfejsu API REST.
UserMessageIfCircuitOpen	Nie.	Komunikat o błędzie, gdy interfejs API REST nie jest osiągalny. Jeśli nie zostanie określony, zostanie zwrócony parametr DefaultUserMessageIfRequestFailed.
UserMessageIfDnsResolutionFailed	Nie.	Komunikat o błędzie dotyczący wyjątku rozpoznawania nazw DNS. Jeśli nie zostanie określony, zostanie zwrócony parametr DefaultUserMessageIfRequestFailed.
UserMessageIfRequestTimeout	Nie.	Komunikat o błędzie po przekroczeniu limitu czasu połączenia. Jeśli nie zostanie określony, zostanie zwrócony parametr DefaultUserMessageIfRequestFailed.

Klucze kryptograficzne

Jeśli typ uwierzytelniania jest ustawiony na Nonewartość , element CryptographicKeys nie jest używany.

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

Jeśli typ uwierzytelniania jest ustawiony na Basicwartość , element CryptographicKeys zawiera następujące atrybuty:

Atrybut	Wymagania	opis
BasicAuthenticationUsername	Tak	Nazwa użytkownika używana do uwierzytelniania.
BasicAuthenticationPassword	Tak	Hasło używane do uwierzytelniania.

W poniższym przykładzie przedstawiono profil techniczny z uwierzytelnianiem podstawowym:

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

Jeśli typ uwierzytelniania jest ustawiony na ClientCertificatewartość , element CryptographicKeys zawiera następujący atrybut:

Atrybut	Wymagania	opis
Clientcertificate	Tak	Certyfikat X509 (zestaw kluczy RSA) używany do uwierzytelniania.

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

Jeśli typ uwierzytelniania jest ustawiony na Bearerwartość , element CryptographicKeys zawiera następujący atrybut:

Atrybut	Wymagania	opis
BearerAuthenticationToken	Nie.	Token elementu nośnego 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>

Jeśli typ uwierzytelniania jest ustawiony na ApiKeyHeaderwartość , element CryptographicKeys zawiera następujący atrybut:

Atrybut	Wymagania	opis
Nazwa nagłówka HTTP, takiego jak `x-functions-key`, lub `x-api-key`.	Tak	Klucz używany do uwierzytelniania.

Uwaga

Obecnie usługa Azure AD B2C obsługuje tylko jeden nagłówek HTTP na potrzeby uwierzytelniania. Jeśli wywołanie RESTful wymaga wielu nagłówków, takich jak identyfikator klienta i wartość klucza tajnego klienta, konieczne będzie utworzenie serwera proxy żądania w jakiś sposób.

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

Zwracanie komunikatu o błędzie weryfikacji

Interfejs API REST może wymagać zwrócenia komunikatu o błędzie, takiego jak "Użytkownik nie został znaleziony w systemie CRM". Jeśli wystąpi błąd, interfejs API REST powinien zwrócić komunikat o błędzie HTTP 4xx, taki jak 400 (nieprawidłowe żądanie) lub kod stanu odpowiedzi 409 (konflikt). Treść odpowiedzi zawiera komunikat o błędzie sformatowany w formacie 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"
}

Atrybut	Wymagania	Opis
version	Tak	Wersja interfejsu API REST. Na przykład: 1.0.1
status	Tak	Numer podobny do kodów stanu odpowiedzi HTTP i musi mieć wartość 409. Usługa REST może zwrócić kod stanu HTTP 4XX, ale wartość `status` pliku w treści odpowiedzi w formacie JSON musi mieć wartość `409`.
code	Nie.	Kod błędu dostawcy punktu końcowego RESTful, który jest wyświetlany po `DebugMode` włączeniu.
requestId	Nie.	Identyfikator żądania od dostawcy punktu końcowego RESTful, który jest wyświetlany po `DebugMode` włączeniu.
userMessage	Tak	Komunikat o błędzie wyświetlany użytkownikowi.
developerMessage	Nie.	Pełny opis problemu i sposób jego rozwiązania, który jest wyświetlany po `DebugMode` włączeniu.
więcej informacji	Nie.	Identyfikator URI wskazujący dodatkowe informacje wyświetlane po `DebugMode` włączeniu.

W poniższym przykładzie przedstawiono klasę języka C#, która zwraca komunikat o błędzie:

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

Następne kroki

Zapoznaj się z następującymi artykułami, aby zapoznać się z przykładami korzystania z profilu technicznego RESTful:

Share via