Definiowanie profilu technicznego RESTful w zasadach niestandardowych usługi Azure Active Directory B2C
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:
- Dodaj transformację oświadczeń wejściowych z odwołaniem do
GenerateJson
przekształcenia oświadczeń. SendClaimsIn
Ustaw opcję metadanych nabody
ClaimUsedForRequestPayload
Ustaw opcję metadanych na nazwę oświadczenia zawierającego ładunek JSON.- W oświadczeniu wejściowym dodaj odwołanie do oświadczenia wejściowego zawierającego ładunek JSON.
- Dodaj transformację oświadczeń wejściowych z odwołaniem do
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 , , Bearer Basic , ClientCertificate lub ApiKeyHeader .
|
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 , Header Url 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:
|
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 None
wartość , 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 Basic
wartość , 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 ClientCertificate
wartość , 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 Bearer
wartość , 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 ApiKeyHeader
wartość , 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:
- Integrowanie wymiany oświadczeń interfejsu API REST w zasadach niestandardowych usługi Azure AD B2C
- Przewodnik: dodawanie łącznika interfejsu API do przepływu użytkownika rejestracji
- Przewodnik: dodawanie wymiany oświadczeń interfejsu API REST do zasad niestandardowych w usłudze Azure Active Directory B2C
- Zabezpieczanie usług interfejsu API REST