Microsoft Entra geliştirici kılavuzu için Spring Boot Starter

Bu makalede, Microsoft Entra Id için Spring Boot Starter'ın özellikleri ve temel senaryoları açıklanmaktadır. Makale ayrıca yaygın sorunlar, geçici çözümler ve tanılama adımları hakkında yönergeler içerir.

Web uygulaması oluştururken kimlik ve erişim yönetimi temel parçalardır. Azure, Azure ekosisteminin geri kalanıyla derin tümleştirmeye sahip bulut tabanlı bir kimlik hizmeti sunar.

Spring Security, Spring tabanlı uygulamalarınızın güvenliğini sağlamayı kolaylaştırsa da, belirli bir kimlik sağlayıcısına uyarlanmamıştır. Microsoft Entra Id için Spring Boot Starter, web uygulamanızı bir Microsoft Entra kiracısına bağlamanızı ve Microsoft Entra Id ile kaynak sunucunuzu korumanızı sağlar. Web uygulamalarını ve kaynak sunucularını korumak için Oauth 2.0 protokolunu kullanır.

Aşağıdaki bağlantılar başlangıç paketine, belgelerine ve örneklerine erişim sağlar:

• Spring-cloud-azure-starter-active-directory paketi (Maven)
• hızlı başlangıç
• Örnekleri

Önkoşullar

Bu kılavuzdaki yönergeleri izlemek için aşağıdaki önkoşullara sahip olmanız gerekir:

• Azure aboneliği; Henüz bir Azure aboneliğiniz yoksa, MSDN abone avantajlarınızı etkinleştirebilir veya ücretsiz bir Azure hesabına kaydolabilirsiniz.
• Desteklenen bir Java Geliştirme Seti (JDK), sürüm 8 veya üzeri. Daha fazla bilgi için bkz. Azure'da Java desteği ve Azure Stack.
• Apache Maven, sürüm 3.0 veya üzeri.
• Microsoft Entra Kimliği ile kaydedilmiş bir uygulama. Daha fazla bilgi için bkz. Hızlı Başlangıç:Microsoft kimlik platformuna uygulama kaydetme.

Önemli

Bu makaledeki adımları tamamlamak için Spring Boot sürüm 2.5 veya üzeri gereklidir.

Temel senaryolar

Bu kılavuzda, aşağıdaki senaryolarda Microsoft Entra starter'ın nasıl kullanılacağı açıklanmaktadır:

• Web uygulamasına erişme
• Bir web uygulamasından kaynak sunucularına erişme
• Kaynak sunucusunu/API koruma
• Kaynak sunucusundan diğer kaynak sunucularına erişme
• Tek bir uygulamada Web uygulaması ve kaynak sunucusu

web uygulaması, kullanıcının oturum açmasını sağlayan herhangi bir web tabanlı uygulamadır. kaynak sunucusu erişim belirtecini doğruladıktan sonra erişimi kabul eder veya reddeder.

Web uygulamasına erişme

Bu senaryoda kullanıcının Microsoft hesabıyla oturum açmasını sağlamak için OAuth 2.0 yetkilendirme kodu verme akışı kullanılır.

Bu senaryoda Microsoft Entra starter'ı kullanmak için aşağıdaki adımları kullanın:

Yeniden yönlendirme URI'sini <application-base-uri>/login/oauth2/code/olarak ayarlayın. Örneğin: http://localhost:8080/login/oauth2/code/. sondaki /eklemeyi unutmayın. Yeniden yönlendirme URI'si hakkında daha fazla bilgi için bkz. Hızlı Başlangıç:Microsoft kimlik platformuna uygulama kaydetme bölümünde Yeniden yönlendirme URI'sini ekleme.

pom.xml dosyanıza aşağıdaki bağımlılıkları ekleyin.

<dependency>
   <groupId>com.azure.spring</groupId>
   <artifactId>spring-cloud-azure-starter-active-directory</artifactId>
</dependency>
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>

Not

Daha fazla bilgi için, Spring Cloud Azure kitaplık sürümlerini bir ürün reçetesi (BOM) kullanarak nasıl yöneteceğinizi öğrenmek amacıyla, Spring Cloud Azure geliştirici kılavuzunun Başlarken bölümüne bakın.

application.yml dosyanıza aşağıdaki özellikleri ekleyin. Bu özelliklerin değerlerini, önkoşullarda açıklandığı gibi Azure portalında oluşturduğunuz uygulama kaydından alabilirsiniz.

spring:
 cloud:
   azure:
     active-directory:
       enabled: true
       profile:
         tenant-id: <tenant>
       credential:
         client-id: <your-client-ID>
         client-secret: <your-client-secret>

Not

tenant-id için izin verilen değerler şunlardır: common, organizations, consumersveya kiracı kimliği. Bu değerler hakkında daha fazla bilgi için, Hata AADSTS50020 - Kimlik sağlayıcısından kullanıcı hesabı kiracımevcut değil bölümünün Yanlış uç nokta (kişisel ve kuruluş hesapları) kullanıldı bölümüne bakın. Tek kiracılı uygulamanızı dönüştürme hakkında bilgi için bkz. Tek kiracılı uygulamayı Microsoft Entra IDüzerinde çok kiracılıya dönüştürme.

Varsayılan güvenlik yapılandırmasını kullanın veya kendi yapılandırmanızı sağlayın.

Spring Cloud Azure 6.x

Seçenek 1: Varsayılan yapılandırmayı kullanın.

Bu seçenekle hiçbir şey yapmanız gerekmez. DefaultAadWebSecurityConfiguration sınıfı otomatik olarak yapılandırılır.

Seçenek 2: Kendi kendine tanımlanmış bir yapılandırma sağlayın.

Yapılandırma sağlamak için, aşağıdaki örnekte gösterildiği gibi AadWebApplicationHttpSecurityConfigurer#aadWebApplicationiçin HttpSecurity yöntemini uygulayın:

@Configuration(proxyBeanMethods = false)
@EnableWebSecurity
@EnableMethodSecurity
public class AadOAuth2LoginSecurityConfig {

   /**
    * Add configuration logic as needed.
    */
   @Bean
   SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
     http.with(AadWebApplicationHttpSecurityConfigurer.aadWebApplication(), Customizer.withDefaults())
         .authorizeHttpRequests(authorize -> authorize.anyRequest().authenticated());
         // Do some custom configuration.
       return http.build();
   }
}

Seçenek 1: Varsayılan yapılandırmayı kullanın.

Bu seçenekle hiçbir şey yapmanız gerekmez. DefaultAadWebSecurityConfiguration sınıfı otomatik olarak yapılandırılır.

Seçenek 2: Kendi kendine tanımlanmış bir yapılandırma sağlayın.

Yapılandırma sağlamak için, aşağıdaki örnekte gösterildiği gibi AadWebApplicationHttpSecurityConfigurer#aadWebApplicationiçin HttpSecurity yöntemini uygulayın:

@Configuration(proxyBeanMethods = false)
@EnableWebSecurity
@EnableMethodSecurity
public class AadOAuth2LoginSecurityConfig {

   /**
    * Add configuration logic as needed.
    */
   @Bean
   SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
       http.apply(AadWebApplicationHttpSecurityConfigurer.aadWebApplication())
               .and()
           .authorizeHttpRequests()
               .anyRequest().authenticated();
           // Do some custom configuration.
       return http.build();
   }
}

Seçenek 1: Varsayılan yapılandırmayı kullanın.

Bu seçenekle hiçbir şey yapmanız gerekmez. DefaultAadWebSecurityConfigurerAdapter sınıfı otomatik olarak yapılandırılır.

Seçenek 2: Kendi kendine tanımlanmış bir yapılandırma sağlayın.

Yapılandırma sağlamak için, aşağıdaki örnekte gösterildiği gibi AadWebSecurityConfigurerAdapter sınıfını genişletin ve super.configure(http) işlevinde configure(HttpSecurity http) çağırın:

@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class AadOAuth2LoginSecurityConfig extends AadWebSecurityConfigurerAdapter {

   /**
    * Add configuration logic as needed.
   */
   @Override
   protected void configure(HttpSecurity http) throws Exception {
       super.configure(http);
       http.authorizeRequests()
           .anyRequest().authenticated();
       // Do some custom configuration.
   }
}

Web uygulamasından kaynak sunucularına erişme

Bu senaryoda Microsoft Entra starter'ı kullanmak için aşağıdaki adımları kullanın:

Yeniden yönlendirme URI'sini daha önce açıklandığı gibi ayarlayın.

pom.xml dosyanıza aşağıdaki bağımlılıkları ekleyin.

<dependency>
   <groupId>com.azure.spring</groupId>
   <artifactId>spring-cloud-azure-starter-active-directory</artifactId>
</dependency>
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>

Not

Daha fazla bilgi için, Spring Cloud Azure kitaplık sürümlerini bir ürün reçetesi (BOM) kullanarak nasıl yöneteceğinizi öğrenmek amacıyla, Spring Cloud Azure geliştirici kılavuzunun Başlarken bölümüne bakın.

Daha önce açıklandığı gibi aşağıdaki özellikleri application.yml dosyanıza ekleyin:

spring:
 cloud:
   azure:
     active-directory:
       enabled: true
       profile:
         tenant-id: <tenant>
       credential:
         client-id: <your-client-ID>
         client-secret: <your-client-secret>
       authorization-clients:
         graph:
           scopes: https://graph.microsoft.com/Analytics.Read, email

Not

tenant-id için izin verilen değerler şunlardır: common, organizations, consumersveya kiracı kimliği. Bu değerler hakkında daha fazla bilgi için, Hata AADSTS50020 - Kimlik sağlayıcısından kullanıcı hesabı kiracımevcut değil bölümünün Yanlış uç nokta (kişisel ve kuruluş hesapları) kullanıldı bölümüne bakın. Tek kiracılı uygulamanızı dönüştürme hakkında bilgi için bkz. Tek kiracılı uygulamayı Microsoft Entra IDüzerinde çok kiracılıya dönüştürme.

Burada graph, OAuth2AuthorizedClientadıdır ve scopes, oturum açarken onay için gereken kapsamlardır.

Uygulamanıza aşağıdaki örneğe benzer bir kod ekleyin:

@GetMapping("/graph")
@ResponseBody
public String graph(
   @RegisteredOAuth2AuthorizedClient("graph") OAuth2AuthorizedClient graphClient
) {
   // toJsonString() is just a demo.
   // oAuth2AuthorizedClient contains access_token. We can use this access_token to access the resource server.
   return toJsonString(graphClient);
}

Burada, graph önceki adımda yapılandırılan istemci kimliğidir. OAuth2AuthorizedClient, kaynak sunucusuna erişmek için kullanılan erişim belirtecini içerir.

Bu senaryoya ilişkin eksiksiz bir örnek için bkz. spring-cloud-azure-starter-active-directory örneği: aad-web-application.

Kaynak sunucusunu/API'lerini koruma

Bu senaryo oturum açmayı desteklemez, ancak erişim belirtecini doğrulayarak sunucuyu korur. Erişim belirteci geçerliyse, sunucu isteğe hizmet eder.

Bu senaryoda Microsoft Entra starter'ı kullanmak için aşağıdaki adımları kullanın:

pom.xml dosyanıza aşağıdaki bağımlılıkları ekleyin.

<dependency>
   <groupId>com.azure.spring</groupId>
   <artifactId>spring-cloud-azure-starter-active-directory</artifactId>
</dependency>
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>

Not

Daha fazla bilgi için, Spring Cloud Azure kitaplık sürümlerini bir ürün reçetesi (BOM) kullanarak nasıl yöneteceğinizi öğrenmek amacıyla, Spring Cloud Azure geliştirici kılavuzunun Başlarken bölümüne bakın.

Daha önce açıklandığı gibi aşağıdaki özellikleri application.yml dosyanıza ekleyin:

spring:
 cloud:
   azure:
     active-directory:
       enabled: true
       credential:
         client-id: <your-client-ID>
       app-id-uri: <your-app-ID-URI>

Erişim belirtecini doğrulamak için hem <your-client-ID> hem de <your-app-ID-URI> değerlerini kullanabilirsiniz. Aşağıdaki görüntülerde gösterildiği gibi Azure portalından <your-app-ID-URI> değerini alabilirsiniz:

Varsayılan güvenlik yapılandırmasını kullanın veya kendi yapılandırmanızı sağlayın.

Spring Cloud Azure 6.x

Seçenek 1: Varsayılan yapılandırmayı kullanın.

Bu seçenekle hiçbir şey yapmanız gerekmez. DefaultAadResourceServerConfiguration sınıfı otomatik olarak yapılandırılır.

Seçenek 2: Kendi kendine tanımlanmış bir yapılandırma sağlayın.

Yapılandırma sağlamak için, aşağıdaki örnekte gösterildiği gibi AadResourceServerHttpSecurityConfigurer#aadResourceServeriçin HttpSecurity yöntemini uygulayın:

@Configuration(proxyBeanMethods = false)
@EnableWebSecurity
@EnableMethodSecurity
public class AadOAuth2ResourceServerSecurityConfig {

   /**
    * Add configuration logic as needed.
    */
   @Bean
   public SecurityFilterChain apiFilterChain(HttpSecurity http) throws Exception {
       http.with(AadResourceServerHttpSecurityConfigurer.aadResourceServer(), Customizer.withDefaults())
           .authorizeHttpRequests(authorize -> authorize.anyRequest().authenticated());
       return http.build();
   }
}

Seçenek 1: Varsayılan yapılandırmayı kullanın.

Bu seçenekle hiçbir şey yapmanız gerekmez. DefaultAadResourceServerConfiguration sınıfı otomatik olarak yapılandırılır.

Seçenek 2: Kendi kendine tanımlanmış bir yapılandırma sağlayın.

Yapılandırma sağlamak için, aşağıdaki örnekte gösterildiği gibi AadResourceServerHttpSecurityConfigurer#aadResourceServeriçin HttpSecurity yöntemini uygulayın:

@Configuration(proxyBeanMethods = false)
@EnableWebSecurity
@EnableMethodSecurity
public class AadOAuth2ResourceServerSecurityConfig {

   /**
    * Add configuration logic as needed.
    */
   @Bean
   public SecurityFilterChain apiFilterChain(HttpSecurity http) throws Exception {
       http.apply(AadResourceServerHttpSecurityConfigurer.aadResourceServer())
               .and()
           .authorizeHttpRequests()
               .anyRequest().authenticated();
       return http.build();
   }
}

Seçenek 1: Varsayılan yapılandırmayı kullanın.

Bu seçenekle hiçbir şey yapmanız gerekmez. DefaultAadResourceServerWebSecurityConfigurerAdapter sınıfı otomatik olarak yapılandırılır.

Seçenek 2: Kendi kendine tanımlanmış bir yapılandırma sağlayın.

Yapılandırma sağlamak için, aşağıdaki örnekte gösterildiği gibi AadResourceServerWebSecurityConfigurerAdapter sınıfını genişletin ve super.configure(http) işlevinde configure(HttpSecurity http) çağırın:

@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class AadOAuth2ResourceServerSecurityConfig extends AadResourceServerWebSecurityConfigurerAdapter {

   /**
    * Add configuration logic as needed.
    */
   @Override
   protected void configure(HttpSecurity http) throws Exception {
       super.configure(http);
       http.authorizeRequests((requests) -> requests.anyRequest().authenticated());
   }
}

Bu senaryoya ilişkin eksiksiz bir örnek için bkz. spring-cloud-azure-starter-active-directory örneği: aad-resource-server.

Kaynak sunucusundan diğer kaynak sunucularına erişme

Bu senaryo, diğer kaynak sunucularını ziyaret eden bir kaynak sunucusunu destekler.

Bu senaryoda Microsoft Entra starter'ı kullanmak için aşağıdaki adımları kullanın:

pom.xml dosyanıza aşağıdaki bağımlılıkları ekleyin.

<dependency>
   <groupId>com.azure.spring</groupId>
   <artifactId>spring-cloud-azure-starter-active-directory</artifactId>
</dependency>
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>

Not

Daha fazla bilgi için, Spring Cloud Azure kitaplık sürümlerini bir ürün reçetesi (BOM) kullanarak nasıl yöneteceğinizi öğrenmek amacıyla, Spring Cloud Azure geliştirici kılavuzunun Başlarken bölümüne bakın.

application.yml dosyanıza aşağıdaki özellikleri ekleyin:

spring:
 cloud:
   azure:
     active-directory:
       enabled: true
       profile:
         tenant-id: <tenant>
       credential:
         client-id: <web-API-A-client-ID>
         client-secret: <web-API-A-client-secret>
       app-id-uri: <web-API-A-app-ID-URI>
       authorization-clients:
         graph:
           scopes:
              - https://graph.microsoft.com/User.Read

Not

tenant-id için izin verilen değerler şunlardır: common, organizations, consumersveya kiracı kimliği. Bu değerler hakkında daha fazla bilgi için, Hata AADSTS50020 - Kimlik sağlayıcısından kullanıcı hesabı kiracımevcut değil bölümünün Yanlış uç nokta (kişisel ve kuruluş hesapları) kullanıldı bölümüne bakın. Tek kiracılı uygulamanızı dönüştürme hakkında bilgi için bkz. Tek kiracılı uygulamayı Microsoft Entra IDüzerinde çok kiracılıya dönüştürme.

Aşağıdaki örnekte gösterildiği gibi, ilgili kaynak sunucusuna erişmek için kodunuzda @RegisteredOAuth2AuthorizedClient özniteliğini kullanın:

@PreAuthorize("hasAuthority('SCOPE_Obo.Graph.Read')")
@GetMapping("call-graph")
public String callGraph(@RegisteredOAuth2AuthorizedClient("graph") OAuth2AuthorizedClient graph) {
   return callMicrosoftGraphMeEndpoint(graph);
}

Bu senaryoyu gösteren eksiksiz bir örnek için, spring-cloud-azure-starter-active-directory örneğine bakın: aad-resource-server-obo.

Bir uygulamada web uygulaması ve kaynak sunucusu

Bu senaryo, tek bir uygulamada bir web uygulamasına erişmeyi ve bir kaynak sunucusunu/API korumayı destekler.

Bu senaryoda aad-starter kullanmak için şu adımları izleyin:

pom.xml dosyanıza aşağıdaki bağımlılıkları ekleyin.

<dependency>
   <groupId>com.azure.spring</groupId>
   <artifactId>spring-cloud-azure-starter-active-directory</artifactId>
</dependency>
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>

Not

Daha fazla bilgi için, Spring Cloud Azure kitaplık sürümlerini bir ürün reçetesi (BOM) kullanarak nasıl yöneteceğinizi öğrenmek amacıyla, Spring Cloud Azure geliştirici kılavuzunun Başlarken bölümüne bakın.

application.yml dosyanızı güncelleştirin. özellik spring.cloud.azure.active-directory.application-typeweb_application_and_resource_serverolarak ayarlayın ve aşağıdaki örnekte gösterildiği gibi her yetkilendirme istemcisi için yetkilendirme türünü belirtin.

spring:
 cloud:
   azure:
     active-directory:
       enabled: true
       profile:
         tenant-id: <tenant>
       credential:
         client-id: <Web-API-C-client-id>
         client-secret: <Web-API-C-client-secret>
       app-id-uri: <Web-API-C-app-id-url>
       application-type: web_application_and_resource_server  # This is required.
       authorization-clients:
         graph:
           authorizationGrantType: authorization_code  # This is required.
           scopes:
             - https://graph.microsoft.com/User.Read
             - https://graph.microsoft.com/Directory.Read.All

Not

tenant-id için izin verilen değerler şunlardır: common, organizations, consumersveya kiracı kimliği. Bu değerler hakkında daha fazla bilgi için, Hata AADSTS50020 - Kimlik sağlayıcısından kullanıcı hesabı kiracımevcut değil bölümünün Yanlış uç nokta (kişisel ve kuruluş hesapları) kullanıldı bölümüne bakın. Tek kiracılı uygulamanızı dönüştürme hakkında bilgi için bkz. Tek kiracılı uygulamayı Microsoft Entra IDüzerinde çok kiracılıya dönüştürme.

Birden çok HttpSecurity örneği yapılandırmak için Java kodu yazın.

Spring Cloud Azure 6.x

Aşağıdaki örnek kodda, AadWebApplicationAndResourceServerConfig biri kaynak sunucusu, diğeri de bir web uygulaması için olmak üzere iki güvenlik filtresi zinciri çekirdeği içerir. apiFilterChain çekirdeği, kaynak sunucusu güvenlik oluşturucusunu yapılandırmak için yüksek önceliğe sahiptir. htmlFilterChain çekirdeği, web uygulaması güvenlik oluşturucusunu yapılandırmak için düşük önceliğe sahiptir.

@Configuration(proxyBeanMethods = false)
@EnableWebSecurity
@EnableMethodSecurity
public class AadWebApplicationAndResourceServerConfig {

    @Bean
    @Order(1)
    public SecurityFilterChain apiFilterChain(HttpSecurity http) throws Exception {
        http.with(AadResourceServerHttpSecurityConfigurer.aadResourceServer(), Customizer.withDefaults())
            // All the paths that match `/api/**`(configurable) work as the resource server. Other paths work as the web application.
            .securityMatcher("/api/**")
            .authorizeHttpRequests(authorize -> authorize.anyRequest().authenticated());
        return http.build();
    }

    @Bean
    public SecurityFilterChain htmlFilterChain(HttpSecurity http) throws Exception {
        // @formatter:off
        http.with(AadWebApplicationHttpSecurityConfigurer.aadWebApplication(), Customizer.withDefaults())
            .authorizeHttpRequests(authorize -> authorize.requestMatchers("/login").permitAll().anyRequest().authenticated());
        // @formatter:on
        return http.build();
    }
}

Aşağıdaki örnek kodda, AadWebApplicationAndResourceServerConfig biri kaynak sunucusu, diğeri de bir web uygulaması için olmak üzere iki güvenlik filtresi zinciri çekirdeği içerir. apiFilterChain çekirdeği, kaynak sunucusu güvenlik oluşturucusunu yapılandırmak için yüksek önceliğe sahiptir. htmlFilterChain çekirdeği, web uygulaması güvenlik oluşturucusunu yapılandırmak için düşük önceliğe sahiptir.

@Configuration(proxyBeanMethods = false)
@EnableWebSecurity
@EnableMethodSecurity
public class AadWebApplicationAndResourceServerConfig {

    @Bean
    @Order(1)
    public SecurityFilterChain apiFilterChain(HttpSecurity http) throws Exception {
        http.apply(AadResourceServerHttpSecurityConfigurer.aadResourceServer())
                .and()
            // All the paths that match `/api/**`(configurable) work as the resource server. Other paths work as the web application.
            .securityMatcher("/api/**")
            .authorizeHttpRequests()
                .anyRequest().authenticated();
        return http.build();
    }

    @Bean
    public SecurityFilterChain htmlFilterChain(HttpSecurity http) throws Exception {
        // @formatter:off
        http.apply(AadWebApplicationHttpSecurityConfigurer.aadWebApplication())
                .and()
            .authorizeHttpRequests()
                .requestMatchers("/login").permitAll()
                .anyRequest().authenticated();
        // @formatter:on
        return http.build();
    }
}

Aşağıdaki örnek kodda AadWebApplicationAndResourceServerConfig biri kaynak sunucusu, diğeri de web uygulaması için olmak üzere iki güvenlik yapılandırması içerir. ApiWebSecurityConfigurationAdapter sınıfı, kaynak sunucusu güvenlik bağdaştırıcısını yapılandırmak için yüksek önceliğe sahiptir. HtmlWebSecurityConfigurerAdapter sınıfı, web uygulaması güvenlik bağdaştırıcısını yapılandırmak için düşük önceliğe sahiptir.

@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class AadWebApplicationAndResourceServerConfig {

   @Order(1)
   @Configuration
   public static class ApiWebSecurityConfigurationAdapter extends AadResourceServerWebSecurityConfigurerAdapter {
       protected void configure(HttpSecurity http) throws Exception {
           super.configure(http);
           // All the paths that match `/api/**`(configurable) work as the resource server. Other paths work as  the web application.
           http.antMatcher("/api/**")
               .authorizeRequests().anyRequest().authenticated();
       }
   }

   @Configuration
   public static class HtmlWebSecurityConfigurerAdapter extends AadWebSecurityConfigurerAdapter {

       @Override
       protected void configure(HttpSecurity http) throws Exception {
           super.configure(http);
           // @formatter:off
           http.authorizeRequests()
                   .antMatchers("/login").permitAll()
                   .anyRequest().authenticated();
           // @formatter:on
       }
   }
}

Uygulama türü

spring.cloud.azure.active-directory.application-type özelliği isteğe bağlıdır çünkü değeri bağımlılıklar tarafından çıkarılabilir. Özelliği yalnızca web_application_and_resource_server değerini kullandığınızda el ile ayarlamanız gerekir.

Bağımlılığı var: spring-security-oauth2-client	Bağımlılığı var: spring-security-oauth2-resource-server	Uygulama türünün geçerli değerleri	Varsayılan değer
Evet	Hayır	web_application	web_application
Hayır	Evet	resource_server	resource_server
Evet	Evet	web_application,resource_server, resource_server_with_obo, web_application_and_resource_server	resource_server_with_obo

Yapılandırılabilir özellikler

Microsoft Entra Id için Spring Boot Starter aşağıdaki özellikleri sağlar:

Özellikler	Açıklama
spring.cloud.azure.aktif-dizin.uygulama-kimlik-uri	Erişim belirtecindeki hedef kitleyi doğrulamak için kaynak sunucusu tarafından kullanılır. Erişim belirteci yalnızca hedef kitle daha önce açıklanan <your-client-ID> veya <your-app-ID-URI> değerlerine eşit olduğunda geçerlidir.
Azure Active Directory için yetkilendirme istemcileri (spring.cloud.azure.active-directory.authorization-clients)	Uygulamanın ziyaret edecek kaynak API'lerini yapılandıran bir harita. Her öğe, uygulamanın ziyaret edecekleri bir kaynak API'sine karşılık gelir. Spring kodunuzda her öğe bir OAuth2AuthorizedClient nesnesine karşılık gelir.
spring.cloud.azure.active-directory.authorization-clients.<your-client-name>. kapsamalar	Uygulamanın edindiği kaynak sunucusunun API izinleri.
spring.cloud.azure.active-directory.authorization-clients.<your-client-name>. authorization-grant-type	Yetkilendirme istemcisinin türü. Desteklenen türler authorization_code (web uygulaması için varsayılan tür), on_behalf_of (resource-server için varsayılan tür), client_credentials.
spring.cloud.azure.active-directory.uygulama-tipi	Uygulama türübakın.
spring.cloud.azure.active-directory.profile.environment.active-directory-endpoint	Yetkilendirme sunucusu için temel URI. Varsayılan değer https://login.microsoftonline.com/.
spring.cloud.azure.active-directory.credential.client-id	Microsoft Entra Id'de kayıtlı uygulama kimliği.
spring.cloud.azure.active-directory.credential.client-secret	Kayıtlı uygulamanın istemci gizli anahtarı.
spring.cloud.azure.active-directory.user-group.use-transitive-members (Basamaklı Üyeleri Kullan)	v1.0/me/transitiveMemberOfolarak ayarlanırsa grupları almak için true kullanın. Aksi takdirde /v1.0/me/memberOfkullanın.
spring.cloud.azure.active-directory.post-logout-redirect-uri	Çıkış işlemi için yönlendirilme URI'si.
spring.cloud.azure.active-directory.profile.tenant-id	Azure kiracı kimliği. tenant-id için izin verilen değerler şunlardır: common, organizations, consumersveya kiracı kimliği.
spring.cloud.azure.active-directory.kullanıcı-grubu.izin-verilen-grup-adları	Beklenen kullanıcı grupları, MemberOf Graph API çağrısından gelen yanıtta bulunduğunda yetki verilecek gruplardır.
spring.cloud.azure.active-directory.kullanıcı-adı-özelliği	Sorumlunun adı olarak hangi talebin bulunacağını gösterir.

Aşağıdaki örneklerde bu özelliklerin nasıl kullanılacağı gösterilmektedir:

Özellik örneği 1: Azure Global yerine Azure China 21Vianet kullanmak için aşağıdaki adımı kullanın.

• application.yml dosyanıza aşağıdaki özellikleri ekleyin:

  spring:
     cloud:
       azure:
         active-directory:
           enabled: true
           profile:
             environment:
               active-directory-endpoint: https://login.partner.microsoftonline.cn
  

Bu yöntemle Azure genel bulutu yerine Azure bağımsız veya ulusal bulut kullanabilirsiniz.

Özellik örneği 2: Bir web uygulamasında bazı yöntemleri korumak için grup adı kullanmak için aşağıdaki adımları kullanın:

application.yml dosyanıza aşağıdaki özelliği ekleyin:

spring:
 cloud:
   azure:
     active-directory:
       enabled: true
       user-group:
         allowed-groups: group1, group2

Varsayılan güvenlik yapılandırmasını kullanın veya kendi yapılandırmanızı sağlayın.

Spring Cloud Azure 6.x

Seçenek 1: Varsayılan yapılandırmayı kullanın. Bu seçenekle hiçbir şey yapmanız gerekmez. DefaultAadWebSecurityConfiguration sınıfı otomatik olarak yapılandırılır.

Seçenek 2: Kendi kendine tanımlanmış bir yapılandırma sağlayın. Yapılandırma sağlamak için, aşağıdaki örnekte gösterildiği gibi AadWebApplicationHttpSecurityConfigurer#aadWebApplicationiçin HttpSecurity yöntemini uygulayın:

@Configuration(proxyBeanMethods = false)
@EnableWebSecurity
@EnableMethodSecurity
public class AadOAuth2LoginSecurityConfig {

   /**
    * Add configuration logic as needed.
    */
   @Bean
   public SecurityFilterChain htmlFilterChain(HttpSecurity http) throws Exception {
       // @formatter:off
       http.with(AadWebApplicationHttpSecurityConfigurer.aadWebApplication(), Customizer.withDefaults())
           .authorizeHttpRequests(authorize -> authorize.anyRequest().authenticated());
       // @formatter:on
       // Do some custom configuration.
       return http.build();
   }
}

Seçenek 1: Varsayılan yapılandırmayı kullanın. Bu seçenekle hiçbir şey yapmanız gerekmez. DefaultAadWebSecurityConfiguration sınıfı otomatik olarak yapılandırılır.

Seçenek 2: Kendi kendine tanımlanmış bir yapılandırma sağlayın. Yapılandırma sağlamak için, aşağıdaki örnekte gösterildiği gibi AadWebApplicationHttpSecurityConfigurer#aadWebApplicationiçin HttpSecurity yöntemini uygulayın:

@Configuration(proxyBeanMethods = false)
@EnableWebSecurity
@EnableMethodSecurity
public class AadOAuth2LoginSecurityConfig {

   /**
    * Add configuration logic as needed.
    */
   @Bean
   public SecurityFilterChain htmlFilterChain(HttpSecurity http) throws Exception {
       // @formatter:off
       http.apply(AadWebApplicationHttpSecurityConfigurer.aadWebApplication())
               .and()
           .authorizeHttpRequests()
               .anyRequest().authenticated();
       // @formatter:on
       // Do some custom configuration.
       return http.build();
   }
}

Seçenek 1: Varsayılan yapılandırmayı kullanın. Bu seçenekle hiçbir şey yapmanız gerekmez. DefaultAadWebSecurityConfigurerAdapter sınıfı otomatik olarak yapılandırılır.

Seçenek 2: Kendi kendine tanımlanmış bir yapılandırma sağlayın. Yapılandırma sağlamak için, aşağıdaki örnekte gösterildiği gibi AadWebSecurityConfigurerAdapter sınıfını genişletin ve super.configure(http) işlevinde configure(HttpSecurity http) çağırın:

@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class AadOAuth2LoginSecurityConfig extends AadWebSecurityConfigurerAdapter {

   /**
    * Add configuration logic as needed.
    */
   @Override
   protected void configure(HttpSecurity http) throws Exception {
       super.configure(http);
       http.authorizeRequests()
           .anyRequest().authenticated();
       // Do some custom configuration.
   }
}

Aşağıdaki örnekte gösterildiği gibi yöntemini korumak için @PreAuthorize ek açıklamasını kullanın:

@Controller
public class RoleController {
   @GetMapping("group1")
   @ResponseBody
   @PreAuthorize("hasRole('ROLE_group1')")
   public String group1() {
       return "group1 message";
   }

   @GetMapping("group2")
   @ResponseBody
   @PreAuthorize("hasRole('ROLE_group2')")
   public String group2() {
       return "group2 message";
   }

   @GetMapping("group1Id")
   @ResponseBody
   @PreAuthorize("hasRole('ROLE_<group1-id>')")
   public String group1Id() {
       return "group1Id message";
   }

   @GetMapping("group2Id")
   @ResponseBody
   @PreAuthorize("hasRole('ROLE_<group2-id>')")
   public String group2Id() {
       return "group2Id message";
   }
}

Özellik örneği 3: Kaynak sunucularını ziyaret eden bir kaynak sunucusunda istemci kimlik bilgisi akışını etkinleştirmek için aşağıdaki adımları kullanın:

application.yml dosyanıza aşağıdaki özelliği ekleyin:

spring:
 cloud:
   azure:
     active-directory:
       enabled: true
       authorization-clients:
         webapiC:   # When authorization-grant-type is null, on behalf of flow is used by default
           authorization-grant-type: client_credentials
           scopes:
             - <Web-API-C-app-id-url>/.default

Uygulamanıza aşağıdaki örneğe benzer bir kod ekleyin:

@PreAuthorize("hasAuthority('SCOPE_Obo.WebApiA.ExampleScope')")
@GetMapping("webapiA/webapiC")
public String callClientCredential() {
   String body = webClient
       .get()
       .uri(CUSTOM_LOCAL_READ_ENDPOINT)
       .attributes(clientRegistrationId("webapiC"))
       .retrieve()
       .bodyToMono(String.class)
       .block();
   LOGGER.info("Response from Client Credential: {}", body);
   return "client Credential response " + (null != body ? "success." : "failed.");
}

Gelişmiş özellikler

Web uygulamasında kimlik belirteciyle erişim denetimini destekleme

Starter, kimlik belirtecinin GrantedAuthority taleplerinden roles oluşturmayı destekler ve bu sayede kimlik belirtecinin bir web uygulamasında yetkilendirme için kullanılmasına izin verir. appRoles talebi oluşturmak ve erişim denetimi uygulamak için Microsoft Entra ID'nin roles özelliğini kullanabilirsiniz.

Not

roles'den oluşturulan appRoles talebi APPROLE_ön ekiyle dekore edilmiştir.

appRoles talebi olarak roles kullanırken, grup özniteliğini aynı anda roles olarak yapılandırmaktan kaçının. Aksi takdirde, grup özniteliği appRolesyerine grup bilgilerini içerme iddiasını geçersiz kılar. Bildiriminizde aşağıdaki yapılandırmadan kaçınmalısınız:

"optionalClaims": {
    "idtoken": [{
        "name": "groups",
        "additionalProperties": ["emit_as_roles"]
    }]
}

Web uygulamasında kimlik belirtecine göre erişim denetimini desteklemek için aşağıdaki adımları kullanın:

Uygulamanıza uygulama rolleri ekleyin ve bunları kullanıcılara veya gruplara atayın. Daha fazla bilgi için Nasıl yapılır: Uygulamanıza uygulama rolleri ekleme ve bunları jetonda alma bölümüne bakın.

Uygulamanızın bildirimine aşağıdaki appRoles yapılandırmasını ekleyin:

 "appRoles": [
   {
     "allowedMemberTypes": [
       "User"
     ],
     "displayName": "Admin",
     "id": "2fa848d0-8054-4e11-8c73-7af5f1171001",
     "isEnabled": true,
     "description": "Full admin access",
     "value": "Admin"
    }
 ]

Uygulamanıza aşağıdaki örneğe benzer bir kod ekleyin:

@GetMapping("Admin")
@ResponseBody
@PreAuthorize("hasAuthority('APPROLE_Admin')")
public String Admin() {
   return "Admin message";
}

Sorun giderme

İstemci günlüğünü etkinleştirme

Java için Azure SDK'ları, uygulama hatalarını gidermeye ve çözmeye yardımcı olmak için tutarlı bir günlüğe kaydetme sistemi sunar. Oluşturulan günlükler, terminale ulaşmadan önce uygulamanın akışını yakalar ve kök sorunun bulunmasına yardımcı olur. Günlüğe kaydetmeyi etkinleştirme yönergeleri için günlüğe kaydetme wiki'sini görüntüleyin.

Spring günlük kaydını etkinleştir

Spring, Spring ortamında desteklenen tüm günlük sistemlerinin logger seviyelerini - örneğin application.properties'daki gibi - logging.level.<logger-name>=<level> kullanarak ayarlamasını sağlar; burada <level>, TRACE, DEBUG, INFO, WARN, ERROR, FATALveya OFF'dan biridir. kök kaydediciyi logging.level.rootkullanarak yapılandırabilirsiniz.

Aşağıdaki örnek, application.properties dosyasındaki olası günlük ayarlarını gösterir:

logging.level.root=WARN
logging.level.org.springframework.web=DEBUG
logging.level.org.hibernate=ERROR

Spring'de günlük yapılandırması hakkında daha fazla bilgi için Spring belgelerindeki Günlüğe Kaydetme bakın.

Sonraki adımlar

Spring ve Azure hakkında daha fazla bilgi edinmek için Azure'da Spring belge merkezine geçin.

Azure 'de ilkbahar