Microsoft kimlik platformu ve OAuth 2.0 istemcisi kimlik bilgileri akışı

  • Makale

OAuth 2.0 istemci kimlik bilgileri verme akışı, bir web hizmetinin (gizli istemci) başka bir web hizmetini çağırırken kimlik doğrulaması için kullanıcının kimliğine bürünmek yerine kendi kimlik bilgilerini kullanmasına izin verir. RFC 6749'da belirtilen ve bazen iki ayaklı OAuth olarak da adlandırılan verme, bir uygulamanın kimliği kullanılarak web'de barındırılan kaynaklara erişmek için kullanılabilir. Bu tür genellikle bir kullanıcıyla hemen etkileşime gerek kalmadan arka planda çalışması gereken sunucudan sunucuya etkileşimler için kullanılır ve genellikle daemon'lar veya hizmet hesapları olarak adlandırılır.

İstemci kimlik bilgileri akışında, izinler bir yönetici tarafından doğrudan uygulamanın kendisine verilir. Uygulama bir kaynağa belirteç sunduğunda, kimlik doğrulamasına dahil olan bir kullanıcı olmadığından, kaynak uygulamanın kendisinin bir eylem gerçekleştirme yetkisine sahip olmasını zorlar. Bu makalede aşağıdakiler için gereken her iki adım da yer alınıyor:

Bu makalede uygulamanızda doğrudan protokol için programlama işlemi açıklanır. Mümkün olduğunda, belirteçleri almak ve güvenli web API'lerini çağırmak için bunun yerine desteklenen Microsoft Kimlik Doğrulama Kitaplıklarını (MSAL) kullanmanızı öneririz. MSAL kullanan örnek uygulamalara da başvurabilirsiniz. Yan not olarak, yenileme belirteçleri bu akışla birlikte hiçbir zaman olarak client_id verilmez ve client_secret (yenileme belirteci almak için bu gereklidir) bunun yerine erişim belirteci almak için kullanılabilir.

Daha yüksek bir güvence düzeyi için, Microsoft kimlik platformu çağrı hizmetinin paylaşılan bir gizli dizi yerine sertifika veya federasyon kimlik bilgileri kullanarak kimlik doğrulaması yapmasına da izin verir. Uygulamanın kendi kimlik bilgileri kullanıldığından, bu kimlik bilgilerinin güvende tutulması gerekir. Bu kimlik bilgilerini asla kaynak kodunuzda yayımlamayın, web sayfalarına eklemeyin veya yaygın olarak dağıtılmış yerel bir uygulamada kullanmayın.

İpucu

Bu isteği Postman'da çalıştırmayı deneyin
Postman'de bu isteği ve daha fazlasını yürütmeyi deneyin. Belirteçleri ve kimlikleri değiştirmeyi unutmayın!

Protokol diyagramı

İstemci kimlik bilgileri akışının tamamı aşağıdaki diyagrama benzer şekilde görünür. Bu makalenin devamında adımların her birini açıklıyoruz.

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

Doğrudan yetkilendirme alma

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

Bu iki yöntem Azure AD'de en yaygın olanıdır ve istemci kimlik bilgileri akışını gerçekleştiren istemciler ve kaynaklar için bunları öneririz. Bir kaynak, istemcilerini başka yollarla yetkilendirmeyi de seçebilir. Her kaynak sunucusu, uygulaması için en anlamlı yöntemi seçebilir.

Erişim denetimi listeleri

Bir kaynak sağlayıcısı, tanıdığı ve belirli bir erişim düzeyi veren uygulama (istemci) kimliklerinin listesine göre yetkilendirme denetimi uygulayabilir. Kaynak Microsoft kimlik platformu bir belirteç aldığında, belirtecin kodunu çözerek ve iss taleplerinden istemcinin appid uygulama kimliğini ayıklayabilir. Ardından, uygulamayı koruduğu bir erişim denetim listesiyle (ACL) 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 bir kullanım örneği, web uygulaması veya web API'sine yönelik testler çalıştırmak için ACL kullanmaktır. Web API'si belirli bir istemciye yalnızca bir alt küme tam izin verebilir. API'de uçtan uca testler çalıştırmak için, Microsoft kimlik platformu belirteçleri alan ve sonra bunları API'ye gönderen bir test istemcisi oluşturabilirsiniz. Ardından API, TEST istemcisinin uygulama kimliğinin ACL'sini denetleerek API'nin tüm işlevselliğine tam erişim sağlar. Bu tür bir ACL kullanıyorsanız, yalnızca çağıranın appid değerini değil, aynı zamanda belirtecin değerine güvenildiğini iss de doğruladığınızdan emin olun.

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

Talep olmadan roles belirteçleri denetleme

Bu ACL tabanlı yetkilendirme düzenini etkinleştirmek için Azure AD uygulamaların başka bir uygulama için belirteç alma yetkisine sahip olmasını gerektirmez. Bu nedenle, yalnızca uygulama belirteçleri bir roles talep olmadan oluşturulabilir. API'leri kullanıma sunan uygulamaların belirteçleri kabul etmek için izin denetimleri uygulaması gerekir.

Uygulamaların uygulamanız için rolsiz yalnızca uygulama erişim belirteçleri almasını engellemek istiyorsanız, uygulamanız için atama gereksinimlerinin etkinleştirildiğinden emin olun. Bu, rolleri atanmamış kullanıcıların ve uygulamaların bu uygulama için belirteç alabilmesini engeller.

Uygulama izinleri

ACL'leri kullanmak yerine, bir dizi uygulama iznini kullanıma açmak için API'leri kullanabilirsiniz. Bunlar bir uygulamaya kuruluşun yöneticisi tarafından verilir ve yalnızca söz konusu kuruluşun ve çalışanlarının sahip olduğu verilere erişmek için kullanılabilir. Örneğin, Microsoft Graph aşağıdakileri yapmak için çeşitli uygulama izinlerini kullanıma sunar:

  • Tüm posta kutularında posta okuma
  • Tüm posta kutularında posta okuma ve yazma
  • Postayı herhangi bir kullanıcı olarak gönderme
  • Dizin verilerini oku

Uygulama rollerini (uygulama izinleri) kendi API'nizle kullanmak için (Microsoft Graph'ın aksine), önce Azure portal API'nin uygulama kaydındaki uygulama rollerini kullanıma sunmanız gerekir. Ardından, istemci uygulamanızın uygulama kaydında bu izinleri seçerek gerekli uygulama rollerini yapılandırın . API'nizin uygulama kaydında hiçbir uygulama rolü göstermediyseniz, Azure portal istemci uygulamanızın uygulama kaydında bu API'ye yönelik uygulama izinlerini belirtemezsiniz.

Uygulama olarak kimlik doğrulaması yaparken (kullanıcı yerine), uygulamanızın adına hareket etmesi gereken kullanıcı olmadığından temsilci izinlerini kullanamazsınız. Yönetici veya API'nin sahibi tarafından verilen uygulama rolleri olarak da bilinen uygulama izinlerini kullanmanız gerekir.

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

Genellikle, uygulama izinlerini 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ı veya ayrılmış bir bağlantı akışı olabilir. Genellikle uygulamanın bu bağlantı görünümünü yalnızca bir kullanıcı iş veya okul Microsoft hesabıyla oturum açtıktan sonra göstermesi mantıklıdır.

Kullanıcıyı uygulamanızda oturum açarsanız, kullanıcıdan uygulama izinlerini onaylamasını istemeden önce kullanıcının ait olduğu kuruluşu tanımlayabilirsiniz. Kesinlikle gerekli olmasa da, kullanıcılarınız için daha sezgisel bir deneyim oluşturmanıza yardımcı olabilir. Kullanıcının oturumunu açmak için Microsoft kimlik platformu protokolü öğreticilerini izleyin.

Dizin yöneticisinden izin isteme

Kuruluşun yöneticisinden izin istemeye hazır olduğunuzda kullanıcıyı Microsoft kimlik platformu yönetici onayı uç noktasına yönlendirebilirsiniz.

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

Profesyonel 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ıyla oturum açması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şlemesi için yanıtın gönderilmesini istediğiniz yeniden yönlendirme URI'si. Portalda kaydettiğiniz yeniden yönlendirme URI'lerinden biriyle tam olarak eşleşmelidir, ancak URL ile kodlanmış olması gerekir ve ek yol kesimleri olabilir.
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. Durum, kimlik doğrulama isteği gerçekleşmeden önce kullanıcının uygulamadaki durumuyla ilgili bilgileri (örneğin, bulunduğu sayfa veya görünüm) kodlamak için kullanılır.

Bu noktada, Azure AD isteği tamamlamak için yalnızca bir kiracı yöneticisinin oturum açabilmesini zorunlu kılabilir. Yöneticiden uygulama kayıt portalında uygulamanız için istediğiniz tüm doğrudan uygulama izinlerini onaylaması istenir.

Başarılı yanıt

Yönetici uygulamanızın izinlerini onaylarsa 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 istediği izinleri GUID biçiminde veren dizin kiracısı.
state İstekte bulunan ve belirteç yanıtında da döndürülen bir değer. İstediğiniz herhangi bir içeriğin dizesi olabilir. Durum, kimlik doğrulama isteği gerçekleşmeden önce kullanıcının uygulamadaki durumuyla ilgili bilgileri (örneğin, bulunduğu sayfa veya görünüm) kodlamak için kullanılır.
admin_consent True olarak ayarlayın.
Hata yanıtı

Yönetici uygulamanızın izinlerini onaylamazsa 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 vermek için kullanabileceğiniz bir hata kodu dizesi.
error_description Hatanın kök nedenini belirlemenize yardımcı olabilecek belirli bir hata iletisi.

Uygulama sağlama uç noktasından başarılı bir yanıt aldıktan sonra uygulamanız istediği doğrudan uygulama izinlerine sahip olur. Artık istediğiniz kaynak için belirteç isteyebilirsiniz.

Belirteç alma

Uygulamanız için gerekli yetkilendirmeyi aldıktan sonra API'ler için erişim belirteçleri alma işlemine devam edin. İstemci kimlik bilgileri atamasını kullanarak belirteç almak için Microsoft kimlik platformu bir POST isteği /token gönderin. Birkaç farklı durum vardır:

İlk durum: Paylaşılan gizli diziyle erişim belirteci isteği

POST /{tenant}/oauth2/v2.0/token HTTP/1.1           //Line breaks for clarity
Host: login.microsoftonline.com:443
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ı planlandığı dizin kiracısı.
client_id Gerekli Uygulamanıza atanan uygulama kimliği. Bu bilgileri uygulamanızı kaydettiğiniz portalda bulabilirsiniz.
scope Gerekli Bu istekteki scope parametre için geçirilen değer, istediğiniz kaynağın kaynak tanımlayıcısı (uygulama kimliği URI'si) olmalıdır ve sonekle birlikte .default eklenmelidir. Dahil edilen tüm kapsamlar tek bir kaynak için olmalıdır. Birden çok kaynak için kapsamlar dahil olmak hataya neden olur.
Microsoft Graph örneği için değeri şeklindedir https://graph.microsoft.com/.default. Bu değer, uygulamanız için yapılandırdığınız tüm doğrudan uygulama izinlerinin Microsoft kimlik platformu uç noktanın kullanmak istediğiniz kaynakla ilişkili olanlar için bir belirteç vermesi gerektiğini belirtir. Kapsam hakkında /.default daha fazla bilgi edinmek için onay belgelerine bakın.
client_secret Gerekli Uygulama kayıt portalında uygulamanız için oluşturduğunuz istemci gizli dizisi. İstemci gizli dizisi gönderilmeden önce URL ile kodlanmış olmalıdır. Rfc 6749 başına Yetkilendirme üst bilgisinde kimlik bilgileri sağlamak yerine temel kimlik doğrulaması deseni de desteklenir.
grant_type Gerekli olarak ayarlanmalıdır client_credentials.

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

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity
Host: login.microsoftonline.com:443
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ı planlandığı dizin kiracısı.
client_id Gerekli Uygulamanıza atanan uygulama (istemci) kimliği.
scope Gerekli Bu istekteki scope parametre için geçirilen değer, istediğiniz kaynağın kaynak tanımlayıcısı (uygulama kimliği URI'si) olmalıdır ve sonekle birlikte .default eklenmelidir. Dahil edilen tüm kapsamlar tek bir kaynak için olmalıdır. Birden çok kaynak için kapsamlar dahil olmak hataya neden olur.
Microsoft Graph örneği için değeri şeklindedir https://graph.microsoft.com/.default. Bu değer, uygulamanız için yapılandırdığınız tüm doğrudan uygulama izinlerinin Microsoft kimlik platformu uç noktanın kullanmak istediğiniz kaynakla ilişkili olanlar için bir belirteç vermesi gerektiğini belirtir. Kapsam hakkında /.default daha fazla bilgi edinmek için onay belgelerine bakın.
client_assertion_type Gerekli Değer olarak urn:ietf:params:oauth:client-assertion-type:jwt-bearerayarlanmalıdır.
client_assertion Gerekli Uygulamanız için kimlik bilgileri olarak kaydettiğiniz 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 edinin.
grant_type Gerekli olarak ayarlanmalıdır client_credentials.

Sertifika tabanlı isteğin parametreleri paylaşılan gizli dizi tabanlı istekten yalnızca bir şekilde farklılık gösterir: client_secret parametresi ve client_assertion parametreleriyle client_assertion_type değiştirilir.

Üçüncü durum: Federasyon kimlik bilgileriyle erişim belirteci isteği

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity
Host: login.microsoftonline.com:443
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
client_assertion Gerekli Uygulamanızın Kubernetes gibi Microsoft kimlik platformu dışında başka bir kimlik sağlayıcısından aldığı onay (JWT veya JSON web belirteci). Bu JWT'nin özellikleri, uygulamanızda federasyon kimliği kimlik bilgileri olarak kaydedilmelidir. Diğer kimlik sağlayıcılarından oluşturulan onayları ayarlamayı ve kullanmayı öğrenmek için iş yükü kimliği federasyonu hakkında bilgi edinin.

İstekteki her şey sertifika tabanlı akışla aynıdır ve kaynağının çok önemli bir istisnası client_assertionvardır. Bu akışta uygulamanız JWT onayını oluşturmaz. Bunun yerine, uygulamanız başka bir kimlik sağlayıcısı tarafından oluşturulan bir JWT kullanır. Bu, başka bir kimlik platformundaki uygulama kimliğinizin Microsoft kimlik platformu içindeki belirteçleri almak için kullanıldığı iş yükü kimliği federasyonu olarak adlandırılır. Bu, işlemlerinizi Azure dışında barındırmak ancak Microsoft kimlik platformu tarafından korunan API'lere erişmek gibi bulutlar arası senaryolar için en uygun yöntemdir. Diğer kimlik sağlayıcıları tarafından oluşturulan gerekli JWT biçimi hakkında bilgi için onay biçimi hakkında bilgi edinin.

Başarılı yanıt

Herhangi bir yöntemden 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'sinde olduğu gibi güvenli kaynakta kimlik doğrulaması yapmak için bu belirteci kullanabilir.
token_type Belirteç türü değerini gösterir. Microsoft kimlik platformu tarafından desteklenen tek türdürbearer.
expires_in Erişim belirtecinin geçerli olduğu süre (saniye).

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'ye yönelik olmayan belirteçlerle ilgili belirli bilgileri varsaymayın.

Hata yanıtı

Hata yanıtı (400 Hatalı İstek) şöyle görünür:

{
  "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": "YYYY-MM-DD HH:MM:SSZ",
  "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 vermek için kullanabileceğiniz bir hata kodu dizesi.
error_description Kimlik doğrulama hatasının kök nedenini belirlemenize yardımcı olabilecek belirli bir hata iletisi.
error_codes Tanılamaya yardımcı olabilecek STS'ye özgü hata kodlarının listesi.
timestamp Hatanın oluştuğu zaman.
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ç edindiğinize göre, kaynağa istek göndermek için belirteci kullanın. Belirtecin süresi dolduğunda, yeni bir erişim belirteci almak için /token uç noktaya isteği yineleyin.

GET /v1.0/users HTTP/1.1
Host: graph.microsoft.com:443
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...

Belirteci kendi belirtecinizle değiştirerek terminalinizde aşağıdaki komutu deneyin.

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

Kod örnekleri ve diğer belgeler

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

Örnek Platform Açıklama
active-directory-dotnetcore-daemon-v2 .NET Core 6.0+ Bir kullanıcı adına değil, uygulamanın kimliğini kullanarak Microsoft Graph'ı sorgulayan bir kiracının kullanıcılarını görüntüleyen bir .NET Core uygulaması. Örnekte ayrıca kimlik doğrulaması için sertifikaların kullanıldığı varyasyon da gösterilmektedir.
active-directory-dotnet-daemon-v2 ASP.NET MVC Bir kullanıcı yerine uygulamanın kimliğini kullanarak Microsoft Graph'ten verileri eşitleyen bir web uygulaması.
ms-identity-javascript-nodejs-console Node.js Konsolu Uygulamanın kimliğini kullanarak Microsoft Graph'i sorgulayarak kiracının kullanıcılarını görüntüleyen bir Node.js uygulaması