Proteger sua API REST usando o Spring Cloud Azure

Este tutorial mostra como habilitar a proteção de APIs REST com Microsoft Entra ID em um aplicativo Spring Boot.

Este artigo usa um sistema de pesquisa como exemplo. O sistema de pesquisa fornece as seguintes APIs REST:

GET /api/survey/question é para visualizar a pesquisa.
POST /api/survey é para preencher a pesquisa.
GET /api/survey é para exibir o resultado da pesquisa.

Neste artigo, você protege essas APIs aplicando o RBAC (controle de acesso baseado em função) para impor os seguintes requisitos:

GET /api/survey/question está disponível para cada solicitação.
POST /api/survey está disponível para solicitações de usuário autenticadas que contêm um token de acesso com o SCOPE_Survey.User escopo concedido.
GET /api/survey está disponível para solicitações de usuário administrador autenticadas que contêm um token de acesso com o escopo SCOPE_Survey.Admin concedido.

Pré-requisitos

Uma assinatura Azure – criar uma gratuitamente.
Java Development Kit (JDK) versão 8 ou superior.
Apache Maven
Azure CLI
Uma instância de Microsoft Entra. Para obter instruções sobre como criar um, consulte Quickstart: Criar um novo locatário em Microsoft Entra ID.
Um aplicativo Spring Boot. Caso não tiver um, crie um projeto Maven com o Spring Initializr. Selecione Maven Project e, em Dependencies, adicione as dependências Spring Web, OAuth2 Resource Server e Microsoft Entra ID e selecione Java versão 8 ou superior.

Importante

É necessário o Spring Boot versão 2.5 ou posterior para concluir as etapas neste artigo.

Registre a API REST

Use as etapas a seguir para registrar sua API Web no portal do Azure.

Entre no portal Azure.
Se você tiver acesso a vários locatários, use o filtro Diretório + assinatura ( ) para selecionar o locatário no qual deseja registrar um aplicativo.
Localize e selecione Microsoft Entra ID.
Em Manage, selecione App registrations>Novo registro.
Insira um nome para seu aplicativo no campo Nome, por exemplo, Api-SurveyService. Os usuários do seu aplicativo podem ver esse nome e você pode alterá-lo mais tarde.
Em Tipos de conta compatíveis, selecione Contas em qualquer diretório da organização.
Selecione Registrar para criar o aplicativo.
Na página Visão Geral do aplicativo, localize o valor da ID do aplicativo (cliente) e registre-o para uso posterior. Você precisa dele para configurar o arquivo de configuração YAML para este projeto.
Em Gerenciar, selecione Expor uma API>Adicionar um escopo. Aceite o URI da ID do Aplicativo proposto (api://{clientId}) selecionando Salvar e continuar e insira as seguintes informações:
- Para Nome do escopo, insira Survey.User.
- Para quem pode consentir, selecione Administradores e usuários.
- Para o nome de exibição de consentimento do administrador, insira Access the survey service as a user..
- Para obter a descrição de consentimento do administrador, insira Allows the users to write data in survey system..
- Para o nome de exibição de consentimento do usuário, insira Access the survey service as a user..
- Para a descrição de consentimento do usuário, insira Allows the users to write data in survey system..
- Para Estado, mantenha Habilitado.
- Selecione Adicionar escopo.
Repita a etapa anterior para adicionar outro escopo. Ao selecionar Adicionar um escopo, insira as seguintes informações:
- Para Nome do escopo, insira Survey.Admin.
- Para quem pode consentir, selecione Administradores e usuários.
- Para o nome de exibição de consentimento do administrador, insira Access the survey service as a admin..
- Para obter a descrição de consentimento do administrador, insira Allows the users to view data in survey system..
- Para o nome de exibição de consentimento do usuário, insira Access the survey service as a admin..
- Para a descrição de consentimento do usuário, insira Allows the users to view data in survey system..
- Para Estado, mantenha Habilitado.
- Selecione Adicionar escopo.

Habilitar o Microsoft Entra ID do Spring Cloud Azure Starter

Em seguida, habilite a proteção da API REST com o Spring Cloud Azure.

Adicionar dependências de segurança

Para instalar o módulo de Azure Active Directory do Spring Cloud Azure Starter, adicione as seguintes dependências ao arquivo pom.xml:

Spring Cloud Azure Bill of Materials (BOM):
```
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.azure.spring</groupId>
      <artifactId>spring-cloud-azure-dependencies</artifactId>
      <version>7.1.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
```
Observação

Se você estiver usando o Spring Boot 4.0.x, defina a spring-cloud-azure-dependencies versão como 7.1.0.

Se você estiver usando o Spring Boot 3.5.x, defina a spring-cloud-azure-dependencies versão como 6.1.0.

Se você estiver usando o Spring Boot 3.1.x-3.5.x, defina a spring-cloud-azure-dependencies versão como 5.25.0.

Se você estiver usando o Spring Boot 2.x, certifique-se de definir a spring-cloud-azure-dependencies versão como 4.20.0.

Esta lista de materiais (BOM) deve ser configurada na <dependencyManagement> seção do arquivo pom.xml. Isso garante que todas as dependências de Azure do Spring Cloud estejam usando a mesma versão.

Para obter mais informações sobre a versão usada para este BOM, consulte Which Version of Spring Cloud Azure Should I Use.

O artefato Microsoft Entra Starter do Spring Cloud Azure:

<dependency>
  <groupId>com.azure.spring</groupId>
  <artifactId>spring-cloud-azure-starter-active-directory</artifactId>
</dependency>

O artefato do Servidor de Recursos OAuth2 do Spring Boot Starter:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>

Autorizar solicitações HTTP

Para proteger as APIs REST da pesquisa, adicione a anotação @PreAuthorize("hasAuthority('SCOPE_Survey.xxx')") com um nome de escopo concreto para habilitar a proteção, conforme mostrado no exemplo a seguir:

import org.springframework.http.MediaType;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.time.LocalDateTime;
import java.util.LinkedHashMap;
import java.util.Map;

@RestController
@RequestMapping("/api/survey")
public class SurveyController {

    private static final String QUESTION = "Which sports do you like most?";
    private final Map<LocalDateTime, String> surveys = new LinkedHashMap<>();

    @GetMapping(value = "/question", produces = MediaType.APPLICATION_JSON_VALUE)
    public String question() {
        return QUESTION;
    }

    @PostMapping
    @PreAuthorize("hasAuthority('SCOPE_Survey.User')")
    public String addAnswer(@RequestParam("answer") String answer) {
        if (StringUtils.hasText(answer)) {
            surveys.put(LocalDateTime.now(), answer);
            return "succeeded";
        }
        return "Failed";
    }

    @GetMapping(produces = MediaType.APPLICATION_JSON_VALUE)
    @PreAuthorize("hasAuthority('SCOPE_Survey.Admin')")
    public Map<LocalDateTime, String> list() {
        return surveys;
    }
}

Atualize a configuração do YAML, conforme mostrado no exemplo a seguir:

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

Observação

Em tokens v1.0, a configuração requer a ID do cliente da API, enquanto em tokens v2.0, você pode usar a ID do cliente ou o URI da ID do aplicativo na solicitação. Você pode configurar ambos para concluir corretamente a validação do público-alvo.

Implantar em Azure Spring Apps

Depois de ter o aplicativo Spring Boot em execução localmente, você poderá movê-lo para produção. Azure Spring Apps facilita a implantação de aplicativos Spring Boot para Azure sem alterações de código. O serviço gerencia a infraestrutura dos aplicativos do Spring para que os desenvolvedores possam se concentrar no código. Azure Spring Apps fornece gerenciamento de ciclo de vida usando monitoramento e diagnóstico abrangentes, gerenciamento de configuração, descoberta de serviço, integração de CI/CD, implantações azul-verde e muito mais. Para obter mais informações, consulte Quickstart: Implantar seu primeiro aplicativo para Azure Spring Apps.

Próximas etapas

Azure para desenvolvedores do Spring Spring Cloud Microsoft Entra ID Samples

Comentários

Esta página foi útil?

Last updated on 2026-03-12