Guide du développeur Spring Boot Starter pour Microsoft Entra

Cet article s’applique à : ✔️ Version 4.19.0 ✔️ Version 5.18.0

Cet article décrit les fonctionnalités et les scénarios de base du démarreur Spring Boot pour Microsoft Entra ID. Cet article contient également des conseils sur les problèmes courants, des solutions de contournement et des étapes de diagnostic.

Quand vous créez une application web, la gestion des identités et des accès est l’un des aspects fondamentaux à prendre en compte. Azure fournit un service d’identité basé sur le cloud qui s’intègre parfaitement aux autres composants de l’écosystème Azure.

Spring Security facilite la sécurisation de vos applications basées sur Spring, mais il peut aussi être utilisé pour d’autres fournisseurs d’identité. Le Spring Boot Starter for Microsoft Entra ID vous permet de connecter votre application Web à un locataire Microsoft Entra et de protéger votre serveur de ressources avec Microsoft Entra ID. Il recourt au protocole OAuth 2.0 pour assurer la protection des applications web et des serveurs de ressources.

Utilisez les liens suivants pour accéder au package de démarrage, à la documentation et à des exemples :

• Le package spring-cloud-azure-starter-active-directory (Maven)
• Démarrage rapide
• Exemples

Prérequis

Pour être en mesure de suivre les instructions de ce guide, vous devez disposer des éléments suivants :

• Un abonnement Azure. Si vous n’avez pas déjà un abonnement Azure, vous pouvez activer vos avantages d’abonné MSDN ou vous inscrire pour un compte Azure gratuit.
• Un kit de développement Java (JDK) pris en charge, version 8 ou supérieure. Pour plus d’informations, consultez Prise en charge de Java sur Azure et Azure Stack.
• Apache Maven, version 3.0 ou supérieure.
• Application inscrite auprès de Microsoft Entra ID. Pour plus d’informations, consultez Démarrage rapide : Enregistrer une application avec la plateforme d’identités Microsoft.

Principaux scénarios

Ce guide décrit comment utiliser le démarreur Microsoft Entra dans les scénarios suivants :

• Accéder à une application web
• Accéder à des serveurs de ressources à partir d’une application web
• Protéger une API/un serveur de ressources
• Accéder à d’autres serveurs de ressources à partir d’un serveur de ressources
• Application web et serveur de ressources dans une même application

Une application web est une application basée sur le web qui permet à un utilisateur de se connecter. Un serveur de ressources accepte ou refuse l’accès après validation d’un jeton d’accès.

Accéder à une application web

Ce scénario utilise le flux d’octroi de code d’autorisation OAuth 2.0 pour permettre à un utilisateur de se connecter en utilisant un compte Microsoft.

Pour utiliser le démarreur Microsoft Entra dans ce scénario, suivez les étapes suivantes :

Définissez l'URI de <redirection à application-base-uri>/login/oauth2/code/. Par exemple : http://localhost:8080/login/oauth2/code/. N’oubliez pas la barre oblique (/) à la fin. Pour plus d’informations sur l’URI de redirection, consultez Ajouter un URI de redirection dans Démarrage rapide : Inscrire une application avec la plateforme d’identités Microsoft.

Ajoutez les dépendances suivantes dans votre fichier 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>

Ajoutez les propriétés suivantes dans votre fichier application.yml. Vous pouvez obtenir les valeurs de ces propriétés à partir de l’inscription d’application que vous avez créée dans le portail Azure, comme cela est décrit dans la section des prérequis.

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

Utilisez la configuration de sécurité par défaut ou fournissez votre propre configuration.

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

Accéder à des serveurs de ressources à partir d’une application web

Pour utiliser le démarreur Microsoft Entra dans ce scénario, suivez les étapes suivantes :

Définissez l’URI de redirection comme vous l’avez appris précédemment.

Ajoutez les dépendances suivantes dans votre fichier 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>

Ajoutez les propriétés suivantes dans votre fichier application.yml, comme décrit précédemment :

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

Ici, graph est le nom de votre OAuth2AuthorizedClient, et scopes définit les étendues requises pour le consentement à la connexion.

Ajoutez du code à votre application, sur le modèle de l’exemple suivant :

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

Ici, graph est l’ID client qui a été configuré à l’étape précédente. OAuth2AuthorizedClient contient le jeton d’accès utilisé pour accéder au serveur de ressources.

Pour un exemple complet démontrant ce scénario, voir spring-cloud-azure-starter-active-directory sample : aad-web-application.

Protéger une API/un serveur de ressources

Ce scénario ne permet pas la connexion, mais il protège le serveur en validant le jeton d’accès. Si le jeton d’accès est valide, le serveur répond à la requête.

Pour utiliser le démarreur Microsoft Entra dans ce scénario, suivez les étapes suivantes :

Ajoutez les dépendances suivantes dans votre fichier 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>

Ajoutez les propriétés suivantes dans votre fichier application.yml, comme décrit précédemment :

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

Vous pouvez utiliser les valeurs <your-client-ID> et <your-app-ID-URI> pour vérifier le jeton d'accès. Vous pouvez obtenir la valeur <your-app-ID-URI> à partir du portail Azure, comme le montrent les images suivantes :

Utilisez la configuration de sécurité par défaut ou fournissez votre propre configuration.

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

Pour un exemple complet démontrant ce scénario, voir spring-cloud-azure-starter-active-directory sample : aad-resource-server.

Accéder à d’autres serveurs de ressources à partir d’un serveur de ressources

Ce scénario permet à un serveur de ressources d’accéder à d’autres serveurs de ressources.

Pour utiliser le démarreur Microsoft Entra dans ce scénario, suivez les étapes suivantes :

Ajoutez les dépendances suivantes dans votre fichier 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>

Ajoutez les propriétés suivantes dans votre fichier 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

Ajoutez l’attribut @RegisteredOAuth2AuthorizedClient dans votre code pour permettre l’accès au serveur de ressources associé, comme le montre l’exemple suivant :

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

Pour un exemple complet de ce scénario, voir spring-cloud-azure-starter-active-directory sample : aad-resource-server-obo.

Application web et serveur de ressources dans une même application

Ce scénario prend en charge l’accès à une application web et la protection d’un serveur de ressources/d’une API dans une même application.

Pour utiliser aad-starter dans ce scénario, procédez comme suit :

Ajoutez les dépendances suivantes dans votre fichier 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>

Mettez à jour votre fichier application.yml. Affectez à la propriété spring.cloud.azure.active-directory.application-type la valeur web_application_and_resource_server et spécifiez le type d’autorisation pour chaque client d’autorisation, comme indiqué dans l’exemple suivant.

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

Écrire du code Java pour configurer plusieurs instances HttpSecurity.

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

Type d’application

La propriété spring.cloud.azure.active-directory.application-type est facultative, car sa valeur peut être déduite par des dépendances. Vous devez définir manuellement cette propriété uniquement lorsque vous utilisez la valeur web_application_and_resource_server.

Propriétés configurables

Le Spring Boot Starter pour Microsoft Entra ID fournit les propriétés suivantes :

Les exemples suivants vous montrent comment utiliser ces différentes propriétés :

Exemple de propriété 1 : Pour utiliser Azure China 21Vianet au lieu d’Azure Global, effectuez l’étape suivante.

• Ajoutez les propriétés suivantes dans votre fichier application.yml :

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

Avec cette méthode, vous pouvez utiliser un cloud national ou souverain Azure au lieu du cloud public Azure.

Exemple de propriété 2 : Pour utiliser un nom de groupe afin de protéger une méthode dans une application web, effectuez les étapes ci-après :

Ajoutez la propriété suivante dans votre fichier application.yml :

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

Utilisez la configuration de sécurité par défaut ou fournissez votre propre configuration.

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

Utilisez l’annotation @PreAuthorize pour protéger la méthode, comme illustré dans cet exemple :

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

Exemple de propriété 3 : Pour activer le flux d’informations d’identification client sur un serveur de ressources qui accède à d’autres serveurs de ressources, effectuez les étapes suivantes :

Ajoutez la propriété suivante dans votre fichier 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

Ajoutez du code à votre application, sur le modèle de l’exemple suivant :

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

Fonctionnalités avancées

Prise en charge du contrôle d’accès par jeton d’ID dans une application web

Le starter prend en charge la création d’un GrantedAuthority à partir de la revendication roles d’un jeton d’ID pour permettre l’autorisation par jeton d’ID dans une application web. Vous pouvez utiliser la fonctionnalité appRoles de Microsoft Entra ID pour créer une réclamation roles et mettre en place un contrôle d'accès.

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

Pour implémenter le contrôle d’accès par jeton d’ID dans une application web, procédez comme suit :

Ajoutez des rôles d’application dans votre application et attribuez-les à des utilisateurs ou à des groupes. Pour plus d’informations, consultez Procédure : Ajouter des rôles d’application dans votre application et les recevoir dans le jeton.

Ajoutez la configuration appRoles suivante au manifeste de votre application :

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

Ajoutez du code à votre application, sur le modèle de l’exemple suivant :

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

Dépannage

Activer la journalisation du client

Les SDK Azure pour Java offrent une histoire de journal cohérente pour aider à dépanner et à résoudre les erreurs d'application. Les journaux générés capturent le flux d’une application avant le point terminal, facilitant ainsi la localisation de la cause racine d’une erreur. Consultez le wiki sur la journalisation pour obtenir des conseils sur l’activation de la journalisation.

Activer la journalisation Sprint

Spring permet à tous les systèmes de journalisation pris en charge de définir des niveaux de journalisation dans l’environnement Spring (par exemple, dans application.properties) en utilisant logging.level.<logger-name>=<level>, où « level » peut avoir l’une des valeurs suivantes : TRACE, DEBUG, INFO, WARN, ERROR, FATAL ou OFF. Vous pouvez configurer le journal racine avec logging.level.root.

L’exemple suivant montre des paramètres de journalisation possibles dans le fichier application.properties :

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

Pour plus d’informations sur la configuration de la journalisation dans Spring, consultez Journalisation dans la documentation Spring.

Étapes suivantes

Pour en savoir plus sur Spring et Azure, poursuivez vers le centre de documentation Spring sur Azure.