Definiera en RESTful-teknisk profil i en anpassad Azure Active Directory B2C-princip

Artikel
01/22/2024

Kommentar

I Azure Active Directory B2C är anpassade principer främst utformade för att hantera komplexa scenarier. I de flesta scenarier rekommenderar vi att du använder inbyggda användarflöden. Om du inte har gjort det kan du läsa mer om startpaketet för anpassad princip i Kom igång med anpassade principer i Active Directory B2C.

Azure Active Directory B2C (Azure AD B2C) ger stöd för integrering av din egen RESTful-tjänst. Azure AD B2C skickar data till RESTful-tjänsten i en insamling av indataanspråk och tar emot data i en insamling av utdataanspråk. Mer information finns i Integrera REST API-anspråksutbyten i din anpassade Azure AD B2C-princip.

Protokoll

Attributet Namn för protokollelementet måste anges till Proprietary. Hanterarattributet måste innehålla det fullständigt kvalificerade namnet på protokollhanterarsammansättningen som används av Azure AD B2C: Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null.

I följande exempel visas en RESTful-teknisk profil:

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

Indataanspråk

Elementet InputClaims innehåller en lista över anspråk som ska skickas till REST-API:et. Du kan också mappa namnet på anspråket till det namn som definierats i REST-API:et. I följande exempel visas mappningen mellan din princip och REST-API:et. GivenName-anspråket skickas till REST-API:et som firstName, medan efternamn skickas som efternamn. E-postanspråket anges som det är.

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

Elementet InputClaimsTransformations kan innehålla en samling InputClaimsTransformation-element som används för att ändra indataanspråken eller generera nya innan de skickas till REST-API:et.

Skicka en JSON-nyttolast

Med den tekniska REST API-profilen kan du skicka en komplex JSON-nyttolast till en slutpunkt.

Så här skickar du en komplex JSON-nyttolast:

Skapa din JSON-nyttolast med GenerateJson-anspråkstransformeringen .
I den tekniska REST API-profilen:
1. Lägg till en transformering av indataanspråk med en referens till GenerateJson anspråkstransformeringen.
2. Ange metadataalternativet SendClaimsIn till body
3. ClaimUsedForRequestPayload Ange metadataalternativet till namnet på anspråket som innehåller JSON-nyttolasten.
4. I indataanspråket lägger du till en referens till det indataanspråk som innehåller JSON-nyttolasten.

I följande exempel TechnicalProfile skickas ett e-postmeddelande med verifiering med hjälp av en e-posttjänst från tredje part (i det här fallet 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>

Utdataanspråk

OutputClaims-elementet innehåller en lista över anspråk som returneras av REST-API:et. Du kan behöva mappa namnet på anspråket som definierats i principen till det namn som definierats i REST-API:et. Du kan också inkludera anspråk som inte returneras av REST-API:et så länge du anger DefaultValue attributet.

Elementet OutputClaimsTransformations kan innehålla en samling OutputClaimsTransformation-element som används för att ändra utdataanspråken eller generera nya.

I följande exempel visas anspråket som returneras av REST-API:et:

MembershipId-anspråket som mappas till anspråksnamnet loyaltyNumber.

Den tekniska profilen returnerar också anspråk som inte returneras av identitetsprovidern:

loyaltyNumberIsNyt anspråk som har ett standardvärde inställt på true.

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

Metadata

Attribut	Obligatoriskt	Beskrivning
ServiceUrl	Ja	URL:en för REST API-slutpunkten.
AuthenticationType	Ja	Den typ av autentisering som utförs av RESTful-anspråksprovidern. Möjliga värden: `None`, `Basic`, `Bearer`, `ClientCertificate`eller `ApiKeyHeader`. Värdet `None` anger att REST-API:et är anonymt. Värdet `Basic` anger att REST-API:et skyddas med grundläggande HTTP-autentisering. Endast verifierade användare, inklusive Azure AD B2C, kan komma åt ditt API. Värdet `ClientCertificate` (rekommenderas) anger att REST-API:et begränsar åtkomsten med hjälp av klientcertifikatautentisering. Endast tjänster som har rätt certifikat, till exempel Azure AD B2C, kan komma åt ditt API. Värdet `Bearer` anger att REST-API:et begränsar åtkomsten med hjälp av klient-OAuth2 Bearer-token. Värdet `ApiKeyHeader` anger att REST-API:et skyddas med API-nyckelns HTTP-huvud, till exempel x-functions-key.
AllowInsecureAuthInProduction	Nej	Anger om `AuthenticationType` kan anges till `none` i produktionsmiljön (`DeploymentMode` för TrustFrameworkPolicy har angetts till `Production`, eller inte angetts). Möjliga värden: sant eller falskt (standard).
SendClaimsIn	Nej	Anger hur indataanspråken skickas till RESTful-anspråksprovidern. Möjliga värden: `Body` (standard), `Form`, `Header`eller `UrlQueryString`. Värdet `Body` är det indataanspråk som skickas i begärandetexten i JSON-format. Värdet `Form` är det indataanspråk som skickas i begärandetexten i ett &ersoch avgränsat nyckelvärdeformat. Värdet `Header` är det indataanspråk som skickas i begärandehuvudet. Värdet `Url` är det indataanspråk som skickas i URL:en, till exempel `https://api.example.com/{claim1}/{claim2}?{claim3}={claim4}`. Värdnamnets del av URL:en får inte innehålla anspråk. Värdet `QueryString` är det indataanspråk som skickas i frågesträngen för begäran. HTTP-verben som anropas av var och en är följande: `Body`:INLÄGG `Form`:INLÄGG `Header`:FÅ `Url`:FÅ `QueryString`:FÅ
ClaimsFormat	Nej	Används inte för närvarande, kan ignoreras.
ClaimUsedForRequestPayload	Nej	Namnet på ett stränganspråk som innehåller nyttolasten som ska skickas till REST-API:et.
FelsökaMode	Nej	Kör den tekniska profilen i felsökningsläge. Möjliga värden: `true`, eller `false` (standard). I felsökningsläge kan REST-API:et returnera mer information. Se avsnittet Returnera felmeddelande.
IncludeClaimResolvingInClaimsHandling	Nej	För indata- och utdataanspråk anger om anspråksmatchning ingår i den tekniska profilen. Möjliga värden: `true`, eller `false` (standard). Om du vill använda en anspråkslösare i den tekniska profilen anger du detta till `true`.
ResolveJsonPathsInJsonTokens	Nej	Anger om den tekniska profilen löser JSON-sökvägar. Möjliga värden: `true`, eller `false` (standard). Använd dessa metadata för att läsa data från ett kapslat JSON-element. I en OutputClaim anger du `PartnerClaimType` till det JSON-sökvägselement som du vill mata ut. Till exempel: `firstName.localized`, eller `data[0].to[0].email`.
UseClaimAsBearerToken	Nej	Namnet på anspråket som innehåller ägartoken.

Felhantering

Följande metadata kan användas för att konfigurera felmeddelandena som visas vid REST API-fel. Felmeddelandena kan lokaliseras.

Attribut	Obligatoriskt	Beskrivning
DefaultUserMessageIfRequestFailed	Nej	Ett standardanpassat felmeddelande för alla REST API-undantag.
UserMessageIfCircuitOpen	Nej	Felmeddelande när REST-API:et inte kan nås. Om det inte anges returneras DefaultUserMessageIfRequestFailed.
UserMessageIfDnsResolutionFailed	Nej	Felmeddelande för DNS-matchningsfelet. Om det inte anges returneras DefaultUserMessageIfRequestFailed.
UserMessageIfRequestTimeout	Nej	Felmeddelande när tidsgränsen för anslutningen har överskrids. Om det inte anges returneras DefaultUserMessageIfRequestFailed.

Krypteringsnycklar

Om typen av autentisering är inställd på Noneanvänds inte cryptographicKeys-elementet.

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

Om typen av autentisering är inställd på Basicinnehåller cryptographicKeys-elementet följande attribut:

Attribut	Obligatoriskt	Beskrivning
BasicAuthenticationUsername	Ja	Användarnamnet som används för att autentisera.
BasicAuthenticationPassword	Ja	Lösenordet som används för att autentisera.

I följande exempel visas en teknisk profil med grundläggande autentisering:

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

Om typen av autentisering är inställd på ClientCertificateinnehåller cryptographicKeys-elementet följande attribut:

Attribut	Obligatoriskt	Beskrivning
ClientCertificate	Ja	X509-certifikatet (RSA-nyckeluppsättningen) som ska användas för att autentisera.

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

Om typen av autentisering är inställd på Bearerinnehåller cryptographicKeys-elementet följande attribut:

Attribut	Obligatoriskt	Beskrivning
BearerAuthenticationToken	Nej	OAuth 2.0-ägartoken.

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

Om typen av autentisering är inställd på ApiKeyHeaderinnehåller cryptographicKeys-elementet följande attribut:

Attribut	Obligatoriskt	Beskrivning
Namnet på HTTP-huvudet, till exempel `x-functions-key`, eller `x-api-key`.	Ja	Nyckeln som används för att autentisera.

Kommentar

För närvarande stöder Azure AD B2C endast ett HTTP-huvud för autentisering. Om ditt RESTful-anrop kräver flera huvuden, till exempel ett klient-ID och ett klienthemlighetsvärde, måste du proxy-överföra begäran på något sätt.

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

Returnerar valideringsfelmeddelande

Rest-API:et kan behöva returnera ett felmeddelande, till exempel "Användaren hittades inte i CRM-systemet". Om ett fel uppstår ska REST API returnera ett HTTP 4xx-felmeddelande, till exempel 400 (felaktig begäran) eller 409 (konflikt) svarsstatuskod. Svarstexten innehåller felmeddelandet formaterat i 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"
}

Attribut	Obligatoriskt	Beskrivning
version	Ja	Din REST API-version. Till exempel: 1.0.1
status	Ja	Ett HTTP-svarsstatuskodsliknande nummer och måste vara 409. Rest-tjänsten kan returnera en HTTP 4XX-statuskod, men värdet för den `status` inlämnade i den JSON-formaterade svarstexten måste vara `409`.
kod	Nej	En felkod från RESTful-slutpunktsprovidern, som visas när `DebugMode` är aktiverad.
requestId	Nej	En begärandeidentifierare från RESTful-slutpunktsprovidern, som visas när `DebugMode` är aktiverad.
userMessage	Ja	Ett felmeddelande som visas för användaren.
developerMessage	Nej	Den utförliga beskrivningen av problemet och hur du åtgärdar det, som visas när `DebugMode` är aktiverat.
moreInfo	Nej	En URI som pekar på ytterligare information, som visas när `DebugMode` är aktiverad.

I följande exempel visas en C#-klass som returnerar ett felmeddelande:

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

Nästa steg

I följande artiklar finns exempel på hur du använder en RESTful-teknisk profil: