Proteggere l'API REST con Spring Cloud Azure

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 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 Quickstart: 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 Maven Project e, in Dependencies, aggiungere il 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.

1. Accedere al portale Azure.

2. Se si ha accesso a più tenant, usare il filtro Directory + sottoscrizione ( ) per selezionare il tenant in cui si vuole registrare un'applicazione.

3. Trovare e selezionare Microsoft Entra ID.

4. In Gestisci selezionare App registrations>Nuova registrazione.

5. 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.

6. Per Tipi di account supportati selezionare Account in qualsiasi directory dell'organizzazione.

7. Selezionare Registra per creare l'applicazione.

8. 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.

9. In Gestisci selezionare Esporre un'API>Aggiungi un ambito. Accettare l'URI dell'ID applicazione proposto (api://{clientId}) selezionando Salva e continua, quindi immettere le informazioni seguenti:

   • Nel campo Nome ambito inserire 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 State, mantieni Abilitato.
   • Seleziona Aggiungi ambito.

10. Ripetere il passaggio precedente per aggiungere un altro ambito. Quando si seleziona Aggiungi un ambito, immettere le informazioni seguenti:

    • Nel campo Nome ambito inserire 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 State, mantieni Abilitato.
    • Seleziona Aggiungi ambito.

Abilitare il Microsoft Entra ID Spring Cloud Azure Starter

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

Aggiungere dipendenze di sicurezza

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

• L'elenco dei materiali di Spring Cloud Azure (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>
  

  Annotazioni

  Se si usa Spring Boot 4.0.x, assicurarsi di impostare la spring-cloud-azure-dependencies versione su 7.1.0.

  Se si usa Spring Boot 3.5.x, assicurarsi di impostare la spring-cloud-azure-dependencies versione su 6.2.0.

  Se si usa Spring Boot 3.1.x-3.5.x, assicurarsi di impostare la spring-cloud-azure-dependencies versione su 5.25.0.

  Se si usa Spring Boot 2.x, assicurarsi di impostare la spring-cloud-azure-dependencies versione su 4.20.0.

  Questo Bill of Material (BOM) deve essere configurato nella sezione <dependencyManagement> del file pom.xml. In questo modo, tutte le dipendenze di Spring Cloud Azure usano la stessa versione.

  Per ulteriori informazioni sulla versione utilizzata per questo BOM, vedere Quale versione di Spring Cloud Azure dovrei usare.

• L'artefatto Spring Cloud Azure Starter di 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.

Distribuire 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 offre la gestione del ciclo di vita usando monitoraggio e diagnostica completi, gestione della configurazione, individuazione dei servizi, integrazione CI/CD, distribuzioni blu-verde e altro ancora. Per altre informazioni, vedere Quickstart: Distribuire la prima applicazione in Azure Spring Apps.

Passaggi successivi

Azure per sviluppatori SpringSpring Cloud Microsoft Entra ID Samples