Yerel kimlik doğrulama API'si başvurusu

Şunlar için geçerlidir: İş gücü kiracılarıDış kiracılar (daha fazla bilgi edinin)

Microsoft Entra'nın yerel kimlik doğrulaması , uygulamanızın kullanıcı arabirimini tarayıcılara kimlik doğrulaması vermek yerine istemci uygulamasında barındırmanıza olanak tanır ve bu da yerel olarak tümleşik bir kimlik doğrulama deneyimi sağlar. Geliştirici olarak, oturum açma arabiriminin genel görünümü üzerinde tam denetime sahipsiniz.

Bu API başvuru makalesi, yalnızca akışı yürütmek için el ile ham HTTP istekleri yaptığınızda gerekli ayrıntıları açıklar. Ancak bu yaklaşımı önermiyoruz. Bu nedenle mümkün olduğunda Microsoft tarafından oluşturulmuş ve desteklenen bir kimlik doğrulama SDK'sı kullanın. SDK'yı kullanma hakkında daha fazla bilgi için bkz . Öğretici: Android mobil uygulamanızı yerel kimlik doğrulaması için hazırlama ve Öğretici: iOS mobil uygulamanızı yerel kimlik doğrulaması için hazırlama.

API uç noktalarına yapılan bir çağrı başarılı olduğunda, hem kullanıcı kimliği için bir kimlik belirteci hem de korumalı API'leri çağırmak için bir erişim belirteci alırsınız. API'den gelen tüm yanıtlar JSON biçimindedir.

Microsoft Entra'nın yerel kimlik doğrulama API'si iki kimlik doğrulama yöntemi için kaydolmayı ve oturum açmayı destekler:

• Bir e-posta ve parola ile kaydolmayı ve oturum açmayı ve self servis parola sıfırlamayı (SSPR) destekleyen parolalı e-posta.

• Tek seferlik geçiş kodu e-posta ile kaydolmayı ve tek seferlik geçiş koduyla oturum açmayı destekleyen bir kerelik geçiş kodunu e-postayla gönderin.

Not

Şu anda yerel kimlik doğrulama API'sinin uç noktaları Çıkış Noktaları Arası Kaynak Paylaşımı'nı (CORS) desteklememektedir.

Önkoşullar

1. Müşteriler kiracısı için Microsoft Entra Dış Kimlik. Henüz bir aboneliğiniz yoksa ücretsiz deneme sürümüne kaydolun.

2. Henüz yapmadıysanız, Microsoft Entra yönetim merkezine bir uygulama kaydedin. Temsilci izinleri verdiğinden ve genel istemci ile yerel kimlik doğrulama akışlarını etkinleştirdiğinizden emin olun.

3. Henüz yapmadıysanız Microsoft Entra yönetim merkezinde kullanıcı akışı oluşturun. Kullanıcı akışını oluştururken, microsoft Entra'nın uygulamanızın göndermesini beklediği öznitelikler bu öznitelikler olduğundan, yapılandırdığınız kullanıcı özniteliklerini not alın. Kimlik sağlayıcıları'nın altında E-posta ile bir kerelik geçiş kodu seçeneğini belirleyin.

4. Uygulama kaydınızı kullanıcı akışıyla ilişkilendirin.

5. Oturum açma akışı için, oturum açma API'lerini test için kullandığınız bir müşteri kullanıcısını kaydedin. Alternatif olarak, kayıt akışını çalıştırdıktan sonra bu test kullanıcısını alabilirsiniz.

6. SSPR akışı için, müşteri kiracısında müşteri kullanıcıları için self servis parola sıfırlamayı etkinleştirin. SSPR, parola kimlik doğrulama yöntemiyle e-posta kullanan müşteri kullanıcıları tarafından kullanılabilir.

Devamlılık belirteci

Akışlardan herhangi birinde, oturum açmada, kaydolmada veya SSPR'de bir uç noktayı her çağırdığınızda, uç nokta yanıtına bir devamlılık belirteci ekler. Devamlılık belirteci, Microsoft Entra Id'nin aynı akış içindeki farklı uç noktalara yapılan çağrılar arasındaki durumu korumak için kullandığı benzersiz bir tanımlayıcıdır. Bu belirteci sonraki isteklere aynı akışa eklemeniz gerekir.

Her devamlılık belirteci belirli bir süre için geçerlidir ve yalnızca aynı akıştaki sonraki istekler için kullanılabilir.

Kaydolma API'si başvurusu

Her iki kimlik doğrulama yönteminde de kullanıcı kayıt akışını tamamlamak için uygulamanız , , /signup/v1.0/challenge/signup/v1.0/continueve /tokenolmak üzere dört uç noktayla etkileşim kurar/signup/v1.0/start.

Kaydolma API'leri uç noktaları

Uç nokta	Açıklama
/signup/v1.0/start	Bu uç nokta kayıt akışını başlatır. Geçerli uygulama kimliğini, yeni kullanıcı adını ve sınama türünü geçirip yeni bir devamlılık belirteci alırsınız. Uygulamanın seçtiği kimlik doğrulama yöntemleri Microsoft Entra tarafından desteklenmiyorsa, uç nokta uygulamaya web kimlik doğrulaması akışı kullanabileceğini belirten bir yanıt döndürebilir.
/signup/v1.0/challenge	Uygulamanız bu uç noktayı Microsoft Entra tarafından desteklenen sınama türlerinin listesiyle çağırır. Microsoft Entra daha sonra kullanıcının kimlik doğrulaması için desteklenen kimlik doğrulama yöntemlerinden birini seçer.
/signup/v1.0/continue	Bu uç nokta, parola ilkesi gereksinimleri veya yanlış öznitelik biçimleri gibi eksik gereksinimler nedeniyle kullanıcı hesabı oluşturmak veya akışı kesintiye uğratmak için akışın devam etmesi için yardımcı olur. Bu uç nokta bir devamlılık belirteci oluşturur ve ardından bunu uygulamaya döndürür. Uygulama Microsoft Entra tarafından seçilen bir kimlik doğrulama yöntemi değilse uç nokta, uygulamaya web tabanlı bir kimlik doğrulama akışı kullanılacağını belirten bir yanıt döndürebilir.
/token	Uygulama, son olarak güvenlik belirteçleri istemek için bu uç noktayı çağırır. Uygulamanın uç noktaya yapılan son başarılı çağrıdan aldığı devamlılık belirtecini içermesi /signup/v1.0/continue gerekir.

Kaydolma sınama türleri

API, istemci uygulamasının Microsoft Entra'ya çağrı yaptığında desteklediği kimlik doğrulama yöntemlerini tanıtmasını sağlar. Bunu yapmak için uygulama, uygulamanın isteğindeki parametresini kullanır challenge_type . Bu parametre, farklı kimlik doğrulama yöntemlerini temsil eden önceden tanımlanmış değerleri tutar.

Yerel kimlik doğrulama sınaması türlerindeki sınama türleri hakkında daha fazla bilgi edinin. Bu makalede, kimlik doğrulama yöntemi için gereken sınama türü değerleri açıklanmaktadır.

Kayıt akışı protokolü ayrıntıları

Sıralı diyagram, kaydolma işleminin akışını gösterir.

Bu diyagram, uygulamanın kullanıcı adını (e-posta), parolayı (parola kimlik doğrulama yöntemleriyle e-posta için) ve kullanıcıdan farklı zamanlarda (ve muhtemelen ayrı ekranlarda) öznitelikleri topladığını gösterir. Bununla birlikte, uygulamanızı kullanıcı adı (e-posta), parola ve gerekli tüm ve isteğe bağlı öznitelik değerlerini aynı ekranda toplayacak şekilde tasarlayabilir ve ardından bunların tümünü uç nokta üzerinden /signup/v1.0/start gönderebilirsiniz. Bu durumda, uygulamanın isteğe bağlı adımlar için çağrı yapması ve yanıtları işlemesi gerekmez.

1. Adım: Kayıt akışını başlatma isteği

Kayıt akışı, uygulamanın kayıt akışını başlatmak için /signup/v1.0/start uç noktaya post isteği göndermesiyle başlar.

Burada istek örnekleri verilmiştir (örnek isteği okunabilirlik için birden çok satırda sunuyoruz):

Örnek 1:

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/start
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&username=contoso-consumer@contoso.com 

Örnek 2 (istekte kullanıcı özniteliklerini ve parolayı ekleyin):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/start
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&password={secure_password}
&attributes={"displayName": "{given_name}", "extension_2588abcdwhtfeehjjeeqwertc_age": "{user_age}", "postalCode": "{user_postal_code}"}
&username=contoso-consumer@contoso.com 

Parametre	Zorunlu	Veri Akışı Açıklaması
tenant_subdomain	Yes	Oluşturduğunuz dış kiracının alt etki alanı. URL'de değerini Dizin (kiracı) alt etki alanıyla değiştirin {tenant_subdomain} . Örneğin, kiracınızın birincil etki alanı contoso.onmicrosoft.com ise contoso kullanın. Kiracı alt etki alanınız yoksa kiracınızın ayrıntılarını okumayı öğrenin.
client_id	Yes	Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği.
username	Yes	Kaydolmak istediği müşteri kullanıcısının e-posta adresi, örneğin contoso-consumer@contoso.com.
challenge_type	Yes	Uygulamanın desteklediği yetkilendirme sınama türü dizelerinin boşlukla ayrılmış listesi.oob password redirect Liste her zaman sınama türünü içermelidir redirect . Değer, parola kimlik doğrulama yöntemiyle e-posta için oob redirect veya oob password redirect için beklenir.
password	Hayır	Uygulamanın müşteri kullanıcısından topladığı parola değeri. Bir kullanıcının parolasını uç noktadaki /signup/v1.0/start veya sonraki /signup/v1.0/continue bir sürüm aracılığıyla gönderebilirsiniz. değerini, uygulamanın müşteri kullanıcısından topladığı parola değeriyle değiştirin {secure_password} . Uygulamanın kullanıcı arabiriminde parola onaylama alanını sağlayarak kullanıcının kullanmak istediği parolanın farkında olduğunu onaylamak sizin sorumluluğunuzdadır. Ayrıca, kullanıcının kuruluşunuzun ilkesine göre neyin güçlü bir parola oluşturduğunu anladığınızdan emin olmanız gerekir. Microsoft Entra'nın parola ilkeleri hakkında daha fazla bilgi edinin. Bu parametre yalnızca parola kimlik doğrulama yöntemine sahip e-postalar için geçerlidir.
attributes	Hayır	Kullanıcı, uygulamanın müşteri kullanıcısından topladığı değerleri öznitelikler. Değer bir dizedir, ancak anahtar değerleri kullanıcı özniteliklerinin programlanabilir adı olan bir JSON nesnesi olarak biçimlendirilir. Bu öznitelikler yerleşik veya özel olabilir ve gerekli veya isteğe bağlı olabilir. Nesnenin anahtar adları, yöneticinin Microsoft Entra yönetim merkezinde yapılandırmış olduğu özniteliklere bağlıdır. Kullanıcı özniteliklerinin bazılarını veya tümünü uç nokta üzerinden veya uç noktadaki /signup/v1.0/continue sonraki bir sürüm aracılığıyla /signup/v1.0/start gönderebilirsiniz. Gerekli tüm öznitelikleri uç nokta üzerinden /signup/v1.0/start gönderirseniz, uç noktada herhangi bir öznitelik /signup/v1.0/continue göndermeniz gerekmez. Ancak, uç nokta aracılığıyla /signup/v1.0/start bazı gerekli öznitelikleri gönderirseniz, kalan gerekli öznitelikleri uç noktada daha sonra /signup/v1.0/continue gönderebilirsiniz. ve {user_age}{postal_code} değerlerini, uygulamanın müşteri kullanıcısından topladığı ad, yaş ve posta kodu değerleriyle değiştirin{given_name}. Microsoft Entra, gönderdiğiniz ve var olmayan öznitelikleri yoksayar.

Başarılı yanıt

Başarılı bir yanıt örneği aşağıda verilmişti:

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

{
    "continuation_token": "AQABAAEAAA…",
} 

Parametre	Açıklama
continuation_token	Microsoft Entra'nın döndürdüğü devamlılık belirteci .

Bir uygulama Microsoft Entra tarafından gerekli bir kimlik doğrulama yöntemini destekleyemezse web tabanlı kimlik doğrulama akışına geri dönüş gerekir. Bu senaryoda Microsoft Entra, yanıtında bir yeniden yönlendirme sınama türü döndürerek uygulamayı bilgilendirmektedir:

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

{     
   "challenge_type": "redirect" 
} 

Parametre	Açıklama
challenge_type	Microsoft Entra, sınama türüne sahip bir yanıt döndürür. Bu sınama türünün değeri, uygulamanın web tabanlı kimlik doğrulama akışını kullanmasını sağlayan yeniden yönlendirmedir.

Bu yanıt başarılı olarak kabul edilir, ancak uygulamanın web tabanlı kimlik doğrulama akışına geçmesi gerekir. Bu durumda, Microsoft tarafından oluşturulmuş ve desteklenen bir kimlik doğrulama kitaplığı kullanmanızı öneririz.

Hata yanıtı

Örnek:

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

{
    "error": "user_already_exists", 
    "error_description": "AADSTS1003037: It looks like you may already have an account.... .\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...", 
    "error_codes": [ 
        1003037 
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
} 

Parametre	Açıklama
error	Hata türlerini sınıflandırmak ve hatalara tepki vermek için kullanılabilecek bir hata kodu dizesi.
error_description	Kimlik doğrulama hatasının nedenini belirlemenize yardımcı olabilecek belirli bir hata iletisi.
error_codes	Hataları tanılamanıza yardımcı olabilecek Microsoft Entra'ya özgü hata kodlarının listesi.
timestamp	Hatanın oluştuğu zaman.
trace_id	İstek için hataları tanılamanıza yardımcı olabilecek benzersiz bir tanımlayıcı.
correlation_id	bileşenler arasında tanılamada yardımcı olabilecek istek için benzersiz bir tanımlayıcı.
invalid_attributes	Doğrulamada başarısız olan özniteliklerin listesi (nesne dizisi). Uygulama kullanıcı öznitelikleri gönderirse ve parametrenin suberror değeri attribute_validation_failed bu yanıt mümkündür.
suberror	Hata türlerini daha fazla sınıflandırmak için kullanılabilecek bir hata kodu dizesi.

Karşılaşabileceğiniz olası hatalar şunlardır (parametrenin error olası değerleri):

Hata değeri	Açıklama
invalid_request	challenge_type parametre değeri desteklenmeyen bir kimlik doğrulama yöntemi içerdiğinde veya istek parametre içermediğinde client_id istemci kimliği değerinin boş veya geçersiz olması gibi istek parametresi doğrulaması başarısız oldu. Hatanın error_description tam nedenini öğrenmek için parametresini kullanın.
invalid_client	Uygulamanın istekte içerdiği istemci kimliği, genel istemci olmadığı veya yerel kimlik doğrulaması için etkinleştirilmediği gibi yerel kimlik doğrulama yapılandırması olmayan bir uygulamaya yöneliktir. Hatanın suberror tam nedenini öğrenmek için parametresini kullanın.
unauthorized_client	İstekte kullanılan istemci kimliği geçerli bir istemci kimliği biçimine sahip, ancak dış kiracıda yok veya yanlış.
unsupported_challenge_type	challenge_type Parametre değeri sınama türünü içermezredirect.
user_already_exists	Kullanıcı zaten var.
invalid_grant	Uygulamanın gönderdiği parola, parola çok kısa olduğu gibi tüm karmaşıklık gereksinimlerini karşılamaz. Hatanın suberror tam nedenini öğrenmek için parametresini kullanın. Bu parametre yalnızca parola kimlik doğrulama yöntemine sahip e-postalar için geçerlidir.

Hata parametresinin değeri invalid_grant ise, Microsoft Entra yanıtına bir suberror parametre ekler. bir invalid_grant hatası için parametrenin suberror olası değerleri şunlardır:

Alt değer	Açıklama
password_too_weak	Karmaşıklık gereksinimlerini karşılamadığından parola çok zayıf. Microsoft Entra'nın parola ilkeleri hakkında daha fazla bilgi edinin. Uygulama bir kullanıcı parolası gönderirse bu yanıt mümkündür.
password_too_short	Yeni parola 8 karakterden azdır. Microsoft Entra'nın parola ilkeleri hakkında daha fazla bilgi edinin. Uygulama bir kullanıcı parolası gönderirse bu yanıt mümkündür.
password_too_long	Yeni parola 256 karakterden uzun. Microsoft Entra'nın parola ilkeleri hakkında daha fazla bilgi edinin. Uygulama bir kullanıcı parolası gönderirse bu yanıt mümkündür.
password_recently_used	Yeni parola, yakın zamanda kullanılan parolayla aynı olmamalıdır. Microsoft Entra'nın parola ilkeleri hakkında daha fazla bilgi edinin. Uygulama bir kullanıcı parolası gönderirse bu yanıt mümkündür.
password_banned	Yeni parola, yasaklanmış bir sözcük, tümcecik veya desen içerir. Microsoft Entra'nın parola ilkeleri hakkında daha fazla bilgi edinin. Uygulama bir kullanıcı parolası gönderirse bu yanıt mümkündür.
password_is_invalid	Parola geçersiz, örneğin izin verilmeyen karakterler kullandığından. Microsoft Entra'nın parola ilkeleri hakkında daha fazla bilgi edinin. Uygulama bir kullanıcı parolası gönderirse bu yanıt mümkündür.

Hata parametresinin değeri invalid_client ise, Microsoft Entra yanıtına bir suberror parametre ekler. invalid_client hatası için parametrenin suberror olası değerleri şunlardır:

Alt değer	Açıklama
nativeauthapi_disabled	Yerel kimlik doğrulaması için etkinleştirilmemiş bir uygulamanın istemci kimliği.

Not

Tüm gerekli öznitelikleri uç nokta üzerinden /signup/v1.0/start gönderirseniz ancak isteğe bağlı özniteliklerin tümünü göndermezseniz, daha sonra uç nokta aracılığıyla /signup/v1.0/continue ek isteğe bağlı öznitelikler gönderemezsiniz. Kaydolma akışının tamamlanması zorunlu olmadığından, Microsoft Entra isteğe bağlı öznitelikleri açıkça istemez. ve uç noktalarına gönderebileceğiniz kullanıcı özniteliklerini öğrenmek için Uç noktalara kullanıcı özniteliklerini gönderme bölümündeki tabloya /signup/v1.0/start bakın./signup/v1.0/continue

2. Adım: Bir kimlik doğrulama yöntemi seçin

Uygulama, Microsoft Entra'nın kullanıcının kimlik doğrulaması için desteklenen sınama türlerinden birini seçmesini istemektedir. Bunu yapmak için uygulama uç noktaya bir çağrı /signup/v1.0/challenge yapar. Uygulamanın istekte uç noktadan aldığı devamlılık belirtecini /signup/v1.0/start içermesi gerekir.

burada isteğin bir örneği verilmiştir (örnek isteği okunabilirlik için birden çok satırda sunuyoruz).

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/challenge
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&continuation_token=AQABAAEAAA…

Parametre	Zorunlu	Veri Akışı Açıklaması
tenant_subdomain	Yes	Oluşturduğunuz dış kiracının alt etki alanı. URL'de değerini Dizin (kiracı) alt etki alanıyla değiştirin {tenant_subdomain} . Örneğin, kiracınızın birincil etki alanı contoso.onmicrosoft.com ise contoso kullanın. Kiracı alt etki alanınız yoksa kiracınızın ayrıntılarını okumayı öğrenin.
client_id	Yes	Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği.
challenge_type	Hayır	Uygulamanın desteklediği yetkilendirme sınama türü dizelerinin boşlukla ayrılmış listesi.oob password redirect Liste her zaman sınama türünü içermelidir redirect . Değerin tek seferlik geçiş kodu e-postası oob redirect ve oob password redirect parola kimlik doğrulama yöntemiyle e-posta için olması beklenir.
continuation_token	Yes	Microsoft Entra'nın önceki istekte döndürdüğü devamlılık belirteci .

Başarılı yanıt

Microsoft Entra, kullanıcının e-postasına tek seferlik bir geçiş kodu gönderir, ardından oob değeri ve tek seferlik geçiş kodu hakkında ek bilgiler içeren sınama türüyle yanıt verir:

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

{
    "interval": 300,
    "continuation_token": "AQABAAEAAAYn...",
    "challenge_type": "oob",
    "binding_method": "prompt",
    "challenge_channel": "email",
    "challenge_target_label": "c***r@co**o**o.com",
    "code_length": 8
} 

Parametre	Açıklama
interval	Uygulamanın OTP'yi yeniden göndermeye çalışmadan önce beklemesi gereken saniye cinsinden süre.
continuation_token	Microsoft Entra'nın döndürdüğü devamlılık belirteci .
challenge_type	Kullanıcının kimlik doğrulaması için seçilen sınama türü.
binding_method	Tek geçerli değer istemdir. Bu parametre gelecekte kullanıcıya tek seferlik geçiş kodunu girmenin daha fazla yolunu sunmak için kullanılabilir. Oob ise challenge_type verilir
challenge_channel	Tek seferlik geçiş kodunun gönderildiği kanalın türü. Şu anda yalnızca e-posta kanalı desteklenmektedir.
challenge_target_label	Tek seferlik geçiş kodunun gönderildiği belirsiz bir e-posta.
code_length	Microsoft Entra'nın oluşturduğu tek seferlik geçiş kodunun uzunluğu.

Bir uygulama Microsoft Entra tarafından gerekli bir kimlik doğrulama yöntemini destekleyemezse web tabanlı kimlik doğrulama akışına geri dönüş gerekir. Bu senaryoda Microsoft Entra, yanıtında bir yeniden yönlendirme sınama türü döndürerek uygulamayı bilgilendirmektedir:

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

{
   "challenge_type": "redirect"
}

Parametre	Açıklama
challenge_type	Microsoft Entra, sınama türüne sahip bir yanıt döndürür. Bu sınama türünün değeri, uygulamanın web tabanlı kimlik doğrulama akışını kullanmasını sağlayan yeniden yönlendirmedir.

Bu yanıt başarılı olarak kabul edilir, ancak uygulamanın web tabanlı kimlik doğrulama akışına geçmesi gerekir. Bu durumda, Microsoft tarafından oluşturulmuş ve desteklenen bir kimlik doğrulama kitaplığı kullanmanızı öneririz.

Hata yanıtı

Örnek:

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

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
} 

Parametre	Açıklama
error	Hata türlerini sınıflandırmak ve hatalara tepki vermek için kullanılabilecek bir hata kodu dizesi.
error_description	Kimlik doğrulama hatasının nedenini belirlemenize yardımcı olabilecek belirli bir hata iletisi.
error_codes	Hataları tanılamanıza yardımcı olabilecek Microsoft Entra'ya özgü hata kodlarının listesi.
timestamp	Hatanın oluştuğu zaman.
trace_id	İstek için hataları tanılamanıza yardımcı olabilecek benzersiz bir tanımlayıcı.
correlation_id	bileşenler arasında tanılamada yardımcı olabilecek istek için benzersiz bir tanımlayıcı.

Karşılaşabileceğiniz olası hatalar şunlardır (parametrenin error olası değerleri):

Hata değeri	Açıklama
invalid_request	İstemci kimliği boş veya geçersiz olduğu için istek parametresi doğrulaması başarısız oldu.
expired_token	Devamlılık belirtecinin süresi doldu.
unsupported_challenge_type	challenge_type Parametre değeri sınama türünü içermezredirect.
invalid_grant	Devamlılık belirteci geçersiz.

3. Adım: Tek seferlik geçiş kodu gönderme

Uygulama, kullanıcının e-postasına gönderilen tek seferlik geçiş kodunu gönderir. Tek seferlik geçiş kodu gönderdiğimiz için bir oob parametre gereklidir ve parametrenin grant_type değeri oob olmalıdır.

aşağıda isteğin bir örneği verilmiştir (örnek isteği okunabilirlik için birden çok satırda sunuyoruz):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded

continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=oob 
&oob={otp_code}

Parametre	Zorunlu	Veri Akışı Açıklaması
tenant_subdomain	Yes	Oluşturduğunuz dış kiracının alt etki alanı. URL'de değerini Dizin (kiracı) alt etki alanıyla değiştirin {tenant_subdomain} . Örneğin, kiracınızın birincil etki alanı contoso.onmicrosoft.com ise contoso kullanın. Kiracı alt etki alanınız yoksa kiracınızın ayrıntılarını okumayı öğrenin.
continuation_token	Yes	Microsoft Entra'nın önceki istekte döndürdüğü devamlılık belirteci .
client_id	Yes	Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği.
grant_type	Yes	Bir kerelik geçiş kodu, parola veya kullanıcı öznitelikleri göndermek için uç noktaya yönelik bir istek /signup/v1.0/continue kullanılabilir. Bu durumda, grant_type değer bu üç kullanım örneğini ayırt etmek için kullanılır. grant_type için olası değerler oob, parola ve özniteliklerdir. Bu çağrıda tek seferlik geçiş kodu gönderdiğimiz için değerin oob olması beklenir.
oob	Yes	Müşteri kullanıcısının e-postasında aldığı tek seferlik geçiş kodu. değerini, müşteri kullanıcısının e-postasında aldığı tek seferlik geçiş kodu değerleriyle değiştirin {otp_code} . Tek seferlik geçiş kodunu yeniden göndermek için uygulamanın uç noktaya yeniden istekte /signup/v1.0/challenge bulunması gerekir.

Uygulama tek seferlik geçiş kodunu başarıyla gönderdikten sonra, kaydolma akışı tabloda gösterildiği gibi senaryolara bağlıdır:

Senaryo	Devam etme
Uygulama, kullanıcının parolasını (parola kimlik doğrulama yöntemiyle e-posta için) uç nokta üzerinden /signup/v1.0/start başarıyla gönderir ve Microsoft Entra yönetim merkezinde hiçbir öznitelik yapılandırılmaz veya gerekli tüm kullanıcı öznitelikleri uç nokta üzerinden /signup/v1.0/start gönderilir.	Microsoft Entra bir devamlılık belirteci oluşturur. Uygulama, 5. adımda gösterildiği gibi güvenlik belirteçleri istemek için devamlılık belirtecini kullanabilir.
Uygulama, kullanıcı parolasını (parola kimlik doğrulama yöntemiyle e-posta için) aracılığıyla /signup/v1.0/startbaşarıyla gönderir, ancak tüm gerekli kullanıcı özniteliklerini göndermez, Microsoft Entra, gerekli kullanıcı özniteliklerinde gösterildiği gibi uygulamanın göndermesi gereken öznitelikleri belirtir.	Uygulamanın uç nokta üzerinden gerekli kullanıcı özniteliklerini göndermesi /signup/v1.0/continue gerekir. Yanıt, gerekli Kullanıcı özniteliklerindeki yanıta benzer. Kullanıcı özniteliklerini gönderme bölümünde gösterilen kullanıcı özniteliklerini gönderin.
Uygulama, kullanıcının parolasını (parola kimlik doğrulama yöntemiyle e-posta için) uç nokta üzerinden /signup/v1.0/start göndermez.	Microsoft Entra'nın yanıtı, kimlik bilgilerinin gerekli olduğunu gösterir. Bkz . yanıt. Bu yanıt, parola kimlik doğrulama yöntemiyle e-posta için mümkündür.

Response

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

{
    "error": "credential_required",
    "error_description": "AADSTS55103: Credential required. Trace ID: d6966055-...-80500 Correlation ID: 3944-...-60d6 Timestamp: yy-mm-dd 02:37:33Z",
    "error_codes": [
        55103
    ],
    "timestamp": "yy-mm-dd 02:37:33Z",
    "trace_id": "d6966055-...-80500",
    "correlation_id": "3944-...-60d6",
    "continuation_token": "AQABEQEAAAA..."
} 

Parametre	Açıklama
error	Hata türlerini sınıflandırmak ve hatalara tepki vermek için kullanılabilecek bir hata kodu dizesi.
error_description	Kimlik doğrulama hatasının nedenini belirlemenize yardımcı olabilecek belirli bir hata iletisi.
error_codes	Hataları tanılamanıza yardımcı olabilecek Microsoft Entra'ya özgü hata kodlarının listesi.
timestamp	Hatanın oluştuğu zaman.
trace_id	İstek için hataları tanılamanıza yardımcı olabilecek benzersiz bir tanımlayıcı.
correlation_id	bileşenler arasında tanılamada yardımcı olabilecek istek için benzersiz bir tanımlayıcı.
continuation_token	Microsoft Entra'nın döndürdüğü devamlılık belirteci .
suberror	Hata türlerini daha fazla sınıflandırmak için kullanılabilecek bir hata kodu dizesi.

Karşılaşabileceğiniz olası hatalar şunlardır (parametrenin error olası değerleri):

Hata değeri	Açıklama
credential_required	Hesap oluşturmak için kimlik doğrulaması gereklidir, bu nedenle kullanıcının sağlaması gereken kimlik bilgilerini belirlemek için uç noktaya bir çağrı /signup/v1.0/challenge yapmanız gerekir.
invalid_request	Devamlılık belirtecinin doğrulanması başarısız oldu veya istek parametre eklemedi client_id istemci kimliği değeri boş veya geçersiz ya da dış kiracı yöneticisi tüm kiracı kullanıcıları için e-posta OTP'sini etkinleştirmemiş gibi istek parametresi doğrulaması başarısız oldu.
invalid_grant	İstekte yer alan verme türü geçerli veya desteklenmiyor ya da OTP değeri yanlış.
expired_token	İstekte yer alan devamlılık belirtecinin süresi doldu.

Hata parametresinin değeri invalid_grant ise, Microsoft Entra yanıtına bir suberror parametre ekler. bir invalid_grant hatası için parametrenin suberror olası değerleri şunlardır:

Alt değer	Açıklama
invalid_oob_value	Tek seferlik geçiş kodu değeri geçersiz.

Kullanıcıdan parola kimlik bilgilerinin toplanması için uygulamanın, kullanıcının sağlaması gereken kimlik bilgilerini belirlemek için /signup/v1.0/challenge uç noktaya bir çağrı yapması gerekir.

aşağıda isteğin bir örneği verilmiştir (örnek isteği okunabilirlik için birden çok satırda sunuyoruz):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/challenge
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&continuation_token=AQABAAEAAA…

Parametre	Zorunlu	Veri Akışı Açıklaması
tenant_subdomain	Yes	Oluşturduğunuz dış kiracının alt etki alanı. URL'de değerini Dizin (kiracı) alt etki alanıyla değiştirin {tenant_subdomain} . Örneğin, kiracınızın birincil etki alanı contoso.onmicrosoft.com ise contoso kullanın. Kiracı alt etki alanınız yoksa kiracınızın ayrıntılarını okumayı öğrenin.
client_id	Yes	Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği.
challenge_type	Hayır	Uygulamanın desteklediği yetkilendirme sınama türü dizelerinin boşlukla ayrılmış listesi.oob password redirect Liste her zaman sınama türünü içermelidir redirect . Parola kayıt akışına sahip e-posta için değerinin içermesi password redirectbeklenir.
continuation_token	Yes	Microsoft Entra'nın önceki istekte döndürdüğü devamlılık belirteci .

Başarılı yanıt

Parola, Microsoft Entra yönetim merkezinde kullanıcı için yapılandırılan kimlik doğrulama yöntemiyse, uygulamaya devamlılık belirtecini içeren bir başarı yanıtı döndürülür.

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

{
    "challenge_type": "password",
    "continuation_token": " AQABAAEAAAAty..."
}

Parametre	Açıklama
challenge_type	parola , gerekli kimlik bilgisi için yanıtta döndürülür.
continuation_token	Microsoft Entra'nın döndürdüğü devamlılık belirteci .

Bir uygulama Microsoft Entra tarafından gerekli bir kimlik doğrulama yöntemini destekleyemezse web tabanlı kimlik doğrulama akışına geri dönüş gerekir. Bu senaryoda Microsoft Entra, yanıtında bir yeniden yönlendirme sınama türü döndürerek uygulamayı bilgilendirmektedir:

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

{     
    "challenge_type": "redirect" 
} 

Parametre	Açıklama
challenge_type	Microsoft Entra, sınama türüne sahip bir yanıt döndürür. Bu sınama türünün değeri, uygulamanın web tabanlı kimlik doğrulama akışını kullanmasını sağlayan yeniden yönlendirmedir.

Bu yanıt başarılı olarak kabul edilir, ancak uygulamanın web tabanlı kimlik doğrulama akışına geçmesi gerekir. Bu durumda, Microsoft tarafından oluşturulmuş ve desteklenen bir kimlik doğrulama kitaplığı kullanmanızı öneririz.

4. Adım: Kaydolmak için kimlik doğrulaması ve belirteç alma

Uygulamanın, önceki adımda Microsoft Entra tarafından istenen kullanıcının kimlik bilgilerini (bu örnekte parola) göndermesi gerekir. Uygulamanın bunu uç nokta üzerinden yapmaması durumunda bir parola kimlik bilgisi göndermesi /signup/v1.0/start gerekir. Uygulama, parolayı /signup/v1.0/continue göndermek için uç noktaya bir istekte bulunur. Parola gönderdiğimiz için bir password parametre gereklidir ve parametrenin grant_type bir değer parolası olmalıdır.

aşağıda isteğin bir örneği verilmiştir (örnek isteği okunabilirlik için birden çok satırda sunuyoruz):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded

continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=password 
&password={secure_password}

Parametre	Zorunlu	Veri Akışı Açıklaması
tenant_subdomain	Yes	Oluşturduğunuz dış kiracının alt etki alanı. URL'de değerini Dizin (kiracı) alt etki alanıyla değiştirin {tenant_subdomain} . Örneğin, kiracınızın birincil etki alanı contoso.onmicrosoft.com ise contoso kullanın. Kiracı alt etki alanınız yoksa kiracınızın ayrıntılarını okumayı öğrenin.
continuation_token	Yes	Microsoft Entra'nın önceki adımda döndürdüğü devamlılık belirteci .
client_id	Yes	Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği.
grant_type	Yes	Bir kerelik geçiş kodu, parola veya kullanıcı öznitelikleri göndermek için uç noktaya yönelik bir istek /signup/v1.0/continue kullanılabilir. Bu durumda, grant_type değer bu üç kullanım örneğini ayırt etmek için kullanılır. grant_type için olası değerler oob, parola ve özniteliklerdir. Bu çağrıda, kullanıcının parolasını gönderdiğimiz için değerin parola olması beklenir.
password	Yes	Uygulamanın müşteri kullanıcısından topladığı parola değeri. değerini, uygulamanın müşteri kullanıcısından topladığı parola değeriyle değiştirin {secure_password} . Uygulamanın kullanıcı arabiriminde parola onaylama alanını sağlayarak kullanıcının kullanmak istediği parolanın farkında olduğunu onaylamak sizin sorumluluğunuzdadır. Ayrıca, kullanıcının kuruluşunuzun ilkesine göre neyin güçlü bir parola oluşturduğunu anladığınızdan emin olmanız gerekir. Microsoft Entra'nın parola ilkeleri hakkında daha fazla bilgi edinin.

Başarılı yanıt

İstek başarılı olursa ancak Microsoft Entra yönetim merkezinde hiçbir öznitelik yapılandırılmadıysa veya gerekli tüm öznitelikler uç nokta üzerinden /signup/v1.0/start gönderildiyse, uygulama herhangi bir öznitelik göndermeden bir devamlılık belirteci alır. Uygulama, 5. adımda gösterildiği gibi güvenlik belirteçleri istemek için devamlılık belirtecini kullanabilir. Aksi takdirde, Microsoft Entra'nın yanıtı uygulamanın gerekli öznitelikleri göndermesi gerektiğini belirtir. Yerleşik veya özel olan bu öznitelikler, kiracı yöneticisi tarafından Microsoft Entra yönetim merkezinde yapılandırıldı.

Kullanıcı öznitelikleri gerekli

Bu yanıt uygulamadan ad, *yaş ve telefon öznitelikleri için değerler göndermesini istemektedir.

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

{
    "error": "attributes_required",
    "error_description": "User attributes required",
    "error_codes": [
            55106
        ],
    "timestamp": "yy-mm-dd 02:37:33Z",
    "trace_id": "d6966055-...-80500",
    "correlation_id": "3944-...-60d6",
    "continuation_token": "AQABAAEAAAAtn...",
    "required_attributes": [
        {
            "name": "displayName",
            "type": "string",
            "required": true,
            "options": {
              "regex": ".*@.**$"
            }
        },
        {
            "name": "extension_2588abcdwhtfeehjjeeqwertc_age",
            "type": "string",
            "required": true
        },
        {
            "name": "postalCode",
            "type": "string",
            "required": true,
            "options": {
              "regex":"^[1-9][0-9]*$"
            }
        }
    ],
}

Not

Özel öznitelikler (dizin uzantıları olarak da bilinir), uzantılar uygulamasının istemci kimliğinin kaldırılmış sürümü olan {appId-without-hyphens} kural extension_{appId-without-hyphens}_{attribute-name} kullanılarak adlandırılır. Örneğin, uzantılar uygulamasının 2588a-bcdwh-tfeehj-jeeqw-ertc istemci kimliği ve öznitelik adı hobiler ise, özel öznitelik olarakextension_2588abcdwhtfeehjjeeqwertc_hobbies adlandırılır. Özel öznitelikler ve uzantı uygulaması hakkında daha fazla bilgi edinin.

Parametre	Açıklama
error	Bir özniteliğin doğrulanması veya gönderilmesi gerektiğinden Microsoft Entra kullanıcı hesabını oluşturamıyorsa bu öznitelik ayarlanır.
error_description	Hatanın nedenini belirlemenize yardımcı olabilecek belirli bir hata iletisi.
error_codes	Hataları tanılamanıza yardımcı olabilecek Microsoft Entra'ya özgü hata kodlarının listesi.
timestamp	Hatanın oluştuğu zaman.
trace_id	İstek için hataları tanılamanıza yardımcı olabilecek benzersiz bir tanımlayıcı.
correlation_id	bileşenler arasında tanılamada yardımcı olabilecek istek için benzersiz bir tanımlayıcı.
continuation_token	Microsoft Entra'nın döndürdüğü devamlılık belirteci .
required_attributes	Devam etmek için uygulamanın bir sonraki çağrıyı göndermesi gereken özniteliklerin listesi (nesne dizisi). Bu öznitelikler, uygulamanın kullanıcı adı dışında göndermesi gereken ek özniteliklerdir. Microsoft Entra, parametrenin değeri error attributes_required ise yanıt olarak bu parametreyi içerir.

Karşılaşabileceğiniz olası hatalar şunlardır (parametrenin error olası değerleri):

Hata değeri	Açıklama
invalid_request	Devamlılık belirtecinin doğrulanması başarısız olduğu veya isteğin parametre içermediği client_id için istemci kimliği değerinin boş veya geçersiz olması gibi istek parametresi doğrulaması başarısız oldu.
invalid_grant	İstekte yer alan verme türü geçerli değil veya desteklenmiyor. için grant_typeolası değerler oob, parola, özniteliklerdir
expired_token	İstekte yer alan devamlılık belirtecinin süresi doldu.
attributes_required	Bir veya daha fazla kullanıcı özniteliği gereklidir.

Bir uygulama Microsoft Entra tarafından gerekli bir kimlik doğrulama yöntemini destekleyemezse web tabanlı kimlik doğrulama akışına geri dönüş gerekir. Bu senaryoda Microsoft Entra, yanıtında bir yeniden yönlendirme sınama türü döndürerek uygulamayı bilgilendirmektedir:

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

{     
   "challenge_type": "redirect" 
} 

Parametre	Açıklama
challenge_type	Microsoft Entra, sınama türüne sahip bir yanıt döndürür. Bu sınama türünün değeri, uygulamanın web tabanlı kimlik doğrulama akışını kullanmasını sağlayan yeniden yönlendirmedir.

Bu yanıt başarılı olarak kabul edilir, ancak uygulamanın web tabanlı kimlik doğrulama akışına geçmesi gerekir. Bu durumda, Microsoft tarafından oluşturulmuş ve desteklenen bir kimlik doğrulama kitaplığı kullanmanızı öneririz.

Hata yanıtı

Örnek:

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

{
    "error": "invalid_grant",
    "error_description": "New password is too weak",
    "error_codes": [
        399246
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6",
    "suberror": "password_too_weak"
}

Parametre	Açıklama
error	Hata türlerini sınıflandırmak ve hatalara tepki vermek için kullanılabilecek bir hata kodu dizesi.
error_description	Kimlik doğrulama hatasının nedenini belirlemenize yardımcı olabilecek belirli bir hata iletisi.
error_codes	Hataları tanılamanıza yardımcı olabilecek Microsoft Entra'ya özgü hata kodlarının listesi.
timestamp	Hatanın oluştuğu zaman.
trace_id	İstek için hataları tanılamanıza yardımcı olabilecek benzersiz bir tanımlayıcı.
correlation_id	bileşenler arasında tanılamada yardımcı olabilecek istek için benzersiz bir tanımlayıcı.
suberror	Hata türlerini daha fazla sınıflandırmak için kullanılabilecek bir hata kodu dizesi.

Karşılaşabileceğiniz olası hatalar şunlardır (parametrenin error olası değerleri):

Hata değeri	Açıklama
invalid_request	Parametre geçersiz bir sınama türü içerdiğinde challenge_type olduğu gibi istek parametresi doğrulaması başarısız oldu.
invalid_grant	Gönderilen izin geçersiz, örneğin gönderilen parola çok kısa. Hatanın suberror tam nedenini öğrenmek için parametresini kullanın.
expired_token	Devamlılık belirtecinin süresi doldu.
attributes_required	Bir veya daha fazla kullanıcı özniteliği gereklidir.

Hata parametresinin değeri invalid_grant ise, Microsoft Entra yanıtına bir suberror parametre ekler. Parametresinin olası değerleri suberror şunlardır:

Alt değer	Açıklama
password_too_weak	Karmaşıklık gereksinimlerini karşılamadığından parola çok zayıf. Microsoft Entra'nın parola ilkeleri hakkında daha fazla bilgi edinin.
password_too_short	Yeni parola 8 karakterden azdır. Microsoft Entra'nın parola ilkeleri hakkında daha fazla bilgi edinin.
password_too_long	Yeni parola 256 karakterden uzun. Microsoft Entra'nın parola ilkeleri hakkında daha fazla bilgi edinin.
password_recently_used	Yeni parola, yakın zamanda kullanılan parolayla aynı olmamalıdır. Microsoft Entra'nın parola ilkeleri hakkında daha fazla bilgi edinin.
password_banned	Yeni parola, yasaklanmış bir sözcük, tümcecik veya desen içerir. Microsoft Entra'nın parola ilkeleri hakkında daha fazla bilgi edinin.
password_is_invalid	Parola geçersiz, örneğin izin verilmeyen karakterler kullandığından. Microsoft Entra'nın parola ilkeleri hakkında daha fazla bilgi edinin. Uygulama bir kullanıcı parolası gönderirse bu yanıt mümkündür.

Kullanıcı özniteliklerini gönderme

Akışa devam etmek için uygulamanın gerekli kullanıcı özniteliklerini göndermek için /signup/v1.0/continue uç noktaya bir çağrı yapması gerekir. Öznitelikleri gönderdiğimiz için bir attributes parametre gereklidir ve parametrenin grant_type özniteliklere eşit bir değeri olmalıdır.

aşağıda isteğin bir örneği verilmiştir (örnek isteği okunabilirlik için birden çok satırda sunuyoruz):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded

&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=attributes 
&attributes={"displayName": "{given_name}", "extension_2588abcdwhtfeehjjeeqwertc_age": "{user_age}", "postaCode": "{postal_code}"}
&continuation_token=AQABAAEAAAAtn...

Parametre	Zorunlu	Veri Akışı Açıklaması
tenant_subdomain	Yes	Oluşturduğunuz dış kiracının alt etki alanı. URL'de değerini Dizin (kiracı) alt etki alanıyla değiştirin {tenant_subdomain} . Örneğin, kiracınızın birincil etki alanı contoso.onmicrosoft.com ise contoso kullanın. Kiracı alt etki alanınız yoksa kiracınızın ayrıntılarını okumayı öğrenin.
continuation_token	Yes	Microsoft Entra'nın önceki istekte döndürdüğü devamlılık belirteci .
client_id	Yes	Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği.
grant_type	Yes	Bir kerelik geçiş kodu, parola veya kullanıcı öznitelikleri göndermek için uç noktaya yönelik bir istek /signup/v1.0/continue kullanılabilir. Bu durumda, grant_type değer bu üç kullanım örneğini ayırt etmek için kullanılır. grant_type için olası değerler oob, parola ve özniteliklerdir. Bu çağrıda kullanıcı öznitelikleri gönderdiğimiz için değerin öznitelik olması beklenir.
attributes	Yes	Uygulamanın müşteri kullanıcısından topladığı kullanıcı öznitelik değerleri. Değer bir dizedir, ancak anahtar değerleri yerleşik veya özel kullanıcı özniteliklerinin adları olan bir JSON nesnesi olarak biçimlendirilir. Nesnenin anahtar adları, yöneticinin Microsoft Entra yönetim merkezinde yapılandırmış olduğu özniteliklere bağlıdır. ve {user_age}{postal_code} değerlerini, uygulamanın müşteri kullanıcısından topladığı ad, yaş ve posta kodu değerleriyle değiştirin{given_name}. Microsoft Entra, gönderdiğiniz ve var olmayan öznitelikleri yoksayar.

Başarılı yanıt

İstek başarılı olursa, Microsoft Entra uygulamanın güvenlik belirteçleri istemek için kullanabileceği bir devamlılık belirteci verir.

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

{  
    "continuation_token": "AQABAAEAAAYn..."
} 

Parametre	Açıklama
continuation_token	Microsoft Entra'nın döndürdüğü devamlılık belirteci .

Bir uygulama Microsoft Entra tarafından gerekli bir kimlik doğrulama yöntemini destekleyemezse web tabanlı kimlik doğrulama akışına geri dönüş gerekir. Bu senaryoda Microsoft Entra, yanıtında bir yeniden yönlendirme sınama türü döndürerek uygulamayı bilgilendirmektedir:

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

{     
   "challenge_type": "redirect" 
} 

Parametre	Açıklama
challenge_type	Microsoft Entra, sınama türüne sahip bir yanıt döndürür. Bu sınama türünün değeri, uygulamanın web tabanlı kimlik doğrulama akışını kullanmasını sağlayan yeniden yönlendirmedir.

Bu yanıt başarılı olarak kabul edilir, ancak uygulamanın web tabanlı kimlik doğrulama akışına geçmesi gerekir. Bu durumda, Microsoft tarafından oluşturulmuş ve desteklenen bir kimlik doğrulama kitaplığı kullanmanızı öneririz.

Hata yanıtı

Örnek:

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

{
    "error": "expired_token",
    "error_description": "AADSTS901007: The continuation_token is expired.  .\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...", 
    "error_codes": [
        552003
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6" 
}

Parametre	Açıklama
error	Hata türlerini sınıflandırmak ve hatalara tepki vermek için kullanılabilecek bir hata kodu dizesi.
error_description	Kimlik doğrulama hatasının nedenini belirlemenize yardımcı olabilecek belirli bir hata iletisi.
error_codes	Hataları tanılamanıza yardımcı olabilecek Microsoft Entra'ya özgü hata kodlarının listesi.
timestamp	Hatanın oluştuğu zaman.
trace_id	İstek için hataları tanılamanıza yardımcı olabilecek benzersiz bir tanımlayıcı.
correlation_id	bileşenler arasında tanılamada yardımcı olabilecek istek için benzersiz bir tanımlayıcı.
continuation_token	Microsoft Entra'nın döndürdüğü devamlılık belirteci .
unverified_attributes	Doğrulanması gereken öznitelik anahtarı adlarının listesi (nesne dizisi). Parametrenin değeri verification_required olduğunda bu parametre yanıta error eklenir.
required_attributes	Uygulamanın göndermesi gereken özniteliklerin listesi (nesne dizisi). Microsoft Entra, parametrenin değeri attributes_required olduğunda yanıtında bu parametreyi error içerir.
invalid_attributes	Doğrulamada başarısız olan özniteliklerin listesi (nesne dizisi). Parametrenin değeri attribute_validation_failed olduğunda bu parametre yanıta suberror eklenir.
suberror	Hata türlerini daha fazla sınıflandırmak için kullanılabilecek bir hata kodu dizesi.

Karşılaşabileceğiniz olası hatalar şunlardır (parametrenin error olası değerleri):

Hata değeri	Açıklama
invalid_request	Devamlılık belirtecinin doğrulanması başarısız olduğu veya isteğin parametre içermediği client_id için istemci kimliği değerinin boş veya geçersiz olması gibi istek parametresi doğrulaması başarısız oldu.
invalid_grant	Sağlanan izin türü geçerli değil, öznitelik doğrulaması başarısız oldu gibi desteklenen veya başarısız doğrulama. Hatanın suberror tam nedenini öğrenmek için parametresini kullanın.
expired_token	İstekte yer alan devamlılık belirtecinin süresi doldu.
attributes_required	Bir veya daha fazla kullanıcı özniteliği gereklidir.

Hata parametresinin değeri invalid_grant ise, Microsoft Entra yanıtına bir suberror parametre ekler. bir invalid_grant hatası için parametrenin suberror olası değerleri şunlardır:

Alt değer	Açıklama
attribute_validation_failed	Kullanıcı özniteliği doğrulaması başarısız oldu. invalid_attributes parametresi, doğrulamada başarısız olan özniteliklerin listesini (nesne dizisi) içerir.

5. Adım: Güvenlik belirteçleri isteği

Uygulama uç noktaya bir POST isteğinde /token bulunur ve güvenlik belirteçlerini almak için önceki adımdan alınan devamlılık belirtecini sağlar.

burada bir istek örneği verilmiştir (örnek isteği okunabilirlik için birden çok satırda sunuyoruz):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
 
continuation_token=ABAAEAAAAtyo... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&username=contoso-consumer@contoso.com
&scope={scopes}
&grant_type=continuation_token 

Parametre	Zorunlu	Veri Akışı Açıklaması
tenant_subdomain	Yes	Oluşturduğunuz dış kiracının alt etki alanı. URL'de değerini Dizin (kiracı) alt etki alanıyla değiştirin {tenant_subdomain} . Örneğin, kiracınızın birincil etki alanı contoso.onmicrosoft.com ise contoso kullanın. Kiracı alt etki alanınız yoksa kiracınızın ayrıntılarını okumayı öğrenin.
client_id	Yes	Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği.
grant_type	Yes	Parametre değeri devamlılık belirteci olmalıdır.
continuation_token	Yes	Microsoft Entra'nın önceki adımda döndürdüğü devamlılık belirteci .
scope	Yes	Erişim belirtecinin geçerli olduğu kapsamların boşlukla ayrılmış listesi. değerini, Microsoft Entra'nın döndürdüğü erişim belirtecinin geçerli olduğu geçerli kapsamlarla değiştirin {scopes} .
username	Yes	Kaydolmak istediği müşteri kullanıcısının e-posta adresi, örneğin contoso-consumer@contoso.com.

Başarılı yanıt

Başarılı bir yanıt örneği aşağıda verilmişti:

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

{
    "token_type": "Bearer",
    "scope": "openid profile",
    "expires_in": 4141,
    "access_token": "eyJ0eXAiOiJKV1Qi...",
    "refresh_token": "AwABAAAA...",
    "id_token": "eyJ0eXAiOiJKV1Q..."
}

Parametre	Açıklama
access_token	Uygulamanın uç noktadan istediği erişim belirteci /token . Uygulama, web API'leri gibi güvenli kaynaklara erişim istemek için bu erişim belirtecini kullanabilir.
token_type	Belirteç türü değerini gösterir. Microsoft Entra'nın desteklediği tek tür Taşıyıcı'dır.
expires_in	Erişim belirtecinin geçerli kaldığı saniye cinsinden süre.
scopes	Erişim belirtecinin geçerli olduğu kapsamların boşlukla ayrılmış listesi.
refresh_token	OAuth 2.0 yenileme belirteci. Uygulama, geçerli erişim belirtecinin süresi dolduktan sonra diğer erişim belirteçlerini almak için bu belirteci kullanabilir. Yenileme belirteçleri uzun ömürlü. Kaynaklara erişimi uzun süreler boyunca koruyabilirler. Erişim belirtecini yenileme hakkında daha fazla bilgi için Erişim belirtecini yenileme makalesine bakın. Not: Yalnızca offline_access kapsamı istendiyse verilir.
id_token	Müşteri kullanıcısını tanımlamak için kullanılan bir JSON Web Belirteci (Jwt). Uygulama, oturum açan kullanıcı hakkındaki bilgileri okumak için belirtecin kodunu çözebilir. Uygulama, değerleri önbelleğe alıp görüntüleyebilir ve gizli istemciler yetkilendirme için bu belirteci kullanabilir. Kimlik belirteçleri hakkında daha fazla bilgi için bkz . Kimlik belirteçleri. Not: Yalnızca openid kapsamı isteniyorsa verilir.

Hata yanıtı

Örnek:

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

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The client doesn't have consent for the requested scopes.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        50126 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
} 

Parametre	Açıklama
error	Hata türlerini sınıflandırmak ve hatalara tepki vermek için kullanılabilecek bir hata kodu dizesi.
error_description	Kimlik doğrulama hatasının nedenini belirlemenize yardımcı olabilecek belirli bir hata iletisi.
error_codes	Hataları tanılamanıza yardımcı olabilecek Microsoft Entra'ya özgü hata kodlarının listesi.
timestamp	Hatanın oluştuğu zaman.
trace_id	İstek için hataları tanılamanıza yardımcı olabilecek benzersiz bir tanımlayıcı.
correlation_id	bileşenler arasında tanılamada yardımcı olabilecek istek için benzersiz bir tanımlayıcı.

Karşılaşabileceğiniz olası hatalar şunlardır (parametrenin error olası değerleri):

Hata değeri	Açıklama
invalid_request	İstemci/uygulamanın istenen kapsamlar için onayı olmaması gibi istek parametresi doğrulaması başarısız oldu.
invalid_grant	İstekte yer alan devamlılık belirteci geçersiz.
unauthorized_client	İstekte yer alan istemci kimliği geçersiz veya yok.
unsupported_grant_type	İstekte yer alan verme türü desteklenmiyor veya yanlış.

Uç noktalara kullanıcı öznitelikleri gönderme

Microsoft Entra yönetim merkezinde kullanıcı özniteliklerini gerektiği gibi veya isteğe bağlı olarak yapılandırabilirsiniz. Bu yapılandırma, uç noktalarına çağrı yaptığınızda Microsoft Entra'nın nasıl yanıt vereceğini belirler. Kaydolma akışının tamamlanması için isteğe bağlı öznitelikler zorunlu değildir. Bu nedenle, tüm öznitelikler isteğe bağlı olduğunda, kullanıcı adı doğrulanması için önce gönderilmelidir. Aksi takdirde, isteğe bağlı öznitelikler olmadan kaydolma tamamlar.

Aşağıdaki tabloda kullanıcı özniteliklerinin Microsoft Entra uç noktalarına ne zaman gönderilmesi mümkün olduğu özetlemektedir.

Uç nokta	Gerekli öznitelikler	İsteğe bağlı öznitelikler	Hem gerekli hem de isteğe bağlı öznitelikler
/signup/v1.0/start bitiş noktası	Yes	Evet	Yes
/signup/v1.0/continue kullanıcı adı doğrulamadan önceki uç nokta	Yes	Evet	Yes
/signup/v1.0/continue kullanıcı adı doğrulaması sonrasında uç nokta	Yes	Hayı	Evet

Kullanıcı öznitelikleri değerlerinin biçimi

Microsoft Entra yönetim merkezinde kullanıcı akışı ayarlarını yapılandırarak kullanıcıdan toplamak istediğiniz bilgileri belirtirsiniz. Hem yerleşik hem de özel öznitelikler için değer toplamayı öğrenmek için Kaydolma sırasında özel kullanıcı özniteliklerini toplama makalesini kullanın.

Yapılandırdığınız öznitelikler için Kullanıcı Giriş Türü de belirtebilirsiniz. Aşağıdaki tabloda desteklenen kullanıcı giriş türleri ve kullanıcı arabirimi denetimleri tarafından toplanan değerlerin Microsoft Entra'ya nasıl gönderilip gönderndiği özetlenmektedir.

Kullanıcı Giriş Türü	Gönderilen değerlerin biçimi
TextBox	İş unvanı , Yazılım Mühendisi gibi tek bir değer.
SingleRadioSelect	Dil, Norveççe gibi tek bir değer.
Onay KutusuMultiSelect	Hobi veya hobi, Dans veya Dans, Yüzme, Seyahat gibi bir veya birden çok değer.

Özniteliklerin değerlerini nasıl gönderdiğinizi gösteren örnek bir istek aşağıda verilmiştir:

POST /{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue HTTP/1.1
Host: {tenant_subdomain}.ciamlogin.com
Content-Type: application/x-www-form-urlencoded
 
continuation_token=ABAAEAAAAtfyo... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=attributes 
&attributes={"jobTitle": "Software Engineer", "extension_2588abcdwhtfeehjjeeqwertc_language": "Norwegian", "extension_2588abcdwhtfeehjjeeqwertc_hobbies": "Dancing,Swimming,Traveling"}
&continuation_token=AQABAAEAAAAtn...

Özel kullanıcı öznitelikleri giriş türleri makalesinde kullanıcı öznitelikleri giriş türleri hakkında daha fazla bilgi edinin.

Kullanıcı özniteliklerine başvurma

Kaydolma kullanıcı akışı oluşturduğunuzda, kayıt sırasında kullanıcıdan toplamak istediğiniz kullanıcı özniteliklerini yapılandırabilirsiniz. Microsoft Entra yönetim merkezindeki kullanıcı özniteliklerinin adları, yerel kimlik doğrulama API'sinde bunlara başvurma yönteminizden farklıdır.

Örneğin, Microsoft Entra yönetim merkezindeki Görünen Ad'a API'de displayName olarak başvurulur.

Yerel kimlik doğrulama API'sinde hem yerleşik hem de özel kullanıcı özniteliklerine başvurmayı öğrenmek için Kullanıcı profili öznitelikleri makalesini kullanın.

Oturum açma API'si başvurusu

Kullanıcıların kaydolmak için kullandıkları kimlik doğrulama yöntemiyle oturum açmaları gerekir. Örneğin, parola kimlik doğrulama yöntemiyle e-posta kullanarak kaydolan kullanıcıların e-postada ve parolada oturum açması gerekir.

Güvenlik belirteçleri istemek için uygulamanız ve /challenge/tokenolmak üzere üç uç noktayla etkileşim kurar/initiate.

Oturum açma API'leri uç noktaları

Uç nokta	Açıklama
/initiate	Bu uç nokta oturum açma akışını başlatır. Uygulamanız zaten var olan bir kullanıcı hesabının kullanıcı adıyla çağırırsa, devamlılık belirteci içeren bir başarı yanıtı döndürür. Uygulamanız Microsoft Entra tarafından desteklenmeyen kimlik doğrulama yöntemlerini kullanmayı isterse, bu uç nokta yanıtı uygulamanıza tarayıcı tabanlı bir kimlik doğrulama akışı kullanması gerektiğini gösterebilir.
/challenge	uygulamanız, kimlik hizmeti tarafından desteklenen sınama türlerinin listesiyle bu uç noktayı çağırır. Kimlik hizmetimiz e-posta gibi seçilen sınama kanalına tek seferlik bir geçiş kodu oluşturur ve gönderir. Uygulamanız bu uç noktayı tekrar tekrar çağırırsa, her çağrı yapıldığında yeni bir OTP gönderilir.
/token	Bu uç nokta uygulamanızdan aldığı tek seferlik geçiş kodunu doğrular ve ardından uygulamanıza güvenlik belirteçleri verir.

Oturum açma sınama türleri

API, uygulamanın Microsoft Entra çağrısı yaptığında desteklediği kimlik doğrulama yöntemlerini tanıtmasına olanak tanır. Bunu yapmak için uygulama isteklerinde parametresini challenge_type kullanır. Bu parametre, farklı kimlik doğrulama yöntemlerini temsil eden önceden tanımlanmış değerleri tutar.

Belirli bir kimlik doğrulama yöntemi için, bir uygulamanın kayıt akışı sırasında Microsoft Entra'ya gönderdiği sınama türü değerleri, uygulama oturum açtığında aynı olur. Örneğin, parola kimlik doğrulama yöntemine sahip e-postada hem kaydolma hem de oturum açma akışları için oob, parola ve yeniden yönlendirme sınama türü değerleri kullanılır.

Yerel kimlik doğrulaması sınama türleri makalesinde sınama türleri hakkında daha fazla bilgi edinin.

Oturum açma akışı protokolü ayrıntıları

Sıralı diyagram, oturum açma işleminin akışını gösterir.

Tek seferlik geçiş kodunu e-postayla gönderme

Uygulama kullanıcının OTP ile e-postasını doğruladıktan sonra güvenlik belirteçleri alır. Tek seferlik geçiş kodunun teslimi gecikirse veya kullanıcının e-postasına hiçbir zaman teslim edilmediyse, kullanıcı bir kerelik başka bir geçiş kodu gönderilmesini isteyebilir. Microsoft Entra, bir önceki doğrulanmamışsa bir kerelik geçiş kodunu yeniden göndermektedir. Microsoft Entra tek seferlik bir geçiş kodunu yeniden gönderdiğinde, daha önce gönderilen kodu geçersiz kılır.

Parola ile e-posta

Bu diyagram, uygulamanın kullanıcıdan farklı zamanlarda (ve muhtemelen ayrı ekranlarda) kullanıcı adı (e-posta) ve parola topladığını gösterir. Ancak, uygulamanızı aynı ekranda iki değeri toplayacak şekilde tasarlayabilirsiniz. Kullanıcı adı (e-posta) ve parolayı aynı ekranda toplarsanız, ikinci ve üçüncü adımlar sekiz ve dokuz. adımlarla birleştirilir. Bu durumda, uygulama parolayı tutar ve ardından gerekli olduğu on adımda gönderir.

İzleyen bölümlerde, sıralı diyagram akışını üç temel adıma özetleyeceğiz.

1. Adım: Oturum açma akışını başlatma isteği

Kimlik doğrulama akışı, uygulamanın oturum açma akışını başlatmak için /initiate uç noktaya post isteği göndermesiyle başlar.

aşağıda isteğin bir örneği verilmiştir (örnek isteği okunabilirlik için birden çok satırda sunuyoruz):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/initiate
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=password redirect
&username=contoso-consumer@contoso.com 

Parametre	Zorunlu	Veri Akışı Açıklaması
tenant_subdomain	Yes	Oluşturduğunuz dış kiracının alt etki alanı. URL'de değerini Dizin (kiracı) alt etki alanıyla değiştirin {tenant_subdomain} . Örneğin, kiracınızın birincil etki alanı contoso.onmicrosoft.com ise contoso kullanın. Kiracı alt etki alanınız yoksa kiracınızın ayrıntılarını okumayı öğrenin.
client_id	Yes	Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği.
username	Yes	Gibi contoso-consumer@contoso.commüşteri kullanıcısının e-postası.
challenge_type	Yes	Uygulamanın desteklediği yetkilendirme sınama türü dizelerinin boşlukla ayrılmış listesi.oob password redirect Liste her zaman sınama türünü içermelidir redirect . Değerin e-posta tek seferlik geçiş kodu ve password redirect parolalı e-posta için olması bekleniroob redirect.

Başarılı yanıt

Başarılı bir yanıt örneği aşağıda verilmişti:

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}

Parametre	Açıklama
continuation_token	Microsoft Entra'nın döndürdüğü devamlılık belirteci .

Bir uygulama Microsoft Entra tarafından gerekli bir kimlik doğrulama yöntemini destekleyemezse web tabanlı kimlik doğrulama akışına geri dönüş gerekir. Bu senaryoda Microsoft Entra, yanıtında bir yeniden yönlendirme sınama türü döndürerek uygulamayı bilgilendirmektedir:

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

{     
   "challenge_type": "redirect" 
} 

Parametre	Açıklama
challenge_type	Microsoft Entra, sınama türüne sahip bir yanıt döndürür. Bu sınama türünün değeri, uygulamanın web tabanlı kimlik doğrulama akışını kullanmasını sağlayan yeniden yönlendirmedir.

Bu yanıt başarılı olarak kabul edilir, ancak uygulamanın web tabanlı kimlik doğrulama akışına geçmesi gerekir. Bu durumda, Microsoft tarafından oluşturulmuş ve desteklenen bir kimlik doğrulama kitaplığı kullanmanızı öneririz.

Hata yanıtı

Örnek:

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

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
} 

Parametre	Açıklama
error	Hata türlerini sınıflandırmak ve hatalara tepki vermek için kullanılabilecek bir hata kodu dizesi.
error_description	Kimlik doğrulama hatasının nedenini belirlemenize yardımcı olabilecek belirli bir hata iletisi.
error_codes	Hataları tanılamanıza yardımcı olabilecek Microsoft Entra'ya özgü hata kodlarının listesi.
timestamp	Hatanın oluştuğu zaman.
trace_id	İstek için hataları tanılamanıza yardımcı olabilecek benzersiz bir tanımlayıcı.
correlation_id	bileşenler arasında tanılamada yardımcı olabilecek istek için benzersiz bir tanımlayıcı.

Karşılaşabileceğiniz olası hatalar şunlardır (parametrenin error olası değerleri):

Hata değeri	Açıklama
invalid_request	Parametre geçersiz bir sınama türü içerdiğinde challenge_type olduğu gibi istek parametresi doğrulaması başarısız oldu. veya istek parametre içermiyordu client_id , istemci kimliği değeri boş veya geçersiz. Hatanın error_description tam nedenini öğrenmek için parametresini kullanın.
unauthorized_client	İstekte kullanılan istemci kimliği geçerli bir istemci kimliği biçimine sahip, ancak dış kiracıda yok veya yanlış.
invalid_client	Uygulamanın istekte içerdiği istemci kimliği, genel istemci olmadığı veya yerel kimlik doğrulaması için etkinleştirilmediği gibi yerel kimlik doğrulama yapılandırması olmayan bir uygulamaya yöneliktir. Hatanın suberror tam nedenini öğrenmek için parametresini kullanın.
user_not_found	Kullanıcı adı yok.
unsupported_challenge_type	challenge_type Parametre değeri sınama türünü içermezredirect.

Hata parametresinin değeri invalid_client ise, Microsoft Entra yanıtına bir suberror parametre ekler. invalid_client hatası için parametrenin suberror olası değerleri şunlardır:

Alt değer	Açıklama
nativeauthapi_disabled	Yerel kimlik doğrulaması için etkinleştirilmemiş bir uygulamanın istemci kimliği.

2. Adım: Bir kimlik doğrulama yöntemi seçin

Akışa devam etmek için uygulama, önceki adımdan aldığı devamlılık belirtecini kullanarak Microsoft Entra'dan kullanıcının kimlik doğrulaması için desteklenen sınama türlerinden birini seçmesini istemektedir. Uygulama uç noktaya bir POST isteğinde bulunur /challenge .

burada bir istek örneği verilmiştir (örnek isteği okunabilirlik için birden çok satırda sunuyoruz):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/challenge
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=password redirect 
&continuation_token=uY29tL2F1dGhlbnRpY... 

Parametre	Zorunlu	Veri Akışı Açıklaması
tenant_subdomain	Yes	Oluşturduğunuz dış kiracının alt etki alanı. URL'de değerini Dizin (kiracı) alt etki alanıyla değiştirin {tenant_subdomain} . Örneğin, kiracınızın birincil etki alanı contoso.onmicrosoft.com ise contoso kullanın. Kiracı alt etki alanınız yoksa kiracınızın ayrıntılarını okumayı öğrenin.
client_id	Yes	Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği.
continuation_token	Yes	Microsoft Entra'nın önceki istekte döndürdüğü devamlılık belirteci .
challenge_type	Hayır	Uygulamanın desteklediği yetkilendirme sınama türü dizelerinin boşlukla ayrılmış listesi.oob password redirect Liste her zaman sınama türünü içermelidir redirect . Değerin e-posta tek seferlik geçiş kodu ve password redirect parolalı e-posta için olması bekleniroob redirect.

Başarılı yanıt

Tek seferlik geçiş kodunu e-postayla gönderme

Kiracı yöneticisi kullanıcının kimlik doğrulama yöntemi olarak Microsoft Entra yönetim merkezinde e-posta tek seferlik geçiş kodu yapılandırdıysa, Microsoft Entra kullanıcının e-postasına tek seferlik bir geçiş kodu gönderir, ardından güçlük türüyle yanıt verir ve tek seferlik geçiş kodu hakkında daha fazla bilgi sağlar.

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "challenge_type": "oob",
    "binding_method": "prompt ", 
    "challenge_channel": "email",
    "challenge_target_label ": "c***r@co**o**o.com ",
    "code_length": 8
} 

Parametre	Açıklama
continuation_token	Microsoft Entra'nın döndürdüğü devamlılık belirteci .
challenge_type	Kullanıcının kimlik doğrulaması için seçilen sınama türü.
binding_method	Tek geçerli değer istemdir. Bu parametre gelecekte kullanıcının tek seferlik geçiş kodunu girmesi için daha fazla yol sunmak için kullanılabilir. Oob ise challenge_type verilir
challenge_channel	Tek seferlik geçiş kodunun gönderildiği kanalın türü. Şu anda e-postayı destekliyoruz.
challenge_target_label	Tek seferlik geçiş kodunun gönderildiği belirsiz bir e-posta.
code_length	Microsoft Entra'nın oluşturduğu tek seferlik geçiş kodunun uzunluğu.

Parola ile e-posta

Kiracı yöneticisi kullanıcının kimlik doğrulama yöntemi olarak Microsoft Entra yönetim merkezinde parolayla e-posta yapılandırdıysa, Microsoft Entra bir parola sınama türü içeren bir başarı yanıtı döndürür.

Örnek:

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

{   
   "continuation_token": "uY29tL2F1dGhlbnRpY",   
   "challenge_type": "password" 
} 

Parametre	Açıklama
continuation_token	Microsoft Entra'nın döndürdüğü devamlılık belirteci .
challenge_type	Microsoft Entra, Microsoft Entra yönetim merkezinde kullanıcı için yapılandırılan desteklenen sınama türünü döndürür. Bu durumda değerlerin parola olması beklenir.

Bir uygulama Microsoft Entra tarafından gerekli bir kimlik doğrulama yöntemini destekleyemezse web tabanlı kimlik doğrulama akışına geri dönüş gerekir. Bu senaryoda Microsoft Entra, yanıtında bir yeniden yönlendirme sınama türü döndürerek uygulamayı bilgilendirmektedir:

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

{     
   "challenge_type": "redirect" 
} 

Parametre	Açıklama
challenge_type	Microsoft Entra, sınama türüne sahip bir yanıt döndürür. Bu sınama türünün değeri, uygulamanın web tabanlı kimlik doğrulama akışını kullanmasını sağlayan yeniden yönlendirmedir.

Bu yanıt başarılı olarak kabul edilir, ancak uygulamanın web tabanlı kimlik doğrulama akışına geçmesi gerekir. Bu durumda, Microsoft tarafından oluşturulmuş ve desteklenen bir kimlik doğrulama kitaplığı kullanmanızı öneririz.

Hata yanıtı

Örnek:

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

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
} 

Parametre	Açıklama
error	Hata türlerini sınıflandırmak ve hatalara tepki vermek için kullanılabilecek bir hata kodu dizesi.
error_description	Kimlik doğrulama hatasının nedenini belirlemenize yardımcı olabilecek belirli bir hata iletisi.
error_codes	Hataları tanılamanıza yardımcı olabilecek Microsoft Entra'ya özgü hata kodlarının listesi.
timestamp	Hatanın oluştuğu zaman.
trace_id	İstek için hataları tanılamanıza yardımcı olabilecek benzersiz bir tanımlayıcı.
correlation_id	bileşenler arasında tanılamada yardımcı olabilecek istek için benzersiz bir tanımlayıcı.

Karşılaşabileceğiniz olası hatalar şunlardır (parametrenin error olası değerleri):

Hata değeri	Açıklama
invalid_request	Parametre geçersiz bir sınama türü içerdiğinde challenge_type olduğu gibi istek parametresi doğrulaması başarısız oldu.
invalid_grant	İstekte yer alan devamlılık belirteci geçerli değil.
expired_token	İstekte yer alan devamlılık belirtecinin süresi doldu.
unsupported_challenge_type	challenge_type Parametre değeri sınama türünü içermezredirect.

3. Adım: Güvenlik belirteçleri isteği

Uygulama uç noktaya bir POST isteğinde /token bulunur ve güvenlik belirteçlerini almak için önceki adımda (bu örnekte parola) seçilen kullanıcının kimlik bilgilerini sağlar.

aşağıda isteğin bir örneği verilmiştir (örnek isteği okunabilirlik için birden çok satırda sunuyoruz):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=password 
&password={secure_password}
&scope=openid offline_access 

Parametre	Zorunlu	Veri Akışı Açıklaması
tenant_subdomain	Yes	Oluşturduğunuz dış kiracının alt etki alanı. URL'de değerini Dizin (kiracı) alt etki alanıyla değiştirin {tenant_subdomain} . Örneğin, kiracınızın birincil etki alanı contoso.onmicrosoft.com ise contoso kullanın. Kiracı alt etki alanınız yoksa kiracınızın ayrıntılarını okumayı öğrenin.
client_id	Yes	Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği.
continuation_token	Yes	Microsoft Entra'nın önceki istekte döndürdüğü devamlılık belirteci .
grant_type	Yes	Değer, parola kimlik doğrulama yöntemine sahip e-posta için parola ve tek seferlik geçiş kodu kimlik doğrulama yöntemi için oob olmalıdır.
scope	Yes	Boşlukla ayrılmış kapsam listesi. Tüm kapsamlar profil, *openid ve e-posta gibi OpenID Connect (OIDC) kapsamlarıyla birlikte tek bir kaynaktan olmalıdır. Uygulamanın kimlik belirteci vermek için Microsoft Entra için openid kapsamı içermesi gerekir. Uygulamanın, Microsoft Entra'nın yenileme belirteci vermesine yönelik offline_access kapsamı içermesi gerekir. Microsoft kimlik platformu İzinler ve onay hakkında daha fazla bilgi edinin.
password	Evet (parolalı e-posta için)	Uygulamanın müşteri kullanıcısından topladığı parola değeri. değerini, uygulamanın müşteri kullanıcısından topladığı parola değeriyle değiştirin {secure_password} .
oob	Evet (e-posta tek seferlik geçiş kodu için)	Müşteri kullanıcısının e-postasında aldığı tek seferlik geçiş kodu. değerini, müşteri kullanıcısının e-postasında aldığı tek seferlik geçiş koduyla değiştirin {otp_code} . Tek seferlik geçiş kodunu yeniden göndermek için uygulamanın uç noktaya yeniden istekte /challenge bulunması gerekir.

Başarılı yanıt

Başarılı bir yanıt örneği aşağıda verilmişti:

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

{
    "token_type": "Bearer",
    "scope": "openid profile",
    "expires_in": 4141,
    "access_token": "eyJ0eXAiOiJKV1Qi...",
    "refresh_token": "AwABAAAA...",
    "id_token": "eyJ0eXAiOiJKV1Q..."
}

Parametre	Açıklama
token_type	Belirteç türü değerini gösterir. Microsoft Entra'nın desteklediği tek tür Taşıyıcı'dır.
scopes	Erişim belirtecinin geçerli olduğu kapsamların boşlukla ayrılmış listesi.
expires_in	Erişim belirtecinin geçerli kaldığı saniye cinsinden süre.
access_token	Uygulamanın uç noktadan istediği erişim belirteci /token . Uygulama, web API'leri gibi güvenli kaynaklara erişim istemek için bu erişim belirtecini kullanabilir.
refresh_token	OAuth 2.0 yenileme belirteci. Uygulama, geçerli erişim belirtecinin süresi dolduktan sonra diğer erişim belirteçlerini almak için bu belirteci kullanabilir. Yenileme belirteçleri uzun ömürlü. Kaynaklara erişimi uzun süreler boyunca koruyabilirler. Erişim belirtecini yenileme hakkında daha fazla bilgi için Erişim belirtecini yenileme makalesine bakın. Not: Yalnızca offline_access kapsamı istemeniz durumunda verilir.
id_token	Müşteri kullanıcısını tanımlamak için kullanılan bir JSON Web Belirteci (Jwt). Uygulama, oturum açan kullanıcı hakkında bilgi istemek için belirtecin kodunu çözebilir. Uygulama, değerleri önbelleğe alıp görüntüleyebilir ve gizli istemciler yetkilendirme için bu belirteci kullanabilir. Kimlik belirteçleri hakkında daha fazla bilgi için bkz . Kimlik belirteçleri. Not: Yalnızca openid kapsamı istemeniz durumunda verilir.

Hata yanıtı

Örnek:

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

{ 
    "error": "invalid_grant", 
    "error_description": "AADSTS901007: Error validating credentials due to invalid username or password.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        50126 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
} 

Parametre	Açıklama
error	Hata türlerini sınıflandırmak ve hatalara tepki vermek için kullanılabilecek bir hata kodu dizesi.
error_description	Kimlik doğrulama hatasının nedenini belirlemenize yardımcı olabilecek belirli bir hata iletisi.
error_codes	Hataları tanılamanıza yardımcı olabilecek Microsoft Entra'ya özgü hata kodlarının listesi.
timestamp	Hatanın oluştuğu zaman.
trace_id	İstek için hataları tanılamanıza yardımcı olabilecek benzersiz bir tanımlayıcı.
correlation_id	bileşenler arasında tanılamada yardımcı olabilecek istek için benzersiz bir tanımlayıcı.

Karşılaşabileceğiniz olası hatalar şunlardır (parametrenin error olası değerleri):

Hata değeri	Açıklama
invalid_request	İstek parametresi doğrulaması başarısız oldu. Ne olduğunu anlamak için hata açıklamasındaki iletiyi kullanın.
invalid_grant	İstekte yer alan devamlılık belirteci geçerli değil veya istekte yer alan müşteri kullanıcı oturum açma kimlik bilgileri geçersiz veya istekte yer alan izin türü bilinmiyor.
invalid_client	İstekte yer alan istemci kimliği genel istemciye yönelik değildir.
expired_token	İstekte yer alan devamlılık belirtecinin süresi doldu.
invalid_scope	İstekte yer alan kapsamı belirlenmiş bir veya daha fazla geçersiz.

Hata parametresinin değeri invalid_grant ise, Microsoft Entra yanıtına bir suberror parametre ekler. bir invalid_grant hatası için parametrenin suberror olası değerleri şunlardır:

Alt değer	Açıklama
invalid_oob_value	Tek seferlik geçiş kodu değeri geçersiz. Bu alt hata yalnızca e-posta tek seferlik geçiş kodu uygular

Self servis parola sıfırlama (SSPR)

Uygulamanızda kimlik doğrulama yöntemi olarak e-posta ve parola kullanıyorsanız, müşteri kullanıcılarının parolalarını sıfırlamasını sağlamak için self servis parola sıfırlama (SSPR) API'sini kullanın. Parolayı unutma veya parola değiştirme senaryoları için bu API'sini kullanın.

Self servis parola sıfırlama API uç noktaları

Bu API'yi kullanmak için uygulama aşağıdaki tabloda gösterilen uç noktayla etkileşim kurar:

Uç nokta	Açıklama
/start	Müşteri kullanıcı uygulamada Parolayı unuttum veya Parolayı değiştir bağlantısını veya düğmesini seçtiğinde uygulamanız bu uç noktayı çağırır. Bu uç nokta kullanıcının kullanıcı adını (e-posta) doğrular, ardından parola sıfırlama akışında kullanmak üzere bir devamlılık belirteci döndürür. Uygulamanız Microsoft Entra tarafından desteklenmeyen kimlik doğrulama yöntemlerini kullanmayı isterse, bu uç nokta yanıtı uygulamanıza tarayıcı tabanlı bir kimlik doğrulama akışı kullanması gerektiğini gösterebilir.
/challenge	İstemci ve devamlılık belirteci tarafından desteklenen sınama türlerinin listesini kabul eder. Tercih edilen kurtarma kimlik bilgilerine bir sınama verilir. Örneğin, oob sınaması müşteri kullanıcı hesabıyla ilişkili e-postaya bant dışı bir tek seferlik geçiş kodu oluşturur. Uygulamanız Microsoft Entra tarafından desteklenmeyen kimlik doğrulama yöntemlerini kullanmayı isterse, bu uç nokta yanıtı uygulamanıza tarayıcı tabanlı bir kimlik doğrulama akışı kullanması gerektiğini gösterebilir.
/continue	Uç nokta tarafından verilen sınamayı /challenge doğrular, ardından uç nokta için /submit bir devam belirteci döndürür veya kullanıcıya başka bir sınama verir.
/submit	Parola sıfırlama akışını tamamlamak için devamlılık belirteciyle birlikte kullanıcı tarafından yeni bir parola girişi kabul eder. Bu uç nokta başka bir devamlılık belirteci oluşturur.
/poll_completion	Son olarak uygulama, parola sıfırlama isteğinin durumunu denetlemek için uç nokta tarafından /submit verilen devamlılık belirtecini kullanabilir.

Self servis parola sıfırlama sınama türleri

API, uygulamanın Microsoft Entra çağrısı yaptığında desteklediği kimlik doğrulama yöntemlerini tanıtmasına olanak tanır. Bunu yapmak için uygulama isteklerinde parametresini challenge_type kullanır. Bu parametre, farklı kimlik doğrulama yöntemlerini temsil eden önceden tanımlanmış değerleri tutar.

SSPR akışı için sınama türü değerleri oob ve yeniden yönlendirmedir.

Yerel kimlik doğrulama sınaması türlerindeki sınama türleri hakkında daha fazla bilgi edinin.

Self servis parola sıfırlama akışı protokolü ayrıntıları

Sıralı diyagramda parola sıfırlama işleminin akışı gösterilir.

Bu diyagram, uygulamanın kullanıcıdan farklı zamanlarda (ve muhtemelen ayrı ekranlarda) kullanıcı adı (e-posta) ve parola topladığını gösterir. Ancak, uygulamanızı aynı ekranda kullanıcı adını (e-posta) ve yeni parolayı toplayacak şekilde tasarlayabilirsiniz. Bu durumda uygulama parolayı tutar ve ardından gerekli olduğu uç nokta üzerinden /submit gönderir.

1. Adım: Self servis parola sıfırlama akışını başlatma isteği

Parola sıfırlama akışı, uygulamanın self servis parola sıfırlama akışını başlatmak için /start uç noktaya bir POST isteği göndermesiyle başlar.

burada bir istek örneği verilmiştir (örnek isteği okunabilirlik için birden çok satırda sunuyoruz):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/start
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&challenge_type=oob redirect 
&username=contoso-consumer@contoso.com 

Parametre	Zorunlu	Veri Akışı Açıklaması
tenant_subdomain	Yes	Oluşturduğunuz dış kiracının alt etki alanı. URL'de değerini Dizin (kiracı) alt etki alanıyla değiştirin {tenant_subdomain} . Örneğin, kiracınızın birincil etki alanı contoso.onmicrosoft.com ise contoso kullanın. Kiracı alt etki alanınız yoksa kiracınızın ayrıntılarını okumayı öğrenin.
client_id	Yes	Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği.
username	Yes	Gibi contoso-consumer@contoso.commüşteri kullanıcısının e-postası.
challenge_type	Yes	Uygulamanın desteklediği yetkilendirme sınama türü dizelerinin boşlukla ayrılmış listesi.oob password redirect Liste her zaman sınama türünü içermelidir redirect . Bu istek için değerinin içermesi oob redirectbeklenir.

Başarılı yanıt

Örnek:

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}

Parametre	Açıklama
continuation_token	Microsoft Entra'nın döndürdüğü devamlılık belirteci .

Bir uygulama Microsoft Entra tarafından gerekli bir kimlik doğrulama yöntemini destekleyemezse web tabanlı kimlik doğrulama akışına geri dönüş gerekir. Bu senaryoda Microsoft Entra, yanıtında bir yeniden yönlendirme sınama türü döndürerek uygulamayı bilgilendirmektedir:

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

{     
   "challenge_type": "redirect" 
} 

Parametre	Açıklama
challenge_type	Microsoft Entra, sınama türüne sahip bir yanıt döndürür. Bu sınama türünün değeri, uygulamanın web tabanlı kimlik doğrulama akışını kullanmasını sağlayan yeniden yönlendirmedir.

Bu yanıt başarılı olarak kabul edilir, ancak uygulamanın web tabanlı kimlik doğrulama akışına geçmesi gerekir. Bu durumda, Microsoft tarafından oluşturulmuş ve desteklenen bir kimlik doğrulama kitaplığı kullanmanızı öneririz.

Hata yanıtı

Örnek:

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

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
} 

Parametre	Açıklama
error	Hata türlerini sınıflandırmak ve hatalara tepki vermek için kullanılabilecek bir hata kodu dizesi.
error_description	Kimlik doğrulama hatasının nedenini belirlemenize yardımcı olabilecek belirli bir hata iletisi.
error_codes	Hataları tanılamanıza yardımcı olabilecek Microsoft Entra'ya özgü hata kodlarının listesi.
timestamp	Hatanın oluştuğu zaman.
trace_id	İstek için hataları tanılamanıza yardımcı olabilecek benzersiz bir tanımlayıcı.
correlation_id	bileşenler arasında tanılamada yardımcı olabilecek istek için benzersiz bir tanımlayıcı.

Karşılaşabileceğiniz olası hatalar şunlardır (parametrenin error olası değerleri):

Hata değeri	Açıklama
invalid_request	parametre geçersiz bir sınama türü içerdiğinde veya istek parametre içermediğinde challenge_typeclient_id istemci kimliği değerinin boş veya geçersiz olması gibi istek parametresi doğrulaması başarısız oldu. Hatanın error_description tam nedenini öğrenmek için parametresini kullanın.
user_not_found	Kullanıcı adı yok.
unsupported_challenge_type	challenge_type Parametre değeri sınama türünü içermezredirect.
invalid_client	Uygulamanın istekte içerdiği istemci kimliği, genel istemci olmadığı veya yerel kimlik doğrulaması için etkinleştirilmediği gibi yerel kimlik doğrulama yapılandırması olmayan bir uygulamaya yöneliktir. Hatanın suberror tam nedenini öğrenmek için parametresini kullanın.
unauthorized_client	İstekte kullanılan istemci kimliği geçerli bir istemci kimliği biçimine sahip, ancak dış kiracıda yok veya yanlış.

Hata parametresinin değeri invalid_client ise, Microsoft Entra yanıtına bir suberror parametre ekler. invalid_client hatası için parametrenin suberror olası değerleri şunlardır:

Alt değer	Açıklama
nativeauthapi_disabled	Yerel kimlik doğrulaması için etkinleştirilmemiş bir uygulamanın istemci kimliği.

2. Adım: Bir kimlik doğrulama yöntemi seçin

Akışa devam etmek için uygulama, microsoft Entra'dan kullanıcının kimlik doğrulaması için desteklenen sınama türlerinden birini seçmesini istemek için önceki adımdan alınan devamlılık belirtecini kullanır. Uygulama uç noktaya bir POST isteğinde bulunur /challenge . Bu istek başarılı olursa, Microsoft Entra kullanıcının hesap e-postasına tek seferlik bir geçiş kodu gönderir. Şu anda yalnızca OTP e-postasını destekliyoruz.

Aşağıda bir örnek verilmiştir (örnek isteği okunabilirlik için birden çok satırda sunuyoruz):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/challenge
Content-Type: application/x-www-form-urlencoded

client_id=client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob redirect
&continuation_token=uY29tL2F1dGhlbnRpY... 

Parametre	Zorunlu	Veri Akışı Açıklaması
tenant_subdomain	Yes	Oluşturduğunuz dış kiracının alt etki alanı. URL'de değerini Dizin (kiracı) alt etki alanıyla değiştirin {tenant_subdomain} . Örneğin, kiracınızın birincil etki alanı contoso.onmicrosoft.com ise contoso kullanın. Kiracı alt etki alanınız yoksa kiracınızın ayrıntılarını okumayı öğrenin.
client_id	Yes	Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği.
continuation_token	Yes	Microsoft Entra'nın önceki istekte döndürdüğü devamlılık belirteci .
challenge_type	Hayır	Uygulamanın desteklediği yetkilendirme sınama türü dizelerinin boşlukla ayrılmış listesi.oob redirect Liste her zaman sınama türünü içermelidir redirect . Bu istek için değerinin içermesi oob redirectbeklenir.

Başarılı yanıt

Örnek:

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "challenge_type": "oob",
    "binding_method": "prompt ", 
    "challenge_channel": "email",
    "challenge_target_label ": "c***r@co**o**o.com ",
    "code_length": 8
} 

Parametre	Açıklama
continuation_token	Microsoft Entra'nın döndürdüğü devamlılık belirteci .
challenge_type	Kullanıcının kimlik doğrulaması için seçilen sınama türü.
binding_method	Tek geçerli değer istemdir. Bu parametre gelecekte kullanıcıya tek seferlik geçiş kodunu girmenin daha fazla yolunu sunmak için kullanılabilir. Oob ise challenge_type verilir
challenge_channel	Tek seferlik geçiş kodunun gönderildiği kanalın türü. Şu anda e-postayı destekliyoruz.
challenge_target_label	Tek seferlik geçiş kodunun gönderildiği belirsiz bir e-posta.
code_length	Microsoft Entra'nın oluşturduğu tek seferlik geçiş kodunun uzunluğu.

Bir uygulama Microsoft Entra tarafından gerekli bir kimlik doğrulama yöntemini destekleyemezse web tabanlı kimlik doğrulama akışına geri dönüş gerekir. Bu senaryoda Microsoft Entra, yanıtında bir yeniden yönlendirme sınama türü döndürerek uygulamayı bilgilendirmektedir:

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

{     
   "challenge_type": "redirect" 
} 

Parametre	Açıklama
challenge_type	Microsoft Entra, sınama türüne sahip bir yanıt döndürür. Bu sınama türünün değeri, uygulamanın web tabanlı kimlik doğrulama akışını kullanmasını sağlayan yeniden yönlendirmedir.

Bu yanıt başarılı olarak kabul edilir, ancak uygulamanın web tabanlı kimlik doğrulama akışına geçmesi gerekir. Bu durumda, Microsoft tarafından oluşturulmuş ve desteklenen bir kimlik doğrulama kitaplığı kullanmanızı öneririz.

Hata yanıtı

Örnek:

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

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
} 

Parametre	Açıklama
error	Hata türlerini sınıflandırmak ve hatalara tepki vermek için kullanılabilecek bir hata kodu dizesi.
error_description	Kimlik doğrulama hatasının nedenini belirlemenize yardımcı olabilecek belirli bir hata iletisi.
error_codes	Hataları tanılamanıza yardımcı olabilecek Microsoft Entra'ya özgü hata kodlarının listesi.
timestamp	Hatanın oluştuğu zaman.
trace_id	İstek için hataları tanılamanıza yardımcı olabilecek benzersiz bir tanımlayıcı.
correlation_id	bileşenler arasında tanılamada yardımcı olabilecek istek için benzersiz bir tanımlayıcı.

Karşılaşabileceğiniz olası hatalar şunlardır (parametrenin error olası değerleri):

Hata değeri	Açıklama
invalid_request	Parametre geçersiz bir sınama türü içerdiğinde challenge_type veya devam belirteci doğrulaması başarısız olduğunda istek parametresi doğrulaması başarısız oldu.
expired_token	Devamlılık belirtecinin süresi doldu.
unsupported_challenge_type	challenge_type Parametre değeri sınama türünü içermezredirect.

3. Adım: Tek seferlik geçiş kodu gönderme

Ardından uygulama uç noktaya bir POST isteğinde bulunur /continue . İstekte, uygulamanın önceki adımda seçilen kullanıcının kimlik bilgilerini ve uç noktadan verilen devam belirtecini içermesi /challenge gerekir.

burada bir istek örneği verilmiştir (örnek isteği okunabilirlik için birden çok satırda sunuyoruz):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/continue
Content-Type: application/x-www-form-urlencoded

continuation_token=uY29tL2F1dGhlbnRpY... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=oob 
&oob={otp_code}

Parametre	Zorunlu	Veri Akışı Açıklaması
tenant_subdomain	Yes	Oluşturduğunuz dış kiracının alt etki alanı. URL'de değerini Dizin (kiracı) alt etki alanıyla değiştirin {tenant_subdomain} . Örneğin, kiracınızın birincil etki alanı contoso.onmicrosoft.com ise contoso kullanın. Kiracı alt etki alanınız yoksa kiracınızın ayrıntılarını okumayı öğrenin.
continuation_token	Yes	Microsoft Entra'nın önceki istekte döndürdüğü devamlılık belirteci .
client_id	Yes	Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği.
grant_type	Yes	Tek geçerli değer oob değeridir.
oob	Yes	Müşteri kullanıcısının e-postasında aldığı tek seferlik geçiş kodu. değerini, müşteri kullanıcısının e-postasında aldığı tek seferlik geçiş koduyla değiştirin {otp_code} . Tek seferlik geçiş kodunu yeniden göndermek için uygulamanın uç noktaya yeniden istekte /challenge bulunması gerekir.

Başarılı yanıt

Örnek:

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

{ 
    "expires_in": 600,
    "continuation_token": "czZCaGRSa3F0MzpnW...",
} 

Parametre	Açıklama
expires_in	continuation_token süresi dolmadan önceki saniye sayısı. En yüksek değer expires_in 600 saniyedir.
continuation_token	Microsoft Entra'nın döndürdüğü devamlılık belirteci .

Hata yanıtı

Örnek:

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

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS55200: The continuation_token is invalid.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        55200 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
} 

Parametre	Açıklama
error	Hata türlerini sınıflandırmak ve hatalara tepki vermek için kullanılabilecek bir hata kodu dizesi.
error_description	Kimlik doğrulama hatasının nedenini belirlemenize yardımcı olabilecek belirli bir hata iletisi.
error_codes	Hataları tanılamanıza yardımcı olabilecek Microsoft Entra'ya özgü hata kodlarının listesi.
timestamp	Hatanın oluştuğu zaman.
trace_id	İstek için hataları tanılamanıza yardımcı olabilecek benzersiz bir tanımlayıcı.
correlation_id	bileşenler arasında tanılamada yardımcı olabilecek istek için benzersiz bir tanımlayıcı.
suberror	Hata türlerini daha fazla sınıflandırmak için kullanılabilecek bir hata kodu dizesi.

Karşılaşabileceğiniz olası hatalar şunlardır (parametrenin error olası değerleri):

Hata değeri	Açıklama
invalid_request	Devamlılık belirtecinin doğrulanması başarısız olduğu veya isteğin parametre içermediğiclient_id, istemci kimliği değerinin boş veya geçersiz olduğu ya da dış kiracı yöneticisinin tüm kiracı kullanıcıları için SSPR ve e-posta OTP'yi etkinleştirmediği gibi istek parametresi doğrulaması başarısız oldu. Hatanın error_description tam nedenini öğrenmek için parametresini kullanın.
invalid_grant	Verme türü bilinmiyor veya beklenen verme türü değeriyle eşleşmiyor. Hatanın suberror tam nedenini öğrenmek için parametresini kullanın.
expired_token	Devamlılık belirtecinin süresi doldu.

Hata parametresinin değeri invalid_grant ise, Microsoft Entra yanıtına bir suberror parametre ekler. bir invalid_grant hatası için parametrenin suberror olası değerleri şunlardır:

Alt değer	Açıklama
invalid_oob_value	Kullanıcı tarafından sağlanan tek seferlik geçiş kodu geçersiz.

4. Adım: Yeni parola gönderme

Uygulama kullanıcıdan yeni bir parola toplar, ardından uç nokta tarafından /continue verilen devamlılık belirtecini kullanarak uç noktaya bir POST isteği /submit göndererek parolayı gönderir.

Aşağıda bir örnek verilmiştir (örnek isteği okunabilirlik için birden çok satırda sunuyoruz):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/submit
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&continuation_token=czZCaGRSa3F0Mzp...
&new_password={new_password}

Parametre	Zorunlu	Veri Akışı Açıklaması
tenant_subdomain	Yes	Oluşturduğunuz dış kiracının alt etki alanı. URL'de değerini Dizin (kiracı) alt etki alanıyla değiştirin {tenant_subdomain} . Örneğin, kiracınızın birincil etki alanı contoso.onmicrosoft.com ise contoso kullanın. Kiracı alt etki alanınız yoksa kiracınızın ayrıntılarını okumayı öğrenin.
continuation_token	Yes	Microsoft Entra'nın önceki istekte döndürdüğü devamlılık belirteci .
client_id	Yes	Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği.
new_password	Yes	Kullanıcının yeni parolası. yerine kullanıcının yeni parolasını yazın {new_password} . Uygulamanın kullanıcı arabiriminde parola onaylama alanını sağlayarak kullanıcının kullanmak istediği parolanın farkında olduğunu onaylamak sizin sorumluluğunuzdadır. Ayrıca, kullanıcının kuruluşunuzun ilkesine göre neyin güçlü bir parola oluşturduğunu anladığınızdan emin olmanız gerekir. Microsoft Entra'nın parola ilkeleri hakkında daha fazla bilgi edinin.

Başarılı yanıt

Örnek:

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "poll_interval": 2
}

Parametre	Açıklama
continuation_token	Microsoft Entra'nın döndürdüğü devamlılık belirteci .
poll_interval	Uygulamanın, uç nokta üzerinden /poll_completion parola sıfırlama isteğinin durumunu denetlemek için yoklama istekleri arasında beklemesi gereken saniye cinsinden minimum süre, bkz . 5. adım

Hata yanıtı

Örnek:

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

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
} 

Parametre	Açıklama
error	Hata türlerini sınıflandırmak ve hatalara tepki vermek için kullanılabilecek bir hata kodu dizesi.
error_description	Kimlik doğrulama hatasının nedenini belirlemenize yardımcı olabilecek belirli bir hata iletisi.
error_codes	Hataları tanılamanıza yardımcı olabilecek Microsoft Entra'ya özgü hata kodlarının listesi.
timestamp	Hatanın oluştuğu zaman.
trace_id	İstek için hataları tanılamanıza yardımcı olabilecek benzersiz bir tanımlayıcı.
correlation_id	bileşenler arasında tanılamada yardımcı olabilecek istek için benzersiz bir tanımlayıcı.
suberror	Hata türlerini daha fazla sınıflandırmak için kullanılabilecek bir hata kodu dizesi.

Karşılaşabileceğiniz olası hatalar şunlardır (parametrenin error olası değerleri):

Hata değeri	Açıklama
invalid_request	İstek parametresi doğrulaması başarısız oldu, örneğin devamlılık belirtecinin doğrulanması başarısız oldu.
expired_token	Devamlılık belirtecinin süresi doldu.
invalid_grant	Gönderilen izin geçersiz, örneğin gönderilen parola çok kısa. Hatanın suberror tam nedenini öğrenmek için parametresini kullanın.

Hata parametresinin değeri invalid_grant ise, Microsoft Entra yanıtına bir suberror parametre ekler. Parametresinin olası değerleri suberror şunlardır:

Alt değer	Açıklama
password_too_weak	Karmaşıklık gereksinimlerini karşılamadığından parola çok zayıf. Microsoft Entra'nın parola ilkeleri hakkında daha fazla bilgi edinin.
password_too_short	Yeni parola 8 karakterden azdır. Microsoft Entra'nın parola ilkeleri hakkında daha fazla bilgi edinin.
password_too_long	Yeni parola 256 karakterden uzun. Microsoft Entra'nın parola ilkeleri hakkında daha fazla bilgi edinin.
password_recently_used	Yeni parola, yakın zamanda kullanılan parolayla aynı olmamalıdır. Microsoft Entra'nın parola ilkeleri hakkında daha fazla bilgi edinin.
password_banned	Yeni parola, yasaklanmış bir sözcük, tümcecik veya desen içerir. Microsoft Entra'nın parola ilkeleri hakkında daha fazla bilgi edinin.
password_is_invalid	Parola geçersiz, örneğin izin verilmeyen karakterler kullandığından. Microsoft Entra'nın parola ilkeleri hakkında daha fazla bilgi edinin. Uygulama bir kullanıcı parolası gönderirse bu yanıt mümkündür.

5. Adım: Parola sıfırlama durumunu yoklama

Son olarak, kullanıcının yapılandırmasının yeni parolayla güncelleştirilmesi biraz gecikmeye neden olduğundan uygulama, parola sıfırlama durumu için Microsoft Entra'yı yoklama amacıyla uç noktayı kullanabilir /poll_completion . Uygulamanın yoklama istekleri arasında beklemesi gereken saniye cinsinden minimum süre, parametresindeki /submitpoll_interval uç noktadan döndürülür.

Aşağıda bir örnek verilmiştir (örnek isteği okunabilirlik için birden çok satırda sunuyoruz):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/poll_completion
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&continuation_token=czZCaGRSa3F0... 

Parametre	Zorunlu	Veri Akışı Açıklaması
tenant_subdomain	Yes	Oluşturduğunuz dış kiracının alt etki alanı. URL'de değerini Dizin (kiracı) alt etki alanıyla değiştirin {tenant_subdomain} . Örneğin, kiracınızın birincil etki alanı contoso.onmicrosoft.com ise contoso kullanın. Kiracı alt etki alanınız yoksa kiracınızın ayrıntılarını okumayı öğrenin.
continuation_token	Yes	Microsoft Entra'nın önceki istekte döndürdüğü devamlılık belirteci .
client_id	Yes	Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği.

Başarılı yanıt

Örnek:

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

{
    "status": "succeeded",
    "continuation_token":"czZCaGRSa3F0..."
} 

Parametre	Açıklama
status	Parola sıfırlama isteğinin durumu. Microsoft Entra başarısız durumunu döndürürse, uygulama uç noktaya başka bir istekte /submit bulunarak yeni parolayı yeniden gönderebilir ve yeni devamlılık belirtecini ekleyebilir.
continuation_token	Microsoft Entra'nın döndürdüğü devamlılık belirteci . Durum başarılı olursa uygulama, Microsoft Entra'nın kayıt akışının 5. adımında açıklandığı gibi uç nokta üzerinden /token güvenlik belirteçleri istemek için döndürdüğü devamlılık belirtecini kullanabilir. Bu, kullanıcı parolasını başarıyla sıfırladıktan sonra yeni bir oturum açma akışı başlatmadan doğrudan uygulamanızda oturum açabileceğiniz anlamına gelir.

Microsoft Entra'nın döndürdüğü olası durumlar (parametrenin status olası değerleri):

Hata değeri	Açıklama
succeeded	Parola sıfırlama başarıyla tamamlandı.
failed	Parola sıfırlama başarısız oldu. Uygulama, uç noktaya başka bir istekte bulunarak yeni parolayı /submit yeniden gönderebilir.
not_started	Parola sıfırlama başlatılmadı. Uygulama daha sonra durumu yeniden denetleyebiliyor.
in_progress	Parola sıfırlama işlemi devam ediyor. Uygulama daha sonra durumu yeniden denetleyebiliyor.

Hata yanıtı

Örnek:

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

{ 
    "error": "expired_token", 
    "error_description": "AADSTS901007: The continuation_token is expired.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        552003 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
} 

Parametre	Açıklama
error	Hata türlerini sınıflandırmak ve hatalara tepki vermek için kullanılabilecek bir hata kodu dizesi.
error_description	Kimlik doğrulama hatasının nedenini belirlemenize yardımcı olabilecek belirli bir hata iletisi.
error_codes	Hataları tanılamanıza yardımcı olabilecek Microsoft Entra'ya özgü hata kodlarının listesi.
timestamp	Hatanın oluştuğu zaman.
trace_id	İstek için hataları tanılamanıza yardımcı olabilecek benzersiz bir tanımlayıcı.
correlation_id	bileşenler arasında tanılamada yardımcı olabilecek istek için benzersiz bir tanımlayıcı.

Karşılaşabileceğiniz olası hatalar şunlardır (parametrenin error olası değerleri):

Hata değeri	Açıklama
invalid_request	İstek parametresi doğrulaması, devam belirtecinin doğrulanması gibi başarısız oldu.
expired_token	Devamlılık belirtecinin süresi doldu.

Sonraki adımlar

• Yerel kimlik doğrulama e-postası OTP API başvurusu.