Kaydolma kullanıcı akışlarını ve özel ilkeleri dış kimlik veri kaynaklarıyla özelleştirmek ve genişletmek için API bağlayıcılarını kullanma

Başlamadan önce, ayarladığınız ilke türünü seçmek için İlke türü seçin 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 tamamen 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'leriyle tümleştirmek için API bağlayıcılarını kullanabilirsiniz. Örneğin API bağlayıcılarıyla şunları yapabilirsiniz:

• Kullanıcı giriş verilerini doğrulayın. Hatalı biçimlendirilmiş veya geçersiz kullanıcı verilerine karşı doğrulama. Örneğin, kullanıcı tarafından sağlanan verileri dış veri deposundaki mevcut verilerle veya izin verilen değerler listesinde doğrulayabilirsiniz. Geçersizse, bir kullanıcıdan geçerli veriler sağlamasını veya kullanıcının kayıt akışına devam etmesini engellemesini isteyebilirsiniz.
• 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 alınan ö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 kullanıcıyla ilgili özniteliklerle belirteçleri zenginleştirin.
• Kullanıcı özniteliklerinin üzerine yaz. Kullanıcıdan toplanan bir özniteliği yeniden biçimlendirin veya bir değer atayın. Örneğin, bir kullanıcı adın tamamını küçük harfle veya tümü büyük harfle girerse, adı yalnızca ilk harfi büyük harfle 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. 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 gerçekleştirilir 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 vermesini 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 sırasında bir kimlik sağlayıcısıyla federasyon kurduktan sonra , yalnızca kaydolma 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

Kaydolma sırasında bir kimlik sağlayıcısıyla federasyon kurduktan sonra

Kullanıcı bir kimlik sağlayıcısıyla (Google, Facebook ve Microsoft Entra Kimliği gibi) kimlik doğrulaması yaptıktan hemen sonra kaydolma işlemindeki bu adımda bir API bağlayıcısı çağrılır. Bu adım, kullanıcı özniteliklerini toplamak için kullanıcıya sunulan form olan öznitelik koleksiyonu sayfasından öncedir. Bir kullanıcı yerel bir hesaba kaydoliyorsa bu adım çağrılmıyor. Aşağıda, bu adımda etkinleştirdiğiniz API bağlayıcısı senaryolarına örnekler 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şlemindeki bu adımda 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ştirebilirsiniz 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 kimliğinde depolamak için dış sistemleri sorgulayın.

Belirteci göndermeden önce (önizleme)

Not

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ştirebilirsiniz senaryo örnekleri verilmiştir:

• Eski kimlik sistemleri, İk sistemleri, dış kullanıcı depoları ve daha fazlası dahil olmak üzere dizinden farklı kaynaklardan kullanıcı hakkındaki özniteliklerle belirteci zenginleştirme.
• Belirteci kendi izin sisteminizde depoladığınız ve yönettiğiniz grup veya rol öznitelikleriyle zenginleştirme.
• Dizindeki taleplerin değerlerine talep dönüştürmeleri veya işlemeleri uygulama.

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

Azure AD B2C 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 değilse bir hata sunabilirsiniz. Api bağlayıcılarını giden web kancalarını desteklemenin bir yolu olarak da düşünebilirsiniz, çünkü çağrı bir olay gerçekleştiğinde ( örneğin bir kaydolma) yapılır.
• talepleri işleme. Bir kullanıcı adını küçük harfle veya tümüyle büyük harfle girerse, REST API'niz adı yalnızca ilk harfi büyük harfle biçimlendirebilir ve B2C Azure AD 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 dönüş 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şlemini çalıştırabilir, izinleri yönetebilir, veritabanlarını denetleyebilir ve diğer iş akışlarını gerçekleştirebilirsiniz.

Not

RESTful hizmetinden Azure AD B2C'ye yavaş yanıt alınıyorsa veya yanıt yoksa, zaman aşımı 30 saniyedir ve yeniden deneme sayısı iki kezdir (toplamda 3 deneme olduğu anlamına gelir). Şu anda zaman aşımı ve yeniden deneme sayısı ayarlarını yapılandıramazsınız.

RESTful hizmetini çağırma

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

• Doğrulama teknik profili. RESTful hizmetine yapılan çağrı, belirtilen kendi kendini onaylanan teknikprofilin 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 iletilerini oluşturun.
  • 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'yi ç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 sonra B2C dizinde yeni bir hesap oluşturur.
• Azure AD B2C bir erişim belirteci 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:

• Gövde, JSON biçiminde HTTP POST istek gövdesinde gönderilir.
• Form, HTTP POST istek gövdesinde ve '&' ayrılmış anahtar değeri biçiminde gönderilir.
• Üst bilgi, HTTP GET isteği üst bilgisinde gönderilir.
• 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

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

RESTful talep sağlayıcısı tarafından ayrıştırılan çıkış talepleri her zaman aşağıdaki gibi düz bir JSON Gövdesi yanıtını ayrıştırmayı bekler:

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

Çıktı 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

Bir sütundaki değer bilinmediğinde veya eksik olduğunda veritabanında null değer kullanılır. Değer içeren JSON anahtarları eklemeyin null . Aşağıdaki örnekte, e-posta değeri döndürür null :

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

Öğe null olduğunda, aşağıdakilerden birini 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ş dize döndür."" Bir integer veri türü için sıfır değeri 0döndürür. Bir dateTime veri türü için en düşük değeri 1970-00-00T00:00:00.0000000Zdöndürür.

Aşağıdaki örnekte null değerin nasıl işlenme şekli 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"
        }
      ]
    }
  }
],

Çıktı 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 bkz. RESTful teknik profili.

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

Rest API teknik profiline doğrudan bir kullanıcı yolculuğundan 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 talepleri JSON biçiminde 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ıları bir Azure veri merkezi IP adresinden gelir.

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

REST API hizmetinizi ve temel bileşenlerini (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 bkz. Azure AD B2C TLS ve şifre paketi gereksinimleri.

Sonraki adımlar

• Kaydolma deneyimlerini değiştirmek için API bağlayıcısı eklemeyi öğrenin
• Belirteçleri dış taleplerle 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:

• İzlenecek yol: Kaydolma kullanıcı akışına API bağlayıcısı ekleme
• İzlenecek yol: Azure Active Directory B2C'de özel ilkelere REST API talep değişimi ekleme
• REST API hizmetlerinizin güvenliğini sağlama
• Başvuru: RESTful teknik profili

• Dış süreçlerle etkileşim kurarken dayanıklılık oluşturmayı öğrenin
• Geliştiriciye yönelik en iyi yöntemlerle Dayanıklılık oluşturmayı öğrenin.