Microsoft Entra Koşullu Erişim için geliştirici kılavuzu

Şunlar için geçerlidir: Aşağıdaki içeriğin iş gücü kiracıları için geçerli olduğunu gösteren beyaz onay işareti simgesine sahip yeşil daire. İş gücü kiracıları (daha fazla bilgi edinin)

Microsoft Entra Id'deki Koşullu Erişim özelliği, uygulamanızın güvenliğini sağlamak ve bir hizmeti korumak için kullanabileceğiniz çeşitli yollardan birini sunar. Koşullu Erişim, geliştiricilerin ve kurumsal müşterilerin hizmetleri çeşitli yollarla korumasını sağlar:

  • Çok faktörlü kimlik doğrulaması
  • Yalnızca Intune'a kayıtlı cihazların belirli hizmetlere erişmesine izin verme
  • Kullanıcı konumlarını ve IP aralıklarını kısıtlama

Koşullu Erişim'in tüm özellikleri hakkında daha fazla bilgi için Koşullu Erişim nedir? makalesine bakın.

Microsoft Entra Id için uygulama oluşturan geliştiriciler için, bu makalede Koşullu Erişim'i nasıl kullanabileceğiniz gösterilir ve koşullu erişim ilkelerinin uygulanmış olabileceği üzerinde denetiminiz olmayan kaynaklara erişmenin etkisi hakkında da bilgi edineceksiniz. Makalede ayrıca, koşullu erişimin adına akış, web uygulamaları, Microsoft Graph'a erişme ve API'leri çağırma üzerindeki etkileri de incelenecektir.

Tek ve çok kiracılı uygulamalar ve yaygın kimlik doğrulama desenleri hakkında bilgi sahibi olduğu varsayılır.

Uyarı

Bu özelliği kullanmak bir Microsoft Entra ID P1 lisansı gerektirir. Gereksinimleriniz için doğru lisansı bulmak için bkz. Ücretsiz, Temel ve Premium sürümlerin genel kullanıma sunulan özelliklerini karşılaştırma. Microsoft 365 İş lisansına sahip müşteriler de Koşullu Erişim özelliklerine erişebilir.

Koşullu Erişim bir uygulamayı nasıl etkiler?

Etkilenen uygulama türleri

Çoğu durumda Koşullu Erişim bir uygulamanın davranışını değiştirmez veya geliştiriciden herhangi bir değişiklik yapılmasını gerektirir. Yalnızca belirli durumlarda bir uygulama bir hizmet için dolaylı veya sessiz bir şekilde belirteç istediğinde, Koşullu Erişim zorluklarını işlemek için kod değişiklikleri gerektirir. Etkileşimli oturum açma isteği gerçekleştirmek kadar basit olabilir.

Özellikle, aşağıdaki senaryolar Koşullu Erişim zorluklarını işlemek için kod gerektirir:

  • Adına akış gerçekleştiren uygulamalar
  • Birden çok hizmete/kaynağa erişen uygulamalar
  • MSAL.js kullanan tek sayfalı uygulamalar
  • Web Uygulamaları bir kaynağı çağırıyor

Koşullu Erişim ilkeleri uygulamaya uygulanabilir, ancak uygulamanızın eriştiği bir web API'sine de uygulanabilir. Koşullu Erişim ilkesini yapılandırma hakkında daha fazla bilgi edinmek için bkz . Hızlı Başlangıç: Microsoft Entra Koşullu Erişim ile belirli uygulamalar için MFA gerektirme.

Senaryoya bağlı olarak, kurumsal müşteri koşullu erişim ilkelerini istediği zaman uygulayabilir ve kaldırabilir. Uygulamanızın yeni bir ilke uygulandığında çalışmaya devam etmesi için sınama işlemeyi uygulayın. Aşağıdaki örnekler zorluklarla başa çıkmayı göstermektedir.

Koşullu Erişim örnekleri

Bazı senaryolar Koşullu Erişimi işlemek için kod değişiklikleri gerektirirken, diğerleri olduğu gibi çalışır. Burada, farklılığa ilişkin bazı içgörüler sağlayan çok faktörlü kimlik doğrulaması yapmak için Koşullu Erişim kullanan birkaç senaryo yer alır.

  • Tek kiracılı bir iOS uygulaması oluşturuyor ve koşullu erişim ilkesi uyguluyorsunuz. Uygulama bir kullanıcıda oturum açar ve bir API'ye erişim istemez. Kullanıcı oturum açtığında, ilke otomatik olarak çağrılır ve kullanıcının çok faktörlü kimlik doğrulaması (MFA) gerçekleştirmesi gerekir.
  • Aşağı akış API'sine erişmek için orta katman hizmeti kullanan yerel bir uygulama oluşturuyorsunuz. Bu uygulamayı kullanan şirketin kurumsal müşterisi aşağı akış API'sine bir ilke uygular. Bir son kullanıcı oturum açtığında, yerel uygulama orta katmana erişim isteğinde bulunur ve belirteci gönderir. Orta katman, alt düzey API'ye erişim istemek için vekaleten akış gerçekleştirir. Bu noktada, orta katmana bir "sınama" talebi sunulur. Orta katman, sınamayı koşullu erişim ilkesine uyması gereken yerel uygulamaya geri gönderir.

Microsoft Grafiği

Microsoft Graph, Koşullu Erişim ortamlarında uygulama oluştururken dikkat edilmesi gereken özel noktalara sahiptir. Genel olarak, Koşullu Erişim'in mekaniği aynı şekilde davranır, ancak kullanıcılarınızın gördüğü ilkeler uygulamanızın grafikten istediği temel verileri temel alır.

Özellikle, tüm Microsoft Graph kapsamları tek tek ilkelerin uygulanabileceği bazı veri kümelerini temsil eder. Koşullu Erişim ilkeleri belirli veri kümelerine atandığından, Microsoft Entra Id, Graph'ın kendisi yerine Graph'ın arkasındaki verilere göre Koşullu Erişim ilkelerini zorunlu kılar.

Örneğin, bir uygulama aşağıdaki Microsoft Graph kapsamlarını isterse,

scopes="ChannelMessages.Read.All Mail.Read"

Bir uygulama, kullanıcılarının Teams ve Exchange'de ayarlanan tüm ilkeleri yerine getirmesini bekleyebilir. Erişim izni verdiğinde bazı kapsamlar birden çok veri kümesiyle eşlenebilir.

Koşullu Erişim ilkesine uyma

Birkaç farklı uygulama topolojisi için, oturum oluşturulduğunda koşullu erişim ilkesi değerlendirilir. Koşullu Erişim ilkesi uygulamaların ve hizmetlerin ayrıntı düzeyi üzerinde çalıştığından, çağrıldığı nokta büyük ölçüde gerçekleştirmeye çalıştığınız senaryoya bağlıdır.

Uygulamanız Koşullu Erişim ilkesine sahip bir hizmete erişmeye çalıştığında Koşullu Erişim sınamasıyla karşılaşabilir. Bu zorluk, Microsoft Entra ID'den gelen yanıtın claims parametresinde kodlanmıştır. İşte bu sınama parametresinin bir örneği:

claims={"access_token":{"polids":{"essential":true,"Values":["<GUID>"]}}}

Geliştiriciler bu sınamayı kabul edebilir ve Microsoft Entra Id'ye yeni bir isteğe ekleyebilir. Bu durumun geçirilmesi, son kullanıcıdan Koşullu Erişim ilkesine uymak için gerekli tüm eylemleri gerçekleştirmesini ister. Aşağıdaki senaryolarda hatanın ayrıntıları ve parametrenin nasıl ayıklandığı açıklanmıştır.

Senaryo

Önkoşullar

Microsoft Entra Koşullu Erişim, Microsoft Entra ID P1 veya P2içeren bir özelliktir. Microsoft 365 İş lisansına sahip müşteriler de Koşullu Erişim özelliklerine erişebilir.

Belirli senaryolar için dikkat edilmesi gerekenler

Aşağıdaki bilgiler yalnızca bu Koşullu Erişim senaryolarında geçerlidir:

  • Adına akış gerçekleştiren uygulamalar
  • Birden çok hizmete/kaynağa erişen uygulamalar
  • MSAL.js kullanan tek sayfalı uygulamalar

Aşağıdaki bölümlerde daha karmaşık olan yaygın senaryolar açıklanmıştır. Temel çalışma ilkesi Koşullu Erişim ilkeleri, Koşullu Erişim ilkesi uygulanmış olan hizmet için belirteç istendiği sırada değerlendirilir.

Senaryo: Uygulama, adına akış düzeni gerçekleştirme

Bu senaryoda, yerel bir uygulamanın bir web hizmetini/API'yi çağırması durumunda adım adım ilerleyeceğiz. Buna karşılık, bu hizmet ardıl hizmeti çağırmak için "adına akış" gerçekleştirir. Bizim örneğimizde, Koşullu Erişim ilkemizi aşağı akış hizmetine (Web API 2) uyguladık ve sunucu/daemon uygulaması yerine yerel bir uygulama kullanıyoruz.

Uygulamanın adına çalıştırdığı akış diyagramı

Web API 1 için ilk belirteç isteği, Web API 1 her zaman aşağı akış API'sine ulaşmayabileceği için son kullanıcıdan çok faktörlü kimlik doğrulaması istemez. Web API 1, Web API 2 için kullanıcı adına belirteç istemeye çalıştığında, kullanıcı çok faktörlü kimlik doğrulamasıyla oturum açmadığından istek başarısız olur.

Microsoft Entra Id bazı ilginç verileri içeren bir HTTP yanıtı döndürür:

Uyarı

Bu örnekte çok faktörlü bir kimlik doğrulama hatası açıklamasıdır, ancak Koşullu Erişim ile ilgili çok çeşitli interaction_required olası özellikler vardır.

HTTP 400; Bad Request
error=interaction_required
error_description=AADSTS50076: Due to a configuration change made by your administrator, or because you moved to a new location, you must use multifactor authentication to access '<Web API 2 App/Client ID>'.
claims={"access_token":{"polids":{"essential":true,"Values":["<GUID>"]}}}

Web API 1'de error=interaction_requiredhatasını yakalar ve claims sınamasını masaüstü uygulamasına geri göndeririz. Bu noktada masaüstü uygulaması yeni bir acquireToken() çağrısı yapabilir ve ek sorgu dizesi parametresi olarak claimssınamasını ekleyebilir. Bu yeni istek, kullanıcının çok faktörlü kimlik doğrulaması gerçekleştirmesini ve ardından bu yeni belirteci Web API 1'e geri göndermesini ve adına akışı tamamlamasını gerektirir.

Bu senaryoyı denemek için .NET kod örneğimize bakın. Talep sınamasını Web API 1'den yerel uygulamaya geri geçirmeyi ve istemci uygulamasında yeni bir istek oluşturmayı gösterir.

Senaryo: Birden çok hizmete erişen uygulama

Bu senaryoda, bir web uygulamasının, biri Koşullu Erişim ilkesine sahip olan iki hizmete eriştiği durum ele alınır. Uygulama mantığınıza bağlı olarak, uygulamanızın her iki web hizmetine de erişim gerektirmediği bir yol olabilir. Bu senaryoda, belirteç isteğinde bulunma sırası son kullanıcı deneyiminde önemli bir rol oynar.

A ve B web hizmetimizin, B web hizmetinin ise Koşullu Erişim ilkemizin uygulandığını varsayalım. İlk etkileşimli kimlik doğrulama isteği her iki hizmet için de onay gerektirir ancak koşullu erişim ilkesi her durumda gerekli değildir. Uygulama B web hizmeti için belirteç isterse, ilke çağrılır ve bu sayede sonraki web hizmeti A istekleri de başarılı olur.

Birden çok hizmet akış diyagramına erişen uygulama

Alternatif olarak, uygulama başlangıçta A web hizmeti için bir belirteç isterse, son kullanıcı Koşullu Erişim ilkesini çağırmaz. Bu, uygulama geliştiricisinin son kullanıcı deneyimini denetlemesine ve Koşullu Erişim ilkesini her durumda çağrılmaya zorlamamasına olanak tanır. Zor bir durum, uygulamanın daha sonra B web hizmeti için bir belirteç istemesidir. Bu noktada, son kullanıcının Koşullu Erişim ilkesine uyması gerekir. Uygulama acquireTokenyapmaya çalıştığında aşağıdaki hatayı üretebilir (aşağıdaki diyagramda gösterilmiştir):

HTTP 400; Bad Request
error=interaction_required
error_description=AADSTS50076: Due to a configuration change made by your administrator, or because you moved to a new location, you must use multifactor authentication to access '<Web API App/Client ID>'.
claims={"access_token":{"polids":{"essential":true,"Values":["<GUID>"]}}}

Birden çok hizmete erişip yeni belirteçApp accessing multiple services requesting a new tokenApp accessing multiple services requesting a new tokentalep edenUygulaması

Uygulama MSAL kitaplığını kullanıyorsa, belirteci alma hatası her zaman etkileşimli olarak yeniden denener. Bu etkileşimli istek gerçekleştiğinde, son kullanıcı Koşullu Erişim'e uyma fırsatına sahip olur. İstek bir AcquireTokenSilentAsync veya PromptBehavior.Never olmadığı sürece bu durum geçerlidir. Bu durumda uygulamanın son kullanıcıya ilkeye uyma fırsatı vermek için etkileşimli bir AcquireToken isteği gerçekleştirmesi gerekir.

Senaryo: MSAL.js kullanan tek sayfalı uygulama (SPA)

Bu senaryoda, MSAL.jskullanarak Koşullu Erişim korumalı bir web API'sini çağıran tek sayfalı bir uygulama (SPA) olduğunda bu durumu inceleyeceğiz. Bu basit bir mimaridir, ancak Koşullu Erişim'i geliştirirken dikkate alınması gereken bazı nüanslara sahiptir.

MSAL.jsiçinde belirteçleri alan birkaç işlev vardır: acquireTokenSilent(), acquireTokenPopup()ve acquireTokenRedirect().

  • acquireTokenSilent() herhangi bir durumda kullanıcı arabirimi göstermediği anlamına gelen bir erişim belirtecini sessizce almak için kullanılabilir.
  • acquireTokenPopup() ve acquireTokenRedirect(), bir kaynak için etkileşimli olarak belirteç istemek amacıyla kullanılır; bu da oturum açma kullanıcı arabiriminin her zaman gösterileceği anlamına gelir.

Bir uygulamanın bir web API'sini çağırmak için erişim belirtecine ihtiyacı olduğunda, bir acquireTokenSilent() girişiminde bulunur. tr-TR: Belirtecin süresi dolduysa veya koşullu erişim politikasına uymamız gerekiyorsa, acquireToken işlevi başarısız olur ve uygulama acquireTokenPopup() veya acquireTokenRedirect() kullanır.

MSAL akış diyagramını kullanan tek sayfalı uygulama

Şimdi Koşullu Erişim senaryomuzla ilgili bir örneği inceleyelim. Son kullanıcı siteye yeni geldi ve oturumu yok. Çok faktörlü kimlik doğrulaması olmadan bir kimlik belirteci almak için bir loginPopup() çağrı gerçekleştiririz. Ardından kullanıcı, uygulamanın bir web API'sinden veri istemesini gerektiren bir düğmeye basar. Kullanıcı henüz çok faktörlü kimlik doğrulaması gerçekleştirmediğinden ve Koşullu Erişim ilkesine uyması gerektiğinden uygulama bir acquireTokenSilent() çağrı yapmayı dener ancak başarısız olur.

Microsoft Entra Id aşağıdaki HTTP yanıtını geri gönderir:

HTTP 400; Bad Request
error=interaction_required
error_description=AADSTS50076: Due to a configuration change made by your administrator, or because you moved to a new location, you must use multifactor authentication to access '<Web API App/Client ID>'.

Uygulamamızın error=interaction_required'ı yakalaması gerekiyor. Uygulama daha sonra aynı kaynakta acquireTokenPopup() veya acquireTokenRedirect() kullanabilir. Kullanıcı çok faktörlü kimlik doğrulaması yapmak zorunda kalır. Kullanıcı çok faktörlü kimlik doğrulamasını tamamladıktan sonra, uygulamaya istenen kaynak için yeni bir erişim belirteci verilir.

Bu senaryoyu denemek için, adına akış kullanarak React SPA'nın Node.js web API çağrısını içeren kod örneğimize bakın. Bu kod örneği, daha önce React SPA'ya kaydettiğiniz Koşullu Erişim ilkesini ve web API'sini kullanarak bu senaryoyu gösterir. Talep sınamasını düzgün bir şekilde işlemeyi ve web API'niz için kullanılabilecek bir erişim belirteci almayı gösterir.

Ayrıca bakınız

  • Last updated on