Microsoft kimlik platformu ve örtülü onay akışı

  • Makale
  • Okumak için 10 dakika

Bu Microsoft kimlik platformu, OAuth 2.0 Belirtimi'ne açıklandığı gibi OAuth 2.0Örtülü Onay akışını destekler. Örtülü iznin tanımlama özelliği, belirteçlerin (kimlik belirteçleri veya erişim belirteçleri) /token uç noktası yerine doğrudan /authorize uç noktası üzerinden döndürülmeleridir. Bu genellikle yetkilendirme kodu akışının bir parçası olarak kullanılır. Bu, yetkilendirme koduyla birlikte /authorize isteğinde kimlik belirteci alınırken "karma akış" olarak da kullanılır.

Bu makalede, Azure AD 'den belirteç istemek için uygulamanızdaki protokolde doğrudan programlanın nasıl yapılacağı açıklanır. Mümkün olduğunda, belirteçleri edinmek ve güvenli Web API 'lerini çağırmakIçin desteklenen Microsoft kimlik doğrulama KITAPLıKLARıNı (msal) kullanmanızı öneririz. Ayrıca , msal kullanan örnek uygulamalaragöz atın.

İpucu

Bu isteği Postman 'da çalıştırmayı deneyin
Bu isteği ve daha fazlasını Postman 'da yürütmeyi deneyin; belirteçleri ve kimlikleri değiştirmeyi unutmayın!

Kimlik doğrulama kod akışını tercih

Üçüncü taraf tanımlama bilgilerinin tarayıcılardan kaldırılması planlarında,örtülü onay akışı artık uygun bir kimlik doğrulama yöntemi değildir. Örtülü akışın sessiz SSO özellikleri üçüncü taraf tanımlama bilgileri olmadan çalışmaz ve uygulamaların yeni bir belirteç almaya çalışırken bozmasına neden olur. Tüm yeni uygulamaların artık örtülü akış yerine tek sayfalı uygulamaları destekleyen yetkilendirme kodu akışını kullanmalarını ve mevcut tek sayfalı uygulamaların da yetkilendirme kod akışına da devam etmek zorunda olduğunu öneririz.

OAuth2 örtülü izni için uygun senaryolar

Örtülü izin, yalnızca oturum açma akışınıza ait ilk ve etkileşimli kısım için güvenilirdir ve üçüncü taraf tanımlama bilgilerinin eksik olması, uygulamanızı etkileyene bir şey değildir. Bu sınırlama, bunu yalnızca karma akışın bir parçası olarak kullanmanız gerektiği anlamına gelir. Burada, uygulamanız yetkilendirme uç noktasına bir kod ve belirteç talep eder. Bu, uygulamanıza yenileme belirteci için kullanıla bir kod aldığından, böylece uygulama oturum açma oturumunun zaman içinde geçerli kalmasını sağlar.

Protokol diyagramı

Aşağıdaki diyagramda, örtülü oturum açma akışının tamamının nasıl olduğu ve sonraki bölümlerde her adımın daha ayrıntılı bir şekilde açıklanmaktadır.

Örtülü oturum açma akışını gösteren diyagram

Oturum açma isteğini gönderme

Kullanıcıyı uygulamanıza başlangıçta oturum açmak için bir OpenID kimlik doğrulaması isteği Bağlan ve kullanıcı arabiriminden bir id_token Microsoft kimlik platformu.

Önemli

Kimlik belirteci ve/veya erişim belirteci başarıyla isteğinde bulununca, Azure portal - Uygulama kayıtları sayfasındaki uygulama kaydında, Örtülü onay ve karma akışlar bölümünde kimlik belirteçleri ve erişim belirteçleri seçerek ilgili örtülü izin akışı etkinleştirilmelidir. Etkinleştirilmemişse bir hata unsupported_response döndürülür: The provided value for the input parameter 'response_type' is not allowed for this client. Expected value is 'code'

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=openid
&response_mode=fragment
&state=12345
&nonce=678910

İpucu

Örtülü akışı kullanarak oturum açma test etmek için'e https://login.microsoftonline.com/common/oauth2/v2.0/authorize.. tıklayın. Oturum açmanın ardından, tarayıcınızın adres https://localhost/myapp/ çubuğundaki ile id_token adresine yönlendirilmesi gerekir.

Parametre Tür Description
tenant gerekli {tenant}İstek yolundaki değer, uygulamada kimlerin oturum açmasını kontrol etmek için kullanılabilir. İzin verilen değerler common , , ve kiracı organizations consumers tanımlayıcılarıdır. Daha fazla ayrıntı için protokol temel bilgilerine bakın. Kritik olarak, bir kullanıcıyı bir kiracıdan başka bir kiracıya imzaladığınız konuk senaryolarında, bunları kaynak kiracıda doğru şekilde oturum açması için kiracı tanımlayıcısını sağlamanız gerekir.
client_id gerekli Uygulamanıza atanan uygulama (Azure portal - Uygulama kayıtları uygulama (istemci) kimliği.
response_type gerekli Oturum açma id_token için OpenID Bağlan içermesi gerekir. Ayrıca, token response_type. Burada kullanmak, yetkilendirme uç noktasına ikinci bir istekte olmak zorunda kalmadan, uygulamanın yetkilendirme uç noktasına hemen bir erişim token belirteci almalarına olanak sağlar. response_type kullanırsanız, parametresi belirteci hangi kaynağın token scope (örneğin, Microsoft Graph'de user.read) vermek üzere belirteci belirten bir kapsam Graph. Yetkilendirme kodu code akışında kullanmak üzere yetkilendirme kodu sağlamak için yerine token de içerebilir. Bu id_token+kod yanıtı bazen karma akış olarak da adlandırılan bir durumdur.
redirect_uri Önerilen Uygulama redirect_uri, burada kimlik doğrulama yanıtları gönderebilirsiniz ve uygulama tarafından alınabilirsiniz. Portalda kayıtlı redirect_uris tam olarak eşleşmesi gerekir, ancak URL ile kodlanmış olmalıdır.
scope gerekli Kapsamların boşlukla ayrılmış listesi. OpenID Bağlan (id_tokens), onay kullanıcı arabiriminde openid "Oturum aç" iznine çevrilen kapsamını içermesi gerekir. İsteğe bağlı olarak, ek kullanıcı verilerine email erişim elde etmek için ve profile kapsamlarını da dahil etmek istemeyebilirsiniz. Erişim belirteci istense, çeşitli kaynaklara onay isteğinde için bu istekte başka kapsamlar da dahil edilebilir.
response_mode isteğe bağlı Elde edilen belirteci uygulamanıza geri göndermek için kullanılacak yöntemi belirtir. Varsayılan olarak yalnızca bir erişim belirteci sorgular, ancak istek bir erişim belirteci id_token.
state Önerilen İstekte bulunan ve belirteç yanıtta da döndürülecek bir değer. Bu, istediğiniz herhangi bir içeriğin dizesi olabilir. Rastgele oluşturulan benzersiz bir değer genellikle siteler arası istek sahtecilik saldırılarını önlemek için kullanılır. Durum, kimlik doğrulama isteği olmadan önce kullanıcının uygulama durumuyla ilgili bilgileri kodlamak için de kullanılır(örneğin, sayfa veya bunların açık olduğu görünüm).
nonce gerekli İstekte yer alan ve uygulama tarafından oluşturulan ve sonuçta elde edilen değere talep olarak id_token değer. Uygulama daha sonra belirteç yeniden yürütme saldırılarını azaltmak için bu değeri doğrular. Değer genellikle isteğin kaynağını tanımlamak için kullanılan rastgele, benzersiz bir dizedir. Yalnızca bir id_token gereklidir.
prompt isteğe bağlı Gerekli kullanıcı etkileşimi türünü gösterir. Şu anda geçerli olan tek değerler 'login', 'none', 'select_account' ve 'consent' değerleridir. prompt=login , kullanıcıya bu istekte kimlik bilgilerini girmeye zorlar ve çoklu oturum açma olumsuz olur. prompt=none tam tersidir; kullanıcının herhangi bir etkileşimli istem ile karşı karşıya olmadığını garantiler. İstek çoklu oturum açma yoluyla sessiz bir şekilde tamamlanamadı Microsoft kimlik platformu hata döndürür. prompt=select_account , oturumda hatırlanan tüm hesapların görünt olduğu bir hesap seçiciye kullanıcı gönderir. prompt=consent , kullanıcı oturum açtırarak kullanıcıdan uygulamaya izinler verilmesini isteyen OAuth onay iletişim kutusunu tetikler.
login_hint isteğe bağlı Kullanıcı adını önceden biliyorsanız, kullanıcının oturum açma sayfasının kullanıcı adı ve e-posta adresi alanını önceden doldurmak için bu parametreyi kullanabilirsiniz. Uygulamalar genellikle, daha önceki bir oturum açmadan isteğe bağlı talebi ayıkladikten sonra yeniden kimlik doğrulaması login_hint sırasında bu parametreyi kullanır.
domain_hint isteğe bağlı Dahil edilirse, kullanıcının oturum açma sayfasından geçen e-posta tabanlı bulma işlemi atlar ve bu da biraz daha kolay bir kullanıcı deneyimine yol alır. Bu parametre genellikle tek bir kiracıda çalışan ve kullanıcıyı ilgili kiracı için federasyon sağlayıcısına iletecekleri bir kiracı içinde bir etki alanı adı sağlayacakları İş Hattı uygulamaları için kullanılır. Bu ipucunun konukların bu uygulamada oturum açmasını engellemektedir ve FIDO gibi bulut kimlik bilgilerinin kullanımını sınırlar.

Bu noktada kullanıcıdan kimlik bilgilerini girmeleri ve kimlik doğrulamasını tamamlamaları istenir. Bu Microsoft kimlik platformu, kullanıcının sorgu parametresinde belirtilen izinleri onaylamış olmasını scope da sağlar. Kullanıcı bu izinlerden hiçbirini kabul ettiyse, kullanıcıdan gerekli izinlere onay istemesi gerekir. Daha fazla bilgi için bkz. izinler, onay ve çok kiracılı uygulamalar.

Kullanıcı kimlik doğrulaması ve onay verdi Microsoft kimlik platformu parametresinde belirtilen yöntemi kullanarak uygulamanıza bir redirect_uri yanıt response_mode geri döner.

Başarılı yanıt

ve kullanarak başarılı bir response_mode=fragment response_type=id_token+code yanıt aşağıdakine benzer (okunaklılık için satır sonları ile):

GET https://localhost/myapp/#
code=0.AgAAktYV-sfpYESnQynylW_UKZmH-C9y_G1A
&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
&state=12345
Parametre Açıklama
code varsa dahil response_type code edilir. Bu, yetkilendirme kodu akışında kullanmak için uygun bir yetkilendirme kodudur.
access_token varsa dahil response_type token edilir. Uygulamanın istenen erişim belirteci. Erişim belirteci kodunun çözülmesi veya başka bir şekilde denetlenmesi gerekir. Bu, opak bir dize olarak kabul edilmelidir.
token_type varsa dahil response_type token edilir. Her zaman Bearer olur.
expires_in varsa dahil response_type token edilir. Önbelleğe alma amacıyla belirteci kaç saniye geçerli olduğunu gösterir.
scope varsa dahil response_type token edilir. Uygulamanın geçerli olduğu kapsamları access_token gösterir. Kullanıcı için geçerli olmayan tüm kapsamları (oturum açmak için kişisel bir hesap kullanılırken yalnızca Azure AD kapsamlarının isten ediyor olması durumunda) dahil etmek zorunda değildir.
id_token İmzalı JSON Web Token (JWT). Uygulama, oturum açan kullanıcı hakkında bilgi isteğinde olmak için bu belirteci segmentlerinin kodunu çözebilirsiniz. Uygulama, değerleri önbelleğe alıp görüntüler ancak herhangi bir yetkilendirme veya güvenlik sınırı için bu değerlere güvenmemelidir. Daha fazla bilgi id_tokens bkz. id_token reference .
Not: Yalnızca kapsam istenen openid ve dahil edildiyse response_type id_tokens sağlanır.
state İsteğe bir durum parametresi dahil edilir, yanıtta aynı değer görünmelidir. Uygulama, istek ve yanıtta durum değerlerinin özdeş olduğunu doğrulamalıdır.

Uyarı

Kodunuzda bu örnekteki belirteçler de dahil olmak üzere sahip olmadığınız API 'leri doğrulamaya veya okumayı denemeyin. Microsoft hizmetleri belirteçleri, JWT olarak doğrulanmayacak özel bir biçim kullanabilir ve tüketici (Microsoft hesabı) kullanıcıları için de şifrelenebilir. Belirteçleri okurken faydalı bir hata ayıklama ve öğrenme aracı olsa da, kodunuzda bu şekilde bağımlılıklar kullanmayın veya kontrol ettiğiniz bir API için olmayan belirteçlerin özelliklerini varsayın.

Hata yanıtı

Ayrıca, redirect_uri uygulamanın bunları uygun şekilde işleyebilmesi için hata yanıtları da gönderilebilir.

GET https://localhost/myapp/#
error=access_denied
&error_description=the+user+canceled+the+authentication
Parametre Açıklama
error Oluşan hata türlerini sınıflandırmak için kullanılabilen ve hatalara yanıt vermek için kullanılabilen bir hata kodu dizesi.
error_description Bir geliştiricinin kimlik doğrulama hatasının kök nedenini belirlemesine yardımcı olabilecek belirli bir hata iletisi.

Arka planda sessizce erişim belirteçleri alma

Önemli

Örtük akışın bu bölümü, üçüncü taraf tanımlama bilgilerinin varsayılan olarak kaldırılmasınedeniyle farklı tarayıcılarda kullanıldığı için uygulamanız için büyük olasılıkla çalışmayabilir. bu, hala kullanım dışı olmayan Chromium tabanlı tarayıcılarda çalışırken, geliştiricilerin akışın bu bölümünü kullanmayı yeniden düşünmelidir. Üçüncü taraf tanımlama bilgilerini desteklemeyen tarayıcılarda, oturum açma sayfasının oturum tanımlama bilgileri tarayıcı tarafından kaldırıldığı için hiçbir kullanıcının oturum açmadığını belirten bir hata alırsınız.

artık kullanıcıyı tek sayfalı uygulamanıza imzaladığınıza göre, Microsoft Graphgibi Microsoft kimlik platformu tarafından güvenliği sağlanmış web apı 'lerini çağırmaya sessizce erişim belirteçleri alabilirsiniz. Response_type kullanarak zaten bir belirteç almış olsanız bile token , kullanıcıyı yeniden oturum açmak üzere yeniden yönlendirmek zorunda kalmadan ek kaynaklara belirteç almak için bu yöntemi kullanabilirsiniz.

normal openıd Bağlan/oauth flow 'da, bunu Microsoft kimlik platformu uç noktasına bir istek yaparak yapabilirsiniz /token . Diğer Web API 'Lerine yönelik yeni belirteçleri almak için isteği gizli bir iframe 'de yapabilirsiniz:

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fuser.read
&response_mode=fragment
&state=12345
&nonce=678910
&prompt=none
&login_hint=myuser@mycompany.com

URL 'deki sorgu parametreleriyle ilgili ayrıntılar için bkz. oturum açma isteğini gönderme.

İpucu

Aşağıdaki isteği bir tarayıcı sekmesine yapıştırmayı & kopyalamayı deneyin! ( login_hint Değerleri, Kullanıcı için doğru değerle değiştirmeyi unutmayın)

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=6731de76-14a6-49ae-97bc-6eba6914391e&response_type=token&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F&scope=https%3A%2F%2Fgraph.microsoft.com%2Fuser.read&response_mode=fragment&state=12345&nonce=678910&prompt=none&login_hint={your-username}

Bunu bir iframe içinde açmak yerine doğrudan bir tarayıcı çubuğuna girtiğinizden, bu, üçüncü taraf tanımlama bilgisi desteği olmayan tarayıcılarda bile çalışacaktır.

prompt=noneBu parametre sayesinde, bu istek hemen başarılı veya başarısız olur ve uygulamanıza geri döner. Yanıt, redirect_uri parametresinde belirtilen yöntemi kullanılarak, belirtilen şekilde uygulamanıza gönderilir response_mode .

Başarılı yanıt

Kullanarak başarılı bir yanıt response_mode=fragment şöyle görünür:

GET https://localhost/myapp/#
access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
&state=12345
&token_type=Bearer
&expires_in=3599
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fdirectory.read
Parametre Açıklama
access_token Dahil ise response_type dahildir token . Uygulamanın istediği erişim belirteci, Microsoft Graph için bu durumda. Erişim belirtecinin kodu çözülemedi veya bunun için bir donuk dize olarak değerlendirilmemelidir.
token_type Her zaman olacak Bearer .
expires_in Önbelleğe alma amacıyla belirtecin geçerli olduğu saniye sayısını gösterir.
scope Access_token geçerli olacağı kapsam (ler) i gösterir. Kullanıcı için geçerli olmadıklarında istenen tüm kapsamları içermeyebilir (oturum açmak için bir kişisel hesap kullanıldığında yalnızca Azure AD kapsamları isteniyorsa).
id_token İmzalı bir JSON Web Token (JWT). Dahil ise response_type dahildir id_token . Uygulama, oturum açan kullanıcı hakkında bilgi istemek için bu belirtecin segmentlerinin kodunu çözebilir. Uygulama, değerleri önbelleğe alabilir ve görüntüleyebilir, ancak herhangi bir yetkilendirme veya güvenlik sınırları için bu değere güvenmemelidir. İd_tokens hakkında daha fazla bilgi için bkz. id_token başvuru.
Note: Yalnızca openid kapsam isteniyorsa sağlandı.
state İsteğe bir durum parametresi dahil edilir, yanıtta aynı değer görünmelidir. Uygulama, istek ve yanıtta durum değerlerinin özdeş olduğunu doğrulamalıdır.

Hata yanıtı

Ayrıca, redirect_uri uygulamanın bunları uygun şekilde işleyebilmesi için hata yanıtları da gönderilebilir. prompt=noneBu durumda, beklenen bir hata şu şekilde olur:

GET https://localhost/myapp/#
error=user_authentication_required
&error_description=the+request+could+not+be+completed+silently
Parametre Açıklama
error Oluşan hata türlerini sınıflandırmak için kullanılabilen ve hatalara yanıt vermek için kullanılabilen bir hata kodu dizesi.
error_description Bir geliştiricinin kimlik doğrulama hatasının kök nedenini belirlemesine yardımcı olabilecek belirli bir hata iletisi.

İframe isteğinde bu hatayı alırsanız, Kullanıcı yeni bir belirteci almak için etkileşimli olarak yeniden oturum açması gerekir. Bu durumu uygulamanız için anlamlı hale getiren her türlü şekilde yapmayı tercih edebilirsiniz.

Belirteçleri yenileme

Örtük izin yenileme belirteçleri sağlamıyor. Her iki id_token s ve access_token s kısa bir süre sonra sona erer, bu nedenle uygulamanızın bu belirteçleri düzenli aralıklarla yenilemeye hazırlanması gerekir. Her iki tür belirteci de yenilemek için, prompt=none kimlik platformunun davranışını denetlemek üzere parametresini kullanarak yukarıdaki aynı gizli iframe isteğini de gerçekleştirebilirsiniz. Yeni bir almak istiyorsanız, id_token id_token ve ' de ' de kullandığınızdan emin olun response_type scope=openid nonce .

Üçüncü taraf tanımlama bilgilerini desteklemeyen tarayıcılarda bu, kullanıcının oturum açmadığını belirten bir hatayla sonuçlanır.

Oturum kapatma isteği gönder

openıd Bağlan, end_session_endpoint uygulamanızın bir kullanıcının oturumunu sona erdirmek ve Microsoft kimlik platformu tarafından ayarlanan tanımlama bilgilerini temizlemek için Microsoft kimlik platformu bir istek göndermesini sağlar. Bir kullanıcıyı bir Web uygulamasından tam olarak imzalamak için, uygulamanız kullanıcıyla kendi oturumunu sonlandırmalıdır (genellikle bir belirteç önbelleğini temizleyerek veya tanımlama bilgilerini bırakarak) ve ardından tarayıcıyı şuraya yönlendirmelidir:

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/logout?post_logout_redirect_uri=https://localhost/myapp/
Parametre Tür Description
tenant gerekli {tenant}İsteğin yolundaki değeri, uygulamada kimlerin oturum açmasını denetlemek için kullanılabilir. İzin verilen değerler, common , organizations consumers ve kiracı tanımlayıcılarıdır. Daha fazla ayrıntı için bkz. protokol temelleri.
post_logout_redirect_uri Önerilen Oturum kapatma tamamlandıktan sonra kullanıcının geri döndürülmesi gereken URL. Bu değer, uygulama için kaydedilmiş yeniden yönlendirme URI 'lerinden biriyle aynı olmalıdır. dahil edilmezse, kullanıcı Microsoft kimlik platformu tarafından genel bir ileti gösterilir.

Sonraki adımlar