Kullanıcı akışına API bağlayıcısı ekleme

API bağlayıcısı kullanmak için, önce API bağlayıcısını oluşturur ve ardından bir kullanıcı akışında etkinleştirirsiniz.

Önemli

• 12 Temmuz 2021'den itibaren, Microsoft Entra B2B müşterileri özel veya iş kolu uygulamaları için self servis kaydolma ile kullanılmak üzere yeni Google tümleştirmeleri ayarlarsa, kimlik doğrulamaları sistem web görünümlerine taşınana kadar Google kimlikleriyle kimlik doğrulaması çalışmaz. Daha fazla bilgi edinin.
• Google, 30 Eylül 2021'den itibaren tümleşik web görünümü oturum açma desteğini kullanımdan kaldırıyor. Uygulamalarınız ekli web görünümüyle kullanıcıların kimliğini doğrularsa ve dış kullanıcı davetleri veya self servis kaydolma için Azure AD B2C veya Microsoft Entra B2B ile Google federasyonu kullanıyorsanız, Google Gmail kullanıcıları kimlik doğrulaması yapamaz. Daha fazla bilgi edinin.

API bağlayıcısı oluşturma

İpucu

Bu makaledeki adımlar, başladığınız portala göre biraz değişiklik gösterebilir.

1. Microsoft Entra yönetim merkezinde en az Kullanıcı Yönetici istrator olarak oturum açın.

2. Kimlik>Dış Kimliklerine>Genel Bakış'a göz atın.

3. Tüm API bağlayıcıları'nı ve ardından Yeni API bağlayıcısı'nı seçin.

   

4. Arama için bir görünen ad sağlayın. Örneğin Onay durumunu denetleyin.

5. API çağrısı için Uç Nokta URL'sini sağlayın.

6. Kimlik doğrulama türünü seçin ve API'nizi çağırmak için kimlik doğrulama bilgilerini yapılandırın. API Bağlan güvenliğini sağlamayı öğrenin.

   

7. Kaydet'i seçin.

API'nize gönderilen istek

API bağlayıcısı, kullanıcı özniteliklerini ('claims') bir JSON gövdesinde anahtar-değer çiftleri olarak göndererek HTTP POST isteği olarak gerçekleştirilmiştir. Öznitelikler, Microsoft Graph kullanıcı özelliklerine benzer şekilde serileştirilir.

Örnek istek

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

İstekte yalnızca Kimlik>Dış Kimliklerine>Genel Bakış>Özel kullanıcı öznitelikleri deneyiminde listelenen kullanıcı özellikleri ve özel öznitelikler gönderilebilir.

Özel öznitelikler dizindeki extension_<extensions-app-id>_AttributeName biçiminde bulunur. API'niz talepleri aynı serileştirilmiş biçimde almayı beklemelidir. Özel öznitelikler hakkında daha fazla bilgi için bkz . Self servis kayıt akışları için özel öznitelikleri tanımlama.

Ayrıca talepler genellikle tüm isteklerde gönderilir:

• Kullanıcı Arabirimi Yerel Ayarları ('ui_locales') - Son kullanıcının cihazında yapılandırıldığı gibi yerel ayarları. Bu, API'niz tarafından uluslararası yanıtları döndürmek için kullanılabilir.

• E-posta Adresi ('e-posta') veya kimlikler ('kimlikler') - Bu talepler API'niz tarafından uygulamada kimlik doğrulayan son kullanıcıyı tanımlamak için kullanılabilir.

Önemli

Bir talebin API uç noktası çağrıldığında bir değeri yoksa, talep API'ye gönderilmez. API'niz bir talebin istekte olmadığı durumu açıkça denetleyecek ve işleyecek şekilde tasarlanmalıdır.

Kullanıcı akışında API bağlayıcısını etkinleştirme

Self servis kayıt kullanıcı akışına API bağlayıcısı eklemek için bu adımları izleyin.

1. Microsoft Entra yönetim merkezinde en az Kullanıcı Yönetici istrator olarak oturum açın.

2. Kimlik>Dış Kimliklerine>Genel Bakış'a göz atın.

3. Kullanıcı akışları'nı ve ardından API bağlayıcısını eklemek istediğiniz kullanıcı akışını seçin.

4. API bağlayıcıları'nı seçin ve ardından kullanıcı akışında aşağıdaki adımlarda çağırmak istediğiniz API uç noktalarını seçin:

   • Kaydolma sırasında bir kimlik sağlayıcısıyla federasyon kurduktan sonra
   • Kullanıcıyı oluşturmadan önce

   

5. Kaydet'i seçin.

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 veya Microsoft Entra Id 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ıya kullanıcı özniteliklerini toplamak için sunulan form olan öznitelik koleksiyonu sayfasından önce geçer.

Bu adımda API'ye gönderilen örnek istek

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "lastName":"Smith",
 "ui_locales":"en-US"
}

API'ye gönderilen tam talepler, kimlik sağlayıcısı tarafından hangi bilgilerin sağlandığına bağlıdır. 'e-posta' her zaman gönderilir.

Bu adımda web API'sinden beklenen yanıt türleri

Web API'si bir kullanıcı akışı sırasında Microsoft Entra Id'den bir HTTP isteği aldığında şu yanıtları döndürebilir:

• Devam yanıtı
• Engelleme yanıtı

Devam yanıtı

Devamlılık yanıtı, kullanıcı akışının sonraki adıma devam etmesi gerektiğini belirtir: öznitelik koleksiyonu sayfası.

Bir devamlılık yanıtında API talepleri döndürebilir. API tarafından bir talep döndürülürse, talep aşağıdakileri yapar:

• Öznitelik koleksiyonu sayfasındaki giriş alanını önceden doldurur.

Devam yanıtı örneğine bakın.

Engelleme Yanıtı

Engelleme yanıtı kullanıcı akışından çıkar. Kullanıcıya bir blok sayfası görüntüleyerek kullanıcı akışının devamını durdurmak için API tarafından kasıtlı olarak yayımlanabilir. Blok sayfası, API tarafından sağlanan öğesini userMessage görüntüler.

Engelleme yanıtı örneğine bakın.

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, Microsoft Entra Id'de bir kullanıcı hesabı oluşturulmadan önce her zaman çağrılır.

Bu adımda API'ye gönderilen örnek istek

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

API'ye gönderilen tam talepler, kullanıcıdan hangi bilgilerin toplandığına veya kimlik sağlayıcısı tarafından sağlandığına bağlıdır.

Bu adımda web API'sinden beklenen yanıt türleri

Web API'si bir kullanıcı akışı sırasında Microsoft Entra Id'den bir HTTP isteği aldığında şu yanıtları döndürebilir:

• Devam yanıtı
• Engelleme yanıtı
• Doğrulama yanıtı

Devam yanıtı

Devamlılık yanıtı, kullanıcı akışının bir sonraki adıma devam etmesi gerektiğini belirtir: kullanıcıyı dizinde oluşturun.

Bir devamlılık yanıtında API talepleri döndürebilir. API tarafından bir talep döndürülürse, talep aşağıdakileri yapar:

• Öznitelik koleksiyonu sayfasından talep için zaten atanmış olan tüm değerleri geçersiz kılar.

Devam yanıtı örneğine bakın.

Engelleme Yanıtı

Engelleme yanıtı kullanıcı akışından çıkar. Kullanıcıya bir blok sayfası görüntüleyerek kullanıcı akışının devamını durdurmak için API tarafından kasıtlı olarak yayımlanabilir. Blok sayfası, API tarafından sağlanan öğesini userMessage görüntüler.

Engelleme yanıtı örneğine bakın.

Doğrulama hatası yanıtı

API doğrulama hatası yanıtıyla yanıtladığında, kullanıcı akışı öznitelik koleksiyonu sayfasında kalır ve kullanıcıya bir userMessage görüntülenir. Daha sonra kullanıcı formu düzenleyebilir ve yeniden gönderebilir. Bu tür bir yanıt, giriş doğrulaması için kullanılabilir.

Doğrulama hatası yanıtı örneğine bakın.

Örnek yanıtlar

Devam yanıtı örneği

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "Continue",
    "postalCode": "12349", // return claim
    "extension_<extensions-app-id>_CustomAttribute": "value" // return claim
}

Parametre	Türü	Zorunlu	Açıklama
sürüm	Dize	Yes	API'nizin sürümü.
eylem	String	Yes	Değer olmalıdır Continue.
<builtInUserAttribute>	<öznitelik türü>	Hayır	Değerler, API bağlayıcısı yapılandırmasında ve kullanıcı akışı için Kullanıcı özniteliklerinde almak üzere Talep olarak seçildiyse dizinde depolanabilir. Değerler, Uygulama talebi olarak seçilirse belirteçte döndürülebilir.
<extension_{extensions-app-id}_CustomAttribute>	<öznitelik türü>	Hayır	Talebin içermesi _<extensions-app-id>_gerekmez, isteğe bağlıdır. Döndürülen değerler bir kullanıcıdan toplanan değerlerin üzerine yazabilir.

Engelleme yanıtı örneği

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "There was an error with your request. Please try again or contact support.",
}

Parametre	Türü	Zorunlu	Açıklama
sürüm	Dize	Yes	API'nizin sürümü.
eylem	String	Yes	Değer şu olmalıdır: ShowBlockPage
userMessage	String	Yes	Kullanıcıya görüntülenecek ileti.

Engelleme yanıtıyla son kullanıcı deneyimi

Doğrulama hatası yanıtı örneği

HTTP/1.1 400 Bad Request
Content-type: application/json

{
    "version": "1.0.0",
    "status": 400,
    "action": "ValidationError",
    "userMessage": "Please enter a valid Postal Code.",
}

Parametre	Türü	Zorunlu	Açıklama
sürüm	Dize	Yes	API'nizin sürümü.
eylem	String	Yes	Değer olmalıdır ValidationError.
durum	Tamsayı / Dize	Yes	Bir ValidationError yanıtı için veya "400" değeri 400olmalıdır.
userMessage	String	Yes	Kullanıcıya görüntülenecek ileti.

Not

HTTP durum kodu, yanıtın gövdesindeki "status" değerine ek olarak "400" olmalıdır.

Doğrulama hatası yanıtıyla son kullanıcı deneyimi

En iyi yöntemler ve sorun giderme

Sunucusuz bulut işlevlerini kullanma

Azure İşlevleri'daki HTTP tetikleyicileri gibi sunucusuz işlevler, API bağlayıcısı ile kullanmak üzere API uç noktaları oluşturmanın bir yolunu sağlar. Sunucusuz bulut işlevini kullanarak doğrulama mantığı gerçekleştirebilir ve kaydolma işlemlerini belirli e-posta etki alanlarıyla sınırlandırabilirsiniz. Sunucusuz bulut işlevi ayrıca karmaşık senaryolar için diğer web API'lerini, veri depolarını ve diğer bulut hizmetlerini çağırabilir ve çağırabilir.

En iyi yöntemler

Şunlardan emin olun:

• API'niz yukarıda açıklandığı gibi API isteği ve yanıt sözleşmelerini takip ediyor.
• API bağlayıcısının Uç Nokta URL'si doğru API uç noktasını gösterir.
• API'niz, bağımlı olduğu alınan taleplerin null değerlerini açıkça denetler.
• API'niz, API Bağlan veya güvenli bir şekilde özetlenen bir kimlik doğrulama yöntemi uygular.
• Akıcı bir kullanıcı deneyimi sağlamak için API'niz mümkün olan en kısa sürede yanıt verir.
  • Microsoft Entra Id yanıt almak için en fazla 20 saniye bekler. Hiçbiri alınmazsa , API'nizi çağırmak için bir kez daha dener (yeniden deneyin ).
  • Sunucusuz bir işlev veya ölçeklenebilir bir web hizmeti kullanıyorsanız, API'yi üretimde "uyanık" veya "sıcak" tutan bir barındırma planı kullanın. Azure İşlevleri için en azından Premium planı kullanmanızı öneririz.
• API'nizin yüksek kullanılabilirliğini sağlayın.
• Aşağı akış API'lerinin, veritabanlarının veya API'nizin diğer bağımlılıklarının performansını izleyin ve iyileştirin.
• Uç noktalarınız Microsoft Entra TLS ve şifreleme güvenlik gereksinimlerine uygun olmalıdır. Daha fazla bilgi için bkz . TLS ve şifre paketi gereksinimleri.

Günlüğe kaydetmeyi kullanma

Genel olarak, api'nizi beklenmeyen hata kodları, özel durumlar ve düşük performans açısından izlemek için Application Insights gibi web API hizmetinizin etkinleştirdiği günlük araçlarını kullanmak yararlı olur.

• HTTP 200 veya 400 olmayan HTTP durum kodlarını izleyin.
• 401 veya 403 HTTP durum kodu genellikle kimlik doğrulamanızla ilgili bir sorun olduğunu gösterir. API'nizin kimlik doğrulama katmanını ve API bağlayıcısında ilgili yapılandırmayı bir kez daha denetleyin.
• Gerekirse geliştirme aşamasında daha agresif günlük düzeyleri (örneğin "izleme" veya "hata ayıklama") kullanın.
• API'nizi uzun yanıt süreleri için izleyin.

Sonraki adımlar

• Self servis kaydolmaya özel onay iş akışı eklemeyi öğrenin
• Hızlı başlangıç örneklerimizi kullanmaya başlayın.