Azure AD B2C'deki API bağlayıcıları hakkında

Önemli

1 Mayıs 2025 tarihinden itibaren Azure AD B2C artık yeni müşteriler için satın alınamayacak. SSS bölümünden daha fazla bilgi edinebilirsiniz.

Başlamadan önce, ayarlamakta olduğunuz ilke türünü seçmek için bu sayfanın üst kısmındaki İlke türü seç seçicisini kullanın. Azure Active Directory B2C, kullanıcıların uygulamalarınızla nasıl etkileşim kurduğunu tanımlamak için iki yöntem sunar: önceden tanımlanmış kullanıcı akışları veya tam olarak yapılandırılabilir özel ilkeler aracılığıyla. Bu makalede gerekli adımlar her yöntem için farklıdır.

Genel Bakış

Geliştirici veya BT yöneticisi olarak, kaydolma deneyimini özelleştirmek ve dış sistemlerle tümleştirmek üzere kaydolma kullanıcı akışlarınızı REST API'lerle tümleştirmek için API bağlayıcılarını kullanabilirsiniz. Örneğin, API bağlayıcıları ile şunları yapabilirsiniz:

Kullanıcı giriş verilerini doğrulayın. Hatalı biçimlendirilmiş veya geçersiz kullanıcı verilerine karşı doğrulama. Örneğin, dış veri deposundaki mevcut verilerde veya izin verilen değerler listesinde kullanıcı tarafından sağlanan verileri doğrulayabilirsiniz. Geçersizse, bir kullanıcıdan geçerli veriler sağlamasını isteyebilir veya kullanıcının kayıt akışına devam etmesini engelleyebilirsiniz.
Kullanıcı kimliğini doğrulayın. Hesap oluşturma kararlarına ek bir güvenlik düzeyi eklemek için bir kimlik doğrulama hizmeti veya dış kimlik veri kaynakları kullanın.
Özel onay iş akışıyla tümleştirme. Hesap oluşturmayı yönetmek ve sınırlamak için özel bir onay sistemine bağlanın.
Dış kaynaklardan gelen özniteliklerle belirteçleri artırma. Bulut sistemleri, özel kullanıcı depoları, özel izin sistemleri, eski kimlik hizmetleri ve daha fazlası gibi Azure AD B2C dışındaki kaynaklardan gelen kullanıcı öznitelikleriyle belirteçleri zenginleştirin.
Kullanıcı özniteliklerini değiştir. Kullanıcıdan toplanan bir özniteliği yeniden biçimlendirin veya bir değer atayın. Örneğin, bir kullanıcı adı yalnızca küçük harfle veya yalnızca büyük harfle girerse, adı yalnızca ilk harfi büyük harfle olacak şekilde biçimlendirebilirsiniz.
Özel iş mantığı çalıştırın. Anında iletme bildirimleri göndermek, şirket veritabanlarını güncelleştirmek, izinleri yönetmek, veritabanlarını denetlemek ve diğer özel eylemleri gerçekleştirmek için bulut sistemlerinizde aşağı akış olaylarını tetikleyebilirsiniz.

API bağlayıcısı, AZURE AD B2C'ye API çağrısı için HTTP uç noktası URL'sini ve kimlik doğrulamasını tanımlayarak API uç noktasını çağırmak için gereken bilgileri sağlar. Bir API bağlayıcısını yapılandırdıktan sonra, bunu kullanıcı akışındaki belirli bir adım için etkinleştirebilirsiniz. Kullanıcı kayıt akışında bu adıma ulaştığında, API bağlayıcısı çağrılır ve API'nize HTTP POST isteği olarak uygulanır ve kullanıcı bilgilerini ("talepler") bir JSON gövdesinde anahtar-değer çiftleri olarak gönderir. API yanıtı, kullanıcı akışının yürütülmesini etkileyebilir. Örneğin, API yanıtı kullanıcının kaydolmasını engelleyebilir, kullanıcıdan bilgileri yeniden yazmasını isteyebilir veya kullanıcı özniteliklerinin üzerine yazabilir.

Kullanıcı akışında API bağlayıcısını etkinleştirebileceğiniz yer

Kullanıcı akışında API bağlayıcısını etkinleştirebileceğiniz üç yer vardır:

Kayıt olma sırasında bir kimlik sağlayıcıyla federasyon kurduktan sonra - yalnızca kayıt olma deneyimleri için geçerlidir
Kullanıcıyı oluşturmadan önce - yalnızca kaydolma deneyimleri için geçerlidir
Belirteci göndermeden önce (önizleme) - kaydolmalar ve oturum açma işlemleri için geçerlidir

Kayıt işleminin bu adımındaki bir API bağlayıcısı, kullanıcı bir kimlik sağlayıcısıyla (Google, Facebook ve Microsoft Entra Id gibi) kimlik doğrulaması yaptıktan hemen sonra çağrılır. Bu adım, kullanıcıya kullanıcı özniteliklerini toplamak için sunulan form olan öznitelik koleksiyonu sayfasından önce geçer. Bir kullanıcı yerel bir hesaba kaydoliyorsa bu adım çağrılmıyor. Bu adımda etkinleştirebilecek api bağlayıcısı senaryolarına örnekler aşağıda verilmiştir:

Kullanıcının mevcut bir sistemdeki talepleri aramak için sağladığı e-postayı veya federasyon kimliğini kullanın. Mevcut sistemden bu talepleri döndür, öznitelik koleksiyonu sayfasını önceden doldurun ve belirteçte döndürülmek üzere kullanılabilir hale getirin.
Sosyal kimliğe dayalı bir izin verme veya engelleme listesi uygulama.

Kullanıcıyı oluşturmadan önce

Kayıt işleminin bu adımındaki bir API bağlayıcısı, varsa öznitelik koleksiyonu sayfasından sonra çağrılır. Bu adım her zaman bir kullanıcı hesabı oluşturulmadan önce çağrılır. Aşağıda, kayıt sırasında bu noktada etkinleştirebilecek senaryo örnekleri verilmiştir:

Kullanıcı giriş verilerini doğrulayın ve bir kullanıcıdan verileri yeniden göndermesini isteyin.
Kullanıcı tarafından girilen verilere göre bir kullanıcı kaydolmasını engelleyin.
Kullanıcı kimliğini doğrulayın.
Kullanıcı hakkındaki mevcut verileri uygulama belirtecinde döndürmek veya Microsoft Entra Id'de depolamak için dış sistemleri sorgulayın.

Jetonu göndermeden önce (önizleme)

Uyarı

Bu özellik genel önizleme aşamasındadır.

Belirteç verilmeden önce kaydolma veya oturum açma işlemindeki bu adımda bir API bağlayıcısı çağrılır. Aşağıda, bu adımda etkinleştirebilecek senaryo örnekleri verilmiştir:

Belirteci eski kimlik sistemleri, İk sistemleri, dış kullanıcı depoları ve daha fazlası dahil olmak üzere dizinden farklı kaynaklardan kullanıcıyla ilgili özniteliklerle zenginleştirme.
Kendi izin sisteminizde depolayıp yönettiğiniz grup veya rol öznitelikleriyle belirteci zenginleştirme.
Dizindeki taleplerin değerlerine talep dönüştürmeleri veya manipülasyonları uygulama.

Azure Active Directory B2C'yi (Azure AD B2C) temel alan Kimlik Deneyimi Çerçevesi, kullanıcı yolculuğu içinde RESTful API'leriyle tümleşebilir. Bu makalede, RESTful teknik profili kullanarak RESTful hizmetiyle etkileşim kuran bir kullanıcı yolculuğu oluşturma gösterilmektedir.

Azure AD B2C'yi kullanarak, kendi RESTful hizmetinizi çağırarak bir kullanıcı yolculuğuna kendi iş mantığınızı ekleyebilirsiniz. Kimlik Deneyimi Çerçevesi, talepleri değiştirmek için RESTful hizmetinizden veri gönderebilir ve alabilir. Örneğin şunları yapabilirsiniz:

Kullanıcı giriş verilerini doğrulamak için dış kimlik veri kaynağını kullanın. Örneğin, kullanıcı tarafından sağlanan e-posta adresinin müşterinizin veritabanında mevcut olduğunu doğrulayabilir ve yoksa bir hata sunabilirsiniz. API bağlayıcılarını, giden webhook'ları destekleme şekli olarak düşünebilirsiniz, çünkü bir olay gerçekleştiğinde, örneğin bir kayıt olduğunda, çağrı yapılır.
Hak taleplerini işleme. Kullanıcı adını küçük harfle veya büyük harfle girerse REST API'niz adı yalnızca ilk harfi büyük harfle biçimlendirebilir ve Azure AD B2C'ye döndürebilir. Ancak, özel bir ilke kullanılırken ClaimsTransformations , RESTful API'sini çağırmak yerine tercih edilir.
Kurumsal iş kolu uygulamalarıyla daha fazla tümleştirerek kullanıcı verilerini dinamik olarak zenginleştirin. RESTful hizmetiniz kullanıcının e-posta adresini alabilir, müşterinin veritabanını sorgulayabilir ve kullanıcının sadakat numarasını Azure AD B2C'ye döndürebilir. Ardından iade talepleri kullanıcının Microsoft Entra hesabında depolanabilir, sonraki düzenleme adımlarında değerlendirilebilir veya erişim belirtecinde yer alabilir.
Özel iş mantığı çalıştırın. Anında iletme bildirimleri gönderebilir, şirket veritabanlarını güncelleştirebilir, kullanıcı geçiş işlemi çalıştırabilir, izinleri yönetebilir, veritabanlarını denetleyebilir ve diğer iş akışlarını gerçekleştirebilirsiniz.

RESTful servis talep değişimi diyagramı

Uyarı

RESTful hizmetinden Azure AD B2C'ye yavaş yanıt alınıyorsa veya yanıt alınmazsa HTTP istekleri iptal edilebilir. Varsayılan zaman aşımı, özel ilkeler için 10 saniye ve kullanıcı akışları için 5 saniyedir. Varsayılan yeniden deneme sayısı birdir (toplamda 2 deneme olduğu anlamına gelir).

RESTful hizmetini çağırma

Etkileşim, REST API talepleri ile Azure AD B2C arasında bilgi alışverişi taleplerini içerir. RESTful hizmetleriyle tümleştirmeyi aşağıdaki yollarla tasarlayabilirsiniz:

Doğrulama teknik profili. RESTful hizmetine yapılan çağrı, belirtilen kendi kendine onaylanan teknik profilin doğrulama teknik profilinde veya bir görüntüleme denetiminin doğrulama görüntüleme denetiminde gerçekleşir. Doğrulama teknik profili, kullanıcı yolculuğu ilerlemeden önce kullanıcı tarafından sağlanan verileri doğrular. Doğrulama teknik profiliyle şunları yapabilirsiniz:
- TALEPLERI REST API'nize gönderin.
- Talepleri doğrulayın ve kullanıcıya görüntülenen özel hata iletileri atın.
- REST API'den sonraki düzenleme adımlarına talepleri geri gönderin.
Talep değişimi. Doğrudan talep değişimi, kullanıcı yolculuğunun düzenleme adımından doğrudan REST API teknik profili çağrılarak yapılandırılabilir. Bu tanım şu şekilde sınırlıdır:
- TALEPLERI REST API'nize gönderin.
- Talepleri doğrulayın ve uygulamaya döndürülen özel hata mesajlarını fırlatın.
- REST API'den sonraki düzenleme adımlarına talepleri geri gönderin.

Özel bir ilke tarafından tanımlanan kullanıcı yolculuğunun herhangi bir adımında REST API çağrısı ekleyebilirsiniz. Örneğin, REST API'sini çağırabilirsiniz:

Oturum açma sırasında, Azure AD B2C kimlik bilgilerini doğrulamadan hemen önce.
Oturum açmadan hemen sonra.
Azure AD B2C dizinde yeni bir hesap oluşturmadan önce.
Azure AD B2C dizinde yeni bir hesap oluşturduğunda.
Azure AD B2C bir erişim jetonu vermeden önce.

Veri gönderme

RESTful teknik profilindeInputClaims öğesi, RESTful hizmetinize gönderilecek taleplerin listesini içerir. Talebinizin adını RESTful hizmetinde tanımlanan adla eşleyebilir, varsayılan bir değer ayarlayabilir ve talep çözümleyicilerini kullanabilirsiniz.

SendClaimsIn özniteliğini kullanarak giriş taleplerinin RESTful talep sağlayıcısına nasıl gönderileceğini yapılandırabilirsiniz. Olası değerler şunlardır:

Body, HTTP POST istek gövdesinde JSON biçiminde gönderilir.
Form, HTTP POST isteği gövdesinde ampersand '&' ile ayrılmış anahtar-değer biçiminde gönderilir.
Üst Bilgi, HTTP GET isteği başlığında gönderildi.
HTTP GET isteği sorgu dizesinde gönderilen QueryString.

Gövde seçeneği yapılandırıldığında, REST API teknik profili bir uç noktaya karmaşık bir JSON yükü göndermenizi sağlar. Daha fazla bilgi için bkz. JSON yükü gönderme.

Veri alma

OutputClaims RESTful teknik profilinin öğ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. DefaultValue özniteliğini ayarladığınız sürece REST API kimlik sağlayıcısı tarafından döndürülmeyecek talepleri de ekleyebilirsiniz.

Çıkış taleplerini ayrıştıran RESTful talep sağlayıcısı, daima aşağıdaki gibi düz bir JSON gövde yanıtı bekler:

{
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "loyaltyNumber":  1234
}

Çıkış talepleri aşağıdaki xml kod parçacığı gibi görünmelidir:

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
  <OutputClaim ClaimTypeReferenceId="email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" />
</OutputClaims>

Null değerleri işleme

Veritabanındaki null değer, sütundaki değer bilinmediğinde veya eksik olduğunda kullanılır. "null" değerine sahip JSON anahtarlarını eklemeyin. Aşağıdaki örnekte e-posta, null değerini döndürür:

{
  "name": "Emily Smith",
  "email": null,
  "loyaltyNumber":  1234
}

Bir öğe null olduğunda, aşağıdakilerden birini de yapabilirsiniz:

JSON'dan anahtar-değer çiftini atla.
Azure AD B2C talep veri türüne karşılık gelen bir değer döndürür. Örneğin, bir string veri türü için boş bir dize "" döndürün. integer Veri türü için sıfır değeri 0döndürür. dateTime Bir veri türü için en düşük değeri 0001-01-01T00:00:00.0000000Zdöndürür.

Aşağıdaki örnekte null değerin nasıl işleneceğini gösterilmektedir. E-posta JSON'dan atlanır:

{
  "name": "Emily Smith",
  "loyaltyNumber":  1234
}

İç içe JSON gövdesini ayrıştırma

İç içe JSON gövdesi yanıtını ayrıştırmak için ResolveJsonPathsInJsonTokens meta verilerini true olarak ayarlayın. Çıkış talebinde PartnerClaimType değerini çıktısını almak istediğiniz JSON yol öğesine ayarlayın.

"contacts": [
  {
    "id": "MAINCONTACT_1",
    "person": {
      "name": "Emily Smith",
      "loyaltyNumber":  1234,
      "emails": [
        {
          "id": "EMAIL_1",
          "type": "WORK",
          "email": "email@domain.com"
        }
      ]
    }
  }
],

Çıkış talepleri aşağıdaki xml kod parçacığı gibi görünmelidir:

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="contacts[0].person.name" />
  <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="contacts[0].person.emails[0].email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="contacts[0].person.loyaltyNumber" />
</OutputClaims>

REST API'yi yerelleştirme

RESTful teknik profilinde, geçerli oturumun dilini/yerel ayarını göndermek ve gerekirse yerelleştirilmiş bir hata iletisi göndermek isteyebilirsiniz. Talep çözümleyicisini kullanarak kullanıcı dili gibi bağlamsal bir talep gönderebilirsiniz. Aşağıdaki örnekte bu senaryoyu gösteren bir RESTful teknik profili gösterilmektedir.

<TechnicalProfile Id="REST-ValidateUserData">
  <DisplayName>Validate user input data</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.azurewebsites.net/api/identity</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="IncludeClaimResolvingInClaimsHandling">true</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="userLanguage" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="email" PartnerClaimType="emailAddress" />
  </InputClaims>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

Hata iletilerini işleme

REST API'nizin "Kullanıcı CRM sisteminde bulunamadı" gibi bir hata iletisi döndürmesi gerekebilir. Hata oluşursa REST API bir HTTP 409 hata iletisi (Çakışma yanıtı durum kodu) döndürmelidir. Daha fazla bilgi için restful teknik profiline bakın.

Bu davranış yalnızca doğrulama teknik profilinden REST API teknik profili çağrılarak gerçekleştirilebilir. Kullanıcının sayfadaki verileri düzeltmesine ve sayfa gönderiminde doğrulamayı yeniden çalıştırmasına izin verme.

Doğrudan bir kullanıcı yolculuğundan REST API teknik profiline başvurursanız, kullanıcı ilgili hata iletisiyle bağlı olan taraf uygulamasına geri yönlendirilir.

REST API'nizin geliştirilmesi

REST API'niz herhangi bir platformda geliştirilebilir ve güvenli olduğu ve JSON biçiminde talep gönderip alabildiği sürece herhangi bir programlama dilinde yazılabilir.

REST API hizmetinize gönderilen istek, Azure AD B2C sunucularından gelir. REST API hizmetinin genel olarak erişilebilen bir HTTPS uç noktasında yayımlanması gerekir. REST API çağrısı bir Azure veri merkezi IP adresinden gelir.

Geliştirme kolaylığı için Azure İşlevleri'nde HTTP tetikleyicileri gibi sunucusuz bulut işlevlerini kullanabilirsiniz.

REST API hizmetinizi ve temel bileşenlerinizi (veritabanı ve dosya sistemi gibi) yüksek oranda kullanılabilir olacak şekilde tasarlamanız gerekir.

Önemli

Uç noktalarınız Azure AD B2C güvenlik gereksinimlerine uygun olmalıdır. Eski TLS sürümleri ve şifreleri kullanım dışıdır. Daha fazla bilgi için Azure AD B2C TLS ve şifre paketi gereksinimleri bölümüne bakın.

Sonraki adımlar

Kaydolma deneyimlerini değiştirmek için API bağlayıcısı eklemeyi öğrenin
Dış taleplerle belirteçleri zenginleştirmek için API bağlayıcısı eklemeyi öğrenin
API Bağlayıcınızın güvenliğini sağlamayı öğrenin
Örneklerimizi kullanmaya başlama

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

Dış süreçlerle etkileşim kurarken dayanıklılık oluşturmayı öğrenin
Geliştirici en iyi yöntemleri aracılığıyla Dayanıklılık oluşturmayı öğrenin.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-04-03