Guía del desarrollador de Spring Boot Starter para Microsoft Entra

Este artículo se aplica a: ✔️ Versión 4.19.0 ✔️ versión 5.18.0

En este artículo se describen las características y las principales aplicaciones prácticas de Spring Boot Starter para Microsoft Entra ID. En este artículo también se incluyen instrucciones sobre problemas comunes, soluciones alternativas y pasos de diagnóstico.

Al crear una aplicación web, la administración de las identidades y el acceso son elementos fundamentales. Azure ofrece un servicio de identidad basado en la nube que tiene una integración profunda con el resto del ecosistema de Azure.

Aunque Spring Security facilita la protección de las aplicaciones basadas en Spring, no está adaptado a un proveedor de identidades específico. El Spring Boot Starter para Microsoft Entra ID permite conectar la aplicación web a un inquilino de Microsoft Entra y proteger el servidor de recursos con Microsoft Entra ID. Usa el protocolo Oauth 2.0 para proteger las aplicaciones web y los servidores de recursos.

Los vínculos siguientes proporcionan acceso al paquete de inicio, la documentación y los ejemplos:

• El paquete spring-cloud-azure-starter-active-directory (Maven)
• Inicio rápido
• Muestras

Requisitos previos

Antes de seguir las instrucciones de esta guía, debe disponer de los requisitos previos siguientes:

• Una suscripción de Azure. Si todavía no la tiene, puede activar sus ventajas como suscriptor de MSDN o registrarse para obtener una cuenta de Azure gratuita.
• Un kit de desarrollo de Java (JDK) compatible (versión 8 o superior). Para más información, consulte Compatibilidad con Java en Azure y Azure Stack.
• Apache Maven, versión 3.0 o posterior.
• Una aplicación registrada con Microsoft Entra ID. Para más información, consulte Inicio rápido: Registrar una aplicación en la plataforma de identidad de Microsoft.

Escenarios principales

En esta guía se describe cómo usar el iniciador de Microsoft Entra en los casos siguientes:

• Acceso a una aplicación web
• Acceso a servidores de recursos desde una aplicación web
• Protección de un servidor de recursos o una API
• Acceso a otros servidores de recursos desde un servidor de recursos
• Aplicación web y servidor de recursos en una aplicación

Una aplicación web es cualquier aplicación basada en web que permite a un usuario iniciar sesión. Un servidor de recursos aceptará o denegará el acceso después de validar un token de acceso.

Acceso a una aplicación web

En este escenario se usa el flujo de concesión de código de autorización de OAuth 2.0 para permitir que un usuario inicie sesión con una cuenta Microsoft.

Para usar el iniciador de Microsoft Entra en esta situación, siga estos pasos:

Defina el URI de redirección en <application-base-uri>/login/oauth2/code/. Por ejemplo: http://localhost:8080/login/oauth2/code/. Asegúrese de incluir la barra diagonal / final. Para más información sobre el identificador URI de redirección, consulte Incorporación de un URI de redirección en Inicio rápido: Registro de una aplicación en la plataforma de identidad de Microsoft.

Agregue las siguientes dependencias al archivo 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>

Agregue las siguientes propiedades al archivo application.yml. Puede obtener los valores de estas propiedades en el registro de la aplicación que creó en Azure Portal, como se describe en los requisitos previos.

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

Use la configuración de seguridad predeterminada o proporcione su propia configuración.

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

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

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

Acceso a servidores de recursos desde una aplicación web

Para usar el iniciador de Microsoft Entra en esta situación, siga estos pasos:

Establezca el identificador URI de redirección como se describió anteriormente.

Agregue las siguientes dependencias al archivo 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>

Agregue las siguientes propiedades al archivo application.yml, como se ha descrito anteriormente:

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

Aquí, graph es el nombre del elemento OAuth2AuthorizedClient y scopes son los ámbitos necesarios para el consentimiento al iniciar sesión.

Agregue a la aplicación código similar al del ejemplo siguiente:

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

Aquí, graph es el identificador de cliente configurado en el paso anterior. OAuth2AuthorizedClient contiene el token de acceso, que se usa para acceder al servidor de recursos.

Para ver un ejemplo completo de este caso, consulte spring-cloud-azure-starter-active-directory sample: aad-web-application.

Protección de un servidor de recursos o una API

Este escenario no admite el inicio de sesión, pero protege el servidor mediante la validación del token de acceso. Si el token de acceso es válido, el servidor atiende la solicitud.

Para usar el iniciador de Microsoft Entra en esta situación, siga estos pasos:

Agregue las siguientes dependencias al archivo 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>

Agregue las siguientes propiedades al archivo application.yml, como se ha descrito anteriormente:

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

Puede usar los valores <your-client-ID> y <your-app-ID-URI> para comprobar el token de acceso. Puede obtener el valor <your-app-ID-URI> en Azure Portal, tal como se muestra en las siguientes imágenes:

Use la configuración de seguridad predeterminada o proporcione su propia configuración.

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

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

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

Para ver un ejemplo completo de este caso, consulte spring-cloud-azure-starter-active-directory sample: aad-resource-server.

Acceso a otros servidores de recursos desde un servidor de recursos

Este escenario posibilita un servidor de recursos que visita otros servidores de recursos.

Para usar el iniciador de Microsoft Entra en esta situación, siga estos pasos:

Agregue las siguientes dependencias al archivo 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>

Agregue las siguientes propiedades al archivo 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

Use el atributo @RegisteredOAuth2AuthorizedClient en el código para acceder al servidor de recursos relacionado, como se muestra en el ejemplo siguiente:

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

Para ver un ejemplo completo de este caso, consulte spring-cloud-azure-starter-active-directory sample: aad-resource-obo.

Aplicación web y servidor de recursos en una aplicación

Este escenario admite acceso a una aplicación web y protección de un servidor de recursos o una API en una aplicación.

Para usar aad-starter en este caso, realice estos pasos:

Agregue las siguientes dependencias al archivo 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>

Actualice el archivo application.yml. Establezca la propiedad spring.cloud.azure.active-directory.application-type en web_application_and_resource_server y especifique el tipo de autorización de cada cliente de autorización, como se muestra en el ejemplo siguiente.

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

Escriba código Java para configurar varias instancias de 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();
    }
}

Tipo de aplicación

La propiedad spring.cloud.azure.active-directory.application-type es opcional porque su valor se puede deducir de las dependencias. Debe establecer manualmente la propiedad solo cuando use el valor web_application_and_resource_server.

Propiedades configurables

El Spring Boot Starter para Microsoft Entra ID ofrece las siguientes propiedades:

En los siguientes ejemplos se muestra cómo usar estas propiedades:

Ejemplo de propiedad 1: para usar Azure China 21Vianet en lugar de Azure global, use el paso siguiente.

• Agregue las siguientes propiedades al archivo application.yml:

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

Con este método, puede usar una nube soberana de Azure o una nube nacional en lugar de la nube pública de Azure.

Ejemplo de propiedad 2: para usar un nombre de grupo para proteger algún método en una aplicación web, siga estos pasos:

Agregue la siguiente propiedad al archivo application.yml:

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

Use la configuración de seguridad predeterminada o proporcione su propia configuración.

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

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

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

Use la anotación @PreAuthorize para proteger el método, como se muestra en el ejemplo siguiente:

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

Ejemplo de propiedad 3: para habilitar el flujo de credenciales de cliente en un servidor de recursos que visita otros servidores de recursos, siga estos pasos:

Agregue la siguiente propiedad al archivo 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

Agregue a la aplicación código similar al del ejemplo siguiente:

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

Características avanzadas

Compatibilidad con el control de acceso mediante un token de identificador en una aplicación web

El iniciador admite la creación de un elemento GrantedAuthority a partir de la notificación roles de un token de identificador para permitir el uso del token de identificador para la autorización en una aplicación web. Puede usar la característica appRoles de Microsoft Entra ID para crear una notificación roles e implementar el control de acceso.

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

Para admitir el control de acceso mediante un token de identificador en una aplicación web, siga estos pasos:

Agregue roles de aplicación en la aplicación y asígnelos a usuarios o grupos. Para más información, consulte Procedimiento: Incorporación de roles de aplicación a una aplicación y su recepción en el token.

Agregue la siguiente configuración de appRoles al manifiesto de la aplicación:

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

Agregue a la aplicación código similar al del ejemplo siguiente:

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

Solución de problemas

Habilitación del registro de cliente

Los SDK de Azure para Java incluyen un historial de registro uniforme que permite solucionar y resolver errores de la aplicación. Los registros generados capturarán el flujo de una aplicación antes de alcanzar el estado terminal para ayudar a encontrar el problema principal. Consulte la wiki de registro para obtener instrucciones sobre cómo habilitar el registro.

Habilitación del registro de Spring

Spring permite que todos los sistemas de registro admitidos establezcan niveles de registrador en el entorno de Spring (por ejemplo, en application.properties), mediante logging.level.<logger-name>=<level>, donde level (nivel) puede ser TRACE, DEBUG, INFO, WARN, ERROR, FATAL u OFF. Puede configurar el registrador raíz mediante logging.level.root.

En el ejemplo siguiente se muestra la posible configuración de registro en el archivo application.properties:

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

Para más información sobre la configuración del registro en Spring, consulte Registro en la documentación de Spring.

Pasos siguientes

Para más información acerca de Spring y Azure, vaya al centro de documentación de Azure.