Microsoft Entra ID'de tek kiracılı uygulamayı çok kiracılıya dönüştürme

  • Makale

Birçok kuruluşa Hizmet Olarak Yazılım (SaaS) uygulaması sunuyorsanız, uygulamanızı çok kiracılıya dönüştürerek herhangi bir Microsoft Entra kiracısından oturum açmaları kabul etmek üzere yapılandırabilirsiniz. Herhangi bir Microsoft Entra kiracısında yer alan kullanıcılar, kendi hesabını uygulamanızla kullanmaya onay verdikten sonra uygulamanızda oturum açabilecektir.

Kendi hesap sistemine (veya diğer bulut sağlayıcılarından gelen diğer oturum açma işlemlerine) sahip mevcut uygulamalar için OAuth2, OpenID Bağlan veya SAML aracılığıyla oturum açma kodu eklemeli ve uygulamanıza "Microsoft ile oturum aç" düğmesini yerleştirmelisiniz.

Bu nasıl yapılır kılavuzunda, tek bir kiracı uygulamasını Microsoft Entra çok kiracılı uygulamasına dönüştürmek için gereken dört adımı üstleneceksiniz:

  1. Uygulama kaydınızı çok kiracılı olacak şekilde güncelleştirme
  2. Kodunuzu uç noktaya istek gönderecek şekilde /common güncelleştirme
  3. Kodunuzu birden çok veren değerini işleyecek şekilde güncelleştirme
  4. Kullanıcı ve yönetici onaylarını anlama ve uygun kod değişiklikleri yapma

Örneklerimizden birini kullanmayı denemek istiyorsanız Microsoft Entra ID ve OpenID Bağlan kullanarak Microsoft Graph'i çağıran çok kiracılı bir SaaS web uygulaması oluşturma bölümüne bakın

Önkoşullar

Kaydı çok kiracılı olacak şekilde güncelleştirme

Varsayılan olarak, Microsoft Entra Id'deki web uygulaması/API kayıtları oluşturma işleminden sonra tek kiracılıdır. Kaydı çok kiracılı hale getirmek için Microsoft Entra yönetim merkezinde oturum açın ve güncelleştirmek istediğiniz uygulama kaydını seçin. Uygulama kaydı açıkken Kimlik Doğrulama bölmesini seçin ve Desteklenen hesap türleri bölümüne gidin. Ayarı herhangi bir kuruluş dizinindeki Hesaplar olarak değiştirin.

Microsoft Entra yönetim merkezinde tek kiracılı bir uygulama oluşturulduğunda, Genel Bakış sayfasında listelenen öğelerden biri Uygulama Kimliği URI'sidir. Bu, bir uygulamanın protokol iletilerinde tanımlanmasının yollarından biridir ve herhangi bir zamanda eklenebilir. Tek kiracılı uygulamalar için Uygulama Kimliği URI'si bu kiracı içinde genel olarak benzersiz olabilir. Buna karşılık, çok kiracılı uygulamalar için tüm kiracılar arasında genel olarak benzersiz olmalıdır ve bu da Microsoft Entra Id'nin uygulamayı tüm kiracılar arasında bulabilmesini sağlar.

Örneğin, kiracınızın adı geçerli bir Uygulama Kimliği URI'si contoso.onmicrosoft.com ise olacaktır https://contoso.onmicrosoft.com/myapp. Uygulama Kimliği URI'si bu desene uymuyorsa, bir uygulamayı çok kiracılı olarak ayarlamak başarısız olur.

İstek göndermek için kodunuzu güncelleştirin /common

Çok kiracılı bir uygulamayla uygulama kullanıcının hangi kiracıdan olduğunu hemen anlayamaz, bu nedenle istekler kiracının uç noktasına gönderemez. Bunun yerine, istekler tüm Microsoft Entra kiracılarında hizmet veren ortak bir uç noktaya (https://login.microsoftonline.com/common) gönderilir ve istekleri işleyen merkezi bir hub görevi görür.

Uygulamanızı IDE'nizde açın, kodunuzu düzenleyin ve kiracı kimliğinizin değerini olarak /commondeğiştirin. Bu uç nokta bir kiracı veya verenin kendisi değildir. Microsoft kimlik platformu uç noktada bir istek /common aldığında, kullanıcıyı oturum açar ve böylece kullanıcının hangi kiracıdan olduğunu bulur. Bu uç nokta, Microsoft Entra Id (OpenID Bağlan, OAuth 2.0, SAML 2.0, WS-Federation) tarafından desteklenen tüm kimlik doğrulama protokolleriyle çalışır.

Uygulamaya verilen oturum açma yanıtı, kullanıcıyı temsil eden bir belirteç içerir. Belirteçteki veren değeri, uygulamaya kullanıcının hangi kiracıdan olduğunu söyler. Bir yanıt uç noktadan döndürdüğünde /common , belirteçteki veren değeri kullanıcının kiracısına karşılık gelir.

Not

Gerçekte çok kiracılı uygulamalar için 2 yetkili vardır:

  • https://login.microsoftonline.com/common herhangi bir kuruluş dizininde (herhangi bir Microsoft Entra dizini) ve kişisel Microsoft hesaplarında (örneğin Skype, XBox) hesapları işleyen uygulamalar için.
  • https://login.microsoftonline.com/organizations herhangi bir kuruluş dizininde (herhangi bir Microsoft Entra dizininde) hesapları işleyen uygulamalar için:

Bu belgedeki açıklamalarda kullanılır common. Ancak uygulamanız Microsoft kişisel hesaplarını desteklemiyorsa ile değiştirebilirsiniz organizations .

Kodunuzu birden çok veren değerini işleyecek şekilde güncelleştirme

Web uygulamaları ve web API'leri Microsoft kimlik platformu belirteçleri alır ve doğrular. Yerel istemci uygulamaları erişim belirteçlerini doğrulamaz ve bunları opak olarak ele almalıdır. Bunun yerine, Microsoft kimlik platformu belirteçleri ister ve alır ve daha sonra doğrulandıkları API'lere göndermek için bunu yapar.

Çok kiracılı uygulamalar bir belirteci doğrularken daha fazla denetim gerçekleştirmelidir. Çok kiracılı bir uygulama, veya /common anahtar URL'lerinden /organizations anahtar meta verilerini kullanacak şekilde yapılandırılır. Uygulama, belirteçteki talebin issuer kiracı kimliği (tid) talebi içerdiğini denetlemenin yanı sıra yayımlanan meta verilerdeki özelliğin belirteçteki taleple eşleşdiğini ississ doğrulamalıdır. Daha fazla bilgi için bkz . Belirteçleri doğrulama.

Kullanıcının Microsoft Entra Id'de bir uygulamada oturum açması için uygulamanın kullanıcının kiracısında temsil edilmesi gerekir. Bu, kuruluşun kiracılarındaki kullanıcılar uygulamada oturum açarken benzersiz ilkeler uygulama gibi işlemler yapmasına olanak tanır. Tek kiracılı bir uygulama için kaydı Microsoft Entra yönetim merkezi aracılığıyla kullanabilirsiniz.

Çok kiracılı bir uygulama için, uygulamanın ilk kaydı geliştirici tarafından kullanılan Microsoft Entra kiracısında bulunur. Farklı bir kiracıdaki bir kullanıcı uygulamada ilk kez oturum açtığında, Microsoft Entra Id uygulama tarafından istenen izinleri onaylamasını ister. Onaylarsa, kullanıcının kiracısında hizmet sorumlusu adlı uygulamanın bir gösterimi oluşturulur ve oturum açma işlemi devam edebilir. Kullanıcının uygulamaya onayını kaydeden dizinde bir temsilci de oluşturulur. Uygulamanın Application ve ServicePrincipal nesneleri ve birbirleriyle ilişkileri hakkında ayrıntılı bilgi için bkz . Uygulama nesneleri ve hizmet sorumlusu nesneleri.

Kullanıcının tek katmanlı bir uygulamaya onayını gösteren diyagram.

Bu onay deneyimi, uygulama tarafından istenen izinlerden etkilenir. Microsoft kimlik platformu iki tür izni destekler;

  • Temsilci: Bu izin, uygulamaya kullanıcının yapabileceklerinin bir alt kümesi için oturum açmış bir kullanıcı olarak davranma olanağı verir. Örneğin, bir uygulamaya oturum açmış kullanıcının takvimini okuması için temsilci izni verilmektedir.
  • Yalnızca uygulama: Bu izin doğrudan uygulamanın kimliğine verilir. Örneğin, uygulamada kimin oturum açtığından bağımsız olarak bir uygulamaya kiracıdaki kullanıcıların listesini okuma izni verilmektedir.

Bazı izinler normal bir kullanıcı tarafından onaylanabilirken, diğerleri kiracı yöneticisinin onayına ihtiyaç duyar.

Kullanıcı ve yönetici onayı hakkında daha fazla bilgi edinmek için bkz . Yönetici onayı iş akışını yapılandırma.

Yalnızca uygulama izinleri her zaman bir kiracı yöneticisinin iznini gerektirir. Uygulamanız yalnızca uygulama izni isterse ve bir kullanıcı uygulamada oturum açmaya çalışırsa, kullanıcının onay veremeyeceğini belirten bir hata iletisi görüntülenir.

Belirli temsilci izinleri de bir kiracı yöneticisinin onayı gerektirir. Örneğin, oturum açmış kullanıcı olarak Microsoft Entra Id'ye geri yazabilmek için kiracı yöneticisinin onayı gerekir. Yalnızca uygulama izinleri gibi, sıradan bir kullanıcı yönetici onayı gerektiren bir temsilci izni isteyen bir uygulamada oturum açmaya çalışırsa, uygulama bir hata alır. İzin için yönetici onayı gerekip gerekmediği, kaynağı yayımlayan geliştirici tarafından belirlenir ve kaynağın belgelerinde bulunabilir. Microsoft Graph API'sinin izin belgeleri, hangi izinlerin yönetici onayı gerektirdiğini gösterir.

Uygulamanız yönetici onayı gerektiren izinler kullanıyorsa, yöneticinin eylemi başlatabileceği bir düğme veya bağlantı eklemeyi göz önünde bulundurun. Uygulamanızın bu eylem için gönderdiği istek, sorgu dizesi parametresini de içeren prompt=consent her zamanki OAuth2/OpenID Bağlan yetkilendirme isteğidir. Yönetici onay verdikten ve hizmet sorumlusu müşterinin kiracısında oluşturulduktan sonra sonraki oturum açma istekleri için prompt=consent parametresi gerekmez. Yönetici, istenen izinlerin kabul edilebilir olduğuna karar verdiğinden, kiracıdaki diğer kullanıcılardan bu noktadan sonra onay istenmez.

Kiracı yöneticisi, normal kullanıcıların uygulamalara onay verme özelliğini devre dışı bırakabilir. Bu özellik devre dışı bırakılırsa, uygulamanın kiracıda kullanılması için her zaman yönetici onayı gerekir. Microsoft Entra yönetim merkezinde uygulamanızı son kullanıcı onayı devre dışı bırakılmış olarak test edebilirsiniz. Kurumsal uygulamalar>Onayı ve izinleri bölümünde Kullanıcı onayına izin verme seçeneğini işaretleyin.

Parametresi, prompt=consent yönetici onayı gerektirmeyen izinler isteyen uygulamalar tarafından da kullanılabilir. Uygulamanın kiracı yöneticisinin bir kez "kaydolduğu" bir deneyime ihtiyaç duyması ve bu noktadan sonra başka hiçbir kullanıcıdan onay istenmez olması, bunun ne zaman kullanılacağını gösteren bir örnektir.

Bir uygulama yönetici onayı gerektiriyorsa ve yönetici parametre gönderilmeden prompt=consent oturum açarsa, yönetici uygulamayı başarıyla onayladığında yalnızca kullanıcı hesabı için geçerli olur. Normal kullanıcılar yine de uygulamada oturum açamaz veya uygulamayı onaylayamaz. Bu özellik, kiracı yöneticisine diğer kullanıcılara erişim izni vermeden önce uygulamanızı keşfetme olanağı vermek istiyorsanız kullanışlıdır.

Uygulamanızın, her biri Microsoft Entra Id'de kendi kaydıyla temsil edilen birden çok katmanı olabilir. Örneğin, web API'sini çağıran yerel bir uygulama veya web API'sini çağıran bir web uygulaması. Her iki durumda da istemci (yerel uygulama veya web uygulaması) kaynağı (web API' sini) çağırmak için izin ister. İstemcinin müşterinin kiracısına başarıyla onay verebilmesi için, izin istediği tüm kaynakların müşterinin kiracısında zaten mevcut olması gerekir. Bu koşul karşılanmazsa Microsoft Entra Id, önce kaynağın eklenmesi gerektiğini belirten bir hata döndürür.

Tek bir kiracıda birden çok katman

Mantıksal uygulamanız ayrı bir istemci ve kaynak gibi iki veya daha fazla uygulama kaydından oluşuyorsa bu sorun olabilir. Önce kaynağı dış kiracıya nasıl alırsınız? Microsoft Entra Id, istemci ve kaynağın tek bir adımda onaylanmalarını sağlayarak bu durumu kapsar. Kullanıcı, onay sayfasında hem istemci hem de kaynak tarafından istenen izinlerin toplamını görür. Bu davranışı etkinleştirmek için, kaynağın uygulama kaydı istemcinin Uygulama Kimliğini uygulama bildiriminde bir knownClientApplications olarak içermelidir. Örneğin:

"knownClientApplications": ["12ab34cd-56ef-78gh-90ij11kl12mn"]

Bu, çok kiracılı bir uygulama örneğinde gösterilmiştir. Aşağıdaki diyagramda, tek bir kiracıda kayıtlı çok katmanlı bir uygulama için onaylara genel bir bakış sağlanır.

Çok katmanlı bilinen istemci uygulamasının onayını gösteren diyagram.

Birden çok kiracıda birden çok katman

Bir uygulamanın farklı katmanları farklı kiracılarda kayıtlıysa benzer bir durum ortaya çıkar. Örneğin, Exchange Online API'sini çağıran yerel bir istemci uygulaması oluşturma örneğini düşünün. Yerel uygulamayı geliştirmek ve daha sonra yerel uygulamanın müşterinin kiracısında çalışması için Exchange Online hizmet sorumlusunun mevcut olması gerekir. Bu durumda, geliştirici ve müşteri, kiracılarında oluşturulacak hizmet sorumlusu için Exchange Online'ı satın almalıdır.

Bu, Microsoft dışında bir kuruluş tarafından oluşturulmuş bir API ise, API'nin geliştiricisinin müşterilerine uygulamanın müşteri kiracılarına onay vermesi için bir yol sağlaması gerekir. Önerilen tasarım, üçüncü taraf geliştiricinin API'yi, kaydolmayı uygulayacak bir web istemcisi olarak da çalışabilecek şekilde derlemesi içindir. Bunu yapmak için:

  1. API'nin çok kiracılı uygulama kaydı/kod gereksinimlerini uyguladığından emin olmak için önceki bölümleri izleyin.
  2. API'nin kapsamlarını/rollerini göstermenin yanı sıra, kaydın "Oturum aç ve kullanıcı profilini oku" iznini (varsayılan olarak sağlanır) içerdiğinden emin olun.
  3. Web istemcisinde bir oturum açma/kaydolma sayfası uygulayın ve yönetici onayı kılavuzunu izleyin.
  4. Kullanıcı uygulamaya onay verdikten sonra kiracısında hizmet sorumlusu ve onay temsilcisi bağlantıları oluşturulur ve yerel uygulama API için belirteçler alabilir.

Aşağıdaki diyagramda, farklı kiracılarda kayıtlı çok katmanlı bir uygulama için onaylara genel bir bakış sağlanır.

Çok katmanlı çok taraflı uygulamaya onay veren diyagram.

Kullanıcılar ve yöneticiler uygulamanızın onayını istedikleri zaman iptal edebilir:

Yönetici bir kiracıdaki tüm kullanıcılar için bir uygulamaya onay verirse, kullanıcılar erişimi tek tek iptal yapamaz. Erişimi yalnızca yönetici ve yalnızca uygulamanın tamamı için iptal edebilir.

Çok kiracılı uygulamalar ve önbelleğe alma erişim belirteçleri

Çok kiracılı uygulamalar, Microsoft Entra Kimliği ile korunan API'leri çağırmak için erişim belirteçleri de alabilir. Microsoft Kimlik Doğrulama Kitaplığı'nı (MSAL) çok kiracılı bir uygulamayla kullanırken karşılaşılan yaygın bir hata, başlangıçta kullanan /commonbir kullanıcı için bir belirteç istemek, bir yanıt almak ve aynı kullanıcı için de kullanarak /commonsonraki bir belirteç istemektir. Microsoft Entra Id'den gelen yanıt kiracıdan geldiğinden, /commonMSAL belirteci kiracıdan olduğu gibi önbelleğe alır. Kullanıcı için erişim belirteci almak için yapılan sonraki çağrı /common önbellek girdisini kaçırır ve kullanıcıdan yeniden oturum açması istenir. Önbelleğin eksik olmasını önlemek için, kiracının uç noktasında zaten oturum açmış bir kullanıcı için sonraki çağrıların yapıldığından emin olun.

Ayrıca bkz.