Microsoft kimlik platformu ve OAuth 2.0 yetkilendirme kodu akışı
OAuth 2.0 yetkilendirme kodu verme türü veya kimlik doğrulama kodu akışı, bir istemci uygulamasının web API'leri gibi korumalı kaynaklara yetkili erişim elde etmelerini sağlar. Kimlik doğrulama kodu akışı, yetkilendirme sunucusundan (Microsoft kimlik platformu) uygulamanıza yeniden yönlendirmeyi destekleyen bir kullanıcı aracısı gerektirir. Örneğin, uygulamanızda oturum açmak ve verilerine erişmek için bir kullanıcı tarafından çalıştırılan bir web tarayıcısı, masaüstü veya mobil uygulama.
Bu makalede, yalnızca akışı yürütmek için ham HTTP isteklerini el ile oluştururken ve dağıtırken gerekli olan düşük düzeyli protokol ayrıntıları açıklanır ve bu önerilmez. Bunun yerine, uygulamalarınızda güvenlik belirteçleri almak ve korumalı web API'lerini çağırmak için Microsoft tarafından oluşturulmuş ve desteklenen bir kimlik doğrulama kitaplığı kullanın.
Kimlik doğrulama kodu akışını destekleyen uygulamalar
Bu tür uygulamalarda erişim belirteçleri ve kimlik belirteçleri almak için Kod Değişimi için Proof Key (PKCE) ve OpenID Connect (OIDC) ile eşleştirilmiş kimlik doğrulama kodu akışını kullanın:
- Tek sayfalı web uygulaması (SPA)
- Standart (sunucu tabanlı) web uygulaması
- Masaüstü ve mobil uygulamalar
Protokol ayrıntıları
OAuth 2.0 yetkilendirme kodu akışı, OAuth 2.0 belirtiminin 4.1 bölümünde açıklanmıştır. OAuth 2.0 yetkilendirme kodu akışını kullanan uygulamalar, Microsoft kimlik platformu (genellikle API'ler) tarafından korunan kaynaklara yönelik isteklere eklenecek bir access_token alır. Uygulamalar ayrıca yenileme mekanizması kullanarak daha önce kimliği doğrulanmış varlıklar için yeni kimlik ve erişim belirteçleri isteyebilir.
Bu diyagram, kimlik doğrulama akışının üst düzey bir görünümünü gösterir:
Tek sayfalı uygulamalar (SPA) için yeniden yönlendirme URI'leri
Kimlik doğrulama kodu akışını kullanan SPA'lar için yeniden yönlendirme URI'leri özel yapılandırma gerektirir.
- PKCE ve çıkış noktaları arası kaynak paylaşımı (CORS) ile kimlik doğrulama kodu akışını destekleyen bir yeniden yönlendirme URI'sini ekleyin: Kimlik doğrulama kodu akışıyla yeniden yönlendirme URI'sini MSAL.js 2.0'daki adımları izleyin.
- Yeniden yönlendirme URI'sini güncelleştirme: Microsoft Entra yönetim merkezindeki uygulama bildirim düzenleyicisini kullanarak yeniden yönlendirme URI'lerini
typespaolarak ayarlayın.
Yeniden spa yönlendirme türü örtük akışla geriye dönük olarak uyumludur. Belirteçleri almak için şu anda örtük akışı kullanan uygulamalar sorunsuz bir şekilde yeniden yönlendirme URI'sine geçebilir spa ve örtük akışı kullanmaya devam edebilir. Bu geriye dönük uyumluluğa rağmen, SPA'lar için PKCE ile kimlik doğrulama kod akışını kullanmanızı öneririz.
Yeniden yönlendirme URI'niz için CORS'yi ayarlamadan yetkilendirme kodu akışını kullanmayı denerseniz konsolda şu hatayı görürsünüz:
access to XMLHttpRequest at 'https://login.microsoftonline.com/common/v2.0/oauth2/token' from origin 'yourApp.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
Bu durumda, uygulama kaydınızı ziyaret edin ve uygulamanızın yeniden yönlendirme URI'sini türünü kullanacak şekilde güncelleştirin spa .
Uygulamalar, yerel uygulamalar veya istemci kimlik bilgisi akışları gibi SPA dışı akışlarla yeniden yönlendirme URI'sini kullanamaz spa . Güvenlik ve en iyi yöntemleri sağlamak için, üst bilgi olmadan yeniden spa yönlendirme URI'sini kullanmayı denerseniz Microsoft kimlik platformu bir Origin hata döndürür. Benzer şekilde Microsoft kimlik platformu, gizli dizilerin tarayıcı içinden kullanılmamasını sağlamak için bir Origin üst bilgi varlığında tüm akışlarda istemci kimlik bilgilerinin kullanılmasını da engeller.
Yetkilendirme kodu isteme
Yetkilendirme kodu akışı, istemcinin kullanıcıyı uç noktaya yönlendirmesiyle /authorize başlar. Bu örnek istekte, istemci kullanıcıdan , offline_accessve https://graph.microsoft.com/mail.read izinlerini istemektediropenid.
Bazı izinler, örneğin kullanarak Directory.ReadWrite.Allbir kuruluşun dizinine veri yazmak için yönetici tarafından kısıtlanmıştır. Uygulamanız bir kuruluş kullanıcısından bu izinlerden birine erişim isterse, kullanıcı uygulamanızın izinlerini onaylama yetkisi olmadığını belirten bir hata iletisi alır. Yönetici tarafından kısıtlanmış kapsamlara erişim istemek için, bunları doğrudan genel yöneticiden istemeniz gerekir. Daha fazla bilgi için bkz . Yönetici kısıtlı izinler.
Aksi belirtilmedikçe, isteğe bağlı parametreler için varsayılan değerler yoktur. Ancak isteğe bağlı parametrelerin atlanması isteği için varsayılan davranış vardır. Varsayılan davranış, tek geçerli kullanıcıda oturum açmak, birden çok kullanıcı varsa hesap seçiciyi göstermek veya oturum açmış kullanıcı yoksa oturum açma sayfasını göstermektir.
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&state=12345
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256
| Parametre | Gerekli/isteğe bağlı | Açıklama |
|---|---|---|
tenant |
gerekli | {tenant} İstek yolundaki değer, uygulamada kimlerin oturum açabileceğini denetlemek için kullanılabilir. Geçerli değerler , organizations, consumersve kiracı tanımlayıcılarıdırcommon. 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 oturum açmak için kiracı tanımlayıcısını sağlamanız gerekir . Daha fazla bilgi için bkz . Uç noktalar. |
client_id |
gerekli | Microsoft Entra yönetim merkezinin uygulamanıza atanmış Uygulama kayıtları deneyimi olan Uygulama (istemci) kimliği. |
response_type |
gerekli | Yetkilendirme kodu akışı için dahil code edilmelidir. Karma akışı dahil id_token edebilir veya token kullanıyor olabilir. |
redirect_uri |
gerekli | redirect_uri Kimlik doğrulama yanıtlarının uygulamanız tarafından gönderilip alınabildiği uygulamanızın. Url ile kodlanmış olması dışında, Microsoft Entra yönetim merkezine kaydettiğiniz yeniden yönlendirme URI'lerinden biriyle tam olarak eşleşmelidir. Yerel ve mobil uygulamalar için önerilen değerlerden birini kullanın: https://login.microsoftonline.com/common/oauth2/nativeclient katıştırılmış tarayıcı kullanan uygulamalar veya http://localhost sistem tarayıcıları kullanan uygulamalar için. |
scope |
gerekli | Kullanıcının onaylamasını istediğiniz kapsamların boşlukla ayrılmış listesi. İsteğin /authorize ayağı için bu parametre birden çok kaynağı kapsayabilir. Bu değer, uygulamanızın çağırmak istediğiniz birden çok web API'sine onay almasına olanak tanır. |
response_mode |
önerilen | Kimlik platformunun istenen belirteci uygulamanıza nasıl döndürmesi gerektiğini belirtir. Desteklenen değerler: - query: Erişim belirteci istenirken varsayılan değerdir. Kodu yeniden yönlendirme URI'nizde sorgu dizesi parametresi olarak sağlar. query Örtük akışı kullanarak kimlik belirteci istenirken parametresi desteklenmez. - fragment: Örtük akışı kullanarak kimlik belirteci istenirken varsayılan değerdir. Ayrıca yalnızca bir kod isteniyorsa da desteklenir.- form_post: Kodu yeniden yönlendirme URI'nize içeren bir POST yürütür. Kod istenirken desteklenir. |
state |
önerilen | İstekte bulunan ve belirteç yanıtında da döndürülen 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. Bu değer, kimlik doğrulama isteği gerçekleşmeden önce kullanıcının uygulamadaki durumuyla ilgili bilgileri de kodlayabilir. Örneğin, sayfayı kodlayabilir veya bulundukları görünümü görüntüleyebilir. |
prompt |
isteğe bağlı | Gerekli kullanıcı etkileşiminin türünü gösterir. Geçerli değerler , , noneconsentve select_accountdeğerleridirlogin.- prompt=login kullanıcıyı bu istekte kimlik bilgilerini girmeye zorlayarak çoklu oturum açma işlemini olumsuz olarak kabul eder.- prompt=none tam tersidir. Kullanıcıya etkileşimli bir istem sunulmamasını sağlar. İstek, çoklu oturum açma kullanılarak sessizce tamamlanamazsa, Microsoft kimlik platformu bir interaction_required hata döndürür.- prompt=consent kullanıcı oturum açtığında OAuth onayı iletişim kutusunu tetikler ve kullanıcıdan uygulamaya izin vermesini ister.- prompt=select_account oturumdaki veya hatırlanan herhangi bir hesaptaki tüm hesapları veya farklı bir hesabı tamamen kullanmayı seçme seçeneğini listeleyen hesap seçimi deneyimi sağlayarak çoklu oturum açmayı kesintiye uğratır. |
login_hint |
isteğe bağlı | Bu parametreyi, kullanıcının oturum açma sayfasının kullanıcı adı ve e-posta adresi alanını önceden doldurmak için kullanabilirsiniz. Uygulamalar, daha önceki bir oturum açmadan isteğe bağlı talebi ayıkladıktan sonra yeniden kimlik doğrulaması sırasında bu parametreyi login_hint kullanabilir. |
domain_hint |
isteğe bağlı | Dahil edilirse, uygulama 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. Örneğin, bunları federasyon kimlik sağlayıcısına gönderme. Uygulamalar, önceki bir oturum açmadan ayıklayarak yeniden kimlik doğrulaması sırasında bu parametreyi tid kullanabilir. |
code_challenge |
önerilen / gerekli | Kod Değişimi için Proof Key (PKCE) kullanarak yetkilendirme kodu vermelerinin güvenliğini sağlamak için kullanılır. Dahil edilirse code_challenge_method gereklidir. Daha fazla bilgi için bkz . PKCE RFC. Bu parametre artık hem genel hem de gizli istemciler olmak üzere tüm uygulama türleri için önerilir ve yetkilendirme kodu akışını kullanan tek sayfalı uygulamalar için Microsoft kimlik platformu tarafından gereklidir. |
code_challenge_method |
önerilen / gerekli | parametresini kodlamak code_verifier için code_challenge kullanılan yöntem. Bu olmalıdırS256, ancak belirtim, istemci SHA256'yı destekleyemezse kullanılmasına plain izin verir. Dışlanırsa, code_challenge varsa düz metin code_challenge olarak kabul edilir. Microsoft kimlik platformu hem S256hem de plain 'yi destekler. Daha fazla bilgi için bkz . PKCE RFC. Bu parametre, yetkilendirme kodu akışını kullanan tek sayfalı uygulamalar için gereklidir. |
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 olunmasını sağlar. Kullanıcı bu izinlerden herhangi birini onaylamadıysa, kullanıcıdan gerekli izinleri onaylamasını ister. Daha fazla bilgi için Microsoft kimlik platformu İzinler ve onay bölümüne bakın.
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
Bu örnekte kullanarak response_mode=querybaşarılı bir yanıt gösterilmektedir:
GET http://localhost?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345
| Parametre | Açıklama |
|---|---|
code |
authorization_code Uygulamanın istediği. Uygulama, yetkilendirme kodunu kullanarak hedef kaynak için erişim belirteci isteyebilir. Yetkilendirme kodları kısa sürelidir. Genellikle, süresi yaklaşık 10 dakika sonra dolar. |
state |
İstekte bir state parametre varsa, yanıtta aynı değer görünmelidir. Uygulama, istek ve yanıttaki durum değerlerinin aynı olduğunu doğrulamalıdır. |
Ayrıca, bir kimlik belirteci isterseniz ve uygulama kaydınızda örtük iznin etkinleştirilmiş olması durumunda da bir kimlik belirteci alabilirsiniz. Bu davranış bazen karma akış olarak adlandırılır. ASP.NET gibi çerçeveler tarafından kullanılır.
Hata yanıtı
Hata yanıtları da uygulamasına redirect_uri gönderilerek uygulamanın bunları uygun şekilde işleyebilmesini sağlayabilir:
GET http://localhost?
error=access_denied
&error_description=the+user+canceled+the+authentication
| Parametre | Açıklama |
|---|---|
error |
Hata türlerini sınıflandırmak ve hatalara tepki vermek için kullanılabilecek bir hata kodu dizesi. Hatanın bu bölümü, uygulamanın hataya uygun şekilde tepki verebilmesi için sağlanır, ancak bir hatanın neden oluştuğunun ayrıntılı bir şekilde açıklanmasını sağlamaz. |
error_description |
Bir geliştiricinin kimlik doğrulama hatasının nedenini belirlemesine yardımcı olabilecek belirli bir hata iletisi. Hatanın bu bölümü, hatanın neden oluştuğuyla ilgili yararlı bilgilerin çoğunu içerir. |
Yetkilendirme uç noktası hataları için hata kodları
Aşağıdaki tabloda, hata yanıtının parametresinde error döndürülebilecek çeşitli hata kodları açıklanmaktadır.
Kimlik belirteci ve karma akış isteme
Yetkilendirme kodunu kullanmadan önce kullanıcının kim olduğunu öğrenmek için, uygulamaların yetkilendirme kodunu istediğinde kimlik belirteci istemesi de yaygın bir durumdur. Bu yaklaşım karma akış olarak adlandırılır çünkü OIDC'yi OAuth2 yetkilendirme kodu akışıyla karıştırır.
Karma akış genellikle web uygulamalarında, özellikle de ASP.NET kod kullanımlarını engellemeden bir kullanıcının sayfasını işlemek için kullanılır. Bu modelde hem tek sayfalı uygulamalar hem de geleneksel web uygulamaları daha düşük gecikme süresinden yararlanılır.
Karma akış, daha önce açıklanan yetkilendirme kodu akışıyla aynıdır ancak üç eklemeyle sağlanır. Bu eklemelerin tümü kimlik belirteci istemek için gereklidir: yeni kapsamlar, yeni bir response_type ve yeni nonce sorgu parametresi.
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code%20id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=fragment
&scope=openid%20offline_access%20https%3A%2F%2Fgraph.microsoft.com%2Fuser.read
&state=12345
&nonce=abcde
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256
yanıt modu olarak kullanılması fragment , yeniden yönlendirmeden kodu okuyan web uygulamalarında sorunlara neden olur. Tarayıcılar parçayı web sunucusuna geçirmez. Bu durumlarda, uygulamalar tüm verilerin sunucuya gönderilmesini sağlamak için yanıt modunu kullanmalıdır form_post .
Başarılı yanıt
Bu örnekte kullanarak response_mode=fragmentbaşarılı bir yanıt gösterilmektedir:
GET https://login.microsoftonline.com/common/oauth2/nativeclient#
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&id_token=eYj...
&state=12345
| Parametre | Açıklama |
|---|---|
code |
Uygulamanın istediği yetkilendirme kodu. Uygulama, yetkilendirme kodunu kullanarak hedef kaynak için erişim belirteci isteyebilir. Yetkilendirme kodları kısa sürelidir ve genellikle süresi yaklaşık 10 dakika sonra doluyor. |
id_token |
Kullanıcı için örtük verme kullanılarak verilen bir kimlik belirteci. Aynı istekteki öğesinin karması code olan özel c_hash bir talep içerir. |
state |
İstekte bir state parametre varsa, yanıtta aynı değer görünmelidir. Uygulama, istek ve yanıttaki durum değerlerinin aynı olduğunu doğrulamalıdır. |
Erişim belirteci için kod kullanma
Tüm gizli istemcilerin istemci gizli dizilerini veya sertifika kimlik bilgilerini kullanma seçeneği vardır. Simetrik paylaşılan gizli diziler Microsoft kimlik platformu tarafından oluşturulur. Sertifika kimlik bilgileri, geliştirici tarafından karşıya yüklenen asimetrik anahtarlardır. Daha fazla bilgi için bkz. Microsoft kimlik platformu uygulama kimlik doğrulama sertifikası kimlik bilgileri.
En iyi güvenlik için sertifika kimlik bilgilerini kullanmanızı öneririz. Yerel uygulamalar ve tek sayfalı uygulamalar içeren genel istemciler, yetkilendirme kodu kullanırken gizli dizileri veya sertifikaları kullanmamalıdır. Yeniden yönlendirme URI'lerinizin her zaman uygulama türünü içerdiğinden ve benzersiz olduğundan emin olun.
client_secret ile erişim belirteci isteme
Artık bir authorization_code aldığınıza ve kullanıcı tarafından izin verildiğine göre kaynağı için öğesini access_token kullanabilirsinizcode. code Uç noktaya bir POST istek göndererek öğesini /token kullanın:
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=11112222-bbbb-3333-cccc-4444dddd5555
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
&client_secret=sampleCredentia1s // NOTE: Only required for web apps. This secret needs to be URL-Encoded.
| Parametre | Gerekli/isteğe bağlı | Açıklama |
|---|---|---|
tenant |
gerekli | {tenant} İstek yolundaki değer, uygulamada kimlerin oturum açabileceğini denetlemek için kullanılabilir. Geçerli değerler , organizations, consumersve kiracı tanımlayıcılarıdırcommon. Daha fazla bilgi için bkz . Uç noktalar. |
client_id |
gerekli | Microsoft Entra yönetim merkezi – Uygulama kayıtları sayfasının uygulamanıza atandığı Uygulama (istemci) kimliği. |
scope |
isteğe bağlı | Boşlukla ayrılmış kapsam listesi. Kapsamların tümü tek bir kaynaktan, OIDC kapsamlarıyla birlikte (profile, openid, email) olmalıdır. Daha fazla bilgi için Microsoft kimlik platformu İzinler ve onay bölümüne bakın. Bu parametre, uygulamaların belirteç kullanım sırasında belirteci istedikleri kaynağı bildirmesine izin vermek için tasarlanmış yetkilendirme kodu akışına yönelik bir Microsoft uzantısıdır. |
code |
gerekli | Akışın authorization_code ilk ayağında edindiğiniz. |
redirect_uri |
gerekli | almak için kullanılan değerin aynısı redirect_uri authorization_code. |
grant_type |
gerekli | Yetkilendirme kodu akışı için olmalıdır authorization_code . |
code_verifier |
önerilen | authorization_code elde etmek için kullanılanla aynı code_verifier . Yetkilendirme kodu verme isteğinde PKCE kullanıldıysa gereklidir. Daha fazla bilgi için bkz . PKCE RFC. |
client_secret |
gizli web uygulamaları için gerekli | Uygulamanızın uygulama kayıt portalında oluşturduğunuz uygulama gizli dizisi. Uygulama gizli dizisini yerel bir uygulamada veya tek sayfalı uygulamada kullanmayın çünkü bir, cihazlarda veya web sayfalarında güvenilir bir client_secret şekilde depolanamaz. Web uygulamaları ve web API'leri için gereklidir ve bu api'ler client_secret sunucu tarafında güvenli bir şekilde depolanabilir. Buradaki tüm parametrelerde olduğu gibi, istemci gizli dizisi de gönderilmeden önce URL ile kodlanmalıdır. Bu adım SDK tarafından gerçekleştirilir. URI kodlaması hakkında daha fazla bilgi için bkz . URI Genel Söz Dizimi belirtimi. Rfc 6749 başına Yetkilendirme üst bilgisinde kimlik bilgileri sağlamak yerine temel kimlik doğrulama deseni de desteklenir. |
Sertifika kimlik bilgileriyle erişim belirteci isteme
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
| Parametre | Gerekli/isteğe bağlı | Açıklama |
|---|---|---|
tenant |
gerekli | {tenant} İstek yolundaki değer, uygulamada kimlerin oturum açabileceğini denetlemek için kullanılabilir. Geçerli değerler , organizations, consumersve kiracı tanımlayıcılarıdırcommon. Daha fazla ayrıntı için bkz . Uç noktalar. |
client_id |
gerekli | Microsoft Entra yönetim merkezi – Uygulama kayıtları sayfasının uygulamanıza atandığı Uygulama (istemci) kimliği. |
scope |
isteğe bağlı | Boşlukla ayrılmış kapsam listesi. Kapsamların tümü tek bir kaynaktan, OIDC kapsamlarıyla birlikte (profile, openid, email) olmalıdır. Daha fazla bilgi için bkz . izinler, onay ve kapsamlar. Bu parametre, yetkilendirme kodu akışının Bir Microsoft uzantısıdır. Bu uzantı, uygulamaların belirteç kullanım sırasında belirteci istedikleri kaynağı bildirmesine olanak tanır. |
code |
gerekli | Akışın authorization_code ilk ayağında edindiğiniz. |
redirect_uri |
gerekli | almak için kullanılan değerin aynısı redirect_uri authorization_code. |
grant_type |
gerekli | Yetkilendirme kodu akışı için olmalıdır authorization_code . |
code_verifier |
önerilen | elde etmek için kullanılanla aynıcode_verifier.authorization_code Yetkilendirme kodu verme isteğinde PKCE kullanıldıysa gereklidir. Daha fazla bilgi için bkz . PKCE RFC. |
client_assertion_type |
gizli web uygulamaları için gerekli | Değerin bir sertifika kimlik bilgisi kullanacak şekilde urn:ietf:params:oauth:client-assertion-type:jwt-bearer ayarlanması gerekir. |
client_assertion |
gizli web uygulamaları için gerekli | Uygulamanız için kimlik bilgileri olarak kaydettiğiniz sertifikayı oluşturmanız ve bu sertifikayla imzalamanız gereken bir JSON web belirteci (JWT) onay. Sertifikanızı kaydetmeyi ve onaylama biçimini öğrenmek için sertifika kimlik bilgileri hakkında bilgi edinin. |
Parametresinin iki parametreyle değiştirilmesi dışında, parametreler paylaşılan gizli dizi tarafından yapılan client_secret istekle aynıdır: a client_assertion_type ve client_assertion.
Başarılı yanıt
Bu örnekte başarılı bir belirteç yanıtı gösterilmektedir:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}
| Parametre | Açıklama |
|---|---|
access_token |
İstenen erişim belirteci. Uygulama, web API'si gibi güvenli kaynakta kimlik doğrulaması yapmak için bu belirteci kullanabilir. |
token_type |
Belirteç türü değerini gösterir. Microsoft Entra ID'nin desteklediği tek türdür Bearer. |
expires_in |
Erişim belirtecinin geçerli olduğu süre (saniye olarak). |
scope |
için geçerli olan kapsamlar access_token . isteğe bağlı. Bu parametre standart değildir ve belirteci atlanırsa akışın ilk ayağında istenen kapsamlar içindir. |
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 ayrıntı için bu makalenin devamında Yer alan Erişim belirtecini yenileme konusuna bakın. Not: Yalnızca kapsam istendiyse offline_access sağlanır. |
id_token |
JSON Web Belirteci. Uygulama, oturum açan kullanıcı hakkında bilgi istemek için bu belirtecin segmentlerinin kodunu çözebilir. Uygulama, değerleri önbelleğe alıp görüntüleyebilir ve gizli istemciler yetkilendirme için bu belirteci kullanabilir. id_tokens hakkında daha fazla bilgi için bkz id_token reference. . Not: Yalnızca kapsam istendiyse openid sağlanır. |
Hata yanıtı
Bu örnek bir Hata yanıtıdır:
{
"error": "invalid_scope",
"error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
"error_codes": [
70011
],
"timestamp": "2016-01-09 02:02:12Z",
"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 |
Bir geliştiricinin kimlik doğrulama hatasının nedenini belirlemesine yardımcı olabilecek belirli bir hata iletisi. |
error_codes |
Tanılamada yardımcı olabilecek STS'ye özgü hata kodlarının listesi. |
timestamp |
Hatanın oluştuğu saat. |
trace_id |
tanılamada yardımcı olabilecek istek için benzersiz bir tanımlayıcı. |
correlation_id |
bileşenler arasında tanılamada yardımcı olabilecek istek için benzersiz bir tanımlayıcı. |
Belirteç uç noktası hataları için hata kodları
| Hata Kodu | Açıklama | İstemci Eylemi |
|---|---|---|
invalid_request |
Gerekli parametre eksik gibi protokol hatası. | İsteği veya uygulama kaydını düzeltin ve isteği yeniden gönderin. |
invalid_grant |
Yetkilendirme kodu veya PKCE kod doğrulayıcı geçersiz veya süresi dolmuş. | Uç noktaya yeni bir istek /authorize deneyin ve parametresinin code_verifier doğru olduğunu doğrulayın. |
unauthorized_client |
Kimliği doğrulanmış istemcinin bu yetkilendirme verme türünü kullanma yetkisi yok. | Bu hata genellikle istemci uygulaması Microsoft Entra Kimliği'ne kaydedilmediğinde veya kullanıcının Microsoft Entra kiracısına eklenmediğinde oluşur. Uygulama, kullanıcıdan uygulamayı yükleme ve Microsoft Entra Id'ye ekleme yönergelerini isteyebilir. |
invalid_client |
İstemci kimlik doğrulaması başarısız oldu. | İstemci kimlik bilgileri geçerli değil. Düzeltmek için, Uygulama Yöneticisi kimlik bilgilerini güncelleştirir. |
unsupported_grant_type |
Yetkilendirme sunucusu yetkilendirme verme türünü desteklemiyor. | İstekteki verme türünü değiştirin. Bu tür bir hata yalnızca geliştirme sırasında oluşmalıdır ve ilk test sırasında algılanmalıdır. |
invalid_resource |
Hedef kaynak mevcut olmadığından, Microsoft Entra Kimliği bulamadığını veya doğru yapılandırılmadığından geçersiz. | Bu kod, varsa kaynağın kiracıda yapılandırılmadığını gösterir. Uygulama, kullanıcıdan uygulamayı yükleme ve Microsoft Entra Id'ye ekleme yönergelerini isteyebilir. |
interaction_required |
OIDC belirtimi bu kodu yalnızca uç noktada çağırdıkça /authorize standart olmayan. İstek için kullanıcı etkileşimi gerekir. Örneğin, başka bir kimlik doğrulama adımı gereklidir. |
İsteği aynı kapsamlarla yeniden deneyin /authorize . |
temporarily_unavailable |
Sunucu geçici olarak isteği işleyemeyecek kadar meşgul. | Küçük bir gecikmeden sonra isteği yeniden deneyin. İstemci uygulaması kullanıcıya yanıtının geçici bir koşul nedeniyle geciktirildiğini açıklayabilir. |
consent_required |
İstek için kullanıcı onayı gerekiyor. Bu hata standart değildir. Genellikle OIDC belirtimleri başına yalnızca uç noktada döndürülür /authorize . İstemci uygulamasının isteme izni olmayan kod kullanım akışında bir scope parametre kullanıldığında döndürülür. |
İstemci, onay tetiklemesi için /authorize kullanıcıyı doğru kapsamlı uç noktaya geri göndermelidir. |
invalid_scope |
Uygulama tarafından istenen kapsam geçersiz. | Kimlik doğrulama isteğindeki scope parametresinin değerini geçerli bir değere güncelleştirin. |
Not
Tek sayfalı uygulamalar, çıkış noktaları arası belirteç kullanımına yalnızca 'Tek Sayfalı Uygulama' istemci türü için izin verilebileceğini belirten bir invalid_request hata alabilir. Bu, belirteci istemek için kullanılan yeniden yönlendirme URI'sinin yeniden spa yönlendirme URI'si olarak işaretlenmediğini gösterir. Bu akışın nasıl etkinleştirileceğine ilişkin uygulama kaydı adımlarını gözden geçirin.
Erişim belirtecini kullanma
Artık başarıyla bir access_tokenedindiğinize göre, belirteci üst bilgisine ekleyerek web API'lerine yönelik isteklerde Authorization kullanabilirsiniz:
GET /v1.0/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
Erişim belirtecini yenileme
Erişim belirteçleri kısa sürelidir. Kaynaklara erişmeye devam etmek için süresi dolduktan sonra bunları yenileyin. Bunu yapmak için /token uç noktaya başka bir POST istek gönderebilirsiniz. yerine öğesini refresh_token codebelirtin. Yenileme belirteçleri, istemcinizin zaten onay aldığı tüm izinler için geçerlidir. Örneğin, için scope=mail.read bir istekte verilen yenileme belirteci, için yeni erişim belirteci istemek için scope=api://contoso.com/api/UseResourcekullanılabilir.
Web uygulamaları ve yerel uygulamalar için yenileme belirteçlerinde belirtilen yaşam süreleri yoktur. Genellikle yenileme belirteçlerinin kullanım ömrü nispeten uzun olur. Ancak bazı durumlarda yenileme belirteçlerinin süresi dolar, iptal edilir veya eylem için yeterli ayrıcalıklar eksik olur. Uygulamanızın belirteç verme uç noktası tarafından döndürülen hataları beklemesi ve işlemesi gerekir. Tek sayfalı uygulamalar, her gün yeni bir kimlik doğrulaması gerektiren, 24 saatlik ömrü olan bir belirteç alır. Bu eylem, üçüncü taraf tanımlama bilgileri etkinleştirildiğinde bir iframe'de sessizce yapılabilir. Safari gibi üçüncü taraf tanımlama bilgileri olmayan tarayıcılarda, tam sayfa gezintisi veya açılır pencere gibi üst düzey bir çerçevede yapılmalıdır.
Yeni erişim belirteçleri almak için kullanıldığında yenileme belirteçleri iptal edilir. Eski yenileme belirtecini atmanız beklenir. OAuth 2.0 belirtimi şunları söyler: "Yetkilendirme sunucusu yeni bir yenileme belirteci verebilir; bu durumda istemci eski yenileme belirtecini atmalı ve yeni yenileme belirteci ile değiştirmelidir. Yetkilendirme sunucusu, istemciye yeni bir yenileme belirteci verdikten sonra eski yenileme belirtecini iptal edebilir."
Önemli
olarak spakaydedilen yeniden yönlendirme URI'sine gönderilen yenileme belirteçleri için yenileme belirtecinin süresi 24 saat sonra dolar. İlk yenileme belirteci kullanılarak alınan ek yenileme belirteçleri bu süre sonu süresi boyunca taşır, bu nedenle uygulamaların her 24 saatte bir yeni yenileme belirteci almak için etkileşimli bir kimlik doğrulaması kullanarak yetkilendirme kodu akışını yeniden çalıştırmaya hazır olması gerekir. Kullanıcıların kimlik bilgilerini girmesi gerekmez ve genellikle herhangi bir kullanıcı deneyimini bile görmezler, yalnızca uygulamanızın yeniden yüklenmesini sağlar. Oturum açma oturumunu görmek için tarayıcının en üst düzey bir çerçevede oturum açma sayfasını ziyaret etmesi gerekir. Bunun nedeni tarayıcılardaki üçüncü taraf tanımlama bilgilerini engelleyen gizlilik özellikleridir.
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=sampleCredentia1s // NOTE: Only required for web apps. This secret needs to be URL-Encoded
| Parametre | Tür | Açıklama |
|---|---|---|
tenant |
gerekli | {tenant} İstek yolundaki değer, uygulamada kimlerin oturum açabileceğini denetlemek için kullanılabilir. Geçerli değerler , organizations, consumersve kiracı tanımlayıcılarıdırcommon. Daha fazla bilgi için bkz . Uç noktalar. |
client_id |
gerekli | Microsoft Entra yönetim merkezinin uygulamanıza atanmış Uygulama kayıtları deneyimi olan Uygulama (istemci) kimliği. |
grant_type |
gerekli | Yetkilendirme kodu akışının bu ayağı için olmalıdır refresh_token . |
scope |
isteğe bağlı | Boşlukla ayrılmış kapsam listesi. Bu bacakta istenen kapsamlar, özgün authorization_code istek ayağında istenen kapsamların bir alt kümesine eşdeğer veya alt kümesi olmalıdır. Bu istekte belirtilen kapsamlar birden çok kaynak sunucusuna yayılmışsa, Microsoft kimlik platformu ilk kapsamda belirtilen kaynak için bir belirteç döndürür. Daha fazla bilgi için Microsoft kimlik platformu İzinler ve onay bölümüne bakın. |
refresh_token |
gerekli | Akışın refresh_token ikinci ayağında edindiğiniz. |
client_secret |
web uygulamaları için gerekli | Uygulamanızın uygulama kayıt portalında oluşturduğunuz uygulama gizli dizisi. Cihazlarında güvenilir bir şekilde depolanamadığından client_secret yerel bir uygulamada kullanılmamalıdır. Web uygulamaları ve web API'leri için gereklidir ve bu api'ler client_secret sunucu tarafında güvenli bir şekilde depolanabilir. Bu gizli dizinin URL ile kodlanmış olması gerekir. Daha fazla bilgi için URI Genel Söz Dizimi belirtimine bakın. |
Başarılı yanıt
Bu örnekte başarılı bir belirteç yanıtı gösterilmektedir:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}
| Parametre | Açıklama |
|---|---|
access_token |
İstenen erişim belirteci. Uygulama, web API'si gibi güvenli kaynakta kimlik doğrulaması yapmak için bu belirteci kullanabilir. |
token_type |
Belirteç türü değerini gösterir. Microsoft Entra ID'nin desteklediği tek tür Taşıyıcı'dır. |
expires_in |
Erişim belirtecinin geçerli olduğu süre (saniye olarak). |
scope |
için geçerli olan kapsamlar access_token . |
refresh_token |
Yeni bir OAuth 2.0 yenileme belirteci. Yenileme belirteçlerinizin mümkün olduğunca uzun süre geçerli kalmasını sağlamak için eski yenileme belirtecini yeni alınan bu yenileme belirteciyle değiştirin. Not: Yalnızca kapsam istendiyse offline_access sağlanır. |
id_token |
İmzasız JSON Web Belirteci. 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. hakkında id_tokendaha fazla bilgi için bkz. Microsoft kimlik platformu kimlik belirteçleri. Not: Yalnızca kapsam istendiyse openid sağlanı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ı
{
"error": "invalid_scope",
"error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
"error_codes": [
70011
],
"timestamp": "2016-01-09 02:02:12Z",
"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 |
Bir geliştiricinin kimlik doğrulama hatasının kök nedenini belirlemesine yardımcı olabilecek belirli bir hata iletisi. |
error_codes |
Tanılamada yardımcı olabilecek STS'ye özgü hata kodlarının listesi. |
timestamp |
Hatanın oluştuğu saat. |
trace_id |
tanılamada yardımcı olabilecek istek için benzersiz bir tanımlayıcı. |
correlation_id |
bileşenler arasında tanılamada yardımcı olabilecek istek için benzersiz bir tanımlayıcı. |
Hata kodlarının ve önerilen istemci eyleminin açıklaması için bkz . Belirteç uç noktası hataları için hata kodları.
Sonraki adımlar
- Kodlamaya başlamak için MSAL JS örneklerinin üzerinden geçin.
- Belirteç değişimi senaryoları hakkında bilgi edinin.