Proteggere le app Java Spring Boot usando ruoli e attestazioni di ruolo

Questo articolo illustra un'app web Java Spring Boot che utilizza la libreria client Microsoft Entra ID Spring Boot Starter per Java per l'autenticazione, l'autorizzazione e l'acquisizione di token. L'app usa il protocollo OpenID Connect per consentire agli utenti di accedere e limita l'accesso ad alcune route utilizzando i ruoli dell'applicazione di Microsoft Entra ID (ruoli dell'app) per l'autorizzazione.

I ruoli dell'app, insieme ai gruppi di sicurezza, sono strumenti comuni per implementare l'autorizzazione. Usando il controllo degli accessi in base al ruolo (RBAC) con ruoli applicazione e attestazioni di ruolo, è possibile applicare in modo sicuro i criteri di autorizzazione con un impegno minimo. Un altro approccio consiste nell'usare i gruppi e le attestazioni di gruppo di Microsoft Entra ID. I gruppi e i ruoli dell'applicazione di Microsoft Entra ID non si escludono reciprocamente. È possibile usarli entrambi per fornire un controllo di accesso con granularità fine.

Per un video che tratta un caso simile, vedi Implementare l'autorizzazione nelle applicazioni usando i ruoli dell'applicazione, i gruppi di sicurezza, gli ambiti e i ruoli di directory.

Per altre informazioni su come funzionano i protocolli in questo e in altri scenari, vedere Autenticazione e autorizzazione.

Il diagramma seguente illustra la topologia dell'app:

Diagramma che mostra la topologia dell'app.

L'app usa la libreria client Spring Boot Starter di Microsoft Entra ID per Java per consentire l'accesso a un utente e ottenere un token ID da Microsoft Entra ID. Il token ID contiene l'attestazione dei ruoli. L'applicazione esamina il valore di questa attestazione per determinare le pagine a cui l'utente è autorizzato ad accedere.

Questo tipo di autorizzazione viene implementato mediante RBAC. Con RBAC, un amministratore assegna le autorizzazioni ai ruoli, non ai singoli utenti o gruppi. L'amministratore può quindi assegnare ruoli a utenti e gruppi diversi per controllare chi può accedere a determinati contenuti e funzionalità.

Questa applicazione di esempio definisce i seguenti due ruoli dell'applicazione:

• : autorizzato ad accedere alle pagine Solo amministratori e Utenti normali.
• : Autorizzato ad accedere alla pagina Utenti normali.

Questi ruoli dell'applicazione sono definiti nel Azure portal nel manifesto di registrazione dell'applicazione. Quando un utente accede all'applicazione, Microsoft Entra ID genera un'attestazione di ruoli per ogni ruolo concesso singolarmente all'utente sotto forma di appartenenza al ruolo.

È possibile assegnare utenti e gruppi ai ruoli tramite il portale di Azure.

Prerequisiti

• versione 15 di JDK. Questo esempio è stato sviluppato in un sistema con Java 15, ma potrebbe essere compatibile con altre versioni.
• Maven 3
• Java Extension Pack for Visual Studio Code è consigliato per eseguire questo esempio in Visual Studio Code.
• Tenant di Microsoft Entra ID. Per altre informazioni, vedere Come ottenere un tenant di Microsoft Entra ID.
• Un account utente nel tenant di Microsoft Entra ID. Questo esempio non funziona con un account Microsoft personale. Pertanto, se si è effettuato l'accesso al portale di Azure con un account personale e non si dispone di un account utente nella directory, è necessario crearne uno ora.
• Visual Studio Code
• Strumenti di Azure per Visual Studio Code

Consigli

• Una certa familiarità con il Spring Framework.
• Una certa familiarità con il terminale Linux/OSX.
• jwt.ms per esaminare i tuoi token.
• Fiddler per monitorare l'attività di rete e risolvere i problemi.
• Segui il blog di Microsoft Entra per rimanere up-to-date con gli ultimi sviluppi.

Configurare l'esempio

Le sezioni seguenti illustrano come configurare l'applicazione di esempio.

Clonare o scaricare il repository di esempio

Per clonare l'esempio, aprire una finestra Bash e usare il comando seguente:

git clone https://github.com/Azure-Samples/ms-identity-msal-java-samples.git
cd 4-spring-web-app/3-Authorization-II/roles

In alternativa, passa al repository ms-identity-msal-java-samples, quindi scaricalo come file .zip ed estrailo sul disco rigido.

Registrare l'applicazione di esempio nel tenant di Microsoft Entra ID

In questo esempio è presente un progetto. Le sezioni seguenti illustrano come registrare l'app usando il portale di Azure.

Scegliere il tenant microsoft Entra ID in cui si desidera creare le applicazioni

Per scegliere il tenant, seguire questa procedura:

1. Accedi al portale di Azure.

2. Se l'account è presente in più tenant di Microsoft Entra ID, selezionare il profilo nell'angolo del portale di Azure e quindi selezionare Cambia directory per modificare la sessione nel tenant di Microsoft Entra ID desiderato.

Registrare l'app (java-spring-webapp-roles)

Per registrare l'app, seguire questa procedura:

1. Passare al portale di Azure e selezionare Microsoft Entra ID.

2. Selezionare Registrazioni app nel riquadro di spostamento e quindi selezionare Nuova registrazione.

3. Nella pagina Registra un'applicazione visualizzata immettere le informazioni di registrazione dell'applicazione seguenti:

   • Nella sezione Nome, immetti un nome significativo per l'applicazione da mostrare agli utenti dell'app, ad esempio .
   • In Tipi di account supportati, seleziona Account solo in questa directory dell'organizzazione.
   • Nella sezione URI di reindirizzamento (facoltativo), seleziona Web nella casella combinata e immetti il seguente URI di reindirizzamento: .

4. Selezionare Registra per creare l'applicazione.

5. Nella pagina di registrazione dell'app, trova e copia il valore ID applicazione (client) da utilizzare in seguito. Questo valore viene usato nel file o nei file di configurazione dell'app.

6. Nella pagina di registrazione dell'app selezionare Certificati e segreti nel riquadro di spostamento per aprire la pagina in cui è possibile generare segreti e caricare i certificati.

7. Nella sezione Segreti client seleziona Nuovo segreto client.

8. Digitare una descrizione, ad esempio il segreto dell'app.

9. Selezionare una scadenza per il segreto o specificare una durata personalizzata. I segreti client sono limitati a una durata massima di 24 mesi e Microsoft consiglia una scadenza inferiore a 12 mesi. Per le app di produzione, preferire un certificato o credenziali di identità federate rispetto a un segreto client.

10. Selezionare Aggiungi. Viene visualizzato il valore generato.

11. Copiare e salvare il valore generato da usare nei passaggi successivi. Questo valore è necessario per i file di configurazione del codice. Questo valore non viene visualizzato di nuovo e non è possibile recuperarlo con altri mezzi. Assicurarsi quindi di salvarlo dal portale di Azure prima di passare a qualsiasi altra schermata o riquadro.

Definire i ruoli dell'app

Per definire i ruoli dell'app, seguire questa procedura:

1. Sempre nella stessa registrazione app, seleziona Ruoli app nel riquadro di navigazione.

2. Seleziona Crea ruolo app, quindi immetti i valori seguenti:

   • Per Nome visualizzato, immetti un nome appropriato, ad esempio PrivilegedAdmin.
   • Per Tipi di membri consentiti, scegliere Utente.
   • Per Valore, immettere PrivilegedAdmin.
   • Per Descrizione, immettere PrivilegedAdmins che possono visualizzare la Pagina di amministrazione.

3. Seleziona Crea ruolo app, quindi immetti i valori seguenti:

   • Per Nome visualizzato, immetti un nome appropriato, ad esempio RegularUser.
   • Per Tipi di membri consentiti, scegliere Utente.
   • Per Valore, immettere RegularUser.
   • Per Descrizione, immettere RegularUsers che possono visualizzare la pagina utente.

4. Selezionare Applica per salvare le modifiche.

Assegnare utenti ai ruoli dell'app

Per aggiungere utenti al ruolo dell'app definito in precedenza, seguire le linee guida qui: Assegnare utenti e gruppi ai ruoli.

Configura l'app (java-spring-webapp-roles) per utilizzare la registrazione dell'app

Usare la procedura seguente per configurare l'app:

1. Aprire il progetto nell'IDE.

2. Aprire il file src\main\resources\application.yml.

3. Trova il segnaposto e sostituisci il valore esistente con l'ID del tenant di Microsoft Entra.

4. Trovare il segnaposto e sostituire il valore esistente con l'ID dell'applicazione o dell'app copiato dal portale di Azure.

5. Individua il segnaposto e sostituisci il valore esistente con il valore che hai salvato durante la creazione di , copiato dal portale di Azure.

6. Aprire il file src/main/java/com/microsoft/azuresamples/msal4j/msidentityspringbootapplication/Sample.Controller.java.

7. Trova in questo file i riferimenti ai ruoli dell'app e . Se necessario, modificarli in modo da riflettere i nomi dei ruoli dell'app scelti nei passaggi precedenti.

Esegui l'esempio

az login

az upgrade

az extension add --name containerapp --upgrade

az extension add --name containerapp --upgrade --allow-preview true

az provider register --namespace Microsoft.App
az provider register --namespace Microsoft.OperationalInsights

export RESOURCE_GROUP="ms-identity-containerapps"
export LOCATION="canadacentral"
export ENVIRONMENT="env-ms-identity-containerapps"
export API_NAME="ms-identity-api"
export JAR_FILE_PATH_AND_NAME="./target/ms-identity-spring-boot-webapp-0.0.1-SNAPSHOT.jar"

az group create  \
    --name $RESOURCE_GROUP \
    --location $LOCATION \

az containerapp env create \
    --name $ENVIRONMENT \
    --resource-group $RESOURCE_GROUP \
    --location $LOCATION

az containerapp env show \
    --name $ENVIRONMENT \
    --resource-group $RESOURCE_GROUP \
    --query properties.defaultDomain

az containerapp up \
    --name $API_NAME \
    --resource-group $RESOURCE_GROUP \
    --location $LOCATION \
    --environment $ENVIRONMENT \
    --artifact <JAR_FILE_PATH_AND_NAME> \
    --ingress external \
    --target-port 8080 \
    --query properties.configuration.ingress.fqdn

Esaminare l'esempio

Per esplorare l'esempio, seguire questa procedura:

1. Notare lo stato di accesso o di disconnessione visualizzato al centro dello schermo.
2. Selezionare il pulsante sensibile al contesto nell'angolo. Questo pulsante mostra Accedi quando avvii l'app per la prima volta. In alternativa, seleziona dettagli del token, solo amministratori o utenti normali. Poiché queste pagine sono protette e richiedono l'autenticazione, si viene reindirizzati automaticamente alla pagina di accesso.
3. Nella pagina successiva seguire le istruzioni e accedere con un account di Microsoft Entra ID tenant.
4. Nella schermata di consenso notare gli ambiti richiesti.
5. Al termine del flusso di accesso, si dovrebbe essere reindirizzati alla home page, che mostra lo stato di accesso o una delle altre pagine, a seconda del pulsante che ha attivato il flusso di accesso.
6. Si noti che il pulsante sensibile al contesto ora indica Disconnetti e visualizza il nome utente.
7. Se si è nella home page, selezionare ID Token Details per visualizzare alcuni dei claim decodificati del token ID, inclusi i ruoli.
8. Seleziona Admins Only per visualizzare . Solo gli utenti con il ruolo app possono visualizzare questa pagina. In caso contrario, viene visualizzato un messaggio di errore di autorizzazione.
9. Seleziona Regular Users per visualizzare la pagina . Solo gli utenti con il ruolo dell'app o possono visualizzare questa pagina. In caso contrario, viene visualizzato un messaggio di errore di autorizzazione.
10. Usare il pulsante nell'angolo per disconnettersi. La pagina di stato riflette il nuovo stato.

Informazioni sul codice

Questo esempio mostra come usare la libreria client Microsoft Entra ID Spring Boot Starter per Java per consentire agli utenti di accedere al tenant di Microsoft Entra ID. L'esempio usa anche gli starter Spring Oauth2 Client e Spring Web Boot. L'esempio usa le attestazioni del token ID ottenuto da Microsoft Entra ID per visualizzare i dettagli dell'utente connesso e per limitare l'accesso ad alcune pagine usando l'attestazione dei ruoli per l'autorizzazione.

Contenuto

La tabella seguente illustra il contenuto della cartella del progetto di esempio:

Attestazioni del token ID

Per estrarre i dettagli del token, l'app utilizza l'oggetto e di Spring Security in una mappatura di richiesta, come mostrato nell'esempio seguente. Per tutti i dettagli su come questa app utilizza le attestazioni del token ID, vedi Sample Controller.

import org.springframework.security.oauth2.core.oidc.user.OidcUser;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
//...
@GetMapping(path = "/some_path")
public String tokenDetails(@AuthenticationPrincipal OidcUser principal) {
    Map<String, Object> claims = principal.getIdToken().getClaims();
}

Elaborare un'attestazione di ruoli nel token ID

L'attestazione dei ruoli del token include i nomi dei ruoli a cui è assegnato l'utente connesso, come illustrato nell'esempio seguente:

{
  ...
  "roles": [
    "PrivilegedAdmin",
    "RegularUser",]
  ...
}

Un modo comune per accedere ai nomi dei ruoli è descritto nella sezione attestazioni del token ID.

Microsoft Entra ID Boot Starter v3.3 e versioni successive analizza automaticamente anche il claim dei ruoli e aggiunge ogni ruolo alle dell'utente connesso, anteponendo a ciascuno la stringa . Questa configurazione consente agli sviluppatori di utilizzare i ruoli dell'applicazione con le annotazioni condizionali di Spring tramite il metodo . Ad esempio, è possibile trovare le seguenti condizioni mostrate in SampleController.java:

@GetMapping(path = "/admin_only")
@PreAuthorize("hasAuthority('APPROLE_PrivilegedAdmin')")
public String adminOnly(Model model) {
    // restrict to users who have PrivilegedAdmin app role only
}
@GetMapping(path = "/regular_user")
@PreAuthorize("hasAnyAuthority('APPROLE_PrivilegedAdmin','APPROLE_RegularUser')")
public String regularUser(Model model) {
    // restrict to users who have any of RegularUser or PrivilegedAdmin app roles
}

Il codice seguente recupera un elenco completo di autorizzazioni per un dato utente:

@GetMapping(path = "/some_path")
public String tokenDetails(@AuthenticationPrincipal OidcUser principal) {
   Collection<? extends GrantedAuthority> authorities = principal.getAuthorities();
}

Collegamenti di accesso e disconnessione

Per l'accesso, l'app effettua una richiesta all'endpoint di accesso di Microsoft Entra ID configurato automaticamente dalla libreria client Spring Boot Starter per Microsoft Entra ID per Java, come illustrato nell'esempio seguente:

<a class="btn btn-success" href="/oauth2/authorization/azure">Sign In</a>

Per disconnettersi, l'app effettua una richiesta POST all'endpoint , come mostrato nell'esempio seguente:

<form action="#" th:action="@{/logout}" method="post">
  <input class="btn btn-warning" type="submit" value="Sign Out" />
</form>

Elementi dell'interfaccia utente dipendenti dall'autenticazione

L'app ha una logica semplice nelle pagine del modello di interfaccia utente per determinare il contenuto da visualizzare in base all'autenticazione dell'utente, come illustrato nell'esempio seguente usando i tag Spring Security Thymeleaf:

<div sec:authorize="isAuthenticated()">
  this content only shows to authenticated users
</div>
<div sec:authorize="isAnonymous()">
  this content only shows to not-authenticated users
</div>

Proteggi le route con AADWebSecurityConfigurerAdapter

Per impostazione predefinita, l'app protegge le pagine ID Token Details, Admins Only e Regular Users in modo che solo gli utenti connessi possano accedervi. L'app configura questi percorsi a partire dalla proprietà nel file application.yml. Per configurare i requisiti specifici della tua app, puoi estendere in una delle tue classi. Per un esempio, vedi la classe SecurityConfig di questa app, illustrata nel codice seguente:

@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class SecurityConfig extends AADWebSecurityConfigurerAdapter{
  @Value( "${app.protect.authenticated}" )
  private String[] protectedRoutes;

    @Override
    public void configure(HttpSecurity http) throws Exception {
    // use required configuration form AADWebSecurityAdapter.configure:
    super.configure(http);
    // add custom configuration:
    http.authorizeRequests()
      .antMatchers(protectedRoutes).authenticated()     // limit these pages to authenticated users (default: /token_details, /admin_only, /regular_user)
      .antMatchers("/**").permitAll();                  // allow all other routes.
    }
}

Ulteriori informazioni

• Documentazione di Microsoft Identity Platform
• Panoramica di Libreria di Autenticazione Microsoft (MSAL)
• Guida introduttiva: registrare un'applicazione con la piattaforma di identità Microsoft
• Guida introduttiva: configurare un'applicazione client per accedere alle API Web
• Comprendere le esperienze di consenso delle applicazioni in Microsoft Entra ID
• Comprendere il consenso dell'utente e dell'amministratore
• Oggetti applicazione e dell'entità servizio in Azure Active Directory
• Cloud nazionali
• Esempi di codice MSAL
• Libreria client Spring Boot Starter di Azure Active Directory per Java
• Microsoft Authentication Library per Java (MSAL4J)
• MSAL4J Wiki
• token ID
• Token di accesso nella piattaforma di identità Microsoft

Per altre informazioni su come funzionano i protocolli OAuth 2.0 in questo scenario e in altri scenari, vedere Scenari di autenticazione per Microsoft Entra ID.