Przewodnik dewelopera Spring Boot Starter dla firmy Microsoft Entra

W tym artykule opisano funkcje i podstawowe scenariusze szablonu startowego Spring Boot dla identyfikatora Entra firmy Microsoft. Ten artykuł zawiera również wskazówki dotyczące typowych problemów, obejść i kroków diagnostycznych.

Podczas tworzenia aplikacji internetowej tożsamość i zarządzanie dostępem są podstawowymi elementami. Platforma Azure oferuje usługę tożsamości opartą na chmurze, która ma głęboką integrację z resztą ekosystemu platformy Azure.

Mimo że usługa Spring Security ułatwia zabezpieczanie aplikacji opartych na platformie Spring, nie jest dostosowane do określonego dostawcy tożsamości. Starter Spring Boot dla Microsoft Entra ID umożliwia połączenie aplikacji internetowej z dzierżawcą Microsoft Entra oraz ochronę serwera zasobów przy użyciu Microsoft Entra ID. Używa protokołu Oauth 2.0 do ochrony aplikacji internetowych i serwerów zasobów.

Poniższe linki zapewniają dostęp do pakietu startowego, dokumentacji i przykładów:

• Pakiet spring-cloud-azure-starter-active-directory (Maven)
• Szybki start
• Próbki

Wymagania wstępne

Aby postępować zgodnie z instrukcjami w tym przewodniku, musisz mieć następujące wymagania wstępne:

• Subskrypcja platformy Azure; Jeśli nie masz jeszcze subskrypcji platformy Azure, możesz aktywować korzyści dla subskrybentów MSDN lub zarejestrować się w celu uzyskania bezpłatnego konta platformy Azure .
• Obsługiwany zestaw Java Development Kit (JDK), wersja 8 lub nowsza. Aby uzyskać więcej informacji, zobacz obsługa języka Java na platformie Azure i w usłudze Azure Stack.
• Apache Maven, wersja 3.0 lub nowsza.
• Aplikacja zarejestrowana w usłudze Microsoft Entra ID. Aby uzyskać więcej informacji, zobacz Szybki start: rejestrowanie aplikacji przy użyciu platformy tożsamości firmy Microsoft.

Ważne

Do wykonania kroków opisanych w tym artykule jest wymagany program Spring Boot w wersji 2.5 lub nowszej.

Podstawowe scenariusze

Niniejszy przewodnik opisuje sposób używania startowego Microsoft Entra w następujących scenariuszach.

• Uzyskiwanie dostępu do aplikacji internetowej
• Uzyskiwanie dostępu do serwerów zasobów z poziomu aplikacji internetowej
• Ochrona serwera zasobów/interfejsu API
• Uzyskiwanie dostępu do innych serwerów zasobów z serwera zasobów
• Aplikacja internetowa i serwer zasobów w jednej aplikacji

Aplikacja internetowa to dowolna aplikacja internetowa, która umożliwia użytkownikowi logowanie się. Serwer zasobów zaakceptuje lub odmówi dostępu po zweryfikowaniu tokenu dostępu.

Uzyskiwanie dostępu do aplikacji internetowej

W tym scenariuszu jest używany przepływ udzielania kodu autoryzacji OAuth 2.0, aby umożliwić użytkownikowi logowanie się przy użyciu konta Microsoft.

Aby użyć narzędzia startowego firmy Microsoft Entra w tym scenariuszu, wykonaj następujące kroki:

Ustaw identyfikator URI przekierowania na <application-base-uri>/login/oauth2/code/. Na przykład: http://localhost:8080/login/oauth2/code/. Pamiętaj, aby uwzględnić końcowy element /. Aby uzyskać więcej informacji na temat identyfikatora URI przekierowania, zobacz Dodaj identyfikator URI przekierowania w Szybki start: rejestrowanie aplikacji przy użyciu Platforma Tożsamości Microsoft.

Dodaj następujące zależności do pliku pom.xml.

<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>

Uwaga

Aby uzyskać więcej informacji na temat zarządzania wersjami bibliotek Spring Cloud Azure przy użyciu Bill of Materials (BOM), zobacz sekcję Wprowadzenie w przewodniku dla deweloperów Spring Cloud Azure.

Dodaj następujące właściwości do pliku application.yml . Wartości tych właściwości można uzyskać z poziomu rejestracji aplikacji utworzonej w witrynie Azure Portal, zgodnie z opisem w wymaganiach wstępnych.

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

Uwaga

Dozwolone wartości dla tenant-id to: common, organizations, consumerslub identyfikator dzierżawy. Aby uzyskać więcej informacji na temat tych wartości, zobacz sekcję Użyto nieprawidłowego punktu końcowego (kont osobistych i organizacyjnych) w Błąd AADSTS50020 — konto użytkownika od dostawcy tożsamości nie istnieje w dzierżawie. Aby uzyskać informacje na temat konwertowania aplikacji jednolicencjonowanej na wielolicencjonowaną, zobacz Convert single-tenant app to multitenant on Microsoft Entra ID.

Użyj domyślnej konfiguracji zabezpieczeń lub podaj własną konfigurację.

Spring Cloud Azure 5.x

Opcja 1. Użyj konfiguracji domyślnej.

Dzięki tej opcji nie musisz nic robić. Klasa DefaultAadWebSecurityConfiguration jest konfigurowana automatycznie.

Opcja 2. Podaj konfigurację zdefiniowaną przez siebie.

Aby podać konfigurację, zastosuj metodę AadWebApplicationHttpSecurityConfigurer#aadWebApplication dla klasy HttpSecurity, jak pokazano w poniższym przykładzie.

@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();
   }
}

Spring Cloud Azure 4.x

Opcja 1. Użyj konfiguracji domyślnej.

Dzięki tej opcji nie musisz nic robić. Klasa DefaultAadWebSecurityConfigurerAdapter jest konfigurowana automatycznie.

Opcja 2. Podaj konfigurację zdefiniowaną przez siebie.

Aby zapewnić konfigurację, rozszerz klasę AadWebSecurityConfigurerAdapter i wywołaj super.configure(http) w funkcji configure(HttpSecurity http), jak pokazano w poniższym przykładzie.

@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.
   }
}

Uzyskiwanie dostępu do serwerów zasobów z poziomu aplikacji internetowej

Aby użyć narzędzia startowego firmy Microsoft Entra w tym scenariuszu, wykonaj następujące kroki:

Ustaw identyfikator URI przekierowania zgodnie z wcześniejszym opisem.

Dodaj następujące zależności do pliku pom.xml.

<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>

Uwaga

Aby uzyskać więcej informacji na temat zarządzania wersjami bibliotek Spring Cloud Azure przy użyciu Bill of Materials (BOM), zobacz sekcję Wprowadzenie w przewodniku dla deweloperów Spring Cloud Azure.

Dodaj następujące właściwości do pliku application.yml , jak opisano wcześniej:

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

Uwaga

Dozwolone wartości dla tenant-id to: common, organizations, consumerslub identyfikator dzierżawy. Aby uzyskać więcej informacji na temat tych wartości, zobacz sekcję Użyto nieprawidłowego punktu końcowego (kont osobistych i organizacyjnych) w Błąd AADSTS50020 — konto użytkownika od dostawcy tożsamości nie istnieje w dzierżawie. Aby uzyskać informacje na temat konwertowania aplikacji jednolicencjonowanej na wielolicencjonowaną, zobacz Convert single-tenant app to multitenant on Microsoft Entra ID.

W tym miejscu graph to nazwa twojego OAuth2AuthorizedClient, a scopes to zakresy potrzebne do uzyskania zgody podczas logowania.

Dodaj kod do aplikacji podobny do poniższego przykładu:

@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);
}

graph W tym miejscu identyfikator klienta jest skonfigurowany w poprzednim kroku. OAuth2AuthorizedClient zawiera token dostępu, który jest używany do uzyskiwania dostępu do serwera zasobów.

Aby zapoznać się z kompletnym przykładem pokazującym ten scenariusz, zobacz przykład spring-cloud-azure-starter-active-directory: aad-web-application.

Ochrona serwera zasobów/interfejsu API

Ten scenariusz nie obsługuje logowania, ale chroni serwer, sprawdzając token dostępu. Jeśli token dostępu jest prawidłowy, serwer obsługuje żądanie.

Aby użyć narzędzia startowego firmy Microsoft Entra w tym scenariuszu, wykonaj następujące kroki:

Dodaj następujące zależności do pliku pom.xml.

<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>

Uwaga

Aby uzyskać więcej informacji na temat zarządzania wersjami bibliotek Spring Cloud Azure przy użyciu Bill of Materials (BOM), zobacz sekcję Wprowadzenie w przewodniku dla deweloperów Spring Cloud Azure.

Dodaj następujące właściwości do pliku application.yml , jak opisano wcześniej:

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

Możesz użyć zarówno wartości <your-client-ID>, jak i <your-app-ID-URI> do zweryfikowania tokena dostępu. Można uzyskać wartość <your-app-ID-URI> w portalu Azure, jak pokazano na poniższych obrazkach.

Użyj domyślnej konfiguracji zabezpieczeń lub podaj własną konfigurację.

Spring Cloud Azure 5.x

Opcja 1. Użyj konfiguracji domyślnej.

Dzięki tej opcji nie musisz nic robić. Klasa DefaultAadResourceServerConfiguration jest konfigurowana automatycznie.

Opcja 2. Podaj konfigurację zdefiniowaną przez siebie.

Aby podać konfigurację, zastosuj metodę AadResourceServerHttpSecurityConfigurer#aadResourceServer dla klasy HttpSecurity, jak pokazano w poniższym przykładzie.

@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();
   }
}

Spring Cloud Azure 4.x

Opcja 1. Użyj konfiguracji domyślnej.

Dzięki tej opcji nie musisz nic robić. Klasa DefaultAadResourceServerWebSecurityConfigurerAdapter jest konfigurowana automatycznie.

Opcja 2. Podaj konfigurację zdefiniowaną przez siebie.

Aby zapewnić konfigurację, rozszerz klasę AadResourceServerWebSecurityConfigurerAdapter i wywołaj super.configure(http) w funkcji configure(HttpSecurity http), jak pokazano w poniższym przykładzie.

@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());
   }
}

Aby zapoznać się z kompletnym przykładem pokazującym ten scenariusz, zobacz przykład spring-cloud-azure-starter-active-directory: aad-resource-server.

Uzyskiwanie dostępu do innych serwerów zasobów z serwera zasobów

Ten scenariusz obsługuje serwer zasobów odwiedzający inne serwery zasobów.

Aby użyć narzędzia startowego firmy Microsoft Entra w tym scenariuszu, wykonaj następujące kroki:

Dodaj następujące zależności do pliku pom.xml.

<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>

Uwaga

Aby uzyskać więcej informacji na temat zarządzania wersjami bibliotek Spring Cloud Azure przy użyciu Bill of Materials (BOM), zobacz sekcję Wprowadzenie w przewodniku dla deweloperów Spring Cloud Azure.

Dodaj następujące właściwości do pliku application.yml:

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

Uwaga

Dozwolone wartości dla tenant-id to: common, organizations, consumerslub identyfikator dzierżawy. Aby uzyskać więcej informacji na temat tych wartości, zobacz sekcję Użyto nieprawidłowego punktu końcowego (kont osobistych i organizacyjnych) w Błąd AADSTS50020 — konto użytkownika od dostawcy tożsamości nie istnieje w dzierżawie. Aby uzyskać informacje na temat konwertowania aplikacji jednolicencjonowanej na wielolicencjonowaną, zobacz Convert single-tenant app to multitenant on Microsoft Entra ID.

Użyj atrybutu @RegisteredOAuth2AuthorizedClient w kodzie, aby uzyskać dostęp do powiązanego serwera zasobów, jak pokazano w poniższym przykładzie:

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

Aby zapoznać się z kompletnym przykładem pokazującym ten scenariusz, zobacz przykład spring-cloud-azure-starter-active-directory: aad-resource-server-obo.

Aplikacja internetowa i serwer zasobów w jednej aplikacji

Ten scenariusz obsługuje dostęp do aplikacji internetowej i ochronę serwera zasobów/interfejsu API w jednej aplikacji.

Aby użyć aad-starter w tym scenariuszu, wykonaj następujące kroki:

Dodaj następujące zależności do pliku pom.xml.

<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>

Uwaga

Aby uzyskać więcej informacji na temat zarządzania wersjami bibliotek Spring Cloud Azure przy użyciu Bill of Materials (BOM), zobacz sekcję Wprowadzenie w przewodniku dla deweloperów Spring Cloud Azure.

Zaktualizuj plik application.yml. Ustaw właściwość spring.cloud.azure.active-directory.application-type na web_application_and_resource_server, i określ typ autoryzacji dla każdego klienta autoryzacji, jak pokazano w poniższym przykładzie.

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

Uwaga

Dozwolone wartości dla tenant-id to: common, organizations, consumerslub identyfikator dzierżawy. Aby uzyskać więcej informacji na temat tych wartości, zobacz sekcję Użyto nieprawidłowego punktu końcowego (kont osobistych i organizacyjnych) w Błąd AADSTS50020 — konto użytkownika od dostawcy tożsamości nie istnieje w dzierżawie. Aby uzyskać informacje na temat konwertowania aplikacji jednolicencjonowanej na wielolicencjonowaną, zobacz Convert single-tenant app to multitenant on Microsoft Entra ID.

Napisz kod Java, aby skonfigurować wiele HttpSecurity wystąpień.

Spring Cloud Azure 5.x

W poniższym przykładowym kodzie AadWebApplicationAndResourceServerConfig zawiera dwa beany łańcucha filtrów zabezpieczeń: jeden dla serwera zasobów i jeden dla aplikacji internetowej. Komponent apiFilterChain ma wysoki priorytet w konfiguracji konstruktora zabezpieczeń serwera zasobów. htmlFilterChain bean ma niski priorytet w konfiguracji konstruktora zabezpieczeń aplikacji internetowej.

@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();
    }
}

Spring Cloud Azure 4.x

W poniższym przykładowym kodzie AadWebApplicationAndResourceServerConfig zawiera dwie konfiguracje zabezpieczeń, jedną dla serwera zasobów i jedną dla aplikacji internetowej. Klasa ApiWebSecurityConfigurationAdapter ma wysoki priorytet w konfiguracji adaptera zabezpieczeń serwera zasobów. Klasa HtmlWebSecurityConfigurerAdapter ma niski priorytet w konfiguracji adaptera zabezpieczeń aplikacji internetowej.

@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
       }
   }
}

Typ aplikacji

Właściwość jest opcjonalna spring.cloud.azure.active-directory.application-type , ponieważ jej wartość może być wnioskowana przez zależności. Należy ręcznie ustawić właściwość tylko wtedy, gdy używasz wartości web_application_and_resource_server.

Ma zależność: spring-security-oauth2-client	Ma zależność: spring-security-oauth2-resource-server	Prawidłowe wartości typu aplikacji	Wartość domyślna
Tak	Nie.	web_application	web_application
Nie.	Tak	resource_server	resource_server
Tak	Tak	web_application,resource_server, resource_server_with_obo, web_application_and_resource_server	resource_server_with_obo

Konfigurowalne właściwości

Szablon startowy Spring Boot dla usługi Microsoft Entra ID zawiera następujące właściwości:

Właściwości	Opis
spring.cloud.azure.active-directory.app-id-uri	Używany przez serwer zasobów do weryfikacji grupy docelowej w tokenie dostępu. Token dostępu jest prawidłowy tylko wtedy, gdy odbiorca jest równy wartościom <your-client-ID> lub <your-app-ID-URI> opisanym wcześniej.
spring.cloud.azure.active-directory.authorization-clients	Mapa, która konfiguruje interfejsy API zasobów, które będzie odwiedzać aplikacja. Każdy element odpowiada jednemu interfejsowi API zasobów, który będzie odwiedzać aplikacja. W kodzie Spring każdy element odpowiada jednemu OAuth2AuthorizedClient obiektowi.
spring.cloud.azure.active-directory.authorization-clients.<your-client-name>. Zakresów	Uprawnienia API serwera zasobów, które aplikacja ma nabyć.
spring.cloud.azure.active-directory.authorization-clients.<your-client-name>. authorization-grant-type	Typ klienta autoryzacji. Obsługiwane typy to authorization_code (typ domyślny aplikacji internetowej), on_behalf_of (typ domyślny dla zasobu-serwera), client_credentials.
spring.cloud.azure.active-directory.typ-aplikacji	Zobacz Typ aplikacji.
spring.cloud.azure.active-directory.profile.environment.active-directory-endpoint	Podstawowy adres URI serwera autoryzacyjnego. Wartość domyślna to https://login.microsoftonline.com/.
spring.cloud.azure.active-directory.credential.client-id	Identyfikator zarejestrowanej aplikacji w Microsoft Entra ID.
spring.cloud.azure.active-directory.credential.client-secret	Tajny klucz klienta zarejestrowanej aplikacji.
spring.cloud.azure.active-directory.user-group.use-transitive-members (ustawienie używane do uwzględniania członków tranzytywnego w grupach użytkowników)	Użyj v1.0/me/transitiveMemberOf aby pobrać grupy, jeśli ustawiono true. W przeciwnym razie użyj /v1.0/me/memberOf.
Wiosenne.chmura.azure.aktywna-katalog.po-wylogowaniu-przekierowanie-uri	URI przekierowania do wylogowania.
spring.cloud.azure.active-directory.profile.tenant-id	Identyfikator dzierżawcy platformy Azure. Dozwolone wartości dla tenant-id to: common, organizations, consumerslub identyfikator dzierżawy.
spring.cloud.azure.active-directory.user-group.allowed-group-names	Oczekiwane grupy użytkowników, którym zostaną przyznane uprawnienia, jeśli zostaną znalezione w odpowiedzi z wywołania interfejsu API Graph MemberOf.
spring.cloud.azure.active-directory.user-name-attribute	Wskazuje, które oświadczenie będzie nazwą głównego podmiotu.

W poniższych przykładach pokazano, jak używać tych właściwości:

Przykład właściwości 1: Aby użyć usługi Azure China 21Vianet zamiast globalnej platformy Azure, wykonaj następujący krok.

• Dodaj następujące właściwości do pliku application.yml:

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

Za pomocą tej metody można użyć suwerennej lub krajowej chmury platformy Azure zamiast chmury publicznej platformy Azure.

Przykład właściwości 2: Aby użyć nazwy grupy do ochrony jakiejś metody w aplikacji internetowej, wykonaj następujące kroki:

Dodaj następującą właściwość do pliku application.yml :

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

Użyj domyślnej konfiguracji zabezpieczeń lub podaj własną konfigurację.

Spring Cloud Azure 5.x

Opcja 1. Użyj konfiguracji domyślnej. Dzięki tej opcji nie musisz nic robić. Klasa DefaultAadWebSecurityConfiguration jest konfigurowana automatycznie.

Opcja 2. Podaj konfigurację zdefiniowaną przez siebie. Aby podać konfigurację, zastosuj metodę AadWebApplicationHttpSecurityConfigurer#aadWebApplication dla klasy HttpSecurity, jak pokazano w poniższym przykładzie.

@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();
   }
}

Spring Cloud Azure 4.x

Opcja 1. Użyj konfiguracji domyślnej. Dzięki tej opcji nie musisz nic robić. Klasa DefaultAadWebSecurityConfigurerAdapter jest konfigurowana automatycznie.

Opcja 2. Podaj konfigurację zdefiniowaną przez siebie. Aby zapewnić konfigurację, rozszerz klasę AadWebSecurityConfigurerAdapter i wywołaj super.configure(http) w funkcji configure(HttpSecurity http), jak pokazano w poniższym przykładzie.

@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.
   }
}

@PreAuthorize Użyj adnotacji, aby chronić metodę, jak pokazano w poniższym przykładzie:

@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";
   }
}

Przykład właściwości 3: Aby włączyć przepływ poświadczeń klienta na serwerze zasobów odwiedzającym serwery zasobów, wykonaj następujące kroki:

Dodaj następującą właściwość do pliku application.yml :

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

Dodaj kod do aplikacji podobny do poniższego przykładu:

@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.");
}

Funkcje zaawansowane

Wsparcie kontroli dostępu za pomocą tokenu ID w aplikacji internetowej

Starter obsługuje tworzenie GrantedAuthority na podstawie oświadczenia tokenu identyfikatora roles, aby umożliwić używanie tokenu identyfikatora do autoryzacji w aplikacji internetowej. Możesz skorzystać z appRoles funkcji Microsoft Entra ID, aby utworzyć roles żądanie i zaimplementować kontrolę dostępu.

Uwaga

Oświadczenie roles wygenerowane na podstawie appRoles jest ozdobione prefiksem APPROLE_.

W przypadku używania appRoles jako roles roszczenia, należy unikać konfigurowania atrybutu grupy jako roles jednocześnie. W przeciwnym razie atrybut grupy zastąpi oświadczenie, aby zawierał informacje o grupie zamiast appRoles. Należy unikać następującej konfiguracji w manifeście:

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

Aby obsługiwać kontrolę dostępu przy użyciu tokenu identyfikatora w aplikacji internetowej, wykonaj następujące kroki:

Dodaj role aplikacji w aplikacji i przypisz je do użytkowników lub grup. Aby uzyskać więcej informacji, zobacz How to: Add app roles to your application and receive them in the token (Instrukcje: dodawanie ról aplikacji do aplikacji i odbieranie ich w tokenie).

Dodaj następującą appRoles konfigurację do manifestu aplikacji:

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

Dodaj kod do aplikacji podobny do poniższego przykładu:

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

Rozwiązywanie problemów

Włączanie rejestrowania klientów

Zestawy SDK platformy Azure dla języka Java oferują spójny scenariusz rejestrowania, który ułatwia rozwiązywanie problemów z błędami aplikacji i rozwiązywanie ich. Wygenerowane dzienniki przechwytują przepływ aplikacji przed dotarciem do terminalu, pomagając zlokalizować główny problem. Wyświetl wiki dotyczące rejestrowania, aby uzyskać wskazówki dotyczące włączania rejestrowania.

Włącz rejestrowanie Spring

Platforma Spring umożliwia wszystkim obsługiwanym systemom rejestrowania ustawianie poziomów rejestratora w środowisku Spring — na przykład w pliku application.properties — przy użyciu logging.level.<logger-name>=<level>, gdzie <level> jest jednym z TRACE, DEBUG, INFO, WARN, ERROR, FATAL lub OFF. Główny rejestrator można skonfigurować przy użyciu polecenia logging.level.root.

W poniższym przykładzie przedstawiono potencjalne ustawienia rejestrowania w pliku application.properties :

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

Aby uzyskać więcej informacji na temat konfiguracji rejestrowania na platformie Spring, zobacz Rejestrowanie w dokumentacji platformy Spring.

Następne kroki

Aby dowiedzieć się więcej na temat oprogramowania Spring i platformy Azure, przejdź do centrum dokumentacji dotyczącej oprogramowania Spring na platformie Azure.

Oprogramowanie Spring na platformie Azure