Proteja sua API REST usando o Spring Cloud Azure

2025-04-24

Este tutorial mostra como habilitar a proteção de APIs REST com a ID do Microsoft Entra 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 do Azure – crie uma gratuitamente.
Java Development Kit (JDK) versão 8 ou superior.
Apache Maven
Azure CLI
Uma instância do Microsoft Entra. Para obter instruções sobre como criar um, consulte Início Rápido: Criar um novo locatário no Microsoft Entra ID.
Um aplicativo Spring Boot. Caso não tiver um, crie um projeto Maven com o Spring Initializr. Selecione o Projeto Maven e, em Dependências, 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 do 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 a ID do Microsoft Entra.
Em Gerenciar, selecione Registros de aplicativo>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 Azure Active Directory do Azure Starter do Spring Cloud, adicione as seguintes dependências ao arquivo pom.xml :

A lista de materiais (BOM) do Azure Spring Cloud:
```
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.azure.spring</groupId>
      <artifactId>spring-cloud-azure-dependencies</artifactId>
      <version>5.22.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
```
Observação

Se você estiver usando o Spring Boot 2.x, certifique-se de definir a spring-cloud-azure-dependencies versão como 4.20.0. Essa Nota de Material (BOM) deve ser configurada na seção <dependencyManagement> do arquivo pom.xml. Isso garante que todas as dependências do Spring Cloud Azure estejam usando a mesma versão. Para obter mais informações sobre a versão usada para este BOM, consulte qual versão do Spring Cloud Azure devo usar.

O artefato do Microsoft Entra do Spring Cloud Azure Starter:

<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 aplicações no 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 no 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. O Azure Spring Apps fornece gerenciamento de ciclo de vida usando monitoramento e diagnóstico abrangentes, gerenciamento de configuração, descoberta de serviços, integração de CI/CD, implantações em “blue-green” e muito mais. Para obter mais informações, confira Início Rápido: implantar o seu primeiro aplicativo ao Azure Spring Apps.

Próximas etapas

Azure para desenvolvedores de Spring Exemplos do Microsoft Entra ID no Spring Cloud

Compartilhar via