Azure Active Directory B2C özel ilkesinde RESTful teknik profili tanımlama

Makale
01/23/2024

Not

Azure Active Directory B2C'de özel ilkeler öncelikli olarak karmaşık senaryoları ele almak için tasarlanmıştır. Çoğu senaryoda, yerleşik kullanıcı akışlarını kullanmanızı öneririz. Bunu yapmadıysanız, Active Directory B2C'de özel ilkeleri kullanmaya başlama bölümünde özel ilke başlangıç paketi hakkında bilgi edinin.

Azure Active Directory B2C (Azure AD B2C), kendi RESTful hizmetinizi tümleştirme desteği sağlar. Azure AD B2C, bir giriş talepleri koleksiyonunda RESTful hizmetine veri gönderir ve verileri bir çıkış talepleri koleksiyonuna geri alır. Daha fazla bilgi için bkz . Azure AD B2C özel ilkenizde REST API talep değişimlerini tümleştirme.

Protokol

Protocol öğesinin Name özniteliği olarak ayarlanmalıdırProprietary. İşleyici özniteliği, Azure AD B2C: tarafından kullanılan protokol işleyici derlemesinin tam adını içermelidir. Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null

Aşağıdaki örnekte RESTful teknik profili gösterilmektedir:

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

Giriş talepleri

InputClaims öğesi, REST API'ye gönderilecek taleplerin listesini içerir. Ayrıca talebinizin adını REST API'de tanımlanan adla eşleyebilirsiniz. Aşağıdaki örnekte, ilkeniz ile REST API arasındaki eşleme gösterilmektedir. givenName talebi REST API'ye firstName olarak, soyadı ise lastName olarak gönderilir. E-posta talebi olduğu gibi ayarlanır.

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

InputClaimsTransformations öğesi, REST API'ye göndermeden önce giriş taleplerini değiştirmek veya yenilerini oluşturmak için kullanılan Bir InputClaimsTransformation öğeleri koleksiyonu içerebilir.

JSON yükü gönderme

REST API teknik profili, bir uç noktaya karmaşık bir JSON yükü göndermenizi sağlar.

Karmaşık bir JSON yükü göndermek için:

GenerateJson talep dönüştürmesi ile JSON yükünüzü oluşturun.
REST API teknik profilinde:
1. Talep dönüştürme başvurusuyla bir giriş talep dönüştürmesi GenerateJson ekleyin.
2. Meta veri seçeneğini olarak SendClaimsIn ayarlayın body
3. ClaimUsedForRequestPayload Meta veri seçeneğini JSON yükünü içeren talebin adına ayarlayın.
4. Giriş talebine JSON yükünü içeren giriş talebine bir başvuru ekleyin.

Aşağıdaki örnek TechnicalProfile , üçüncü taraf e-posta hizmetini (bu örnekte SendGrid) kullanarak bir doğrulama e-postası gönderir.

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

Çıkış talepleri

OutputClaims öğesi, REST API tarafından döndürülen taleplerin listesini içerir. İlkenizde tanımlanan talebin adını REST API'de tanımlanan adla eşlemeniz gerekebilir. Ayrıca, özniteliğini ayarladığınız DefaultValue sürece REST API tarafından döndürülmeyecek talepleri de ekleyebilirsiniz.

OutputClaimsTransformations öğesi, çıkış taleplerini değiştirmek veya yenilerini oluşturmak için kullanılan OutputClaimsTransformation öğelerinin bir koleksiyonunu içerebilir.

Aşağıdaki örnekte REST API tarafından döndürülen talep gösterilmektedir:

loyaltyNumber talep adına eşlenen MembershipId talebi.

Teknik profil, kimlik sağlayıcısı tarafından döndürülmeyen talepleri de döndürür:

varsayılan değeri olarak ayarlanmış trueolan loyaltyNumberIsNew talebi.

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

Meta veri

Öznitelik	Zorunlu	Açıklama
ServiceUrl	Yes	REST API uç noktasının URL'si.
Authenticationtype	Yes	RESTful talep sağlayıcısı tarafından gerçekleştirilen kimlik doğrulama türü. Olası değerler: `None`, `Basic`, `Bearer`, `ClientCertificate`veya `ApiKeyHeader`. değeri REST `None` API'nin anonim olduğunu gösterir. değeri, `Basic` REST API'nin HTTP temel kimlik doğrulaması ile güvenli olduğunu gösterir. API'nize yalnızca Azure AD B2C dahil doğrulanmış kullanıcılar erişebilir. `ClientCertificate` (önerilen) değeri, REST API'nin istemci sertifikası kimlik doğrulaması kullanarak erişimi kısıtladığını gösterir. API'nize yalnızca uygun sertifikalara sahip hizmetler (örneğin Azure AD B2C) erişebilir. değeri, `Bearer` REST API'nin istemci OAuth2 Taşıyıcı belirtecini kullanarak erişimi kısıtladığını gösterir. `ApiKeyHeader` değeri, REST API'nin x-functions-key gibi API anahtarı HTTP üst bilgisi ile güvenli olduğunu gösterir.
AllowInsecureAuthInProduction	Hayır	öğesinin `AuthenticationType` üretim ortamında (`DeploymentModenone` TrustFrameworkPolicy'nin olarak ayarlanıp ayarlanamayacağını `Production`veya belirtilmediğini) gösterir. Olası değerler: true veya false (varsayılan).
SendClaimsIn	Hayır	Giriş taleplerinin RESTful talep sağlayıcısına nasıl gönderileceğini belirtir. Olası değerler: `Body` (varsayılan), `Form`, `Header`veya `UrlQueryString`. `Body` Değer, JSON biçiminde istek gövdesinde gönderilen giriş talebidir. `Form` Değer, istek gövdesinde ve '&' ayrılmış anahtar değeri biçiminde gönderilen giriş talebidir. `Header` Değer, istek üst bilgisinde gönderilen giriş talebidir. `Url` Değer, URL'de gönderilen giriş talebidir; örneğin, `https://api.example.com/{claim1}/{claim2}?{claim3}={claim4}`. URL'nin ana bilgisayar adı bölümü talep içeremez. `QueryString` Değer, istek sorgu dizesinde gönderilen giriş talebidir. Her birinin çağırdığı HTTP fiilleri aşağıdaki gibidir: `Body`:YAYINLA `Form`:YAYINLA `Header`:AL `Url`:AL `QueryString`:AL
ClaimsFormat	Hayır	Şu anda kullanılmaz, yoksayılabilir.
ClaimUsedForRequestPayload	Hayır	REST API'ye gönderilecek yükü içeren bir dize talebi adı.
DebugMode	Hayır	Teknik profili hata ayıklama modunda çalıştırır. Olası değerler: `true`veya `false` (varsayılan). Hata ayıklama modunda REST API daha fazla bilgi döndürebilir. Geri dönen hata iletisi bölümüne bakın.
IncludeClaimResolvingInClaimsHandling	Hayır	Giriş ve çıkış talepleri için, talep çözümlemesinin teknik profile dahil edilip edilmeyeceğini belirtir. Olası değerler: `true`veya `false` (varsayılan). Teknik profilde bir talep çözümleyicisi kullanmak istiyorsanız, bunu olarak `true`ayarlayın.
ResolveJsonPathsInJsonTokens	Hayır	Teknik profilin JSON yollarını çözümleyip çözümlemediğini gösterir. Olası değerler: `true`veya `false` (varsayılan). İç içe JSON öğesinden verileri okumak için bu meta verileri kullanın. OutputClaim içinde, çıkışını `PartnerClaimType` almak istediğiniz JSON yol öğesine ayarlayın. Örneğin: `firstName.localized`, veya `data[0].to[0].email`.
UseClaimAsBearerToken	Hayır	Taşıyıcı belirtecini içeren talebin adı.

Hata işleme

REST API hatasından sonra görüntülenen hata iletilerini yapılandırmak için aşağıdaki meta veriler kullanılabilir. Hata iletileri yerelleştirilebilir.

Öznitelik	Zorunlu	Açıklama
DefaultUserMessageIfRequestFailed	Hayır	Tüm REST API özel durumları için varsayılan özelleştirilmiş hata iletisi.
UserMessageIfCircuitOpen	Hayır	REST API'ye ulaşılamıyorsa hata iletisi. Belirtilmezse DefaultUserMessageIfRequestFailed döndürülür.
UserMessageIfDnsResolutionFailed	Hayır	DNS çözümleme özel durumu için hata iletisi. Belirtilmezse DefaultUserMessageIfRequestFailed döndürülür.
UserMessageIfRequestTimeout	Hayır	Bağlantı zaman aşımına uğradıysa hata iletisi. Belirtilmezse DefaultUserMessageIfRequestFailed döndürülür.

Şifreleme anahtarları

Kimlik doğrulama türü olarak Noneayarlanırsa, CryptographicKeys öğesi kullanılmaz.

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

Kimlik doğrulama türü olarak Basicayarlanırsa, CryptographicKeys öğesi aşağıdaki öznitelikleri içerir:

Öznitelik	Zorunlu	Açıklama
BasicAuthenticationUsername	Yes	Kimlik doğrulaması için kullanılan kullanıcı adı.
BasicAuthenticationPassword	Yes	Kimlik doğrulaması için kullanılan parola.

Aşağıdaki örnekte temel kimlik doğrulamasına sahip bir teknik profil gösterilmektedir:

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

Kimlik doğrulama türü olarak ayarlanırsaClientCertificate, CryptographicKeys öğesi aşağıdaki özniteliği içerir:

Öznitelik	Zorunlu	Açıklama
ClientCertificate	Yes	Kimlik doğrulaması için kullanılacak X509 sertifikası (RSA anahtar kümesi).

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

Kimlik doğrulama türü olarak ayarlanırsaBearer, CryptographicKeys öğesi aşağıdaki özniteliği içerir:

Öznitelik	Zorunlu	Açıklama
BearerAuthenticationToken	Hayır	OAuth 2.0 Taşıyıcı Belirteci.

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

Kimlik doğrulama türü olarak ayarlanırsaApiKeyHeader, CryptographicKeys öğesi aşağıdaki özniteliği içerir:

Öznitelik	Zorunlu	Açıklama
HTTP üst bilgisinin adı , veya `x-api-key`gibi`x-functions-key`.	Yes	Kimlik doğrulaması için kullanılan anahtar.

Not

Şu anda Azure AD B2C kimlik doğrulaması için yalnızca bir HTTP üst bilgisini destekler. RESTful çağrınız istemci kimliği ve istemci gizli anahtarı değeri gibi birden çok üst bilgi gerektiriyorsa, isteği bir şekilde ara sunucu olarak kullanmanız gerekir.

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

Doğrulama hata iletisi döndürülerek

REST API'nizin 'Kullanıcı CRM sisteminde bulunamadı' gibi bir hata iletisi döndürmesi gerekebilir. Hata oluşursa REST API 400 (hatalı istek) veya 409 (çakışma) yanıt durum kodu gibi bir HTTP 4xx hata iletisi döndürmelidir. Yanıt gövdesi JSON'da biçimlendirilmiş hata iletisi içeriyor:

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

Öznitelik	Zorunlu	Açıklama
sürüm	Yes	REST API sürümünüz. Örneğin: 1.0.1
durum	Yes	HTTP yanıt durumu kodları benzeri bir sayıdır ve 409 olmalıdır. REST hizmetiniz bir HTTP 4XX durum kodu döndürebilir, ancak JSON biçimli yanıt gövdesinde dosyalanan değerinin `status` olması `409`gerekir.
kod	Hayır	ETKINLEŞTIRildiğinde `DebugMode` görüntülenen RESTful uç nokta sağlayıcısından bir hata kodu.
requestId	Hayır	ETKINLEŞTIRildiğinde `DebugMode` görüntülenen RESTful uç nokta sağlayıcısından bir istek tanımlayıcısı.
userMessage	Yes	Kullanıcıya gösterilen bir hata iletisi.
developerMessage	Hayır	Sorunun ayrıntılı açıklaması ve sorunun nasıl düzeltildiği, etkinleştirildiğinde `DebugMode` görüntülenen.
moreInfo	Hayır	Etkinleştirildiğinde `DebugMode` görüntülenen ek bilgilere işaret eden bir URI.

Aşağıdaki örnekte hata iletisi döndüren bir C# sınıfı gösterilmektedir:

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

Sonraki adımlar

RESTful teknik profili kullanma örnekleri için aşağıdaki makalelere bakın: