Aracılığıyla paylaş

Microsoft kimlik platformu kapsamlar ve izinler

  • Makale

Microsoft kimlik platformu OAuth 2.0 yetkilendirme protokolunu uygular. OAuth 2.0, üçüncü taraf bir uygulamanın bir kullanıcı adına web'de barındırılan kaynaklara erişebildiği bir yöntemdir. Microsoft kimlik platformu ile tümleşen web'de barındırılan tüm kaynakların kaynak tanımlayıcısı veya uygulama kimliği URI'si vardır.

Bu makalede, kimlik platformundaki kapsamlar ve izinler hakkında bilgi edineceksiniz.

Aşağıdaki listede Microsoft web'de barındırılan kaynaklara ilişkin bazı örnekler gösterilmektedir:

  • Microsoft Graph: https://graph.microsoft.com
  • Microsoft 365 Posta API'si: https://outlook.office.com
  • Azure Key Vault: https://vault.azure.net

Aynı durum, Microsoft kimlik platformu tümleştirilen tüm üçüncü taraf kaynaklar için de geçerlidir. Bu kaynaklardan herhangi biri, bu kaynağın işlevselliğini daha küçük parçalara bölmek için kullanılabilecek bir izin kümesi de tanımlayabilir. Örnek olarak, Microsoft Graph'ın aşağıdaki görevleri yerine getirmek için diğerlerinin yanı sıra tanımlanmış izinleri vardır:

  • Kullanıcının takvimini okuma
  • Kullanıcının takvimine yazma
  • Postayı kullanıcı olarak gönderme

Bu tür izin tanımları nedeniyle kaynak, verileri ve API işlevselliğinin nasıl kullanıma sunulduğu üzerinde ayrıntılı denetime sahiptir. Üçüncü taraf bir uygulama, kullanıcılardan ve yöneticilerden bu izinleri isteyebilir. Bu izinler, uygulamanın verilere erişebilmesi veya kullanıcı adına işlem yapması için isteği onaylaması gerekir.

Bir kaynağın işlevselliği küçük izin kümelerinde öbeklendiğinde, üçüncü taraf uygulamalar yalnızca işlevlerini gerçekleştirmek için ihtiyaç duydukları izinleri istemek üzere oluşturulabilir. Kullanıcılar ve yöneticiler uygulamanın hangi verilere erişebileceğini bilir. Ayrıca uygulamanın kötü amaçlı hareket etmediğinden daha emin olabilirler. Geliştiriciler her zaman en az ayrıcalık ilkesine uymalı ve yalnızca uygulamalarının çalışması için gereken izinleri istemelidir.

OAuth 2.0'da bu tür izin kümeleri kapsam olarak adlandırılır. Bunlar genellikle izinler olarak da adlandırılır. Microsoft kimlik platformu, bir izin dize değeri olarak temsil edilir. Bir uygulama, sorgu parametresinde izni belirterek gereken izinleri istemektedir scope . Kimlik platformu çeşitli iyi tanımlanmış OpenID Connect kapsamlarını ve kaynak tabanlı izinleri destekler (her izin, kaynağın tanımlayıcısına veya uygulama kimliği URI'sine izin değeri eklenerek belirtilir). Örneğin, izin dizesi https://graph.microsoft.com/Calendars.Read Microsoft Graph'ta kullanıcı takvimlerini okumak için izin istemek için kullanılır.

Yetkilendirme sunucusuna yapılan isteklerde, Microsoft kimlik platformu için kaynak tanımlayıcısı kapsam parametresinde atlanırsa, kaynağın Microsoft Graph olduğu varsayılır. Örneğin scope=User.Read ile https://graph.microsoft.com/User.Read eşdeğerdir.

Yönetici tarafından kısıtlanmış izinler

Microsoft kimlik platformu izinler yönetici kısıtlanmış olarak ayarlanabilir. Örneğin, daha yüksek ayrıcalıklı microsoft graph izinlerinin çoğu yönetici onayı gerektirir. Uygulamanız yönetici tarafından kısıtlanmış izinlere ihtiyaç duyuyorsa, kuruluşun yöneticisinin bu kapsamları kuruluşun kullanıcıları adına onaylaması gerekir. Aşağıdaki bölümde bu tür izinlerin örnekleri verilmiştir:

  • User.Read.All: Kullanıcının tüm profillerini okuma
  • Directory.ReadWrite.All: Bir kuruluşun dizinine veri yazma
  • Groups.Read.All: Kuruluşun dizinindeki tüm grupları okuma

Not

Microsoft kimlik platformu yetkilendirme, belirteç veya onay uç noktalarına yönelik isteklerde, kaynak tanımlayıcısı kapsam parametresinde atlanırsa kaynağın Microsoft Graph olduğu varsayılır. Örneğin scope=User.Read ile https://graph.microsoft.com/User.Read eşdeğerdir.

Tüketici kullanıcı bu tür verilere uygulamaya erişim izni verse de kuruluş kullanıcıları aynı hassas şirket verileri kümesine erişim izni veremez. 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.

Uygulama uygulama izinleri isterse ve bir yönetici bu izinleri verirse, bu izin belirli bir kullanıcı adına yapılmaz. Bunun yerine istemci uygulamasına doğrudan izinler verilir. Bu tür izinler yalnızca arka planda çalışan daemon hizmetleri ve diğer etkileşimli olmayan uygulamalar tarafından kullanılmalıdır. Doğrudan erişim senaryosu hakkında daha fazla bilgi için Microsoft kimlik platformu erişim senaryoları bölümüne bakın.

Web API'sinde kapsamları kullanıma sunma hakkında adım adım kılavuz için bkz . Web API'sini kullanıma açmak için uygulama yapılandırma.

OpenID Connect kapsamları

OpenID Connect'in Microsoft kimlik platformu uygulaması, Microsoft Graph'ta da barındırılan birkaç iyi tanımlanmış kapsama sahiptir: openid, email, profileve offline_access. address ve phone OpenID Connect kapsamları desteklenmez.

OpenID Connect kapsamlarını ve belirteci isterseniz, UserInfo uç noktasını çağırmak için bir belirteç alırsınız.

Kapsam openid

Bir uygulama OpenID Connect kullanarak oturum açarsa kapsamı istemesi openid gerekir. Kapsam, openid iş hesabı onay sayfasında Oturum açma izni olarak görünür.

Bu izni kullanarak bir uygulama, talep biçiminde sub kullanıcı için benzersiz bir tanımlayıcı alabilir. İzin, uygulamaya UserInfo uç noktasına da erişim verir. Kapsam, openid kimlik belirteçlerini almak için Microsoft kimlik platformu belirteci uç noktasında kullanılabilir. Uygulama kimlik doğrulaması için bu belirteçleri kullanabilir.

Kapsam email

Kapsam, email kapsam ve diğer kapsamlarla openid birlikte kullanılabilir. Uygulamaya kullanıcının birincil e-posta adresine talep biçiminde email erişim verir.

Talep email , belirteçte yalnızca kullanıcı hesabıyla ilişkili bir e-posta adresi varsa eklenir ve bu her zaman böyle değildir. Uygulamanız kapsamı kullanıyorsa email , uygulamanın belirteçte talep bulunmayan email bir olayı işleyebilmesi gerekir.

Kapsam profile

Kapsam, profile kapsam ve diğer kapsamlarla openid birlikte kullanılabilir. Uygulamaya kullanıcı hakkında büyük miktarda bilgiye erişim sağlar. Erişebileceği bilgiler kullanıcının verilen adını, soyadını, tercih edilen kullanıcı adını ve nesne kimliğini içerir ancak bunlarla sınırlı değildir.

Belirli bir kullanıcı için parametresinde bulunan taleplerin profile id_tokens tam listesi için başvuruya id_tokensbakın.

Kapsam offline_access

Kapsam, offline_access uygulamanızın uzun bir süre boyunca kullanıcı adına kaynaklara erişmesini sağlar. Onay sayfasında bu kapsam, erişim izni verdiğiniz verilere erişimi koru olarak görünür.

Kullanıcı kapsamı onayladığında offline_access uygulamanız Microsoft kimlik platformu belirteç uç noktasından yenileme belirteçleri alabilir. Yenileme belirteçleri uzun ömürlü. Uygulamanız, eskilerinin süresi dolduğunda yeni erişim belirteçleri alabilir.

Not

Bu izin şu anda yenileme belirteci sağlamayan akışlar (örtük akış gibi) için bile tüm onay sayfalarında görünür. Bu kurulum, bir istemcinin örtük akış içinde başlayıp yenileme belirtecinin beklendiği kod akışına geçebileceği senaryoları ele alır.

Microsoft kimlik platformu (v2.0 uç noktasına yapılan istekler), uygulamanızın offline_access yenileme belirteçlerini almak için kapsamı açıkça istemesi gerekir. Bu nedenle, OAuth 2.0 yetkilendirme kodu akışında bir yetkilendirme kodu kullandığınızda, yalnızca uç noktadan bir erişim belirteci /token alırsınız.

Erişim belirteci genellikle yaklaşık bir saat geçerlidir. Bu noktada uygulamanızın yeni yetkilendirme kodu istemek için /authorize kullanıcıyı uç noktaya yeniden yönlendirmesi gerekir. Bu yeniden yönlendirme sırasında ve uygulama türüne bağlı olarak kullanıcının kimlik bilgilerini yeniden girmesi veya izinleri yeniden onaylaması gerekebilir.

Yenileme belirtecinin süresi erişim belirtecinden daha uzundur ve genellikle bir gün boyunca geçerlidir. Yenileme belirteçlerini alma ve kullanma hakkında daha fazla bilgi için Microsoft kimlik platformu protokolü başvurusuna bakın.

Yenileme belirtecinin yanıta eklenmesi, uygulamanızın belirli yapılandırması ve yetkilendirme işlemi sırasında istenen kapsamlar dahil olmak üzere çeşitli faktörlere bağlı olabilir. Yanıtta bir yenileme belirteci almayı bekliyor ancak alamazsanız aşağıdaki faktörleri göz önünde bulundurun:

  • Kapsam gereksinimleri: Kapsamları ve diğer gerekli kapsamları istediğinizden offline_access emin olun.
  • Yetkilendirme verme türü: Yenileme belirteci genellikle yetkilendirme kodu verme türü kullanılırken sağlanır. Akışınız farklıysa yanıtı etkileyebilir.
  • İstemci yapılandırması: Kimlik platformunda uygulamanızın ayarlarını denetleyin. Bazı yapılandırmalar refresh_tokens verilmesini kısıtlayabilir.

Kapsam .default

Kapsam .default , belirli izinleri tanımlamadan bir istekteki bir kaynak hizmetine (API) genel olarak başvurmak için kullanılır. Onay gerekiyorsa, uygulama kaydında listelenen tüm gerekli izinler (listedeki tüm API'ler için) için onay istenmesi gerektiğini belirten sinyaller kullanılır .default .

Kapsam parametresi değeri, kaynak ve .defaultiçin tanımlayıcı URI'si kullanılarak, eğik çizgi (/ ) ile ayrılmış olarak oluşturulur. Örneğin, kaynağın tanımlayıcı URI'si ise https://contoso.comistek kapsamı olur https://contoso.com/.default. Belirteci doğru şekilde istemek için ikinci bir eğik çizgi eklemeniz gereken durumlar için, sondaki eğik çizgi hakkındaki bölüme bakın.

kullanımı scope={resource-identifier}/.default , işlevsel olarak v1.0 uç noktasıyla aynıdır resource={resource-identifier} (burada {resource-identifier} API'nin tanımlayıcı URI'sidir, örneğin https://graph.microsoft.com Microsoft Graph).

Kapsam.default, herhangi bir OAuth 2.0 akışında ve yönetici onayı başlatmak için kullanılabilir. Bunun kullanımı, Adına Bağlı akışında ve istemci kimlik bilgileri akışında gereklidir.

İstemciler, statik (.default) onay ile dinamik onayı tek bir istekte birleştiremez. Bu nedenle scope=https://graph.microsoft.com/.default Mail.Read , kapsam türlerini birleştirdiğinden bir hatayla sonuçlanır.

Kapsam .default parametresi yalnızca, oturum açmış kullanıcı adına istemci ile kaynak arasında herhangi bir temsilci izni verilmemişse bir onay istemi tetikler.

Onay varsa, döndürülen belirteç oturum açmış kullanıcı için bu kaynak için verilen tüm kapsamları içerir. Ancak, istenen kaynak için izin verilmediyse (veya parametresi sağlanmışsa prompt=consent ), istemci uygulama kaydında yapılandırılan tüm gerekli izinler için listedeki tüm API'ler için bir onay istemi gösterilir.

Örneğin, kapsam https://graph.microsoft.com/.default istenirse uygulamanız Microsoft Graph API'si için bir erişim belirteci talep eder. Oturum açmış kullanıcı adına Microsoft Graph için en az bir temsilci izni verilmişse, oturum açma devam eder ve bu kullanıcı için verilmiş olan tüm Microsoft Graph temsilci izinleri erişim belirtecinde yer alır. İstenen kaynak için izin verilmediyse (bu örnekte Microsoft Graph), listedeki tüm API'ler için uygulamada yapılandırılmış tüm gerekli izinler için bir onay istemi sunulur.

Örnek 1: Kullanıcı veya kiracı yöneticisi izinler verdi

Bu örnekte, kullanıcı veya kiracı yöneticisi istemciye ve User.Read Microsoft Graph izinlerini vermişMail.Read.

İstemci isterse scope=https://graph.microsoft.com/.default, istemci uygulamasının Microsoft Graph için kayıtlı izinlerinin içeriği ne olursa olsun hiçbir onay istemi gösterilmez. Döndürülen belirteç ve User.Readkapsamlarını Mail.Read içerir.

Örnek 2: Kullanıcı istemci ile kaynak arasında izin vermemiş

Bu örnekte, kullanıcı istemci ile Microsoft Graph arasında onay vermemiş veya bir yöneticisi yoktur. İstemci ve Contacts.Readizinleri User.Read için kaydoldu. Ayrıca Azure Key Vault kapsamına https://vault.azure.net/user_impersonationda kaydolmlenmiştir.

İstemci için scope=https://graph.microsoft.com/.defaultbir belirteç istediğinde, kullanıcı Microsoft Graph User.Read ve kapsamları ve Contacts.Read Azure Key Vault user_impersonation kapsamı için bir onay sayfası görür. Döndürülen belirteç yalnızca User.Read ve Contacts.Read kapsamlarını içerir ve yalnızca Microsoft Graph'ta kullanılabilir.

Örnek 3: Kullanıcı onay vermiş ve istemci daha fazla kapsam istemektedir

Bu örnekte, kullanıcı istemci için zaten onay vermiş Mail.Read . İstemci kapsam için kaydolms.Contacts.Read

İstemci ilk olarak ile scope=https://graph.microsoft.com/.defaultoturum açar. Yanıtın scopes parametresine bağlı olarak, uygulamanın kodu yalnızca Mail.Read verilmiş olduğunu algılar. İstemci daha sonra kullanarak scope=https://graph.microsoft.com/.defaultikinci bir oturum açma işlemi başlatır ve bu kez kullanarak prompt=consentonayı zorlar. Kullanıcının uygulamanın kaydettiği tüm izinler için onay vermesine izin verilirse, onay istemi gösterilir. (Aksi takdirde, bir hata iletisi veya yönetici onayı istek formu gösterilir.) hem hem Mail.Read de Contacts.Read onay isteminde olacaktır. Onay verilirse ve oturum açma işlemi devam ederse, döndürülen belirteç Microsoft Graph içindir ve ve Contacts.ReadiçerirMail.Read.

.default İstemci ile kapsamı kullanma

Bazı durumlarda, bir istemci kendi .default kapsamını isteyebilir. Aşağıdaki örnekte bu senaryo gösterilmektedir.

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
    ?response_type=token            //Code or a hybrid flow is also possible here
    &client_id=00001111-aaaa-2222-bbbb-3333cccc4444
    &scope=9ada6f8a-6d83-41bc-b169-a306c21527a5/.default
    &redirect_uri=https%3A%2F%2Flocalhost
    &state=1234

Bu kod örneği, önceki onay açıklamaları ve senaryo için geçerliyse tüm kayıtlı izinler için bir onay .default sayfası oluşturur. Ardından kod, erişim belirteci yerine bir döndürür id_token.

Bu kurulum, Microsoft kimlik platformu hedefleyen yeni istemciler tarafından kullanılmamalıdır. Azure AD Kimlik Doğrulama Kitaplığı'ndan (ADAL) Microsoft Kimlik Doğrulama Kitaplığı'na (MSAL) geçiş yapmaya dikkat edin.

İstemci kimlik bilgileri verme akışı ve .default

Başka bir kullanımı.default, web API'sini çağırmak için istemci kimlik bilgileri verme akışını kullanan bir daemon uygulaması gibi etkileşimli olmayan bir uygulamada uygulama rolleri (uygulama izinleri olarak da bilinir) istemektir.

Bir web API'sine yönelik uygulama rollerini (uygulama izinleri) tanımlamak için bkz . Uygulamanıza uygulama rolleri ekleme.

İstemci hizmetinizdeki istemci kimlik bilgileri istekleri içermelidirscope={resource}/.default. Burada, {resource} uygulamanızın çağırmak istediği ve erişim belirteci almak istediği web API'sini bulabilirsiniz. Tek tek uygulama izinlerini (rolleri) kullanarak istemci kimlik bilgileri isteği verme desteklenmez. Bu web API'sine verilen tüm uygulama rolleri (uygulama izinleri) döndürülen erişim belirtecinde yer alır.

Uygulama için yönetici onayı vermek de dahil olmak üzere tanımladığınız uygulama rollerine erişim izni vermek için bkz . İstemci uygulamasını web API'sine erişecek şekilde yapılandırma.

Sondaki eğik çizgi ve .default

Bazı kaynak URI'leri, örneğin https://contoso.com/ yerine sondaki eğik çizgiye https://contoso.comsahiptir. Sondaki eğik çizgi, belirteç doğrulamasıyla ilgili sorunlara neden olabilir. Sorunlar öncelikle Azure Resource Manager (https://management.azure.com/) için belirteç istendiğinde oluşur.

Bu durumda, kaynak URI'sinde sondaki eğik çizgi, belirteç istendiğinde eğik çizginin mevcut olması gerektiği anlamına gelir. Bu nedenle için https://management.azure.com/ bir belirteç istediğinizde ve kullandığınızda .defaultisteğinde https://management.azure.com//.default bulunmanız gerekir (çift eğik çizgiye dikkat edin!).

Genel olarak belirtecin verildiğini doğrularsanız ve belirtecin kabul etmesi gereken API tarafından reddediliyorsa ikinci bir eğik çizgi eklemeyi ve yeniden denemeyi göz önünde bulundurun.

Ayrıca bkz.