Microsoft kimlik platformu ve OAuth 2.0 örtük izin akışı

  • Makale

Microsoft kimlik platformu, OAuth 2.0 Belirtiminde açıklandığı gibi OAuth 2.0 örtük izin akışını destekler. Örtük vermenin tanımlayıcı özelliği, belirteçlerin (kimlik belirteçleri veya erişim belirteçleri) /token uç noktası yerine doğrudan /authorize uç noktasından döndürülür. Bu genellikle yetkilendirme kodu akışının bir parçası olarak kullanılır ve "karma akış" olarak adlandırılır. Kimlik belirtecini bir yetkilendirme koduyla birlikte /authorize isteğinde alır.

Bu makalede, Microsoft Entra Id'den belirteç istemek için uygulamanızdaki protokole karşı doğrudan programlama açıklanmaktadır. Mümkün olduğunda, belirteçleri almak ve güvenli web API’lerini aramak yerine desteklenen Microsoft Kimlik Doğrulama Kitaplıklarını (MSAL) kullanmanızı öneririz. Ayrıca MSAL kullanan örnek uygulamalara da göz atın.

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

Tarayıcılardan üçüncü taraf tanımlama bilgilerini kaldırma planlarıyla, örtük verme akışı artık uygun bir kimlik doğrulama yöntemi değildir. Örtük akışın sessiz çoklu oturum açma (SSO) özellikleri üçüncü taraf tanımlama bilgileri olmadan çalışmaz ve yeni bir belirteç almaya çalıştıklarında uygulamaların bozulmasına neden olur. Tüm yeni uygulamaların örtük akış yerine artık tek sayfalı uygulamaları destekleyen yetkilendirme kodu akışını kullanmasını kesinlikle öneririz. Mevcut tek sayfalı uygulamalar da yetkilendirme kodu akışına geçirilmelidir.

OAuth2 örtük izni için uygun senaryolar

Örtük izin, üçüncü taraf tanımlama bilgilerinin olmamasının uygulamanızı etkilemediği oturum açma akışınızın yalnızca ilk, etkileşimli bölümü için güvenilirdir. Bu sınırlama, bunu yalnızca uygulamanızın yetkilendirme uç noktasından bir kodun yanı sıra belirteç istediği karma akışın bir parçası olarak kullanmanız gerektiği anlamına gelir. Karma akışta uygulamanız yenileme belirteci için kullanılabilecek bir kod alır ve böylece uygulamanızın oturum açma oturum açma oturumlarının zaman içinde geçerli kalmasını sağlar.

Protokol diyagramı

Aşağıdaki diyagramda örtük oturum açma akışının tamamının nasıl göründüğü ve izleyen bölümlerde her adım ayrıntılı olarak açıklanmaktadır.

Diagram showing the implicit sign-in flow

Oturum açma isteğini gönderme

Kullanıcıyı başlangıçta uygulamanızda oturum açmak için bir OpenID Bağlan kimlik doğrulama isteği gönderebilir ve Microsoft kimlik platformu'ndan bir id_token alabilirsiniz.

Önemli

Kimlik belirtecini ve/veya erişim belirtecini başarıyla istemek için, Microsoft Entra yönetim merkezi - Uygulama kayıtları sayfasındaki uygulama kaydında, Örtük izin ve karma akışlar bölümünde Kimlik belirteçleri ve erişim belirteçleriseçilerek ilgili örtük izin akışı etkinleştirilmelidir. Etkinleştirilmemişse bir unsupported_response hata 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=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=openid
&response_mode=fragment
&state=12345
&nonce=678910
Parametre Tür Açıklama
tenant gerekli {tenant} İstek yolundaki değer, uygulamada kimlerin oturum açabileceğini denetlemek için kullanılabilir. İzin verilen değerler , organizations, consumersve kiracı tanımlayıcılarıdırcommon. Daha fazla ayrıntı için bkz . protokolle ilgili temel bilgiler. Kritik olarak, bir kullanıcıyı bir kiracıdan başka bir kiracıya imzaladığınız konuk senaryoları için, bu kullanıcıyı kaynak kiracıda doğru şekilde oturum açmak için kiracı tanımlayıcısını sağlamanız gerekir .
client_id gerekli Microsoft Entra yönetim merkezi - Uygulama kayıtları sayfasının uygulamanıza atandığı Uygulama (istemci) kimliği.
response_type gerekli OpenID Bağlan oturum açma için dahil id_token edilmelidir. Ayrıca response_type, içerebilir token. token Burada kullanmak, uygulamanızın yetkilendirme uç noktasına ikinci bir istekte bulunmak zorunda kalmadan yetkilendirme uç noktasından hemen erişim belirteci almasına olanak sağlar. response_type kullanırsanız token parametresi, scope belirteci hangi kaynak için düzenleyebileceğinizi belirten bir kapsam içermelidir (örneğin, user.read Microsoft Graph'ta). Ayrıca yetkilendirme kodu akışında kullanmak üzere bir yetkilendirme kodu sağlama yerine token de içerebilircode. Bu id_token+code yanıt bazen karma akış olarak adlandırılır.
redirect_uri önerilen Kimlik doğrulama yanıtlarının uygulamanız tarafından gönderilip alınabildiği uygulamanızın yeniden yönlendirme URI'si. Url ile kodlanmış olması dışında portalda kaydettiğiniz yeniden yönlendirme URI'lerinden biriyle tam olarak eşleşmelidir.
scope gerekli Boşlukla ayrılmış kapsam listesi. OpenID Bağlan ()id_tokens için, onay kullanıcı arabirimindeki "Oturum açın" iznine çevrilen kapsamını openidiçermelidir. İsteğe bağlı olarak, ek kullanıcı verilerine email erişim elde etmek için ve profile kapsamlarını da dahil etmek isteyebilirsiniz. Erişim belirteci istenirse, çeşitli kaynaklara onay istemek için bu isteğe başka kapsamlar da ekleyebilirsiniz.
response_mode isteğe bağlı Sonuçta elde edilen belirteci uygulamanıza geri göndermek için kullanılacak yöntemi belirtir. Varsayılan olarak yalnızca erişim belirtecini sorgular, ancak istek bir id_token içeriyorsa parçalar.
state önerilen İstekte bulunan ve belirteç yanıtında da döndürülecek bir değer. İstediğiniz herhangi bir içeriğin dizesi olabilir. Rastgele oluşturulan benzersiz bir değer genellikle siteler arası istek sahteciliği saldırılarını önlemek için kullanılır. Durum, kimlik doğrulaması isteği gerçekleşmeden önce kullanıcının uygulamadaki durumuyla ilgili bilgileri (örneğin, üzerinde bulunduğu sayfa veya görünüm) kodlamak için de kullanılır.
nonce gerekli İstekte bulunan ve uygulama tarafından oluşturulan ve sonuçta elde edilen kimlik belirtecinde talep olarak yer alacak bir değer. Uygulama daha sonra belirteç yeniden yürütme saldırılarını azaltmak için bu değeri doğrulayabilir. Değeri genellikle isteğin kaynağını tanımlamak için kullanılabilecek rastgele, benzersiz bir dizedir. Yalnızca bir id_token istendiğinde gereklidir.
prompt isteğe bağlı Gerekli kullanıcı etkileşiminin türünü gösterir. Şu anda tek geçerli değerler , , noneselect_accountve consentdeğerleridirlogin. prompt=login , kullanıcıyı bu istekte kimlik bilgilerini girmeye zorlar ve çoklu oturum açma işlemini olumsuzlar. prompt=none tam tersidir; kullanıcıya herhangi bir etkileşimli istem sunulmamasını sağlar. İstek SSO aracılığıyla sessizce tamamlanamazsa Microsoft kimlik platformu bir hata döndürür. prompt=select_account kullanıcıyı oturumda anımsanan tüm hesapların görüntülendiği bir hesap seçiciye gönderir. prompt=consent kullanıcı oturum açtığında OAuth onayı iletişim kutusunu tetikler ve kullanıcıdan uygulamaya izin vermesini ister.
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. Genellikle, uygulamalar önceden bir oturum açmadan isteğe bağlı talebi ayıkladıktan sonra yeniden kimlik doğrulaması sırasında bu parametreyi login_hintkullanır.
domain_hint isteğe bağlı Dahil edilirse, kullanıcının oturum açma sayfasından geçtiği e-posta tabanlı bulma işlemini atlar ve bu da biraz daha kolay bir kullanıcı deneyimine yol açar. Bu parametre genellikle tek bir kiracıda çalışan İş Kolu uygulamaları için kullanılır. Burada, belirli bir kiracı içinde bir etki alanı adı sağlar ve kullanıcıyı bu kiracının federasyon sağlayıcısına iletir. Bu ipucu, konukların bu uygulamada oturum açmasını engeller ve FIDO gibi bulut kimlik bilgilerinin kullanımını sınırlar.

Bu noktada kullanıcıdan kimlik bilgilerini girmesi ve kimlik doğrulamasını tamamlaması istenir. Microsoft kimlik platformu, kullanıcının sorgu parametresinde belirtilen izinlere onay verdiğinden scope de emin olur. Kullanıcı bu izinlerden hiçbirini onaylamadıysa, kullanıcıdan gerekli izinleri onaylamasını ister. Daha fazla bilgi için bkz . izinler, onay ve çok kiracılı uygulamalar.

Kullanıcı kimlik doğrulaması yapıp onay verdikten sonra, Microsoft kimlik platformu parametresinde response_mode belirtilen yöntemi kullanarak belirtilen redirect_urikonumunda uygulamanıza bir yanıt döndürür.

Başarılı yanıt

ve kullanarak response_mode=fragmentresponse_type=id_token+code başarılı bir yanıt aşağıdaki gibi görünür (okunabilirlik 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 dahilse response_type dahil.code Yetkilendirme kodu akışında kullanıma uygun bir yetkilendirme kodudur.
access_token dahilse response_type dahil.token Uygulamanın istediği erişim belirteci. Erişim belirtecinin kodu çözülmeyecek veya başka bir şekilde incelenmemeli, opak bir dize olarak kabul edilmelidir.
token_type dahilse response_type dahil.token Bu her zaman olacaktır Bearer.
expires_in dahilse response_type dahil.token Önbelleğe alma amacıyla belirtecin geçerli olduğu saniye sayısını gösterir.
scope dahilse response_type dahil.token access_token geçerli olacağı kapsamları gösterir. Kullanıcı için geçerli değilse, istenen tüm kapsamları içermeyebilir. Örneğin, kişisel bir hesap kullanarak oturum açarken istenen Microsoft Entra-only kapsamları.
id_token İmzalı JSON Web Belirteci (JWT). 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ırı için bunlara güvenmemelidir. Kimlik belirteçleri hakkında daha fazla bilgi için bkz id_token reference. .
Not: Yalnızca kapsam istendiyse ve response_type dahil id_tokensedildiyse openid sağlanır.
state İstekte bir durum parametresi varsa, yanıtta aynı değer görünmelidir. Uygulama, istek ve yanıttaki durum değerlerinin aynı olduğunu doğrulamalıdır.

Uyarı

Bu örnekteki belirteçler de dahil olmak üzere sahip olmadığınız API'lerin belirteçlerini kodunuzda doğrulamayı 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 okumak yararlı bir hata ayıklama ve öğrenme aracı olsa da, kodunuzda buna bağımlılıkları almayın veya denetlediğiniz bir API için olmayan belirteçlerle ilgili belirli bilgileri varsaymayın.

Hata yanıtı

Hata yanıtları da uygulamasına redirect_uri gönderilerek uygulamanın bunları uygun şekilde işleyebilmesini sağlayabilir:

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ılabilecek ve hatalara tepki 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.

Erişim belirteçlerini sessizce 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ığından uygulamanız için çalışma olasılığı düşüktür. Bu, şu anda Gizli'de olmayan Chromium tabanlı tarayıcılarda çalışmaya devam etse de, geliştiricilerin akışın bu bölümünü kullanmayı yeniden düşünmesi gerekir. Üçü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ığından hiçbir kullanıcının oturum açmadığını belirten bir hata alırsınız.

Kullanıcıyı tek sayfalı uygulamanızda oturum açtığınıza göre, Microsoft Graph gibi Microsoft kimlik platformu tarafından güvenliği sağlanan web API'lerini çağırmak için erişim belirteçlerini sessizce alabilirsiniz. response_type kullanarak token bir belirteç aldıysanız bile, kullanıcıyı yeniden oturum açmaya yönlendirmeden ek kaynaklara belirteç almak için bu yöntemi kullanabilirsiniz.

Normal OpenID Bağlan/OAuth akışında, Microsoft kimlik platformu /token uç noktasına bir istekte bulunarak bunu yapabilirsiniz. Diğer web API'leri için yeni belirteçler almak için gizli bir iframe'de istekte bulunabilirsiniz:

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444&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 kopyalamayı ve yapıştırmayı deneyin! (Değerleri kullanıcınız için doğru değerle değiştirmeyi login_hint unutmayın)

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=535fb089-9ff3-47b6-9bfb-4f1264799865&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 girdiğinizden, bunun üçüncü taraf tanımlama bilgisi desteği olmayan tarayıcılarda bile çalışacağını unutmayın.

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

Başarılı yanıt

Kullanarak response_mode=fragment başarılı bir yanıt şö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 dahilse response_type dahil.token Bu örnekte Microsoft Graph için uygulamanın istediği erişim belirteci. Erişim belirtecinin kodu çözülmeyecek veya başka bir şekilde incelenmemeli, opak bir dize olarak kabul edilmelidir.
token_type Bu her zaman olacaktır Bearer.
expires_in Önbelleğe alma amacıyla belirtecin geçerli olduğu saniye sayısını gösterir.
scope Erişim belirtecinin geçerli olacağı kapsamları gösterir. Kullanıcı için geçerli değilse istenen kapsamların tümünü içermeyebilir (oturum açmak için kişisel bir hesap kullanıldığında yalnızca Microsoft Entra kapsamlarının istenmesi durumunda).
id_token İmzalı JSON Web Belirteci (JWT). dahilse response_type dahil.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ırı için bunlara güvenmemelidir. id_tokens hakkında daha fazla bilgi için başvuruya id_tokenbakın.
Not: Yalnızca kapsam istendiyse openid sağlanır.
state İstekte bir durum parametresi varsa, yanıtta aynı değer görünmelidir. Uygulama, istek ve yanıttaki durum değerlerinin aynı olduğunu doğrulamalıdır.

Hata yanıtı

Hata yanıtları da uygulamasına redirect_uri gönderilerek uygulamanın bunları uygun şekilde işleyebilmesini sağlayabilir. durumunda prompt=none, beklenen bir hata olacaktır:

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ılabilecek ve hatalara tepki 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.

iframe isteğinde bu hatayı alırsanız, kullanıcının yeni bir belirteç almak için etkileşimli olarak yeniden oturum açması gerekir. Bu durumu uygulamanız için anlamlı olacak şekilde işlemeyi seçebilirsiniz.

Belirteçleri yenileme

Örtük izin, yenileme belirteçleri sağlamaz. Hem kimlik belirteçlerinin hem de erişim belirteçlerinin süresi kısa bir süre sonra dolacak, bu nedenle uygulamanızın bu belirteçleri düzenli aralıklarla yenilemeye hazır olması gerekir. Her iki belirteç türünü de yenilemek için, kimlik platformunun davranışını denetlemek için parametresini kullanarak yukarıdan prompt=none aynı gizli iframe isteğini gerçekleştirebilirsiniz. Yeni bir kimlik belirteci almak istiyorsanız ve scope=openidiçinde ve parametresini nonce kullandığınızdan id_tokenresponse_type emin olun.

Üçüncü taraf tanımlama bilgilerini desteklemeyen tarayıcılarda bu, hiçbir kullanıcının oturum açmadığını belirten bir hataya neden olur.

Oturum kapatma isteği gönderme

OpenID Bağlanend_session_endpoint, uygulamanızın kullanıcının oturumunu sonlandırmak ve Microsoft kimlik platformu tarafından ayarlanan tanımlama bilgilerini temizlemek için Microsoft kimlik platformu bir istek göndermesine olanak tanır. Bir kullanıcıyı web uygulamasından tamamen kapatmak için uygulamanızın kullanıcıyla kendi oturumunu sonlandırması (genellikle belirteç önbelleğini temizleyerek veya tanımlama bilgilerini bırakarak) ve ardından tarayıcıyı şu konuma yönlendirmelidir:

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/logout?post_logout_redirect_uri=https://localhost/myapp/
Parametre Tür Açıklama
tenant gerekli {tenant} İstek yolundaki değer, uygulamada kimlerin oturum açabileceğini denetlemek için kullanılabilir. İzin verilen değerler , organizations, consumersve kiracı tanımlayıcılarıdırcommon. Daha fazla ayrıntı için bkz . protokolle ilgili temel bilgiler.
post_logout_redirect_uri önerilen Oturumu kapatma tamamlandıktan sonra kullanıcının döndürülmesi gereken URL. Bu değer, uygulama için kaydedilen yeniden yönlendirme URI'lerinden biriyle eşleşmelidir. Dahil değilse, kullanıcıya Microsoft kimlik platformu tarafından genel bir ileti gösterilir.

Sonraki adımlar