Abilitare le app Java Tomcat per l'accesso degli utenti e l'accesso a Microsoft Graph

Questo articolo mostra un'app Java Tomcat che consente agli utenti di accedere e ottiene un token di accesso per effettuare chiamate a Microsoft Graph. Utilizza la Libreria di Autenticazione Microsoft (MSAL) per Java.

Il diagramma seguente illustra la topologia dell'app:

Diagramma che mostra la topologia dell'app.

L'app client usa MSAL per Java (MSAL4J) per eseguire l'accesso di un utente e ottenere un access token per Microsoft Graph da Microsoft Entra ID. Il token di accesso dimostra che l'utente è autorizzato ad accedere all'endpoint dell'API Microsoft Graph come definito nell'ambito.

Prerequisiti

• Java 8 o versione successiva
• Maven 3
• Tenant di Microsoft Entra ID. Per altre informazioni, vedere Come ottenere un tenant di Microsoft Entra ID.
• Un account utente nel tenant Microsoft Entra ID del proprio ambiente, se si desidera lavorare solo con gli account nella directory organizzativa, ovvero in modalità a tenant singolo. 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.
• Un account utente nel tenant di Microsoft Entra ID di qualsiasi organizzazione se si vuole usare gli account in qualsiasi directory organizzativa, ovvero in modalità multi-tenant. Questo esempio deve essere modificato per lavorare con un account Microsoft personale. 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.
• Un account Microsoft personale, ad esempio Xbox, Hotmail, Live e così via, se vuoi lavorare con account Microsoft personali.

• 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/2-Authorization-I/call-graph

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-call-graph)

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 visualizzata immettere le informazioni di registrazione dell'applicazione seguenti:

   • Nella sezione Name, immetti un nome significativo per l'applicazione da visualizzare 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.
     • Selezionare Account in qualsiasi directory dell'organizzazione se si desidera che gli utenti di qualsiasi tenant di Microsoft Entra ID possano usare l'applicazione, ovvero un'applicazione multi-tenant.
     • Seleziona Account in qualsiasi directory organizzativa e account Microsoft personali per raggiungere la più ampia gamma di clienti, ovvero un'applicazione multi-tenant che supporta anche gli account Microsoft personali.

   • Selezionare Account Microsoft personali per l'uso solo da parte degli utenti di account Microsoft personali, ad esempio Hotmail, Live, Skype e Xbox.

   • Nella sezione Redirect URI, 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. 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.

13. Nella pagina di registrazione dell'app selezionare Autorizzazioni API nel riquadro di spostamento per aprire la pagina per aggiungere l'accesso alle API necessarie per l'applicazione.

14. Selezionare Aggiungi autorizzazioni.

15. Verificare che la scheda API Microsoft sia selezionata.

16. Nella sezione API Microsoft più usate selezionare Microsoft Graph.

17. Nella sezione Autorizzazioni delegate, selezionare User.Read dall'elenco. Se necessario, usare la casella di ricerca.

18. Selezionare Aggiungi autorizzazioni.

Configura l'app (java-servlet-webapp-call-graph) per utilizzare la registrazione dell'app

Usare la procedura seguente per configurare l'app:

1. Aprire il progetto nell'IDE.

2. Apri il file ./src/main/resources/authentication.properties.

3. Trova la stringa . Sostituire il valore esistente con uno dei valori seguenti:

   • L'ID del tenant di Microsoft Entra ID se hai registrato la tua app con l'opzione Account solo in questa directory organizzativa.
   • La parola se hai registrato l'app con l'opzione Account in qualsiasi directory organizzativa.
   • La parola se hai registrato l'app con l'opzione Account in qualsiasi directory organizzativa e account Microsoft personali.
   • La parola se hai registrato l'app con l'opzione account Microsoft personali.

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

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

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. Selezionare Call Graph per effettuare una chiamata all'endpoint /me di Microsoft Graph e visualizzare alcuni dettagli dell'utente ottenuti.
8. Usare il pulsante nell'angolo per disconnettersi.

Informazioni sul codice

Questo esempio usa MSAL per Java (MSAL4J) per accedere a un utente e ottenere un token per l'API Microsoft Graph. Usa Microsoft Graph SDK per Java per ottenere dati da Graph. È necessario aggiungere queste librerie ai progetti usando Maven.

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:

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 ID 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 da impostare per creare un .
   • : 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 configurato 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 . Puoi aggiungere altri ambiti, 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 or groups claim(s)
app.protect.authenticated=/token_details, /call_graph

Grafo delle chiamate

Quando l'utente accede a , l'applicazione crea un'istanza di di Java Graph SDK, passando il token di accesso dell'utente autenticato. Il client Graph inserisce il token di accesso nelle intestazioni delle proprie richieste. L'app chiede quindi al client Graph di chiamare l'endpoint per ottenere i dettagli dell'utente attualmente autenticato.

Se hai già un token di accesso valido per Graph Service con lo scope , è sufficiente il codice seguente per accedere all'endpoint :

//CallGraphServlet.java
User user = GraphHelper.getGraphClient(contextAdapter).me().buildRequest().get();

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. Per impostazione predefinita, l'applicazione imposta il valore di scopes su . Questo particolare ambito dell'API Microsoft Graph consiste nell'accedere alle informazioni dell'utente connesso corrente. L'endpoint di Graph per accedere a queste informazioni è . Tutte le richieste valide effettuate a questo endpoint devono includere un che contiene l'ambito nell'intestazione .

Ulteriori informazioni

• Libreria di Autenticazione Microsoft (MSAL) per Java
• Piattaforma di identità Microsoft (Microsoft Entra ID per gli sviluppatori)
• 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