Guia do desenvolvedor do Spring Boot Starter for Microsoft Entra

Este artigo aplica-se a:✅ Versão 4.19.0 ✅ Versão 5.19.0

Este artigo descreve os recursos e cenários principais do Spring Boot Starter para Microsoft Entra ID. O artigo também inclui orientações 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 peças fundamentais. O Azure oferece um serviço de identidade baseado na nuvem que tem integração profunda com o resto do ecossistema do Azure.

Embora o Spring Security facilite a proteção de seus aplicativos baseados no Spring, ele não é adaptado a 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 Microsoft Entra ID. Ele usa o protocolo Oauth 2.0 para proteger aplicativos da web e servidores de recursos.

Os links a seguir fornecem acesso ao pacote inicial, documentação e exemplos:

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

Pré-requisitos

Para seguir as instruções deste guia, você deve ter os seguintes pré-requisitos:

• Uma assinatura do Azure; se você ainda não tiver uma assinatura do Azure, poderá ativar seus benefícios de assinante do MSDN ou se inscrever para uma conta gratuita do Azure .
• Um Java Development Kit (JDK) suportado, versão 8 ou superior. Para obter mais informações, consulte suporte Java no Azure e Azure Stack.
• Apache Maven, versão 3.0 ou superior.
• Uma aplicação registada com o Microsoft Entra ID. Para obter mais informações, consulte Guia de início rápido : registrar um aplicativo com a plataforma de identidade da Microsoft.

Cenários principais

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

• Aceder a uma aplicação Web
• Acessar servidores de recursos a partir de um aplicativo Web
• Proteger um servidor de recursos/API
• Acessar outros servidores de recursos a partir de um servidor de recursos
• aplicativo Web e servidor de recursos em um aplicativo

Um aplicativo Web é qualquer aplicação baseada na Web que permite que um utilizador inicie sessão. Um servidor de recursos aceitará ou negará acesso após validar um token de acesso.

Aceder a uma aplicação Web

Este cenário utiliza o fluxo de concessão de código de autorização OAuth 2.0 para permitir que um utilizador inicie sessão com uma conta Microsoft.

Para usar o Microsoft Entra starter nesse cenário, use as seguintes etapas:

Defina o URI de redirecionamento como <application-base-uri>/login/oauth2/code/. Por exemplo: http://localhost:8080/login/oauth2/code/. Certifique-se de incluir o final /. Para obter mais informações sobre o URI de redirecionamento, consulte Adicionar um URI de redirecionamento em Iniciação Rápida: registrar uma aplicação com a plataforma de identidade da Microsoft.

Adicione as seguintes dependências ao seu 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 seu arquivo application.yml. Você pode obter os valores para essas propriedades do registro de aplicativo criado 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.

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

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

Acessar servidores de recursos a partir de um aplicativo Web

Para usar o Microsoft Entra starter nesse cenário, use as seguintes etapas:

Defina o URI de redirecionamento conforme descrito anteriormente.

Adicione as seguintes dependências ao seu 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 seu 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 OAuth2AuthorizedCliente scopes são as permissões necessárias para o consentimento ao fazer login.

Adicione código ao seu aplicativo semelhante ao exemplo a seguir:

@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 é o ID do cliente configurado na etapa anterior. OAuth2AuthorizedClient contém o token de acesso, que é usado para acessar o servidor de recursos.

Para ver um exemplo completo demonstrando este cenário, consulte o exemplo de spring-cloud-azure-starter-active-directory: aad-web-application.

Proteger um servidor/API de recursos

Este cenário não permite iniciar sessão, mas protege o servidor validando o token de acesso. Se o token de acesso for válido, o servidor atende a solicitação.

Para usar o Microsoft Entra starter nesse cenário, use as seguintes etapas:

Adicione as seguintes dependências ao seu 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 seu 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 tanto os valores <your-client-ID> quanto os valores <your-app-ID-URI> para verificar o token de acesso. Você pode obter o valor seu-aplicativo-ID-URI no portal do Azure, conforme mostrado nas imagens a seguir:

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

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

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

Para obter um exemplo completo demonstrando esse cenário, consulte exemplo de spring-cloud-azure-starter-active-directory: aad-resource-server.

Aceder a outros servidores de recursos a partir de um servidor de recursos

Este cenário suporta um servidor de recursos que visita outros servidores de recursos.

Para usar o Microsoft Entra starter nesse cenário, use as seguintes etapas:

Adicione as seguintes dependências ao seu 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 seu 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 exemplo a seguir:

@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 este cenário, consulte o exemplo do spring-cloud-azure-starter-active-directory: aad-resource-server-obo.

Aplicativo Web e servidor de recursos em um aplicativo

Este cenário oferece suporte ao Acessar um aplicativo web e Proteger um servidor de recursos/API num só aplicativo.

Para utilizar aad-starter neste cenário, siga estes passos:

Adicione as seguintes dependências ao seu 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 seu arquivo application.yml. Defina a propriedade spring.cloud.azure.active-directory.application-type como web_application_and_resource_servere especifique o tipo de autorização para cada cliente de autorização, conforme mostrado no 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 código Java para configurar várias instâncias HttpSecurity.

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

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

Tipo de aplicação

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

Propriedades configuráveis

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

Os exemplos a seguir mostram como usar essas propriedades:

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

• Adicione as seguintes propriedades ao seu arquivo application.yml:

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

Com este método, pode utilizar um Azure soberano ou nacional 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, use as seguintes etapas:

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

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

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

Use a anotação @PreAuthorize para proteger o método, conforme mostrado no exemplo a seguir:

@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 num servidor de recursos que interage com outros servidores de recursos, siga as etapas abaixo:

Adicione a seguinte propriedade ao seu 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 exemplo a seguir:

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

Funcionalidades avançadas

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

O starter suporta a criação de GrantedAuthority a partir da declaração de roles de um 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 de 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 em seu aplicativo e atribua-as a usuários ou grupos. Para obter mais informações, consulte Como adicionar funções de aplicativo ao seu aplicativo e recebê-las no token.

Adicione a seguinte configuração appRoles ao manifesto do 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 exemplo a seguir:

@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 aplicativos. Os logs produzidos capturarão o fluxo de um aplicativo antes de chegar ao terminal, ajudando a localizar o problema raiz. Veja o registro em log wiki para obter orientação sobre como habilitar o registro.

Ativar a geração de logs do Spring

O Spring permite que todos os sistemas de logging suportados definam níveis de registo no ambiente Spring (por exemplo, em application.properties) usando logging.level.<logger-name>=<level>, em que o nível pode ser um dos TRACE, DEBUG, INFO, WARN, ERROR, FATAL ou OFF. Você pode configurar o registrador raiz usando logging.level.root.

O exemplo a seguir mostra possíveis configurações de 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 de registo no Spring, consulte Registo na documentação do Spring.

Próximos passos

Para saber mais sobre o Spring e o Azure, continue para o centro de documentação do Spring on Azure.