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

OAuth 2.0 istemci kimlik bilgileri verme akışı, bir web hizmetinin (gizli istemci) bir kullanıcının kimliğine bürünmek yerine kendi kimlik bilgilerini kullanmasına izin verir. Rfc 6749'da belirtilen ve bazen iki bacaklı OAuth olarak da adlandırılan izin, 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şim olmadan arka planda çalışması gereken sunucudan sunucuya etkileşimler için kullanılır ve genellikle daemon veyahizmet 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 eylem gerçekleştirme yetkisine sahip olmasını zorlar. Bu makalede aşağıdakiler için gereken her iki adım da yer almaktadır:

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 aramak 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 hiçbir zaman olarak client_id verilmez ve client_secret (yenileme belirtecini almak için gerekli olacaktır) 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 gizli dizi yerine sertifika veya federasyon kimlik bilgileri kullanarak kimlik doğrulaması yapmasına da olanak tanır. 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ış bir yerel uygulamada kullanmayı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.

Diagram showing the client credentials flow

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, Microsoft Entra Id'de en yaygın kullanılan yöntemdir 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 mantıklı yöntemi seçebilir.

Erişim denetim listeleri

Bir kaynak sağlayıcısı, tanıdığı ve belirli bir erişim düzeyi veren uygulama (istemci) kimliklerinin listesine göre yetkilendirme denetimini zorunlu kabilir. 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 denetimi 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 testleri ç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, ACL'yi test istemcisinin uygulama kimliği için API'nin tüm işlevselliğine tam erişim için denetler. 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 Microsoft Entra Id, uygulamaların başka bir uygulama için belirteç alma yetkisine sahip olmasını gerektirmez. Bu nedenle, yalnızca uygulama belirteçleri talep roles edilmeden yayımlanabilir. 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 İZİNLERİ

ACL'leri kullanmak yerine, bir dizi uygulama iznini kullanıma açmak için API'leri kullanabilirsiniz. Bunlar bir kuruluş yöneticisi tarafından bir uygulamaya verilir ve yalnızca söz konusu kuruluşa ve çalışanlarına ait 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 okuma

Uygulama rollerini (uygulama izinleri) kendi API'nizle (Microsoft Graph'ın aksine) kullanmak için, önce uygulama rollerini Microsoft Entra yönetim merkezindeki API'nin uygulama kaydında 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 herhangi bir uygulama rolü göstermediyseniz, istemci uygulamanızın Microsoft Entra yönetim merkezindeki 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. 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 genellikle 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ıyı oturum 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=535fb089-9ff3-47b6-9bfb-4f1264799865
&state=12345
&redirect_uri=http://localhost/myapp/permissions

Profesyonel ipucu: Aşağıdaki isteği bir tarayıcıya yapıştırmayı deneyin.

https://login.microsoftonline.com/common/adminconsent?client_id=535fb089-9ff3-47b6-9bfb-4f1264799865&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 Zorunlu Microsoft Entra yönetim merkezinin uygulamanıza atanmış Uygulama kayıtları deneyimi olan Uygulama (istemci) kimliği.
redirect_uri Zorunlu Uygulamanızın işlemesi için yanıtın gönderilmesini istediğiniz yeniden yönlendirme URI'si. Url ile kodlanmış olması ve ek yol kesimlerine sahip olması dışında portalda kaydettiğiniz yeniden yönlendirme URI'lerinden biriyle tam olarak eşleşmelidir.
state Önerilir İ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 kodlamak için kullanılır( örneğin, üzerinde bulunduğu sayfa veya görünüm).

Bu noktada Microsoft Entra Id, 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 kodlamak için kullanılır( örneğin, üzerinde bulunduğu sayfa veya görünüm).
admin_consent True olarak ayarlayın.
Hata yanıtı

Yönetici uygulamanızın izinlerini onaylamıyorsa, 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 almaya devam edin. İstemci kimlik bilgileri verme işlemini 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 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

client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=sampleCredentials
&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ışmak üzere planladığı dizin kiracısı.
client_id Zorunlu Uygulamanıza atanan uygulama kimliği. Bu bilgileri uygulamanızı kaydettiğiniz portalda bulabilirsiniz.
scope Zorunlu 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ı ve sonekle .default birlikte 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 bildirir. Kapsam hakkında /.default daha fazla bilgi edinmek için onay belgelerine bakın.
client_secret Zorunlu 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ğrulama deseni de desteklenir.
grant_type Zorunlu olarak ayarlanmalıdır client_credentials.

İkinci durum: Sertifika ile 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
tenant Gerekli Uygulamanın GUID veya etki alanı adı biçiminde üzerinde çalışmak üzere planladığı dizin kiracısı.
client_id Zorunlu Uygulamanıza atanan uygulama (istemci) kimliği.
scope Zorunlu 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ı ve sonekle .default birlikte 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 bildirir. Kapsam hakkında /.default daha fazla bilgi edinmek için onay belgelerine bakın.
client_assertion_type Zorunlu Değeri olarak urn:ietf:params:oauth:client-assertion-type:jwt-bearerayarlanmalıdır.
client_assertion Zorunlu Uygulamanız için kimlik bilgileri olarak kaydettiğiniz sertifikayı oluşturmanız ve bu sertifikayla 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 Zorunlu 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ü kimlik federasyonu hakkında bilgi edinin.

İstekteki her şey sertifika tabanlı akışla aynıdır ve kaynağının ö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çinde 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 için 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 6.0+ Kullanıcı adına değil, uygulamanın kimliğini kullanarak Microsoft Graph'i sorgulayan bir kiracının kullanıcılarını görüntüleyen bir ASP.NET Core uygulaması. Örnek ayrıca kimlik doğrulaması için sertifikaların kullanıldığı varyasyonu gösterir.
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ı