Proteggere l'API REST con Spring Cloud Azure

2025-06-17

Questa esercitazione illustra come abilitare la protezione delle API REST con Microsoft Entra ID in un'applicazione Spring Boot.

Questo articolo usa un sistema di sondaggi come esempio. Il sistema di sondaggio fornisce le API REST seguenti:

GET /api/survey/question è per visualizzare il sondaggio.
POST /api/survey è per compilare il sondaggio.
GET /api/survey è per visualizzare il risultato del sondaggio.

In questo articolo si proteggono queste API applicando il controllo degli accessi in base al ruolo per applicare i requisiti seguenti:

GET /api/survey/question è disponibile per ogni richiesta.
POST /api/survey è disponibile per le richieste utente autenticate contenenti un token di accesso con l'ambito SCOPE_Survey.User concesso.
GET /api/survey è disponibile per le richieste utente amministratore autenticate contenenti un token di accesso con l'ambito SCOPE_Survey.Admin concesso.

Prerequisiti

Una sottoscrizione di Azure: crearne una gratuitamente.
Java Development Kit (JDK) versione 8 o successiva.
Apache Maven
Interfaccia della riga di comando di Azure
Istanza di Microsoft Entra. Per istruzioni sulla creazione di un tenant, vedere Avvio rapido: Creare un nuovo tenant in Microsoft Entra ID.
Applicazione Spring Boot. Se non ne hai uno, crea un progetto Maven con Spring Initializr. Assicurarsi di selezionare Progetto Maven e, in Dipendenze, aggiungere le dipendenze Spring Web, OAuth2 Resource Server e Microsoft Entra ID e quindi selezionare Java versione 8 o successiva.

Importante

Per completare i passaggi descritti in questo articolo, sono necessari Spring Boot di versione 2.5 o successiva.

Registrare l'API REST

Usare la procedura seguente per registrare l'API Web nel portale di Azure.

Accedere al portale di Azure.
Se si ha accesso a più tenant, usare il filtro Directory + sottoscrizione ( ) per selezionare il tenant in cui si vuole registrare un'applicazione.
Trovare e selezionare Microsoft Entra ID.
In Gestisci selezionare Registrazioni app>Nuova registrazione.
Immettere un nome per l'applicazione nel campo Nome , ad esempio Api-SurveyService. Gli utenti dell'app potrebbero visualizzare questo nome ed è possibile modificarlo in un secondo momento.
Per Tipi di account supportati, selezionare gli account in qualsiasi directory organizzativa.
Selezionare Registra per creare l'applicazione.
Nella pagina Panoramica dell'app cercare il valore ID applicazione (client) e quindi registrarlo per usarlo in un secondo momento. È necessario configurare il file di configurazione YAML per questo progetto.
In Gestisci selezionare Esporre un'API>Aggiungi un ambito. Accettare l'URI ID applicazione proposto (api://{clientId}) selezionando Salva e continua, quindi immettere le informazioni seguenti:
- In Nome ambito immettere Survey.User.
- Per Chi può fornire il consenso, selezionare Amministratori e utenti.
- Per Nome visualizzato del consenso amministratore, inserisci Access the survey service as a user..
- Per Descrizione del consenso amministratore, immettere Allows the users to write data in survey system..
- In Nome visualizzato consenso utente immettere Access the survey service as a user..
- Per Descrizione del consenso utente immettere Allows the users to write data in survey system..
- Per Stato, lasciare Abilitato.
- Selezionare Aggiungi ambito.
Ripetere il passaggio precedente per aggiungere un altro ambito. Quando si seleziona Aggiungi un ambito, immettere le informazioni seguenti:
- In Nome ambito immettere Survey.Admin.
- Per Chi può fornire il consenso, selezionare Amministratori e utenti.
- Per Nome visualizzato del consenso amministratore, inserisci Access the survey service as a admin..
- Per Descrizione del consenso amministratore, immettere Allows the users to view data in survey system..
- In Nome visualizzato consenso utente immettere Access the survey service as a admin..
- Per Descrizione del consenso utente immettere Allows the users to view data in survey system..
- Per Stato, lasciare Abilitato.
- Selezionare Aggiungi ambito.

Abilitare l'ID Microsoft Entra di Spring Cloud Azure Starter

Abilitare quindi la protezione dell'API REST con Spring Cloud Azure.

Aggiungere dipendenze di sicurezza

Per installare il modulo Spring Cloud Azure Starter Azure Active Directory, aggiungere le seguenti dipendenze al file pom.xml :

Lista dei Materiali (BOM) di Spring Cloud Azure.
```
<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>
```
Annotazioni

Se si usa Spring Boot 2.x, assicurarsi di impostare la spring-cloud-azure-dependencies versione su 4.20.0. Questa distinta base deve essere configurata nella <dependencyManagement> sezione del file dipom.xml . In questo modo tutte le dipendenze di Spring Cloud Azure usano la stessa versione. Per ulteriori informazioni sulla versione utilizzata per questa distinta base, consultare Quale versione di Spring Cloud Azure dovrei usare.

Artefatto di Spring Cloud Azure Starter Microsoft Entra:

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

Componente di Spring Boot Starter OAuth2 Resource Server

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

Autorizzare le richieste HTTP

Per proteggere le API REST del sondaggio, aggiungere l'annotazione @PreAuthorize("hasAuthority('SCOPE_Survey.xxx')") con un nome di ambito concreto per abilitare la protezione, come illustrato nell'esempio seguente:

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

Aggiornare la configurazione YAML come illustrato nell'esempio seguente:

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>

Annotazioni

Nei token v1.0, la configurazione richiede l'ID client dell'API, mentre nei token v2.0 è possibile usare l'ID client o l'URI ID applicazione nella richiesta. È possibile configurare entrambi per completare correttamente la convalida del gruppo di destinatari.

Distribuzione su Azure Spring Apps

Dopo aver eseguito l'applicazione Spring Boot in locale, è possibile spostarla nell'ambiente di produzione. Azure Spring Apps semplifica la distribuzione di applicazioni Spring Boot in Azure senza modifiche al codice. Il servizio gestisce l'infrastruttura delle applicazioni Spring in modo che gli sviluppatori possano concentrarsi sul codice. Azure Spring Apps fornisce la gestione del ciclo di vita tramite funzionalità complete di monitoraggio e diagnostica, gestione della configurazione, individuazione dei servizi, integrazione di CI/CD, distribuzioni blu/verde e altro ancora. Per altre informazioni, vedere Avvio rapido: Distribuire la prima applicazione in Azure Spring Apps.

Passaggi successivi

Azure per gli sviluppatori Spring Esempi di Microsoft Entra ID per Spring Cloud