Proteggere le app Tomcat Java usando ruoli e attestazioni di ruolo

Questo articolo illustra un'app Java Tomcat che usa OpenID Connect per consentire agli utenti di accedere e i ruoli dell'applicazione di Microsoft Entra ID (app roles) per l'autorizzazione.

Questa applicazione implementa il controllo degli accessi basato sui ruoli (RBAC) utilizzando la funzionalità dei ruoli dell'applicazione e dei claim di ruolo di Microsoft Entra ID. 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.

È anche possibile usare RBAC con ruoli dell'applicazione e claim di ruolo per applicare in modo sicuro i criteri di autorizzazione.

Per un video che illustra questo scenario e questo esempio, vedi Implementare l'autorizzazione nelle applicazioni usando ruoli dell'app, gruppi di sicurezza, ambiti e ruoli di directory.

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

Questa applicazione usa MSAL per Java (MSAL4J) per consentire a un utente di accedere e ottenere un token ID da Microsoft Entra ID.

Questo esempio usa innanzitutto MSAL per Java (MSAL4J) per accedere all'utente. Nella home page viene visualizzata un'opzione che consente all'utente di visualizzare le attestazioni nei token ID. Questa applicazione consente inoltre agli utenti di visualizzare una pagina di amministrazione con privilegi o una normale pagina utente, a seconda del ruolo dell'app a cui sono stati assegnati. L'idea consiste nel fornire un esempio di come, all'interno di un'applicazione, l'accesso a determinate funzionalità o pagine sia limitato a subset di utenti a seconda del ruolo a cui appartengono.

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 due seguenti ruoli 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

• JDK versione 8 o successive
• Maven 3
• Tenant di Microsoft Entra ID. Per altre informazioni, vedere Come ottenere un tenant di Microsoft Entra ID.
• Un account utente nel proprio tenant Microsoft Entra ID se si desidera lavorare solo con gli account nella directory dell'organizzazione, ovvero in modalità single-tenant. Se non hai ancora creato un account utente nel tuo tenant, dovresti farlo prima di continuare. Per altre informazioni, vedi Come creare, invitare ed eliminare utenti.

• Tomcat 9
• Visual Studio Code
• Strumenti di Azure per Visual Studio Code

Consigli

• Una certa familiarità con Java / Jakarta Servlets.
• 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 3-java-servlet-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-servlet-webapp-roles)

Per prima cosa, registrare una nuova app nel portale di Azure, seguendo le istruzioni in Guida introduttiva: Registrare un'applicazione con la piattaforma di Microsoft Identity.

Usare quindi la procedura seguente per completare la registrazione:

1. Passare alla pagina Registrazioni app della piattaforma di identità Microsoft per sviluppatori.

2. Seleziona Nuova registrazione.

3. Nella pagina Registra un'applicazione che viene visualizzata, immetti le seguenti informazioni di registrazione dell'app:

   • Nella sezione Name, immettere un nome significativo per l'applicazione da mostrare agli utenti dell'app - per esempio, .

   • In Tipi di account supportati selezionare una delle opzioni seguenti:

     • Selezionare Account solo in questa directory dell'organizzazione se si sta creando un'applicazione destinata all'uso esclusivo degli utenti del tenant, ovvero un'applicazione a tenant singolo.

   • Nella sezione Redirect URI, seleziona Web nella combo-box e inserisci 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. Seleziona Salva per salvare le modifiche.

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

8. Nella sezione Segreti client seleziona Nuovo segreto client.

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

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

11. Selezionare Aggiungi. Viene visualizzato il valore generato.

12. 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'applicazione

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'applicazione

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-servlet-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 authentication.properties.

3. Trova la stringa . Sostituire il valore esistente con l'ID tenant di Microsoft Entra ID.

4. Individuare la stringa e sostituire il valore esistente con l'ID applicazione o dell'applicazione copiata dal portale di Azure.

5. Trova la stringa e sostituisci il valore esistente con il valore salvato durante la creazione dell'app nel portale di Azure.

6. Individua la proprietà e assicurati che il valore sia impostato su , oppure sostituisci i nomi con quelli dei ruoli specifici.

Compilare l'esempio

Per compilare l'esempio usando Maven, passare alla directory contenente il file pom.xml per l'esempio e quindi eseguire il comando seguente:

mvn clean package

Questo comando genera un file .war che puoi eseguire su vari server applicativi.

Esegui l'esempio

Please confirm webapp properties
AppName : msal4j-servlet-auth-1707209552268
ResourceGroup : msal4j-servlet-auth-1707209552268-rg
Region : centralus
PricingTier : P1v2
OS : Linux
Java Version: Java 11
Web server stack: Tomcat 9.0
Deploy to slot : false
Confirm (Y/N) [Y]: [INFO] Saving configuration to pom.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  37.112 s
[INFO] Finished at: 2024-02-06T08:53:02Z
[INFO] ------------------------------------------------------------------------

<build>
    <plugins>
        <plugin>
            <groupId>com.microsoft.azure</groupId>
            <artifactId>>azure-webapp-maven-plugin</artifactId>
            <version>x.xx.x</version>
            <configuration>
                <schemaVersion>v2</schemaVersion>
                <resourceGroup>your-resourcegroup-name</resourceGroup>
                <appName>your-app-name</appName>
            ...
            </configuration>
        </plugin>
    </plugins>
</build>

az login

mvn package azure-webapp:deploy

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.
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. Si noti che il pulsante sensibile al contesto ora indica Disconnetti e visualizza il nome utente.
6. Selezionare Dettagli token ID per vedere alcune delle dichiarazioni decodificate del token ID.
7. Seleziona Admins Only per visualizzare la pagina . Solo gli utenti con il ruolo app possono visualizzare questa pagina. In caso contrario, viene visualizzato un messaggio di errore di autorizzazione.
8. 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.
9. Usare il pulsante nell'angolo per disconnettersi.

Informazioni sul codice

Questo esempio usa MSAL per Java (MSAL4J) per eseguire l'accesso di un utente e ottenere un token di ID che potrebbe contenere il claim dei ruoli. In base all'attestazione dei ruoli presente, l'utente connesso può accedere a nessuna, una o entrambe le pagine protette, e .

Per replicare il comportamento di questo esempio, è possibile copiare il file pom.xml e il contenuto delle cartelle helper e authservlets nella cartella src/main/java/com/microsoft/azuresamples/msal4j . È inoltre necessario il authentication.properties file. Queste classi e file contengono codice generico che è possibile usare in un'ampia gamma di applicazioni. È anche possibile copiare il resto dell'esempio, ma le altre classi e file vengono compilati in modo specifico per soddisfare l'obiettivo di questo esempio.

Contenuto

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

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": [
    "Role1",
    "Role2",]
  ...
}

ConfidentialClientApplication

Un'istanza di viene creata nel file AuthHelper.java, come mostrato nell'esempio seguente. Questo oggetto consente di creare l'URL di autorizzazione di Microsoft Entra e consente anche di scambiare il token di autenticazione per un token di accesso.

// getConfidentialClientInstance method
IClientSecret secret = ClientCredentialFactory.createFromSecret(SECRET);
confClientInstance = ConfidentialClientApplication
                     .builder(CLIENT_ID, secret)
                     .authority(AUTHORITY)
                     .build();

Per l'istanziazione vengono utilizzati i seguenti parametri:

• ID client dell'app.
• Il segreto del client, necessario per le applicazioni client confidenziali.
• L'autorità Microsoft Entra ID, che include l'ID del tenant Microsoft Entra.

In questo esempio questi valori vengono letti dal file authentication.properties usando un lettore di proprietà nel file Config.java .

Procedura dettagliata

I passaggi seguenti forniscono una procedura dettagliata delle funzionalità dell'app:

1. Il primo passaggio del processo di accesso consiste nell'inviare una richiesta all'endpoint per il tenant Microsoft Entra ID. L'istanza di MSAL4J viene utilizzata per costruire un URL della richiesta di autorizzazione. L'app reindirizza il browser a questo URL, dove l'utente accede.

   final ConfidentialClientApplication client = getConfidentialClientInstance();
   AuthorizationRequestUrlParameters parameters = AuthorizationRequestUrlParameters.builder(Config.REDIRECT_URI, Collections.singleton(Config.SCOPES))
           .responseMode(ResponseMode.QUERY).prompt(Prompt.SELECT_ACCOUNT).state(state).nonce(nonce).build();
   
   final String authorizeUrl = client.getAuthorizationRequestUrl(parameters).toString();
   contextAdapter.redirectUser(authorizeUrl);
   

   L'elenco seguente descrive le funzionalità di questo codice:

   • : parametri che devono essere impostati per costruire un AuthorizationRequestUrl.
   • : dove Microsoft Entra ID reindirizza il browser, insieme al codice di autorizzazione, dopo aver raccolto le credenziali dell'utente. Deve corrispondere all'URI di reindirizzamento nella registrazione dell'app Microsoft Entra ID nel portale di Azure.
   • : Scopes sono le autorizzazioni richieste dall'applicazione.
     • Normalmente, i tre scope sono sufficienti per ricevere una risposta con un token ID.
     • L'elenco completo degli ambiti richiesti dall'app è disponibile nel file authentication.properties . È possibile aggiungere altri scope, ad esempio .

2. L'utente riceve una richiesta di accesso da Microsoft Entra ID. Se il tentativo di accesso ha esito positivo, il browser dell'utente viene reindirizzato all'endpoint di reindirizzamento dell'app. Una richiesta valida per questo endpoint contiene un codice di autorizzazione.

3. L'istanza scambia quindi questo codice di autorizzazione con un token ID e un token di accesso ottenuti da Microsoft Entra ID.

   // First, validate the state, then parse any error codes in response, then extract the authCode. Then:
   // build the auth code params:
   final AuthorizationCodeParameters authParams = AuthorizationCodeParameters
           .builder(authCode, new URI(Config.REDIRECT_URI)).scopes(Collections.singleton(Config.SCOPES)).build();
   
   // Get a client instance and leverage it to acquire the token:
   final ConfidentialClientApplication client = AuthHelper.getConfidentialClientInstance();
   final IAuthenticationResult result = client.acquireToken(authParams).get();
   

   L'elenco seguente descrive le funzionalità di questo codice:

   • : Parametri che devono essere impostati per scambiare il codice di autorizzazione con un token ID e/o un token di accesso.
   • : Il codice di autorizzazione ricevuto all'endpoint di reindirizzamento.
   • : l'URI di reindirizzamento utilizzato nel passaggio precedente deve essere passato di nuovo.
   • : gli scope utilizzati nel passaggio precedente devono essere passati nuovamente.

4. Se ha esito positivo, vengono estratti i claims del token. Se il controllo del nonce ha esito positivo, i risultati vengono collocati in - un'istanza di - e salvati nella sessione. L'applicazione può quindi istanziare il dalla sessione tramite un'istanza di ogni volta che deve accedervi, come mostrato nel codice seguente:

   // parse IdToken claims from the IAuthenticationResult:
   // (the next step - validateNonce - requires parsed claims)
   context.setIdTokenClaims(result.idToken());
   
   // if nonce is invalid, stop immediately! this could be a token replay!
   // if validation fails, throws exception and cancels auth:
   validateNonce(context);
   
   // set user to authenticated:
   context.setAuthResult(result, client.tokenCache().serialize());
   

Proteggere le route

Per informazioni su come l'app di esempio filtra l'accesso alle route, vedere AuthenticationFilter.java. Nel file authentication.properties, la proprietà contiene le route separate da virgole a cui possono accedere solo gli utenti autenticati, come mostrato nell'esempio seguente:

# for example, /token_details requires any user to be signed in and does not require special roles claim(s)
app.protect.authenticated=/token_details

Anche tutti i percorsi elencati nei set di regole separati da virgole sotto non sono accessibili agli utenti non autenticati, come mostrato nell'esempio seguente. Tuttavia, questi percorsi contengono anche un elenco di assegnazioni ai ruoli dell'app separato da spazi: solo gli utenti che dispongono di almeno uno dei ruoli corrispondenti possono accedere a questi percorsi dopo aver effettuato l'autenticazione.

# local short names for app roles - for example, sets admin to mean PrivilegedAdmin (useful for long rule sets defined in the next key, app.protect.roles)
app.roles=admin PrivilegedAdmin, user RegularUser

# A route and its corresponding <space-separated> role(s) that can access it; the start of the next route & its role(s) is delimited by a <comma-and-space-separator>
# this says: /admins_only can be accessed by PrivilegedAdmin, /regular_user can be accessed by PrivilegedAdmin role and the RegularUser role
app.protect.roles=/admin_only admin, /regular_user admin user

Ambiti

Scopes indicano a Microsoft Entra ID il livello di accesso che l'applicazione richiede.

In base agli ambiti richiesti, Microsoft Entra ID presenta una finestra di dialogo di consenso all'utente al momento dell'accesso. Se l'utente acconsente a uno o più scope e ottiene un token, gli scope a cui ha acconsentito vengono codificati nel risultante.

Per gli ambiti richiesti dall'applicazione, vedere authentication.properties. Questi tre ambiti vengono richiesti da MSAL e forniti da Microsoft Entra ID per impostazione predefinita.

Ulteriori informazioni

• Libreria di Autenticazione Microsoft (MSAL) per Java
• piattaforma di identità Microsoft
• Guida introduttiva: registrare un'applicazione con la piattaforma di identità Microsoft
• Comprendere le esperienze di consenso delle applicazioni in Microsoft Entra ID
• Comprendere il consenso dell'utente e dell'amministratore
• Esempi di codice MSAL
• Come: aggiungere ruoli dell'app all'applicazione e riceverli nel token
• Gestire l'assegnazione utente per un'app in Microsoft Entra ID