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, akışı çalıştırmak amacıyla ham HTTP isteklerini elle oluşturup gönderirken gerekli olan düşük düzeyli protokol ayrıntıları açıklanmaktadır ve bunu tavsiye etmiyoruz. 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'lar) 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 type kullanarak yeniden yönlendirme URI'lerini spa olarak ayarlayın.

Yeniden spa yönlendirme türü örtük akışla geriye dönük olarak uyumludur. Şu anda belirteçleri almak için örtük akışı kullanan uygulamalar, sorun yaşamadan spa yönlendirme URI türüne geçebilir 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/oauth2/v2.0/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 yönlendirme URI'sini spa türünü kullanacak şekilde güncelleyin.

Uygulamalar, yerel uygulamalar veya istemci kimlik bilgisi akışları gibi SPA dışı akışlarda spa yeniden yönlendirme URI'sini kullanamaz. Güvenlik ve en iyi yöntemleri sağlamak için, Microsoft kimlik platformu, üst bilgi olmadan bir spa yönlendirme URI'sini kullanmayı denerseniz bir Origin hata döndürür. Benzer şekilde Microsoft kimlik platformu, bir Origin üst bilgisi mevcut olduğunda, tarayıcı içinden gizli bilgilerin kullanılmasını engellemek için tüm akışlarda istemci kimlik bilgilerinin kullanılmasını da önler.

Yetkilendirme kodu isteme

Yetkilendirme kodu akışı, istemcinin kullanıcıyı uç noktaya yönlendirmesiyle /authorize başlar. Bu örnek istekte, istemci kullanıcıdan , openidve offline_access izinlerini istemektedirhttps://graph.microsoft.com/mail.read.

Bazı izinler yönetici kısıtlamasına tabidir; örneğin, Directory.ReadWrite.All kullanarak bir kuruluşun dizinine veri yazmak. 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

Bu noktada kullanıcıdan kimlik bilgilerini girmesi ve kimlik doğrulamasını tamamlaması istenir. Microsoft kimlik platformu, kullanıcının scope sorgu parametresinde belirtilen izinlere onay verdiğinden emin olunmasını da 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 redirect_uri belirtilen yöntemi kullanarak belirtilen response_modekonumunda uygulamanıza bir yanıt döndürür.

Başarılı yanıt

Bu örnek, response_mode=query kullanımıyla başarılı bir yanıt gösteriyor.

GET http://localhost?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345

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 redirect_uri’e gönderilerek uygulamanın bunları uygun şekilde işleyebilmesi için sağlanabilir.

GET http://localhost?
error=access_denied
&error_description=the+user+canceled+the+authentication

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 istemek ya da karma akış kullanmak

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.

Hibrit akış, genellikle web uygulamalarında, özellikle ASP.NET üzerinde kod çözümlemesini engellemeden bir sayfanın kullanıcıya görüntülenmesi 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 örnek response_mode=fragment ile başarılı bir yanıt gösterilmektedir.

GET https://login.microsoftonline.com/common/oauth2/nativeclient#
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&id_token=eYj...
&state=12345

Erişim belirteci için kodu çözün

Tüm gizli istemcilerin istemci gizli anahtarlarını veya sertifika kimlik bilgilerini kullanma seçeneği vardır. Simetrik paylaşılan gizli anahtarlar 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 kimliği 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 kullanarak bir erişim belirteci isteyin

Artık bir authorization_code aldığınıza ve kullanıcıdan izin aldıktan sonra, code öğesini access_token kaynağa geçirmek için kullanabilirsiniz. code öğesini, POST isteği göndererek /token son nokta aracılığıyla kullanarak faydalanı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.

Sertifika kimlik bilgileriyle erişim belirteci talep etme

// 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

Parametreler, client_secret parametresinin iki parametreyle, yani client_assertion_type ve client_assertion ile değiştirilmesi dışında, paylaşılan gizli dizi tarafından yapılan istekle aynıdır.

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..."
}

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"
}

Belirteç uç noktası hataları için hata kodları

Erişim belirtecini kullanma

Artık başarıyla bir access_token edindiğinize göre, belirteci Authorization üst bilgisine ekleyerek web API'lerine isteklerde 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 POST uç noktaya başka bir /token istek gönderebilirsiniz. code yerine refresh_token öğesini sağlayın. Yenileme belirteçleri, istemcinizin zaten onay aldığı tüm izinler için geçerlidir. Örneğin, scope=mail.read için bir istekte verilen bir yenileme belirteci, scope=api://contoso.com/api/UseResource için yeni bir erişim belirteci istemek amacıyla kullanı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 edilmez. Eski yenileme belirtecini silmeniz 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."

// 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

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..."
}

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"
}

Hata kodlarının ve önerilen istemci eylemlerinin açıklaması için, Belirteç uç noktası hataları için hata kodları başlığına bakın.

Sonraki adımlar

• Kodlamaya başlamak için MSAL JS örneklerinin üzerinden geçin.
• Belirteç değişimi senaryoları hakkında bilgi edinin.