Guida per gli sviluppatori di Spring Boot Starter per Microsoft Entra

Questo articolo si applica a: ✔️ Versione 4.19.0 ✔️ versione 5.18.0

Questo articolo descrive le funzionalità e gli scenari principali di Spring Boot Starter per Microsoft Entra ID. Include anche indicazioni sui problemi comuni, le soluzioni alternative e le procedure di diagnostica.

Quando si crea un'applicazione Web, la gestione delle identità e degli accessi è fondamentale. Azure offre un servizio di gestione delle identità basato sul cloud con un'integrazione approfondita con il resto dell'ecosistema di Azure.

Anche se Spring Security semplifica la protezione delle applicazioni basate su Spring, non è adatta a un provider di identità specifico. Spring Boot Starter per Microsoft Entra ID consente di connettere l'applicazione Web a un tenant di Microsoft Entra e proteggere il server di risorse con Microsoft Entra ID. Usa il protocollo Oauth 2.0 per proteggere applicazioni Web e server di risorse.

I collegamenti seguenti forniscono l'accesso al pacchetto iniziale, alla documentazione e agli esempi:

• Pacchetto spring-cloud-azure-starter-active-directory (Maven)
• Avvio rapido
• Esempi

Prerequisiti

Per seguire le istruzioni riportate in questa guida, è necessario disporre dei prerequisiti seguenti:

• Sottoscrizione di Azure; se non si ha una sottoscrizione di Azure, è possibile attivare i vantaggi per i sottoscrittori di MSDN oppure iscriversi per ottenere un account Azure gratuito.
• Java Development Kit (JDK) supportato, versione 8 o successiva. Per altre informazioni, vedere Supporto java in Azure e Azure Stack.
• Apache Maven, versione 3.0 o successiva.
• Applicazione registrata con Microsoft Entra ID. Per altre informazioni, vedi Avvio rapido: Registrare un'applicazione con la piattaforma di identità di Microsoft.

Scenari chiave

Questa guida descrive come usare Microsoft Entra Starter negli scenari seguenti:

• Accedere a un'applicazione Web
• Accedere ai server delle risorse da un'applicazione Web
• Proteggere un server di risorse o un'API
• Accedere ad altri server di risorse da un server di risorse
• Applicazione Web e server risorse in un'unica applicazione

Un'applicazione Web è qualsiasi applicazione basata sul Web che consente a un utente di accedere. Un server di risorse accetterà o negherà l'accesso dopo la convalida di un token di accesso.

Accedere a un'applicazione Web

Questo scenario usa il flusso di concessione del codice di autorizzazione OAuth 2.0 per consentire a un utente di accedere con un account Microsoft.

Per usare Microsoft Entra Starter in questo scenario, seguire questa procedura:

Impostare l'URI di reindirizzamento su <application-base-uri>/login/oauth2/code/. Ad esempio: http://localhost:8080/login/oauth2/code/. Assicurarsi di includere l'oggetto finale /. Per altre informazioni sull'URI di reindirizzamento, vedere Aggiungere un URI di reindirizzamento in Avvio rapido: Registrare un'applicazione con Microsoft Identity Platform.

Aggiungere le dipendenze seguenti al file 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>

Aggiungere le proprietà seguenti al file application.yml . È possibile ottenere i valori per queste proprietà dalla registrazione dell'app creata nel portale di Azure, come descritto nei prerequisiti.

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

Usare la configurazione di sicurezza predefinita o specificare la propria configurazione.

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

Accedere ai server delle risorse da un'applicazione Web

Per usare Microsoft Entra Starter in questo scenario, seguire questa procedura:

Impostare l'URI di reindirizzamento come descritto in precedenza.

Aggiungere le dipendenze seguenti al file 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>

Aggiungere le proprietà seguenti al file application.yml , come descritto in precedenza:

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

Di seguito è graph riportato il nome dell'oggetto OAuth2AuthorizedCliente scopes sono gli ambiti necessari per il consenso durante l'accesso.

Aggiungere codice all'applicazione simile all'esempio seguente:

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

Di seguito è graph riportato l'ID client configurato nel passaggio precedente. OAuth2AuthorizedClient contiene il token di accesso, usato per accedere al server di risorse.

Per un esempio completo che illustra questo scenario, vedere spring-cloud-azure-starter-active-directory sample: aad-web-application.

Proteggere un server di risorse o un'API

Questo scenario non supporta l'accesso, ma protegge il server convalidando il token di accesso. Se il token di accesso è valido, il server gestisce la richiesta.

Per usare Microsoft Entra Starter in questo scenario, seguire questa procedura:

Aggiungere le dipendenze seguenti al file 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>

Aggiungere le proprietà seguenti al file application.yml , come descritto in precedenza:

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

È possibile usare sia i valori your-client-ID> che< your-app-ID-URI> per verificare il token di accesso.< È possibile ottenere il <valore your-app-ID-URI> dal portale di Azure, come illustrato nelle immagini seguenti:

Usare la configurazione di sicurezza predefinita o specificare la propria configurazione.

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

Per un esempio completo che illustra questo scenario, vedere spring-cloud-azure-starter-active-directory sample: aad-resource-server.

Accedere ad altri server di risorse da un server di risorse

Questo scenario supporta un server di risorse che visita altri server di risorse.

Per usare Microsoft Entra Starter in questo scenario, seguire questa procedura:

Aggiungere le dipendenze seguenti al file 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>

Aggiungere le proprietà seguenti al file 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

Usare l'attributo @RegisteredOAuth2AuthorizedClient nel codice per accedere al server di risorse correlato, come illustrato nell'esempio seguente:

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

Per un esempio completo che illustra questo scenario, vedere spring-cloud-azure-starter-active-directory sample: aad-resource-server-obo.

Applicazione Web e server risorse in un'unica applicazione

Questo scenario supporta Access a web application (Accesso a un'applicazione Web) e Protect a resource server/API in un'unica applicazione.

Per usare aad-starter in questo scenario, seguire questa procedura:

Aggiungere le dipendenze seguenti al file 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>

Aggiornare il file application.yml . Impostare la proprietà spring.cloud.azure.active-directory.application-type su web_application_and_resource_servere specificare il tipo di autorizzazione per ogni client di autorizzazione, come illustrato nell'esempio seguente.

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

Scrivere codice Java per configurare più HttpSecurity istanze.

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

Tipo di applicazione

La spring.cloud.azure.active-directory.application-type proprietà è facoltativa perché il relativo valore può essere dedotto dalle dipendenze. È necessario impostare manualmente la proprietà solo quando si utilizza il web_application_and_resource_server valore .

Proprietà configurabili

Spring Boot Starter per Microsoft Entra ID fornisce le proprietà seguenti:

Gli esempi seguenti illustrano come usare queste proprietà:

Esempio di proprietà 1: per usare Azure China 21Vianet anziché Azure Global, usare il passaggio seguente.

• Aggiungere le proprietà seguenti al file application.yml :

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

Con questo metodo, è possibile usare un cloud sovrano o nazionale di Azure anziché il cloud pubblico di Azure.

Esempio di proprietà 2: Per usare un nome di gruppo per proteggere un metodo in un'applicazione Web, seguire questa procedura:

Aggiungere la proprietà seguente al file application.yml :

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

Usare la configurazione di sicurezza predefinita o specificare la propria configurazione.

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

Usare l'annotazione @PreAuthorize per proteggere il metodo , come illustrato nell'esempio seguente:

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

Esempio di proprietà 3: Per abilitare il flusso delle credenziali client in un server risorse che visita i server delle risorse, seguire questa procedura:

Aggiungere la proprietà seguente al file 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

Aggiungere codice all'applicazione simile all'esempio seguente:

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

Funzionalità avanzate

Supportare il controllo di accesso in base al token ID in un'applicazione Web

Lo starter supporta la creazione GrantedAuthority dall'attestazione di roles un token ID per consentire l'uso del token ID per l'autorizzazione in un'applicazione Web. È possibile usare la appRoles funzionalità di Microsoft Entra ID per creare un'attestazione roles e implementare il controllo di accesso.

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

Per supportare il controllo di accesso in base al token ID in un'applicazione Web, seguire questa procedura:

Aggiungere ruoli dell'app nell'applicazione e assegnarli a utenti o gruppi. Per altre informazioni, vedere Procedura: Aggiungere ruoli dell'app all'applicazione e riceverli nel token.

Aggiungere la configurazione seguente appRoles al manifesto dell'applicazione:

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

Aggiungere codice all'applicazione simile all'esempio seguente:

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

Risoluzione dei problemi

Abilitare la registrazione client

Gli SDK di Azure per Java offrono una storia di registrazione coerente per risolvere e risolvere gli errori delle applicazioni. I log prodotti acquisiranno il flusso di un'applicazione prima di raggiungere il terminale, consentendo di individuare il problema radice. Visualizzare il wiki di registrazione per indicazioni sull'abilitazione della registrazione.

Abilitare la registrazione Spring

Spring consente a tutti i sistemi di registrazione supportati di impostare i livelli di logger nell'ambiente Spring (ad esempio, in application.properties) usando logging.level.<logger-name>=<level> dove level è uno dei livelli TRACE, DEBUG, INFO, WARN, ERROR, FATAL o OFF. È possibile configurare il logger radice usando logging.level.root.

L'esempio seguente mostra le potenziali impostazioni di registrazione nel file application.properties :

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

Per altre informazioni sulla configurazione della registrazione in Spring, vedere Registrazione nella documentazione di Spring.

Passaggi successivi

Per altre informazioni su Spring e Azure, passare al centro di documentazione di Spring in Azure.