Guia do desenvolvedor do Spring Boot Starter para Microsoft Entra

Este artigo se aplica a: ✔️ Versão 4.19.0 ✔️ Versão 5.17.0

Este artigo descreve os recursos e os principais cenários do Spring Boot Starter para Microsoft Entra ID. Este artigo também inclui diretrizes sobre problemas comuns, soluções alternativas e etapas de diagnóstico.

Quando você está criando um aplicativo Web, o gerenciamento de identidade e acesso são partes fundamentais. O Azure oferece um serviço de identidade baseado em nuvem que tem integração profunda com o restante do ecossistema do Azure.

Embora a Segurança do Spring facilite a proteção dos seus aplicativos baseados em Spring, ela não é adaptada para um provedor de identidade específico. O Spring Boot Starter para Microsoft Entra ID permite que você conecte seu aplicativo Web a um locatário do Microsoft Entra e proteja seu servidor de recursos com o ID do Microsoft Entra. Ele usa o protocolo OAuth 2.0 para proteger aplicativos Web e servidores de recursos.

Os seguintes links fornecem acesso ao pacote inicial, à documentação e aos exemplos:

• Pacote spring-cloud-azure-starter-active-directory (Maven)
• Início rápido
• Amostras

Pré-requisitos

Para seguir as instruções deste artigo, é necessário cumprir os seguintes pré-requisitos:

• Uma assinatura do Azure; se ainda não tiver uma assinatura do Azure, você poderá ativar o benefício de assinante do MSDN ou inscrever-se para uma conta gratuita do Azure.
• Um JDK (Java Development Kit) compatível, versão 8 ou posterior. Para obter mais informações, confira Suporte a Java no Azure e no Azure Stack.
• Apache Maven, versão 3.0 ou superior.
• Um aplicativo registrado com o Microsoft Entra ID. Para obter mais informações, consulte Início rápido: Registrar um aplicativo na plataforma de identidade da Microsoft.

Principais cenários

Este guia descreve como usar o iniciador do Microsoft Entra nos seguintes cenários:

• Acessar um aplicativo Web
• Acessar servidores de recursos por meio de um aplicativo Web
• Proteger um servidor de recursos/uma API
• Acessar outros servidores de recursos por meio de um servidor de recursos
• Aplicativo Web e servidor de recursos em um aplicativo

Aplicativo Web é qualquer aplicativo baseado na Web que permita a um usuário entrar. O servidor de recursos aceita ou nega acessos após validar tokens de acesso.

Acessar um aplicativo Web

Esse cenário usa o fluxo de concessão de código de autorização OAuth 2.0 para permitir que um usuário entre com uma conta Microsoft.

Para usar o iniciador do Microsoft Entra neste cenário, execute as seguintes etapas:

Defina o URI de redirecionamento como <application-base-uri>/login/oauth2/code/. Por exemplo: http://localhost:8080/login/oauth2/code/. Inclua à direita /. Para obter mais informações sobre o URI de redirecionamento, confira Adicionar um URI de redirecionamento no Início rápido: registrar um aplicativo com a plataforma de identidade da Microsoft.

Adicione as dependências a seguir no arquivo 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>

Adicione as propriedades a seguir ao arquivo application.yml. Você pode obter os valores dessas propriedades por meio do registro de aplicativo que criou no portal do Azure, conforme descrito nos pré-requisitos.

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

Use a configuração de segurança padrão ou forneça sua própria configuração.

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

Acessar servidores de recursos por meio de um aplicativo Web

Para usar o iniciador do Microsoft Entra neste cenário, execute as seguintes etapas:

Defina o URI de redirecionamento conforme descrito anteriormente.

Adicione as dependências a seguir no arquivo 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>

Adicione as seguintes propriedades ao arquivo application.yml, conforme 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

Aqui, graph é o nome do seu OAuth2AuthorizedClient e scopes são os escopos necessários para o consentimento ao fazer logon.

Adicione código ao seu aplicativo semelhante ao seguinte exemplo:

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

Aqui, graph é a ID do cliente configurada na etapa anterior. OAuth2AuthorizedClient contém o token de acesso, que é usado para acessar o servidor de recursos.

Para obter um exemplo completo que demonstra esse cenário, consulte spring-cloud-azure-starter-active-directory sample: aad-web-application.

Proteger um servidor de recursos/uma API

Esse cenário não dá suporte à entrada, mas protege o servidor validando o token de acesso. Se o token de acesso for válido, o servidor entregará a solicitação.

Para usar o iniciador do Microsoft Entra neste cenário, execute as seguintes etapas:

Adicione as dependências a seguir no arquivo 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>

Adicione as seguintes propriedades ao arquivo application.yml, conforme descrito anteriormente:

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

Você pode usar os valores <your-client-ID> e <your-app-ID-URI> para verificar o token de acesso. Você pode obter o valor <your-app-ID-URI> do portal do Azure, conforme mostrado nas seguintes imagens:

Use a configuração de segurança padrão ou forneça sua própria configuração.

@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 obter um exemplo completo que demonstra esse cenário, consulte spring-cloud-azure-starter-active-directory sample: aad-resource-server.

Acessar outros servidores de recursos por meio de um servidor de recursos

Esse cenário dá suporte para um servidor de recursos visitar outros servidores de recursos.

Para usar o iniciador do Microsoft Entra neste cenário, execute as seguintes etapas:

Adicione as dependências a seguir no arquivo 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>

Adicione as seguintes propriedades ao arquivo 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 o atributo @RegisteredOAuth2AuthorizedClient em seu código para acessar o servidor de recursos relacionado, conforme mostrado no seguinte exemplo:

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

Para obter um exemplo completo que demonstra esse cenário, consulte spring-cloud-azure-starter-active-directory sample: aad-resource-server-obo.

Aplicativo Web e servidor de recursos em um aplicativo

Este cenário dá suporte para Acessar um aplicativo Web e Proteger um servidor/API de recursos em um aplicativo.

Para usar aad-starter nesse cenário, siga estas etapas:

Adicione as dependências a seguir no arquivo 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>

Atualize o arquivo application.yml. Defina a propriedade spring.cloud.azure.active-directory.application-type como web_application_and_resource_server e especifique o tipo de autorização de cada cliente de autorização, conforme mostra o exemplo a seguir.

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

Escreva o código Java para configurar várias instâncias 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 aplicativo

A propriedade spring.cloud.azure.active-directory.application-type é opcional porque o respectivo valor pode ser inferido por dependências. Você precisa definir a propriedade manualmente somente quando o valor web_application_and_resource_server é usado.

Propriedades configuráveis

O Iniciador do Spring Boot para Microsoft Entra ID fornece as seguintes propriedades:

Os seguintes exemplos mostram como você usa essas propriedades:

Exemplo de propriedade 1: para usar o Azure China 21Vianet em vez do Azure Global, execute a etapa a seguir.

• Adicione as seguintes propriedades ao arquivo application.yml:

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

Com esse método, você pode usar uma nuvem soberana ou nacional do Azure em vez da nuvem pública do Azure.

Exemplo de propriedade 2: para usar um nome de grupo para proteger algum método em um aplicativo Web, execute as seguintes etapas:

Adicione a seguinte propriedade ao arquivo application.yml:

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

Use a configuração de segurança padrão ou forneça sua própria configuração.

@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 a anotação @PreAuthorize para proteger o método, conforme mostrado no seguinte exemplo:

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

Exemplo de propriedade 3: para habilitar o fluxo de credenciais do cliente em um servidor de recursos que visite outros servidores de recursos, use as seguintes etapas:

Adicione a seguinte propriedade ao arquivo 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

Adicione código ao seu aplicativo semelhante ao seguinte exemplo:

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

Recursos avançados

Suporte ao controle de acesso por token de ID em um aplicativo Web

O iniciador dá suporte à criação de GrantedAuthority por meio de uma declaração roles de token de ID para permitir o uso do token de ID para autorização em um aplicativo Web. Você pode usar o recurso appRoles do Microsoft Entra ID para criar uma declaração roles e implementar o controle de acesso.

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

Para dar suporte ao controle de acesso por token de ID em um aplicativo Web, use as seguintes etapas:

Adicione funções de aplicativo ao seu aplicativo e atribua-nas a usuários ou grupos. Para obter mais informações, confira Como fazer: adicionar funções de aplicativo ao seu aplicativo e recebê-las no token.

Adicione a seguinte configuração appRoles ao manifesto do seu aplicativo:

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

Adicione código ao seu aplicativo semelhante ao seguinte exemplo:

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

Solução de problemas

Habilitar o log do cliente

Os SDKs do Azure para Java oferecem uma história de log consistente para ajudar a solucionar problemas e resolver erros de aplicativo. Os logs produzidos capturam o fluxo de um aplicativo antes de alcançar o terminal, ajudando a localizar o problema raiz. Confira o wiki de registro em log para obter diretrizes sobre como habilitar esse recurso.

Habilitar o registro em log no Spring

O Spring permite que todos os sistemas de registrar em log compatíveis definam níveis de agente no ambiente do Spring (por exemplo, em application.properties) usando logging.level.<logger-name>=<level> nos casos em que o nível é TRACE, DEBUG, INFO, WARN, ERROR, FATAL ou OFF. Você pode configurar o agente raiz usando logging.level.root.

O seguinte exemplo mostra as possíveis configurações para registrar em log no arquivo application.properties:

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

Para obter mais informações sobre a configuração para registrar em log no Spring, confira Registro em log na documentação do Spring.

Próximas etapas

Para saber mais sobre o Spring e o Azure, continue no Spring no Centro de Documentação do Azure.