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 Yazım Denetleme Anahtarı (PKCE) ve OpenID Bağlan (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 typespa olarak 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.

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 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 bir Genel Yönetici istrator'dan 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 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

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

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

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.

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

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

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_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_tokencodebelirtin. 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."

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