Microsoft Kimlik Platformu'nda izin ve onay istemeye yönelik geliştirici kılavuzu

Microsoft kimlik platformundaki uygulamalar, gerekli kaynaklara veya API'lere erişim elde etmek için onay kullanır. Farklı uygulama senaryoları için farklı onay türleri daha iyidir. Uygulamanız için en iyi onay yaklaşımını seçmek, kullanıcılar ve kuruluşlarda daha başarılı olmasını sağlar.

Bu makalede, farklı onay türleri ve onay yoluyla uygulamanız için izin isteme hakkında bilgi edineceksiniz.

Uyarı

Dış kiracılardaki uygulamalar için müşteriler izinleri kendileri onaylayamaz. Bir yöneticinin, uygulamanın kaynaklara kendi adına erişmesi için onay vermesi gerekir. Daha fazla bilgi için bkz. Yönetici onayı verme.

Statik kullanıcı onayı senaryosunda, Microsoft Entra yönetim merkezinde uygulamanın yapılandırmasında ihtiyaç duyduğu tüm izinleri belirtmeniz gerekir. Kullanıcı (veya yönetici uygun şekilde) bu uygulama için onay vermiyorsa, Microsoft kimlik platformu kullanıcıdan şu anda onay sağlamasını ister.

Statik izinler, yöneticilerin kuruluştaki tüm kullanıcılar adına onay vermesine de olanak tanır.

Statik onayı ve tek bir izin listesini kullanarak kodu güzel ve basit tutar, ancak uygulamanızın ihtiyaç duyabileceği tüm izinleri önceden istediği anlamına da gelir. Bu ayar, kullanıcıların ve yöneticilerin uygulamanızın erişim isteğini onaylamasını engelleyebilir.

Microsoft kimlik platformu uç noktasıyla, Microsoft Entra yönetim merkezindeki uygulama kayıt bilgilerinde tanımlanan statik izinleri yoksayabilirsiniz. Bunun yerine, uygulamanın kodundan dinamik olarak izin isteyebilirsiniz. Müşteri daha fazla uygulama özelliği kullandığından, önceden en az izin kümesini isteyerek başlayabilir ve zaman içinde başkalarından istekte bulunabilirsiniz. Bunu yapmak için, erişim belirteci isterken, uygulamanızın ihtiyaç duyduğu kapsamları, uygulama kayıt bilgilerinde önceden tanımlanmalarına gerek kalmadan, scope parametresine ekleyerek belirtebilirsiniz.

Kullanıcı istekteki kapsamlardan herhangi birini onaylamadıysa, bu istekteki tüm izinler için onay istemi alır. Bunlar, söz konusu uygulama için daha önce verilmiş olan diğer izinlere ek olarak (artımlı) verilir. Artımlı onay yalnızca yetki verilmiş izinler için geçerlidir, uygulama izinleri için değil.

Bir uygulamanın parametre aracılığıyla dinamik olarak izin istemesine scope izin vermek, geliştiricilere kullanıcınızın deneyimi üzerinde tam denetim sağlar. İlk yetkilendirme isteğinde onay deneyiminizi ön yükleyip tüm izinleri isteyebilirsiniz. Uygulamanız çok sayıda izin gerektiriyorsa, zaman içinde uygulamanın belirli özelliklerini kullanmaya çalışırken kullanıcıdan bu izinleri artımlı olarak toplayabilirsiniz.

Önemli

Dinamik onay kullanışlı olabilir, ancak yönetici onayı gerektiren izinler için önemli bir zorluk sunar. Portaldaki Uygulama kayıtları ve Kurumsal uygulamalar dikey pencerelerindeki yönetici onayı deneyimi, onay zamanında bu dinamik yetkilerin farkında değildir. Geliştiricinin portalda uygulamanın ihtiyaç duyduğu tüm yönetici ayrıcalıklı izinlerini listelemesini öneririz.

Bu, kiracı yöneticilerinin portaldaki tüm kullanıcıları adına bir kez onay vermesine olanak tanır. Kullanıcıların oturum açarken bu izinler için onay deneyiminden geçmesi gerekmez. Alternatif olarak bu izinler için dinamik onay kullanabilirsiniz. Yönetici onayı vermek için, tek bir yönetici uygulamada oturum açar, uygun izinler için bir onay istemi tetikler ve onay iletişim kutusunda tüm kuruluşum için onay seçer.

OpenID Connect veya OAuth 2.0 yetkilendirme isteğinde, bir uygulama sorgu parametresini kullanarak scope ihtiyaç duyduğu izinleri isteyebilir. Örneğin, bir kullanıcı uygulamada oturum açtığında uygulama aşağıdaki örneğe benzer bir istek gönderir. (Satır sonları okunabilirlik için eklenir).

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=
https%3A%2F%2Fgraph.microsoft.com%2Fcalendars.read%20
https%3A%2F%2Fgraph.microsoft.com%2Fmail.send
&state=12345

scope parametresi, uygulamanın istediği temsilci izinlerinin boşlukla ayrılmış bir listesidir. Her izin, kaynağın tanımlayıcısına (uygulama kimliği URI'si) izin değeri eklenerek belirtilir. İstek örneğinde, uygulamanın kullanıcının takvimini okuması ve postayı kullanıcı olarak göndermesi için izin gerekiyor.

Oturum açma sonrasında Microsoft kimlik platformu mevcut kullanıcı onayını denetler. Kullanıcı istenen izinleri onaylamazsa ve yönetici de bu izinleri onaylamazsa, platform kullanıcıdan onay vermesini ister.

Aşağıdaki örnekte(" offline_access Erişim verdiğiniz verilere erişimi koruyun") izni ve User.Read ("Oturum açın ve profilinizi okuyun") izni, bir uygulamaya ilk onayda otomatik olarak eklenir. Bu izinler, uygun uygulama işlevselliği için gereklidir.

İzin, offline_access uygulamaya yerel uygulamalar ve web uygulamaları için kritik öneme sahip yenileme belirteçlerine erişim verir. User.Read izni, sub talebine erişim sağlar. İstemcinin veya uygulamanın zaman içinde kullanıcıyı doğru şekilde tanımlamasına ve temel kullanıcı bilgilerine erişmesine olanak tanır.

İş hesabı onayı gösteren örnek ekran görüntüsü.

Kullanıcı izin isteğini onayladığında onay kaydedilir. Kullanıcının daha sonra uygulamada oturum açarken yeniden onay vermesine gerek yoktur.

Kiracının tamamı için onay istemek için yönetici onayı gerekir. Bir kuruluş adına yapılan yönetici onayı için uygulama için kayıtlı statik izinler gerekir. Bir yöneticinin kuruluşun tamamı adına onay vermesi gerekiyorsa Bu izinleri Microsoft Entra uygulama kayıt portalında ayarlayın.

Uygulamanız yönetici onayı gerektiren temsilci izinleri istediğinde, kullanıcılar "yetkisiz onay" hatası görür ve bir yöneticiden erişim istemeleri gerekir. Yönetici kiracının tamamı için onay verdiğinde, onay iptal edilmediği veya yeni izinler eklenmediği sürece kullanıcılardan bir daha istenmez.

Aynı uygulamayı kullanan yöneticiler yönetici onayı istemini görür. Yönetici onayı istemi, kiracının tamamı için kullanıcılar adına istenen verilere uygulamaya erişim izni vermelerini sağlayan bir onay kutusu sağlar. Kullanıcı ve yönetici onayı deneyimi hakkında daha fazla bilgi için bkz. Uygulama onayı deneyimi.

Microsoft Graph için yönetici onayı gerektiren temsilci izinlerine örnek olarak şunlar verilebilir:

  • User.Read.All kullanarak tüm kullanıcının tam profillerini okuma
  • Directory.ReadWrite.All kullanarak kuruluşun dizinine veri yazma
  • Groups.Read.All kullanarak kuruluşun dizinindeki tüm grupları okuma

Microsoft Graph izinlerinin tam listesini görüntülemek için bkz. Microsoft Graph izinleri başvurusu.

Ayrıca, kendi kaynaklarınızdaki izinleri yönetici onayı gerektirecek şekilde yapılandırabilirsiniz. Yönetici onayı gerektiren kapsamların nasıl ekleneceği hakkında daha fazla bilgi için bkz. Yönetici onayı gerektiren bir kapsam ekleme.

Bazı kuruluşlar kiracı için varsayılan kullanıcı onayı ilkesini değiştirebilir. Uygulamanız izinlere erişim istediğinde bu ilkelere göre değerlendirilir. Kullanıcının varsayılan olarak gerekli olmasa bile yönetici onayı istemesi gerekebilir. Yöneticilerin uygulamalar için onay ilkelerini nasıl yönettiğini öğrenmek için bkz. Uygulama onay ilkelerini yönetme.

Uyarı

Microsoft kimlik platformunda yetkilendirme, belirteç veya onay isteklerinde, scope parametresindeki kaynak tanımlayıcıyı atlamak Microsoft Graph'ı varsayılan yapar. Örneğin, scope=User.Read olarak https://graph.microsoft.com/User.Readdeğerlendirilir.

Uygulama izinleri her zaman yönetici onayı gerektirir. Uygulama izinlerinin kullanıcı bağlamı yoktur ve onay verme işlemi 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 etkileşimli olmayan diğer uygulamalar tarafından kullanılır. Yöneticilerin izinleri önceden yapılandırması ve Microsoft Entra yönetim merkezi aracılığıyla yönetici onayı vermesi gerekir.

İzin isteyen uygulamanın çok kiracılı bir uygulama olması durumunda, uygulama kaydı yalnızca oluşturulduğu kiracıda bulunur, bu nedenle izinler yerel kiracıda yapılandırılamaz. Uygulama yönetici onayı gerektiren izinler isterse, yöneticinin kullanıcılar adına onay alması gerekir. Bu izinlere onay vermek için yöneticilerin uygulamada oturum açmaları gerekir, bu nedenle yönetici onayı oturum açma deneyimi tetiklenir. Çok kiracılı uygulamalar için yönetici onayı deneyimini ayarlamayı öğrenmek için bkz. Çok kiracılı oturum açmaları etkinleştirme

Yönetici, aşağıdaki seçeneklerle bir uygulama için onay verebilir.

Genellikle, yönetici onayı gerektiren bir uygulama oluşturduğunuzda, uygulamanın yöneticinin uygulamanın izinlerini onayladığı bir sayfa veya görünüm gerekir. Bu sayfa şu şekilde olabilir:

  • Uygulamanın kayıt akışının bir parçası.
  • Uygulama ayarlarının bir bölümü.
  • Özel bir "bağlanma" süreci.

Çoğu durumda, uygulamanın "bağlan" görünümünü yalnızca bir kullanıcı iş Microsoft hesabı veya okul Microsoft hesabıyla oturum açtıktan sonra göstermesi mantıklıdır.

Kullanıcıyı uygulamanızda oturum açtığınızda, gerekli izinleri onaylamasını istemeden önce yöneticinin ait olduğu kuruluşu tanımlayabilirsiniz. Bu adım kesinlikle gerekli olmasa da, kuruluş 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.

Microsoft Entra uygulama kayıt portalında izinleri isteme

Microsoft Entra uygulama kayıt portalında, uygulamalar hem temsilci izinleri hem de uygulama izinleri dahil olmak üzere ihtiyaç duydukları izinleri listeleyebilir. Bu kurulum, .default kapsamının ve Microsoft Entra yönetim merkezindeki Yönetici onayı ver seçeneğinin kullanılmasına olanak tanır.

Genel olarak, izinler belirli bir uygulama için statik olarak tanımlanmalıdır. Bunlar, uygulamanın dinamik veya artımlı olarak istediği izinlerin üst kümesi olmalıdır.

Uyarı

Uygulama izinleri yalnızca .default kullanılarak istenebilir. Bu nedenle uygulamanızın uygulama izinlerine ihtiyacı varsa, bunların Microsoft Entra uygulama kayıt portalında listelenmiş olduğundan emin olun.

Bir uygulama için statik olarak istenen izinlerin listesini yapılandırmak için:

  1. Microsoft Entra yönetim merkezinde en az Bir Bulut Uygulaması Yöneticisi olarak oturum açın.
  2. Entra ID>Uygulama kayıtları>Tüm uygulamalar'a göz atın.
  3. Bir uygulama seçin veya henüz yapmadıysanız bir uygulama oluşturun .
  4. Uygulamanın Genel Bakış sayfasındaki Yönet'in altında API İzinleri>İzin ekle'yi seçin.
  5. Kullanılabilir API'ler listesinden Microsoft Graph'ı seçin. Ardından uygulamanızın gerektirdiği izinleri ekleyin.
  6. İzin Ekle'yi seçin.

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=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True
Parametre Açıklama
tenant Uygulamanıza istediği izinleri GUID biçiminde veren dizin kiracısı.
state İstek içinde yer alan ve belirteç yanıtında 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 bulundukları sayfa veya görünüm).
admin_consent olarak Trueayarlanır.

Yönetici onayı uç noktasından başarılı bir yanıt aldıktan sonra, uygulamanıza istediği izinler verilir. Ardından, istediğiniz kaynak için bir belirteç isteyebilirsiniz.

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 Oluşan hata türlerini sınıflandırmak için kullanılabilecek bir hata kodu dizesi. Hatalara tepki vermek için de kullanılabilir.
error_description Geliştiricinin hatanın kök nedenini tanımlamasına yardımcı olabilecek belirli bir hata iletisi.

Kullanıcı uygulamanızın izinlerini onayladıktan sonra uygulamanız, uygulamanın belirli bir kapasitedeki bir kaynağa erişim iznini temsil eden erişim belirteçleri alabilir. Erişim belirteci yalnızca tek bir kaynak için kullanılabilir. Ancak erişim belirtecinin içinde uygulamanızın bu kaynak için aldığı her izin kodlanmıştır. Erişim belirteci almak için uygulamanız Microsoft kimlik platformu belirteç uç noktasına şu şekilde bir istekte bulunabilir:

POST common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/json

{
    "grant_type": "authorization_code",
    "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "scope": "https://microsoft.graph.com/Mail.Read https://microsoft.graph.com/mail.send",
    "code": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...",
    "redirect_uri": "https://localhost/myapp",
    "client_secret": "A1bC2dE3f..."  // NOTE: Only required for web apps
}

Kaynağa yönelik HTTP isteklerinde elde edilen erişim belirtecini kullanabilirsiniz. Kaynak, uygulamanızın belirli bir görevi gerçekleştirmek için uygun izne sahip olduğunu güvenilir bir şekilde gösterir.

OAuth 2.0 protokolü ve erişim belirteçlerini alma hakkında daha fazla bilgi için bkz. Microsoft kimlik platformu uç nokta protokolü başvurusu.

İlgili içerik

  • Last updated on