Microsoft kimlik platformu ve OAuth 2,0 yetkilendirme kodu akışı

OAuth 2,0 yetkilendirme kodu verme, Web API 'Leri gibi korumalı kaynaklara erişim kazanmak için bir cihaza yüklenen uygulamalarda kullanılabilir. OAuth 2,0 ve açık kimlik Bağlan (oıdc) Microsoft kimlik platformu uygulamasını kullanarak, mobil ve masaüstü uygulamalarınıza oturum açma ve apı erişimi de ekleyebilirsiniz.

Bu makalede, herhangi bir dili kullanarak 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.

OAuth 2,0 yetkilendirme kodu akışı, oauth 2,0 belirtiminin 4,1 bölümündeaçıklanmaktadır. OıDC ile, tek sayfalı uygulamalar, Web uygulamalarıve yerel olarak yüklenen uygulamalardahil olmak üzere uygulama türlerinin çoğunda kimlik doğrulama ve yetkilendirme gerçekleştirmek için kullanılır. flow, uygulamaların, Microsoft kimlik platformu tarafından güvenliği sağlanmış kaynaklara erişmek için kullanılabilecek access_tokens güvenli bir şekilde almasına olanak sağlar, ayrıca, ek access_tokens almak için belirteçleri ve oturum açmış kullanıcı için kimlik belirteçlerini yenileyin.

Protokol diyagramı

Yüksek düzeyde, bir uygulamanın tüm kimlik doğrulama akışı şuna benzer bir bit:

Tek sayfalı uygulamalar için yeniden yönlendirme URI kurulumu gerekli

Tek sayfalı uygulamalar için yetkilendirme kodu akışı, bazı ek kurulum gerektirir. Yeniden yönlendirme URI 'nizi CORS için etkin olarak işaretlemek üzere tek sayfalı uygulamanızı oluşturmaya yönelik yönergeleri izleyin. CORS 'yi etkinleştirmek üzere var olan bir yeniden yönlendirme URI 'sini güncelleştirmek için, bildirim düzenleyicisini açın ve type yeniden YÖNLENDIRME URI 'nizin alanını spa bölümünde olarak ayarlayın replyUrlsWithType . Ayrıca, kimlik doğrulama sekmesinin "Web" bölümünde yeniden yönlendirme URI 'sine tıklayıp, yetkilendirme kodu akışını kullanarak geçirmek istediğiniz URI 'Leri seçebilirsiniz.

spaYeniden yönlendirme türü, örtük akışla geriye dönük olarak uyumludur. Belirteçleri almak için örtük akışı kullanan uygulamalar, spa yeniden YÖNLENDIRME URI 'sine sorun olmadan geçebilir ve dolaylı akışı kullanmaya devam edebilir.

Yetkilendirme kodu akışını kullanmaya çalışırsanız ve şu hatayı görebilirsiniz:

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.

Ardından, uygulama kaydınızı ziyaret edin ve uygulamanız için yeniden yönlendirme URI 'sini yazın spa .

Uygulamalar spa , yerel uygulamalar veya istemci kimlik bilgileri akışları gıbı Spa olmayan akışlarla yeniden yönlendirme URI 'sini kullanamaz. Güvenlik ve en iyi uygulamaları sağlamak için, bir spa üst bilgi olmadan yeniden yönlendirme URI 'si kullan seçeneğini kullanmayı denerseniz Microsoft Identity platformu bir hata döndürür Origin . Benzer şekilde, Microsoft Identity platformu, Origin parolaların tarayıcıdan kullanılmadığından emin olmak için, bir üst bilgi varlığı içindeki istemci kimlik bilgilerinin (OBO akışında, istemci kimlik bilgileri akışında ve Auth Code Flow) kullanılmasını da engeller.

Yetkilendirme kodu iste

Yetkilendirme kodu akışı, kullanıcıyı uç noktaya yönlendiren istemciyle başlar /authorize . Bu istekte istemci,, openid offline_access ve https://graph.microsoft.com/mail.read izinlerini kullanıcıdan ister. Bazı izinler yönetici kısıtlanıyor, örneğin kullanarak bir kuruluşun dizinine veri yazma Directory.ReadWrite.All . Uygulamanız bir kuruluş kullanıcısının bu izinlerinden birine erişim isterse, kullanıcı uygulamanızın izinlerini kabul etmek için yetkilendirilmediğini bildiren bir hata iletisi alır. Yönetici kısıtlı kapsamlara erişim istemek için, bunları doğrudan bir genel yöneticiden istemeniz gerekir. Daha fazla bilgi için Yönetici kısıtlı izinleriokuyun.

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read%20api%3A%2F%2F
&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 de sahip olduğundan emin olur scope . Kullanıcı bu izinlerden herhangi birine onay vermediyseniz, kullanıcıdan gerekli izinleri onaylaması istenir. İzinlerin, izin ve çok kiracılı uygulamaların ayrıntıları burada verilmiştir.

kullanıcı kimlik doğrulamasından ve onay vertikten sonra, Microsoft kimlik platformu redirect_uri parametresinde belirtilen yöntemi kullanarak, belirtilen şekilde uygulamanıza bir yanıt döndürür response_mode .

Başarılı yanıt

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

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

Ayrıca, bir kimlik belirteci isteğinde bulunduysanız ve uygulama kaydında örtülü izni etkinleştirdiyseniz de bir kimlik belirteci alırsınız. Bu bazen "karma akış"olarak adlandırılır ve bu durum, ASP.NET.

Hata yanıtı

Uygulamanın bunları uygun şekilde işlemesi redirect_uri için hata yanıtları da uygulamasına gönderebilirsiniz:

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 döndürülen error çeşitli hata kodları açık almaktadır.

Kimlik belirteci de isteği (karma akış)

Yetkilendirme kodunu kullanmadan önce kullanıcının kim olduğunu öğrenmek için, uygulamaların yetkilendirme kodunu talep eden bir kimlik belirteci de talep etmek yaygın bir durumdur. Bu karma akış olarak adlandırılan bu akış, örtülü izni yetkilendirme kod akışıyla karıştırabilir. Karma akış, özellikle de kod geri ödemesini engellemeden bir kullanıcıya sayfa işlemek isteyen web uygulamaları için yaygın olarak ASP.NET. Hem tek sayfalı uygulamalar hem de geleneksel web uygulamaları, bu modelde daha az gecikme süresinden yararlanabilir.

Karma akış, daha önce açıklanan yetkilendirme kod akışıyla aynıdır, ancak üç eklemeyle aynıdır. Bunların hepsi kimlik belirteci isteğinde mevcuttur: yeni kapsamlar, yeni response_type ve yeni bir nonce sorgu parametresi.

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&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ımı, tarayıcılar parçayı web sunucusuna geçemeyeceği için kodu yeniden yönlendirmeden okumakta olan fragment web uygulamaları için soruna neden olur. Bu gibi durumlarda uygulamaların tüm verilerin form_post sunucuya gönderildiğini sağlamak için yanıt modunu kullanmaları gerekir.

Başarılı yanıt

kullanarak başarılı bir yanıt response_mode=fragment şöyle olacaktır:

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 istemciler istemci gizli dizilerini (Microsoft kimlik platformu tarafından oluşturulan simetrik paylaşılan gizli diziler) ve sertifika kimlik bilgilerini (geliştiricitarafından yüklenen asimetrik anahtarlar) kullanma seçeneğine sahip olur. En iyi güvenlik için sertifika kimlik bilgilerinin kullanılması önerilir. Genel istemciler (yerel uygulamalar ve tek sayfalı uygulamalar) yetkilendirme kodu kullanılırken gizli dizileri veya sertifikaları kullanmaması gerekir. Yeniden yönlendirme URL'lerinin uygulama türünü doğru şekilde göstermesini ve benzersiz olmasını her zaman garanti edin.

Client_secret ile erişim belirteci client_secret

Artık bir kaynak authorization_code ve kullanıcı tarafından izin verilmiş olduğunuza göre, istenen kaynağa bir için code access_token kullanabilirsiniz. Bunu yapmak için uç POST noktasına bir istek /token gönderebilirsiniz:

// 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=6731de76-14a6-49ae-97bc-6eba6914391e
&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=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only required for web apps. This secret needs to be URL-Encoded.

Sertifika kimlik bilgileriyle erişim belirteci isteği

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&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

Parametrenin iki parametreyle değiştirilmesi dışında, paylaşılan gizli bilgiyle yapılan istekte parametrelerin aynı olduğunu fark client_secret vardır: ve client_assertion_type client_assertion .

Başarılı yanıt

Başarılı bir belirteç yanıtı şuna benzer olacaktır:

{
    "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ı

Hata yanıtları şuna benzer:

{
  "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: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
  "correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}

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

Erişim belirtecini kullanma

Artık başarıyla edindiniz access_token , bu API 'yi üstbilgiye dahil ederek Web API 'lerine yönelik isteklerde kullanabilirsiniz Authorization :

GET /v1.0/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...

Erişim belirtecini Yenile

Access_tokens kısa ömürlü ve kaynaklara erişmeye devam etmek için süreleri dolduktan sonra yenilemeniz gerekir. Bunu, uç noktasına başka bir istek göndererek yapabilirsiniz POST /token refresh_token code . Yenileme belirteçleri, istemcinizin zaten onay aldığı tüm izinler için geçerlidir. bu nedenle, için bir istekte verilen yenileme belirteci scope=mail.read için yeni bir erişim belirteci istemek üzere kullanılabilir scope=api://contoso.com/api/UseResource .

Web uygulamaları ve yerel uygulamalar için yenileme belirteçleri, belirtilen ömürleri içermez. Genellikle, yenileme belirteçlerinin yaşam süreleri nispeten uzundur. Ancak, bazı durumlarda belirteçleri yenileme süre sonu, iptal etme veya istenen eylem için yeterli ayrıcalıklara sahip değil. Uygulamanızın belirteç verme uç noktası tarafından döndürülen hataları beklemesi ve işlemesi gerekir. Ancak tek sayfalı uygulamalar, 24 saatlik bir yaşam süresine sahip bir belirteç alır ve her gün yeni bir kimlik doğrulaması gerektirir. Bu, 3. taraf tanımlama bilgileri etkinleştirildiğinde bir IFRAME içinde sessizce yapılabilir, ancak Safari gibi 3. taraf tanımlama bilgileri olmadan tarayıcılarda bir üst düzey çerçevede (tam sayfa gezintisi veya açılan pencere penceresi) yapılması gerekir.

Yeni erişim belirteçleri elde etmek için kullanıldığında yenileme belirteçleri iptal edilmese de, eski yenileme belirtecini atmayı bekliyorcaksınız. OAuth 2,0 belirtimi şöyle diyor: "yetkilendirme sunucusu yeni bir yenileme belirteci verebilir, bu durumda istemcinin eski yenileme belirtecini atılması ve yeni yenileme belirteci Ile değiştirmeniz gerekir. Yetkilendirme sunucusu, istemciye yeni bir yenileme belirteci gönderdikten sonra eski yenileme belirtecini iptal edebılır. "

// 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=535fb089-9ff3-47b6-9bfb-4f1264799865
&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

Başarılı bir belirteç yanıtı şöyle görünür:

{
    "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: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
  "correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}

Hata kodlarının ve önerilen istemci eyleminin açıklaması için bkz. belirteç uç noktası hataları Için hata kodları.