Microsoft kimlik platformu ve OAuth 2,0 istemci kimlik bilgileri akışı

Bir uygulamanın kimliğini kullanarak Web 'de barındırılan kaynaklara erişmek için, bazen iki adet aralıklı OAuth olarak adlandırılan RFC 6749 ' de belirtilen OAuth 2,0 istemci kimlik bilgileri verme ' yi kullanabilirsiniz. Kullanıcının anında etkileşime geçmesi gerekmeyen ve arka planda çalışması gereken sunucular arası etkileşimler için genellikle bu izin türü kullanılır. Bu tür uygulamalar genellikle Daemon 'ları veya hizmet hesapları olarak adlandırılır.

Bu makalede, 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 istemci kimlik bilgileri verme akışı, bir Web hizmetinin (gizli istemci) başka bir Web hizmetini çağırırken kimlik doğrulaması yapmak yerine kendi kimlik bilgilerini kullanmasına izin verir. daha yüksek bir güvence düzeyi için Microsoft kimlik platformu, çağıran hizmetin kimlik bilgileri olarak bir sertifika (paylaşılan gizlilik yerine) kullanmasına de olanak tanır. Uygulamaların kimlik bilgileri kullanıldığı için, bu kimlik bilgilerinin güvenli tutulması gerekir. bu kimlik bilgisini kaynak kodunuzda hiçbir şekilde yayımlayamaz, Web sayfalarına katıştırın veya yaygın olarak dağıtılmış bir yerel uygulamada kullanın.

İstemci kimlik bilgileri akışında, izinler doğrudan uygulamanın kendisine bir yönetici tarafından verilir. Uygulama bir kaynağa belirteç sunduğunda, kaynak, kimlik doğrulamasında yer alan hiçbir Kullanıcı olmadığından uygulamanın kendisini bir eylem gerçekleştirmek üzere yetkilendirmesiyle zorlar. Bu makalede, bir uygulamayı BIR API çağrısını yetkilendirmekiçin gereken adımlar ve bu API 'yi çağırmak için gereken belirteçleri almaadımları ele alınmaktadır.

Protokol diyagramı

Tüm istemci kimlik bilgileri akışı aşağıdaki diyagrama benzer şekilde görünür. Bu makalenin ilerleyen kısımlarında bulunan adımların her birini açıklıyoruz.

İstemci kimlik bilgileri akışını gösteren diyagram

Doğrudan yetkilendirmeyi al

Bir uygulama, genellikle bir kaynağa iki şekilde erişmek için doğrudan yetkilendirme alır:

Bu iki yöntem, Azure AD 'de en yaygın bir deyişle, istemci kimlik bilgileri akışını gerçekleştiren istemciler ve kaynaklar için önerilir. Bir kaynak, istemcilerini başka yollarla yetkilendirmeyi de seçebilir. Her kaynak sunucusu, uygulaması için en mantıklı hale getiren yöntemi seçebilir.

Erişim denetimi listeleri

Bir kaynak sağlayıcısı, bildiği ve belirli bir erişim düzeyi veren uygulama (istemci) kimliklerinin listesini temel alan bir Yetkilendirme denetimini uygulayabilir. kaynak Microsoft kimlik platformu bir belirteç aldığında, belirtecin kodunu çözebilir ve istemcinin uygulama kimliğini appid ve iss taleplerinden ayıklayabilir. Ardından uygulamayı, tuttuğu bir erişim denetim listesi (ACL) ile karşılaştırır. ACL 'nin ayrıntı düzeyi ve yöntemi kaynaklar arasında önemli ölçüde farklılık gösterebilir.

Yaygın kullanım durumu, bir Web uygulaması veya Web API 'SI için testler çalıştırmak üzere bir ACL kullanmaktır. Web API 'SI, belirli bir istemciye yönelik tam izinlerin yalnızca bir alt kümesini verebilir. apı üzerinde uçtan uca testler çalıştırmak için, Microsoft kimlik platformu belirteçleri alan ve ardından bunları apı 'ye gönderen bir test istemcisi oluşturun. Ardından API, API 'nin tüm işlevlerine tam erişim için test istemcisinin uygulama KIMLIĞI ACL 'sini denetler. Bu tür bir ACL kullanırsanız, yalnızca arayanın değerini değil, appid belirtecin değerinin güvenilir olduğunu da doğruladığınızdan emin olun iss .

Bu tür bir yetkilendirme, kişisel Microsoft hesapları olan tüketici kullanıcılarının sahip olduğu verilere erişmesi gereken Daemon 'ları ve hizmet hesapları için ortaktır. Kuruluşlara ait veriler için, uygulama izinleri aracılığıyla gerekli yetkilendirmeyi almanızı öneririz.

Belirteçleri talep olmadan denetleme roles

Bu ACL tabanlı yetkilendirme modelini etkinleştirmek için Azure AD, uygulamaların başka bir uygulama için belirteçleri almak üzere yetkilendirilmesini gerektirmez. Bu nedenle, yalnızca uygulama belirteçleri talep olmadan verilebilir roles . API 'Leri kullanıma sunan uygulamaların belirteçleri kabul etmek için izin denetimleri uygulaması gerekir.

Uygulamaların uygulamanıza yönelik salt uygulama erişim belirteçlerini almasını engellemek isterseniz, uygulamanız için kullanıcı atama gereksinimlerinin etkinleştirildiğinden emin olun. Bu, atanmış rolleri olmayan kullanıcıların ve uygulamaların bu uygulama için bir belirteç alabilmesi engellenecek.

Uygulama izinleri

ACL 'Leri kullanmak yerine, Uygulama izinleri kümesini kullanıma sunmak Için API 'leri kullanabilirsiniz. Uygulama izni bir kuruluşun yöneticisi tarafından uygulamaya verilir ve yalnızca söz konusu kuruluşa ve çalışanlarına ait olan verilere erişmek için kullanılabilir. örneğin, Microsoft Graph aşağıdakileri yapmak için çeşitli uygulama izinleri sunar:

  • Tüm posta kutularındaki postaları oku
  • Tüm posta kutularındaki postaları Okuma ve yazma
  • Herhangi bir kullanıcı olarak posta gönder
  • Dizin verilerini oku

uygulama izinlerini kendi apı 'niz ile kullanmak için (Microsoft Graph aksine), önce apı 'nin Azure portal içindeki uygulama kaydında kapsamları tanımlayarak apı 'yi kullanıma sunmalısınız . Daha sonra, istemci uygulamanızın uygulama kaydında bu izinleri seçerek API 'ye erişimi yapılandırın . API 'nin uygulama kaydında hiçbir kapsam çıkarmadığınız takdirde, Azure portal istemci uygulamanızın uygulama kaydında Bu API 'ye yönelik uygulama izinleri belirtemezsiniz.

Bir uygulama olarak kimlik doğrulaması yaparken (bir kullanıcının aksine), temsilci izinleri (bir kullanıcı tarafından verilen kapsamlar) kullanamazsınız. Uygulama için yönetici veya Web API 'SI tarafından ön kimlik doğrulama aracılığıyla verilen, rol olarak da bilinen uygulama izinlerini kullanmanız gerekir.

Uygulama izinleri hakkında daha fazla bilgi için bkz. izinler ve onay.

Genellikle, uygulama izinleri kullanan bir uygulama oluşturduğunuzda, uygulama, yöneticinin uygulamanın izinlerini onayladığı bir sayfa veya görünüm gerektirir. Bu sayfa, uygulamanın oturum açma akışının bir parçası, uygulamanın ayarlarının bir parçası olabilir veya adanmış bir "Connect" akışı olabilir. Çoğu durumda, uygulamanın bu "Bağlan" görünümünü yalnızca bir kullanıcı iş veya okul Microsoft hesabı oturum açtıktan sonra göstermesini mantıklı hale getirir.

Kullanıcıyı uygulamanıza imzalarsanız, kullanıcının uygulama izinlerini onaylamasını istemek için önce kullanıcının sahip olduğu kuruluşu belirleyebilirsiniz. Kesinlikle gerekli olmasa da, kullanıcılarınız için daha sezgisel bir deneyim oluşturmanıza yardımcı olabilir. kullanıcı oturumu açmak için Microsoft kimlik platformu protokol öğreticileriniizleyin.

Dizin yöneticisinden izinleri isteme

kuruluşun yöneticisinden izin istemek için hazırsanız, kullanıcıyı Microsoft kimlik platformu yönetici onay uç noktasına yönlendirebilirsiniz.

İpucu

Bu isteği Postman 'da yürütmeyi deneyin! (En iyi sonuçları elde etmek için kendi uygulama KIMLIĞINIZI kullanın; öğretici uygulaması yararlı izinler istemez.)  Bu Isteği Postman 'da çalıştırmayı deneyin

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/adminconsent?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&state=12345
&redirect_uri=http://localhost/myapp/permissions

Pro ipucu: aşağıdaki isteği bir tarayıcıda yapıştırmayı deneyin.

https://login.microsoftonline.com/common/adminconsent?client_id=6731de76-14a6-49ae-97bc-6eba6914391e&state=12345&redirect_uri=http://localhost/myapp/permissions
Parametre Koşul Açıklama
tenant Gerekli İzin istemek istediğiniz dizin kiracısı. Bu, GUID veya kolay ad biçiminde olabilir. Kullanıcının hangi kiracıya ait olduğunu bilmiyorsanız ve herhangi bir kiracı ile oturum açmalarına izin vermek istiyorsanız kullanın common .
client_id Gerekli Azure Portal – uygulama kayıtları deneyiminin uygulamanıza atandığı uygulama (istemci) kimliği .
redirect_uri Gerekli Uygulamanızın işlenmesi için yanıtın gönderilmesini istediğiniz yeniden yönlendirme URI 'SI. Portalın, URL kodlamalı olması ve ek yol segmentlerine sahip olması dışında, portalda kaydettiğiniz yeniden yönlendirme URI 'lerinden biriyle tam olarak eşleşmesi gerekir.
state Önerilen İsteğin belirteç yanıtında de döndürülen bir değeri. İstediğiniz herhangi bir içerik dizesi olabilir. Durum, kullanıcının uygulamadaki durumu hakkında bilgi kodlamak için kullanılır; Örneğin, bulunan sayfa veya görünüm gibi kimlik doğrulama isteği gerçekleştirilmeden önce.

Bu noktada, Azure AD yalnızca kiracı yöneticisinin isteği tamamlamada oturum açmasını zorunlu kılar. Yönetici, uygulama kayıt portalı 'nda uygulamanız için istediğiniz tüm doğrudan uygulama izinlerini onaylaması istenecektir.

Başarılı yanıt

Yönetici, uygulamanız için izinleri onayladığında, başarılı yanıt şöyle görünür:

GET http://localhost/myapp/permissions?tenant=a8990e1f-ff32-408a-9f8e-78d3b9139b95&state=state=12345&admin_consent=True
Parametre Açıklama
tenant Uygulamanıza, istenen izinleri (GUID biçiminde) vermiş olan dizin kiracısı.
state İstekte, belirteç yanıtında döndürülen bir değer. İstediğiniz herhangi bir içerik dizesi olabilir. Durum, kullanıcının uygulamadaki durumu hakkında bilgi kodlamak için kullanılır; Örneğin, bulunan sayfa veya görünüm gibi kimlik doğrulama isteği gerçekleştirilmeden önce.
admin_consent True olarak ayarlayın.
Hata yanıtı

Yönetici, uygulamanız için izinleri onaylamadıysanız, başarısız yanıt şöyle görünür:

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
Parametre Açıklama
error Hata türlerini sınıflandırmak için kullanabileceğiniz ve hatalara tepki olarak kullanabileceğiniz bir hata kodu dizesi.
error_description Hatanın kök nedenini tanımlamanıza yardımcı olacak belirli bir hata iletisi.

Uygulama sağlama uç noktasına başarılı bir yanıt verdikten sonra, uygulamanız istenen doğrudan uygulama izinlerini elde etti. Artık istediğiniz kaynak için bir belirteç isteğide bulundurebilirsiniz.

Belirteç alın

Uygulamanız için gerekli yetkilendirmeyi edindikten sonra API'ler için erişim belirteçleri almakla devam edin. İstemci kimlik bilgileri iznini kullanarak belirteç almak için aşağıdaki sunucuya bir POST /token Microsoft kimlik platformu:

İpucu

Bu isteği Postman'de yürütmeyi deneyin! (En iyi sonuçlar için kendi uygulama kimliğinizi kullanın; öğretici uygulaması yararlı izinler talep etmez.)  Bu isteği Postman'de çalıştırmayı deneyin

İlk durum: Paylaşılan gizli bir gizli dosya ile belirteç isteğine erişme

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=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=sampleCredentia1s
&grant_type=client_credentials
# Replace {tenant} with your tenant!
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'client_id=535fb089-9ff3-47b6-9bfb-4f1264799865&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default&client_secret=qWgdYAmab0YSkuL1qKv5bPX&grant_type=client_credentials' 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token'
Parametre Koşul Açıklama
tenant Gerekli Uygulamanın GUID veya etki alanı adı biçiminde üzerinde çalışması planladığı dizin kiracısı.
client_id Gerekli Uygulamanıza atanan uygulama kimliği. Bu bilgileri, uygulamanızı kaydeden portalda bulabilirsiniz.
scope Gerekli Bu istekte parametresi için geçirilen değer, istediğiniz kaynağın kaynak tanımlayıcısı (uygulama kimliği URI'si) olmalı ve son scope .default eke ekli olmalıdır. Microsoft Graph değeri https://graph.microsoft.com/.default olur.
Bu değer Microsoft kimlik platformu uygulamanız için yapılandırmış olduğunu tüm doğrudan uygulama izinlerine göre belirtir. Uç nokta, kullanmak istediğiniz kaynakla ilişkilendirilmiş olanlar için bir belirteç verir. Kapsam hakkında daha fazla /.default bilgi edinmek için onay belgelerine bakın.
client_secret Gerekli Uygulama kayıt portalında uygulama için oluşturulan istemci gizli kodu. gönderilmeden önce istemci gizli adı URL ile kodlanmış olmalıdır.
grant_type Gerekli olarak ayarlanmış olması client_credentials gerekir.

İkinci durum: Sertifika ile belirteç isteğine erişme

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

scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=97e0a5b7-d745-40b6-94fe-5f77d35c6e05
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials
Parametre Koşul Açıklama
tenant Gerekli Uygulamanın GUID veya etki alanı adı biçiminde üzerinde çalışması planladığı dizin kiracısı.
client_id Gerekli Uygulamanıza atanan uygulama (istemci) kimliği.
scope Gerekli Bu istekte parametresi için geçirilen değer, istediğiniz kaynağın kaynak tanımlayıcısı (uygulama kimliği URI'si) olmalı ve son scope .default eke ekli olmalıdır. Microsoft Graph değeri https://graph.microsoft.com/.default olur.
Bu değer, Microsoft kimlik platformu için yapılandırmış olduğunu ve kullanmak istediğiniz kaynakla ilişkili olanlar için bir belirteç ataması gerektiğini kullanıcıya bilgi verir. Kapsam hakkında daha fazla /.default bilgi edinmek için onay belgelerine bakın.
client_assertion_type Gerekli Değerin olarak ayarlanmış olması urn:ietf:params:oauth:client-assertion-type:jwt-bearer gerekir.
client_assertion Gerekli Uygulamanıza kimlik bilgileri olarak kaydolan sertifikayı oluşturmanız ve imzalamanız gereken bir onay (JSON web belirteci). Sertifikanızı kaydetmeyi ve onaylama biçimini öğrenmek için sertifika kimlik bilgileri hakkında bilgi okuyun.
grant_type Gerekli olarak ayarlanmış olması client_credentials gerekir.

Parametrelerin paylaşılan gizli bilgiyle yapılan istekle neredeyse aynı olduğunu, ancak client_secret parametresinin iki parametreyle değiştirildik: client_assertion_type ve client_assertion.

Başarılı yanıt

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

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}
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. Bu dosyanın desteklediği tek Microsoft kimlik platformu bearer türüdir.
expires_in Erişim belirtecin geçerli olduğu süre (saniye olarak).

Hata yanıtı

Hata yanıtı şöyle görünüyor:

{
  "error": "invalid_scope",
  "error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/.default 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"
}
Parametre Açıklama
error Oluşan hata türlerini sınıflandırmak ve hatalara tepki etmek için kullanabileceğiniz bir hata kodu dizesi.
error_description Kimlik doğrulama hatasının kök nedenini tanımlamanıza yardımcı olacak belirli bir hata iletisi.
error_codes Tanılamada yardımcı olacak STS'ye özgü hata kodlarının listesi.
timestamp Hatanın meydana geldiği saat.
trace_id Tanılamaya yardımcı olmak için isteğin benzersiz tanımlayıcısı.
correlation_id Bileşenler arasında tanılamaya yardımcı olmak için isteğin benzersiz tanımlayıcısı.

Belirteç kullanma

Artık bir belirteç edindildiniz, belirteci kullanarak kaynağa istekte bulundunız. Belirteci süresi dolduğunda, yeni bir erişim /token belirteci almak için uç noktasına isteği tekrarlayın.

GET /v1.0/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
# Pro tip: Try the following command! (Replace the token with your own.)

curl -X GET -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...." 'https://graph.microsoft.com/v1.0/me/messages'

Kod örnekleri ve diğer belgeler

Microsoft Kimlik Doğrulama Kitaplığı'nın istemci kimlik bilgilerine genel bakış belgelerini okuyun

Örnek Platform Açıklama
active-directory-dotnetcore-daemon-v2 .NET Core 2.1 Konsolu Microsoft Graph sorgusunu yapan bir kiracının kullanıcılarını görüntüleyen basit bir .NET Core uygulaması Graph kullanıcı adına değil uygulamanın kimliğini kullanır. Örnek ayrıca kimlik doğrulaması için sertifikaların nasıl kullanıla çeşitlek olduğunu da göstermektedir.
active-directory-dotnet-daemon-v2 ASP.NET MVC Microsoft Graph'den veri eşitlenen bir web uygulaması, kullanıcı adına değil uygulamanın kimliğini kullanarak.