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/macOS 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
Microsoft Entra dış kiracısı. Henüz bir kiracınız yoksa bir dış kiracı oluşturun.
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.
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 olduğundan, gerektiği gibi yapılandırdığınız kullanıcı özniteliklerini not alın.
Uygulama kaydınızı kullanıcı akışıyla ilişkilendirin.
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.
SSPR akışı için dış kiracıdaki 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/continue
ve /token
olmak üzere dört uç noktayla etkileşim kurar/signup/v1.0/start
.
Kaydolma API'leri uç noktaları
Bitiş noktası | 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 | Gerekli | Açıklama |
---|---|---|
tenant_subdomain |
Evet | 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 |
Evet | Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği. |
username |
Evet | Kaydolmak istediği müşteri kullanıcısının e-posta adresi, örneğin contoso-consumer@contoso.com. |
challenge_type |
Evet | 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
1003037
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
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 | Gerekli | Açıklama |
---|---|---|
tenant_subdomain |
Evet | 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 |
Evet | 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 |
Evet | 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
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 | Gerekli | Açıklama |
---|---|---|
tenant_subdomain |
Evet | 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 |
Evet | Microsoft Entra'nın önceki istekte döndürdüğü devamlılık belirteci . |
client_id |
Evet | Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği. |
grant_type |
Evet | 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 |
Evet | 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/start baş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. |
Yanıt
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 | Gerekli | Açıklama |
---|---|---|
tenant_subdomain |
Evet | 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 |
Evet | 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 redirect beklenir. |
continuation_token |
Evet | 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 | Gerekli | Açıklama |
---|---|---|
tenant_subdomain |
Evet | 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 |
Evet | Microsoft Entra'nın önceki adımda döndürdüğü devamlılık belirteci . |
client_id |
Evet | Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği. |
grant_type |
Evet | 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 |
Evet | 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_type olası 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": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd",
"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 | Gerekli | Açıklama |
---|---|---|
tenant_subdomain |
Evet | 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 |
Evet | Microsoft Entra'nın önceki istekte döndürdüğü devamlılık belirteci . |
client_id |
Evet | Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği. |
grant_type |
Evet | 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 |
Evet | 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
552003
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
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 | Gerekli | Açıklama |
---|---|---|
tenant_subdomain |
Evet | 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 |
Evet | Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği. |
grant_type |
Evet | Parametre değeri devamlılık belirteci olmalıdır. |
continuation_token |
Evet | Microsoft Entra'nın önceki adımda döndürdüğü devamlılık belirteci . |
scope |
Evet | 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 |
Evet | 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
50126
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
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.
Bitiş noktası | Gerekli öznitelikler | İsteğe bağlı öznitelikler | Hem gerekli hem de isteğe bağlı öznitelikler |
---|---|---|---|
/signup/v1.0/start bitiş noktası |
Evet | Evet | Evet |
/signup/v1.0/continue kullanıcı adı doğrulamadan önceki uç nokta |
Evet | Evet | Evet |
/signup/v1.0/continue kullanıcı adı doğrulaması sonrasında uç nokta |
Evet | Hayır | 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
/token
olmak üzere üç uç noktayla etkileşim kurar/initiate
.
Oturum açma API'leri uç noktaları
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.
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.
İ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 | Gerekli | Açıklama |
---|---|---|
tenant_subdomain |
Evet | 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 |
Evet | Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği. |
username |
Evet | Gibi contoso-consumer@contoso.commüşteri kullanıcısının e-postası. |
challenge_type |
Evet | 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
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 | Gerekli | Açıklama |
---|---|---|
tenant_subdomain |
Evet | 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 |
Evet | Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği. |
continuation_token |
Evet | 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
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. |
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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
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 | Gerekli | Açıklama |
---|---|---|
tenant_subdomain |
Evet | 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 |
Evet | Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği. |
continuation_token |
Evet | Microsoft Entra'nın önceki istekte döndürdüğü devamlılık belirteci . |
grant_type |
Evet | 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 |
Evet | 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
50126
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
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:
Bitiş noktası | 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 | Gerekli | Açıklama |
---|---|---|
tenant_subdomain |
Evet | 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 |
Evet | Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği. |
username |
Evet | Gibi contoso-consumer@contoso.commüşteri kullanıcısının e-postası. |
challenge_type |
Evet | 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 redirect beklenir. |
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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
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_type 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. |
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 | Gerekli | Açıklama |
---|---|---|
tenant_subdomain |
Evet | 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 |
Evet | Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği. |
continuation_token |
Evet | 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 redirect beklenir. |
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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
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 | Gerekli | Açıklama |
---|---|---|
tenant_subdomain |
Evet | 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 |
Evet | Microsoft Entra'nın önceki istekte döndürdüğü devamlılık belirteci . |
client_id |
Evet | Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği. |
grant_type |
Evet | Tek geçerli değer oob değeridir. |
oob |
Evet | 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
55200
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
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 | Gerekli | Açıklama |
---|---|---|
tenant_subdomain |
Evet | 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 |
Evet | Microsoft Entra'nın önceki istekte döndürdüğü devamlılık belirteci . |
client_id |
Evet | Microsoft Entra yönetim merkezine kaydettiğiniz uygulamanın Uygulama (istemci) kimliği. |
new_password |
Evet | 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
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 /submit
poll_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 | Gerekli | Açıklama |
---|---|---|
tenant_subdomain |
Evet | 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 |
Evet | Microsoft Entra'nın önceki istekte döndürdüğü devamlılık belirteci . |
client_id |
Evet | 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
552003
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
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. |
İlgili içerik
- Özel talep sağlayıcısı yapılandırma.