Microsoft kimlik platformu kapsamlar ve izinler

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 ediniyorsunuz.

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

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

Aynı durum, Microsoft kimlik platformuyla tümleşen tüm üçüncü taraf kaynaklar için de geçerlidir. Bu kaynaklardan herhangi biri, bu kaynağın işlevselliğini daha küçük öbeklere bölen bir izin kümesi de tanımlayabilir. Örnek olarak , Microsoft Graph diğerlerinin yanı sıra aşağıdaki görevleri gerçekleştirme izinlerini tanımlar:

  • 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. Uygulama, verilere erişebilmek veya kullanıcı adına işlem yapabilmek için bu kişilerin 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 platformunda, izin bir 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.

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
  • Group.Read.All: Kuruluşun dizinindeki tüm grupları okuma

Note

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. Bu kapsamlar bazen isteğe bağlıdır ve kimlik belirtecini zenginleştirmek için dikkate alınır. Bu kapsamlar her zaman kullanıcıya onay isteminde ayrı satırlarda gösterilmez.

OpenID Connect kapsamlarını ve bir belirteci talep ederseniz, UserInfo uç noktasına erişmek için bir belirteç alırsınız.

Kapsam openid

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

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

Kapsam email

email kapsamı, openid kapsamı ve diğer kapsamlarla 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 email kapsamını kullanıyorsa, uygulamanın belirteçte email talep bulunmadığı bir durumu işleyebilmesi gerekir.

Kapsam profile

Kapsam, profile kapsam ile openid kapsamı ve diğer kapsamlar ile 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 profile parametresinde yer alan taleplerin tam listesini görmek için id_tokens bakın.

Kapsam offline_access

Kapsamoffline_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 sürdür izni olarak görünür.

Herhangi bir temsilci izni verildiğinde, offline_access örtük olarak sağlanır. Uygulamanın offline_access'e sahip olduğunu, herhangi bir temsilci izni verildiyse varsayabilirsiniz. Yenileme belirteçleri uzun ömürlü. Uygulamanız, eskilerinin süresi dolduğunda yeni erişim belirteçleri alabilir.

Note

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 platformunda (v2.0 uç noktasına yapılan isteklerde), uygulamanızın yenileme belirteçlerini almak için offline_access kapsamını açıkça talep etmesi gerekir. OAuth 2.0 yetkilendirme kodu akışında bir yetkilendirme kodu kullandığınızda, uç noktasından bir erişim belirteci alırsınız.

Erişim belirteci 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 90 gün 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ı bekliyorsanız ancak alamıyorsanız, aşağıdaki faktörleri göz önünde bulundurun:

  • Kapsam gereksinimleri: offline_access kapsamları ve diğer gerekli kapsamları istediğinizden emin olun.
  • Yetkilendirme verme türü: Yetkilendirme kodu verme türü kullanılırken yenileme belirteci sağlanır. Akışınız farklıysa yanıt etkilenebilir.
  • İ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. Doğru bir şekilde belirteci talep etmek için ikinci bir eğik çizgi eklemeniz gereken durumlar için, sondaki eğik çizgiler hakkında bölüme bakın.

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

Kapsam .default , herhangi bir OAuth 2.0 akışında ve yönetici onayı başlatmak için kullanılabilir. Kullanımı On-Behalf-Of akışı ve istemci kimlik bilgileri akışı 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.

.default kapsam parametresi, oturum açmış kullanıcı adına istemci ile kaynak arasında hiçbir yetkilendirilmiş izin verilmemiş olması durumunda, onay istemine yol açar.

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 prompt=consent parametresi sağlanmışsa), 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 verildiyse oturum açma işlemi devam eder. Bu kullanıcı için verilen 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ılan 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 Mail.Read ve User.Read Microsoft Graph izinlerini vermiştir.

İ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ç, Mail.Read ve User.Read kapsamlarını içerir.

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

Bu örnekte, ne kullanıcı ne de bir yönetici istemci ile Microsoft Graph arasında onay vermiştir. İstemci, User.Read ve Contacts.Read izinlerine kaydoldu ve https://vault.azure.net/user_impersonationAzure Key Vault kapsamına kaydedildi.

İstemci scope=https://graph.microsoft.com/.default için bir belirteç istediğinde, kullanıcı Microsoft Graph User.Read ve Contacts.Read kapsamları ile 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ı zaten Mail.Read istemci için onay vermiş. Müşteri Contacts.Read kapsamına kaydolmuş.

İstemci ilk olarak scope=https://graph.microsoft.com/.default ile oturum 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 izinleri onaylamasına izin veriliyorsa, ona onay istemi gösterilir. (Aksi takdirde, bir hata iletisi veya yönetici onayı isteği formu gösterilir.) Hem Contacts.Read hem de Mail.Read onay istemindedir. Onay verilirse ve oturum açma işlemi devam ederse, döndürülen belirteç Microsoft Graph içindir ve Mail.Read ile Contacts.Read içerir.

İstemciyle .default kapsamını 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

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

Microsoft kimlik platformunu hedefleyen yeni istemciler bu kurulumu kullanmamalıdır. Emin olun Azure AD Kimlik Doğrulama Kitaplığı'ndan (ADAL) Microsoft Kimlik Doğrulama Kitaplığı'na (MSAL) geçiş yapın.

İ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 hizmetinizde, istemci kimlik bilgileri talepleri 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, jeton 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, https://management.azure.com/ için bir belirteç istediğinizde ve .default kullandığınızda, https://management.azure.com//.default isteğinde 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 bakınız

  • Last updated on