Przewodnik dewelopera Spring Boot Starter dla firmy Microsoft Entra

Ten artykuł dotyczy: ✔️ wersja 4.19.0 ✔️ w wersji 5.15.0

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. Szablon startowy Spring Boot dla usługi Microsoft Entra ID umożliwia łączenie aplikacji internetowej z dzierżawą firmy Microsoft Entra i ochronę serwera zasobów za pomocą identyfikatora Entra firmy Microsoft. 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
• Samples

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 utworzyć bezpłatne konto 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, Skorzystaj z systemu szybkiego startu: Zarejestruj aplikację na platformie tożsamości Microsoft.

Podstawowe scenariusze

W tym przewodniku opisano sposób używania szablonu startowego Firmy 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ć szablonu startowego firmy Microsoft Entra w tym scenariuszu, wykonaj następujące kroki:

Ustaw identyfikator URI przekierowania na <wartość application-base-uri>/login/oauth2/code/. Na przykład: http://localhost:8080/login/oauth2/code/. Pamiętaj, aby uwzględnić końcowy /ciąg . Aby uzyskać więcej informacji na temat identyfikatora URI przekierowania, zobacz Dodawanie identyfikatora URI przekierowania w przewodniku 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>

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>

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

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

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

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

Aby użyć szablonu 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>

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

graph W tym miejscu znajduje się nazwa elementu OAuth2AuthorizedClienti scopes są zakresami wymaganymi 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ć szablonu 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>

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>

Aby zweryfikować token dostępu, możesz użyć zarówno wartości your-client-ID-,> jak i< identyfikatora-URI> aplikacji.< Wartość your-app-ID-URI> można pobrać <z witryny Azure Portal, jak pokazano na poniższych obrazach:

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

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

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

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

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

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>

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

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

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

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

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 web_application_and_resource_server wartości.

Konfigurowalne właściwości

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

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

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

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

@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

Obsługa kontroli dostępu według tokenu identyfikatora w aplikacji internetowej

Szablon startowy obsługuje tworzenie GrantedAuthority na podstawie oświadczenia tokenu identyfikatora roles , aby zezwolić na używanie tokenu identyfikatora do autoryzacji w aplikacji internetowej. Możesz użyć appRoles funkcji Microsoft Entra ID, aby utworzyć roles oświadczenie i zaimplementować kontrolę dostępu.

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

Aby obsługiwać kontrolę dostępu według 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 witrynę typu wiki rejestrowania, aby uzyskać wskazówki dotyczące włączania rejestrowania.

Włączanie rejestrowania 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 metody logging.level.<logger-name>=<level> , gdzie poziom jest jednym z poziomów 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.