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

  • Makale

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.

Not

Bu özelliği kullanmak bir Microsoft Entra ID P1 lisansı gerektirir. Gereksinimlerinize uygun lisansı bulmak için bkz. Ücretsiz, Temel ve Premium sürümlerinin genel olarak sağlanan ö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
  • Kaynağı çağıran Web Apps

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 örneklerde sınama işleme gösterilmektedir.

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, aşağı akış API'sine erişim istemek için adına 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 Graph

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 veren 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 sınama, Microsoft Entra Id'den gelen yanıtta gelen parametresinde kodlanmıştır claims . İş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.

Senaryolar

Önkoşullar

Microsoft Entra Koşullu Erişim, Microsoft Entra Id P1 veya P2'de bulunan 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: Kullanıcı adına akışını gerçekleştiren uygulama

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 aşağı akış hizmetini çağırmak için "adına" akışını yapar. 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.

App performing the on-behalf-of flow diagram

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:

Not

Bu örnekte bu çok faktörlü kimlik doğrulama hatası açıklamasıdır ancak Koşullu Erişim ile ilgili çok çeşitli interaction_required olası durumlar 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 multi-factor authentication to access '<Web API 2 App/Client ID>'.
claims={"access_token":{"polids":{"essential":true,"Values":["<GUID>"]}}}

Web API 1'de hatasını error=interaction_requiredyakalar ve sınamayı claims masaüstü uygulamasına geri göndeririz. Bu noktada, masaüstü uygulaması yeni acquireToken() bir çağrı yapabilir ve sınamayı claimsek sorgu dizesi parametresi olarak 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 senaryoya bakmak 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 ilkesi atanmış olan iki hizmete erişmesi durumunda izlenir. 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 sonraki web hizmeti A istekleri de aşağıdaki gibi başarılı olur.

App accessing multiple-services flow diagram

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 bunu acquireTokendenediğinde aşağıdaki hatayı oluşturabilir (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 multi-factor authentication to access '<Web API App/Client ID>'.
claims={"access_token":{"polids":{"essential":true,"Values":["<GUID>"]}}}

App accessing multiple services requesting a new token

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 bu durumda uygulamanın son kullanıcıya ilkeye uyma fırsatı vermek için etkileşimli AcquireToken bir istek gerçekleştirmesi gerekmediği sürece bu durum geçerlidir.

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

Bu senaryoda, MSAL.js kullanarak 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.js 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() her ikisi de her zaman oturum açma kullanıcı arabirimini gösterdiği anlamına gelen bir kaynak için etkileşimli olarak belirteç istemek için kullanılır.

Bir uygulamanın web API'sini çağırmak için erişim belirtecine ihtiyacı olduğunda, bir acquireTokenSilent()dener. Belirtecin süresi dolduysa veya koşullu erişim ilkesine uymamız gerekiyorsa acquireToken işlevi başarısız olur ve uygulama veya acquireTokenRedirect()kullanıracquireTokenPopup().

Single-page app using MSAL flow diagram

Şimdi Koşullu Erişim senaryomuzla ilgili bir örneği inceleyelim. Son kullanıcı siteye yeni girdi 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 multi-factor authentication to access '<Web API App/Client ID>'.

Uygulamamızın öğesini yakalaması error=interaction_requiredgerekiyor. Uygulama daha sonra ya da acquireTokenPopup()acquireTokenRedirect() aynı kaynakta 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 senaryosunu denemek için, adına akış kodu örneği kullanarak Web API'Node.js React SPA çağrısı ö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 bkz.