Condividi tramite

Proteggere le app Tomcat Java usando gruppi e attestazioni di gruppo

  • Articolo

Questo articolo illustra come creare un'app Java Tomcat che consente di accedere agli utenti con Microsoft Authentication Library (MSAL) per Java. L'app limita anche l'accesso alle pagine in base all'appartenenza al gruppo di sicurezza Microsoft Entra ID.

Il diagramma seguente illustra la topologia dell'app:

Diagramma che mostra la topologia dell'app.

L'app client usa MSAL per Java (MSAL4J) per consentire agli utenti di accedere a un tenant di Microsoft Entra ID e ottenere un token ID da Microsoft Entra ID. Il token ID dimostra che un utente è autenticato con questo tenant. L'app protegge le route in base allo stato di autenticazione e all'appartenenza al gruppo dell'utente.

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

Prerequisiti

  • JDK versione 8 o 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.
  • Due gruppi di sicurezza e GroupAdmin GroupMember, contenenti gli utenti con cui si vuole eseguire il test.

Consigli

  • Familiarità con Java /Jakarta Servlets.
  • Una certa familiarità con il terminale Linux/OSX.
  • jwt.ms per controllare i token.
  • Fiddler per monitorare l'attività di rete e la risoluzione dei problemi.
  • Segui il blog di Microsoft Entra ID per rimanere aggiornato 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/groups

In alternativa, passare al repository ms-identity-msal-java-samples , quindi scaricarlo come file .zip ed estrarlo nel disco rigido.

Importante

Per evitare limitazioni di lunghezza del percorso di file in Windows, clonare o estrarre il repository in una directory vicino alla radice del disco rigido.

Registrare l'applicazione di esempio con il 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. Accedere 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-groups)

Prima di tutto, registrare una nuova app nel portale di Azure seguendo le istruzioni riportate in Avvio rapido: Registrare un'applicazione con Microsoft Identity Platform.

Usare quindi la procedura seguente per completare la registrazione:

  1. Passare alla pagina Registrazioni app di Microsoft Identity Platform per sviluppatori.

  2. Seleziona Nuova registrazione.

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

    • Nella sezione Nome immettere un nome di applicazione significativo da visualizzare agli utenti dell'app, java-servlet-webapp-groupsad esempio .
    • In Tipi di account supportati selezionare Account solo in questa directory organizzativa.
    • Nella sezione URI di reindirizzamento selezionare Web nella casella combinata e immettere l'URI di reindirizzamento seguente: http://localhost:8080/msal4j-servlet-groups/auth/redirect.

  4. Selezionare Registra per creare l'applicazione.

  5. Nella pagina di registrazione dell'app trovare e copiare il valore ID applicazione (client) da usare in un secondo momento. 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 delle durate disponibili: in 1 anno, in 2 anni o Mai scadute.

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

  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 e GroupMember.Read.All dall'elenco. Se necessario, usare la casella di ricerca.

  18. Selezionare Aggiungi autorizzazioni.

  19. GroupMember.Read.All richiede il consenso dell'amministratore, quindi selezionare Concedi/revoca il consenso amministratore per {tenant}, quindi selezionare Sì quando viene chiesto se si vuole concedere il consenso per le autorizzazioni richieste per tutti gli account nel tenant. Per eseguire questa azione, è necessario essere un amministratore tenant di Microsoft Entra ID.

Configurare l'app (java-servlet-webapp-groups) per usare la registrazione dell'app

Usare la procedura seguente per configurare l'app:

Nota

Nei passaggi seguenti è ClientID uguale Application ID a o AppId.

  1. Aprire il progetto nell'IDE.

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

  3. Trovare la stringa {enter-your-tenant-id-here}. Sostituire il valore esistente con l'ID tenant di Microsoft Entra se l'app è stata registrata con l'opzione Account solo in questa directory organizzativa.

  4. Trovare la stringa {enter-your-client-id-here} e sostituire il valore esistente con l'ID applicazione o clientId l'applicazione java-servlet-webapp-groups copiata dal portale di Azure.

  5. Trovare la stringa {enter-your-client-secret-here} e sostituire il valore esistente con il valore salvato durante la creazione dell'appjava-servlet-webapp-groups, nella portale di Azure.

Configurare i gruppi di sicurezza

Sono disponibili le opzioni seguenti su come configurare ulteriormente le applicazioni per ricevere l'attestazione dei gruppi:

Nota

Per ottenere il gruppo locale o On Premises Group Security Identifier anziché l'ID gruppo, vedere la sezione Prerequisiti per l'uso samAccountName degli attributi di gruppo sincronizzati da Active Directory in Configurare le attestazioni di gruppo per le applicazioni usando Microsoft Entra ID.

Configurare l'applicazione per ricevere tutti i gruppi a cui viene assegnato l'utente connesso, inclusi i gruppi annidati

Per configurare l'applicazione, seguire questa procedura:

  1. Nella pagina di registrazione dell'app selezionare Configurazione token nel riquadro di spostamento per aprire la pagina in cui è possibile configurare i token forniti dalle attestazioni rilasciate all'applicazione.

  2. Selezionare Aggiungi attestazione gruppi per aprire la schermata Modifica attestazione gruppi.

  3. Selezionare Gruppi di sicurezza OPPURE l'opzione Tutti i gruppi (incluse le liste di distribuzione ma non i gruppi assegnati all'applicazione). La scelta di entrambe le opzioni nega l'effetto dell'opzione Gruppi di sicurezza.

  4. Nella sezione ID selezionare ID gruppo. Questa selezione fa sì che Microsoft Entra ID invii l'ID oggetto dei gruppi a cui l'utente viene assegnato nell'attestazione di gruppi del token ID ricevuto dall'app dopo l'accesso di un utente.

Configurare l'applicazione per ricevere i valori delle attestazioni dei gruppi da un set filtrato di gruppi a cui potrebbe essere assegnato un utente

Questa opzione è utile quando si verificano i casi seguenti:

  • L'applicazione è interessata a un set selezionato di gruppi a cui potrebbe essere assegnato un utente di accesso.
  • L'applicazione non è interessata a ogni gruppo di sicurezza a cui l'utente viene assegnato nel tenant.

Questa opzione consente all'applicazione di evitare il problema di eccedenza .

Nota

Questa funzionalità non è disponibile nell'edizione Microsoft Entra ID Free.

Le assegnazioni di gruppi annidate non sono disponibili quando si usa questa opzione.

Per abilitare questa opzione nell'app, seguire questa procedura:

  1. Nella pagina di registrazione dell'app selezionare Configurazione token nel riquadro di spostamento per aprire la pagina in cui è possibile configurare i token forniti dalle attestazioni rilasciate all'applicazione.

  2. Selezionare Aggiungi attestazione gruppi per aprire la schermata Modifica attestazione gruppi.

  3. Selezionare Gruppi assegnati all'applicazione.

    Scegliendo altre opzioni, ad esempio Gruppi di sicurezza o Tutti i gruppi (incluse le liste di distribuzione ma non i gruppi assegnati all'applicazione), nega i vantaggi derivanti dalla scelta dell'app per usare questa opzione.

  4. Nella sezione ID selezionare ID gruppo. Questa selezione comporta l'invio dell'ID oggetto dei gruppi a cui l'utente viene assegnato nell'attestazione groups del token ID.

  5. Se si espone un'API Web usando l'opzione Esporre un'API , è anche possibile scegliere l'opzione ID gruppo nella sezione Accesso . Questa opzione comporta l'invio dell'ID oggetto dei gruppi a cui l'utente viene assegnato nell'attestazione groups del token di accesso.

  6. Nella pagina di registrazione dell'app selezionare Panoramica nel riquadro di spostamento per aprire la schermata di panoramica dell'applicazione.

  7. Selezionare il collegamento ipertestuale con il nome dell'applicazione in Applicazione gestita nella directory locale. Questo titolo di campo potrebbe essere troncato, ad esempio Managed application in .... Quando si seleziona questo collegamento, passare alla pagina Panoramica dell'applicazione aziendale associata all'entità servizio per l'applicazione nel tenant in cui è stata creata. È possibile tornare alla pagina di registrazione dell'app usando il pulsante Indietro del browser.

  8. Selezionare Utenti e gruppi nel riquadro di spostamento per aprire la pagina in cui è possibile assegnare utenti e gruppi all'applicazione.

  9. Seleziona Aggiungi utente.

  10. Selezionare Utenti e gruppi nella schermata risultante.

  11. Scegliere i gruppi da assegnare a questa applicazione.

  12. Selezionare Seleziona per completare la selezione dei gruppi.

  13. Selezionare Assegna per completare il processo di assegnazione del gruppo.

    L'applicazione riceve ora questi gruppi selezionati nell'attestazione dei gruppi quando un utente che accede all'app è membro di uno o più gruppi assegnati.

  14. Selezionare Proprietà nel riquadro di spostamento per aprire la pagina in cui sono elencate le proprietà di base dell'applicazione. Impostare il flag Assegnazione utente obbligatoria? su Sì.

Importante

Quando si imposta Assegnazione utente obbligatoria? su Sì, Microsoft Entra ID verifica che solo gli utenti assegnati all'applicazione nel riquadro Utenti e gruppi siano in grado di accedere all'app. È possibile assegnare gli utenti direttamente o assegnando i gruppi di sicurezza a cui appartengono.

Configurare l'app (java-servlet-webapp-groups) per riconoscere gli ID gruppo

Usare la procedura seguente per configurare l'app:

Importante

Nella pagina Configurazione token, se si sceglie un'opzione diversa da groupID, ad esempio DNSDomain\sAMAccountName, è necessario immettere il nome del gruppo nei passaggi seguenti, ad esempio , contoso.com\Test Group anziché l'ID oggetto:

  1. Aprire il file ./src/main/resources/authentication.properties .

  2. Trovare la stringa {enter-your-admins-group-id-here} e sostituire il valore esistente con l'ID oggetto del GroupAdmin gruppo copiato dal portale di Azure. Rimuovere anche le parentesi graffe dal valore segnaposto.

  3. Trovare la stringa {enter-your-users-group-id-here} e sostituire il valore esistente con l'ID oggetto del GroupMember gruppo copiato dal portale di Azure. Rimuovere anche le parentesi graffe dal valore segnaposto.

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 con estensione war che è possibile eseguire in vari server applicazioni.

Eseguire l'esempio

Le sezioni seguenti illustrano come distribuire l'esempio in app Azure Servizio.

Prerequisiti

Configurare il plug-in Maven

Quando si esegue la distribuzione in app Azure Servizio, la distribuzione usa automaticamente le credenziali di Azure dall'interfaccia della riga di comando di Azure. Se l'interfaccia della riga di comando di Azure non è installata in locale, il plug-in Maven esegue l'autenticazione con OAuth o con l'accesso del dispositivo. Per altre informazioni, vedere Autenticazione con i plug-in Maven.

Per configurare il plug-in, seguire questa procedura:

  1. Eseguire il comando seguente per configurare la distribuzione. Questo comando consente di configurare il sistema operativo del servizio app Azure, la versione Java e la versione di Tomcat.

    mvn com.microsoft.azure:azure-webapp-maven-plugin:2.13.0:config

  2. Per Crea nuova configurazione di esecuzione, premere Y, quindi premere INVIO.

  3. Per Definisci valore per il sistema operativo, premere 1 per Windows o 2 per Linux, quindi premere INVIO.

  4. Per Definisci valore per javaVersion, premere 2 per Java 11 e quindi premere INVIO.

  5. Per Definisci valore per webContainer, premere 4 per Tomcat 9.0, quindi premere INVIO.

  6. Per Definisci valore per pricingTier, premere INVIO per selezionare il livello P1v2 predefinito.

  7. Per Conferma premere Y, quindi premere INVIO.

L'esempio seguente mostra l'output del processo di distribuzione:

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

Dopo aver confermato le scelte, il plug-in aggiunge l'elemento e le impostazioni del plug-in necessari al file di pom.xml del progetto per configurare l'app per l'esecuzione in app Azure Servizio.

La parte pertinente del file pom.xml dovrebbe essere simile all'esempio seguente:

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

È possibile modificare le configurazioni per servizio app direttamente nel pom.xml. Alcune configurazioni comuni sono elencate nella tabella seguente:

Proprietà Richiesto Descrizione
subscriptionId false ID della sottoscrizione.
resourceGroup true Gruppo di risorse di Azure per l'app.
appName true Nome dell'app.
region false Area in cui ospitare l'app. Il valore predefinito è centralus. Per le aree valide, vedere Aree supportate.
pricingTier false Piano tariffario per l'app. Il valore predefinito è P1v2 per un carico di lavoro di produzione. Il valore minimo consigliato per lo sviluppo e il test Java è B2. Per altre informazioni, vedere Prezzi di servizio app.
runtime false Configurazione dell'ambiente di runtime. Per altre informazioni, vedere Dettagli della configurazione.
deployment false Configurazione della distribuzione. Per altre informazioni, vedere Dettagli della configurazione.

Per l'elenco completo delle configurazioni, vedere la documentazione di riferimento sul plug-in. Tutti i plug-in Azure Maven condividono un set comune di configurazioni. Per queste configurazioni, vedere Configurazioni comuni. Per le configurazioni specifiche del servizio app Azure, vedere App di Azure: Dettagli configurazione.

Assicurarsi di salvare i appName valori e resourceGroup per usarli in un secondo momento.

Preparare l'app per la distribuzione

Quando si distribuisce l'applicazione in servizio app, l'URL di reindirizzamento viene modificato nell'URL di reindirizzamento dell'istanza dell'app distribuita. Usare la procedura seguente per modificare queste impostazioni nel file delle proprietà:

  1. Passare al file authentication.properties dell'app e modificare il valore di app.homePage in base al nome di dominio dell'app distribuita, come illustrato nell'esempio seguente. Ad esempio, se si sceglie example-domain per il nome dell'app nel passaggio precedente, è ora necessario usare https://example-domain.azurewebsites.net per il app.homePage valore . Assicurarsi di aver modificato anche il protocollo da http a https.

    # app.homePage is by default set to dev server address and app context path on the server
# for apps deployed to azure, use https://your-sub-domain.azurewebsites.net
app.homePage=https://<your-app-name>.azurewebsites.net

  2. Dopo aver salvato questo file, usare il comando seguente per ricompilare l'app:

    mvn clean package

Importante

In questo stesso file authentication.properties è disponibile un'impostazione per .aad.secret Non è consigliabile distribuire questo valore in servizio app. Nessuno dei due è consigliabile lasciare questo valore nel codice e potenzialmente eseguirne il push nel repository Git. Per rimuovere questo valore segreto dal codice, è possibile trovare indicazioni più dettagliate nella sezione Deploy to servizio app - Remove secret (Distribuisci in servizio app - Rimuovi segreto). Questo materiale sussidiario aggiunge passaggi aggiuntivi per il push del valore del segreto in Key Vault e per l'uso dei riferimenti all'insieme di credenziali delle chiavi.

Aggiornare la registrazione dell'app Microsoft Entra ID

Poiché l'URI di reindirizzamento cambia nell'app distribuita in app Azure Servizio, è anche necessario modificare l'URI di reindirizzamento nella registrazione dell'app Microsoft Entra ID. Attenersi alla seguente procedura per apportare questa modifica:

  1. Passare alla pagina Registrazioni app di Microsoft Identity Platform per sviluppatori.

  2. Usare la casella di ricerca per cercare la registrazione dell'app, java-servlet-webapp-authenticationad esempio .

  3. Aprire la registrazione dell'app selezionandone il nome.

  4. Seleziona Autenticazione dal menu.

  5. Nella sezione URI di reindirizzamento Web - selezionare Aggiungi URI.

  6. Compilare l'URI dell'app, aggiungendo /auth/redirect , ad esempio . https://<your-app-name>.azurewebsites.net/auth/redirect

  7. Seleziona Salva.

Distribuire l'app

È ora possibile distribuire l'app nel servizio app Azure. Usare il comando seguente per assicurarsi di aver eseguito l'accesso all'ambiente Azure per eseguire la distribuzione:

az login

Con tutta la configurazione pronta nel file pom.xml , è ora possibile usare il comando seguente per distribuire l'app Java in Azure:

mvn package azure-webapp:deploy

Al termine della distribuzione, l'applicazione è pronta in http://<your-app-name>.azurewebsites.net/. Aprire l'URL con il Web browser locale, in cui verrà visualizzata la pagina iniziale dell'applicazione msal4j-servlet-auth .

Esaminare l'esempio

Per esplorare l'esempio, seguire questa procedura:

  1. Si noti lo stato di accesso o disconnesso visualizzato al centro della schermata.
  2. Selezionare il pulsante sensibile al contesto nell'angolo. Questo pulsante legge Accedi quando si esegue l'app per la prima volta.
  3. Nella pagina successiva seguire le istruzioni e accedere con un account nel tenant microsoft Entra ID.
  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 ID Token Details (Dettagli token ID) per visualizzare alcune delle attestazioni decodificate del token ID.
  7. Selezionare Gruppi per visualizzare le informazioni sull'appartenenza al gruppo di sicurezza per l'utente connesso.
  8. Selezionare Solo amministratore o Utente normale per accedere agli endpoint protetti dell'attestazione dei gruppi.
    • Se l'utente connesso è nel GroupAdmin gruppo, l'utente può immettere entrambe le pagine.
    • Se l'utente connesso è nel GroupMember gruppo, l'utente può immettere solo la pagina Utente normale.
    • Se l'utente connesso non è in nessun gruppo, l'utente non può accedere a una delle due pagine.
  9. Usare il pulsante nell'angolo per disconnettersi.
  10. Dopo la disconnessione, selezionare ID Token Details (Dettagli token ID) per osservare che l'app visualizza un 401: unauthorized errore anziché le attestazioni del token ID quando l'utente non è autorizzato.

Informazioni sul codice

Questo esempio usa MSAL per Java (MSAL4J) per accedere a un utente e ottenere un token ID che potrebbe contenere l'attestazione dei gruppi. Se sono presenti troppi gruppi per l'emissione nel token ID, l'esempio usa Microsoft Graph SDK per Java per ottenere i dati di appartenenza al gruppo da Microsoft Graph. In base ai gruppi a cui appartiene l'utente, l'utente connesso può accedere a nessuno, uno o entrambe le pagine Admins Only protette e Regular Users.

Se si vuole replicare il comportamento di questo esempio, è necessario aggiungere MSAL4J e Microsoft Graph SDK ai progetti usando Maven. È possibile copiare il file pom.xml e il contenuto delle cartelle helper e authservlets nella cartella src/main/java/com/microsoft/azuresamples/msal4j . È necessario anche il file authentication.properties . 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:

File/cartella Descrizione
src/main/java/com/microsoft/azuresamples/msal4j/groupswebapp/ Questa directory contiene le classi che definiscono la logica di business back-end dell'app.
src/main/java/com/microsoft/azuresamples/msal4j/authservlets/ Questa directory contiene le classi usate per l'accesso e la disconnessità degli endpoint.
____Servlet.java Tutti gli endpoint disponibili sono definiti nelle classi .java che terminano in ____Servlet.java.
src/main/java/com/microsoft/azuresamples/msal4j/helpers/ Classi helper per l'autenticazione.
AuthenticationFilter.java Reindirizza le richieste non autenticate agli endpoint protetti a una pagina 401.
src/main/resources/authentication.properties Microsoft Entra ID e configurazione del programma.
src/main/webapp/ Questa directory contiene l'interfaccia utente - Modelli JSP
CHANGELOG.md Elenco delle modifiche apportate all'esempio.
CONTRIBUTING.md Linee guida per contribuire all'esempio.
LICENZA Licenza per l'esempio.

Elaborare un'attestazione di gruppi nei token, inclusa la gestione dell'eccedenza

Le sezioni seguenti descrivono come l'app elabora un'attestazione di gruppi.

Attestazione gruppi

L'ID oggetto dei gruppi di sicurezza di cui l'utente connesso è membro viene restituito nell'attestazione groups del token, illustrato nell'esempio seguente:

{
  ...
  "groups": [
    "0bbe91cc-b69e-414d-85a6-a043d6752215",
    "48931dac-3736-45e7-83e8-015e6dfd6f7c",]
  ...
}

Attestazione di eccedenza dei gruppi

Per assicurarsi che le dimensioni del token non superino i limiti delle dimensioni dell'intestazione HTTP, Microsoft Identity Platform limita il numero di ID oggetto inclusi nell'attestazione dei gruppi.

Il limite di eccedenza è 150 per i token SAML, 200 per i token JWT e 6 per le applicazioni a pagina singola. Se un utente è membro di più gruppi rispetto al limite di eccedenza, Microsoft Identity Platform non genera gli ID gruppo nell'attestazione dei gruppi nel token. Include invece un'attestazione di eccedenza nel token che indica all'applicazione di eseguire una query sull'API Microsoft Graph per recuperare l'appartenenza al gruppo dell'utente, come illustrato nell'esempio seguente:

{
  ...
  "_claim_names": {
    "groups": "src1"
    },
    {
   "_claim_sources": {
    "src1": {
        "endpoint":"[Graph Url to get this user's group membership from]"
        }
    }
  ...
}

Creare lo scenario di eccedenza in questo esempio per il test

Per creare lo scenario di eccedenza, è possibile seguire questa procedura:

  1. È possibile usare il file BulkCreateGroups.ps1 fornito nella cartella AppCreationScripts per creare un numero elevato di gruppi e assegnare loro utenti. Questo file consente di testare gli scenari di eccedenza durante lo sviluppo. Ricordarsi di modificare l'elemento fornito dall'utente objectId nello script BulkCreateGroups.ps1 .

  2. Quando si esegue questo esempio e si verifica un'eccedenza, viene visualizzato _claim_names nella home page dopo l'accesso dell'utente.

  3. È consigliabile usare la funzionalità di filtro dei gruppi, se possibile, per evitare di incorrere in eccedenze di gruppo. Per altre informazioni, vedere la sezione Configurare l'applicazione per ricevere i valori delle attestazioni dei gruppi da un set filtrato di gruppi a cui potrebbe essere assegnato un utente.

  4. Nel caso in cui non sia possibile evitare di eseguire l'eccedenza del gruppo, è consigliabile seguire questa procedura per elaborare l'attestazione dei gruppi nel token:

    1. Verificare la presenza dell'attestazione _claim_names con uno dei valori che si tratta di gruppi. Questa attestazione indica l'eccedenza.
    2. Se trovato, effettuare una chiamata all'endpoint specificato in _claim_sources per recuperare i gruppi dell'utente.
    3. Se non viene trovato alcun elemento, esaminare l'attestazione dei gruppi per i gruppi dell'utente.

Nota

La gestione dell'eccedenza richiede una chiamata a Microsoft Graph per leggere le appartenenze ai gruppi dell'utente connesso, pertanto l'app deve disporre dell'autorizzazione GroupMember.Read.All per l'esecuzione corretta della funzione getMemberObjects .

Per altre informazioni sulla programmazione per Microsoft Graph, vedere il video Introduzione a Microsoft Graph per sviluppatori.

ConfidentialClientApplication

Viene creata un'istanza ConfidentialClientApplication nel file AuthHelper.java , come illustrato 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 la creazione di istanze vengono usati i parametri seguenti:

  • ID client dell'app.
  • Segreto client, che è un requisito per le applicazioni client riservate.
  • Microsoft Entra ID Authority, che include l'ID tenant di Microsoft Entra.

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

Procedura

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 /authorize tenant di Microsoft Entra ID. L'istanza DI MSAL4J ConfidentialClientApplication viene usata 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:

    • AuthorizationRequestUrlParameters: parametri che devono essere impostati per compilare un oggetto AuthorizationRequestUrl.
    • REDIRECT_URI: dove Microsoft Entra reindirizza il browser, insieme al codice di autenticazione, dopo aver raccolto le credenziali utente. Deve corrispondere all'URI di reindirizzamento nella registrazione dell'app Microsoft Entra ID nel portale di Azure.
    • SCOPES: gli ambiti sono autorizzazioni richieste dall'applicazione.
      • In genere, i tre ambiti openid profile offline_access sono sufficienti per ricevere una risposta del token ID.
      • L'elenco completo degli ambiti richiesti dall'app è disponibile nel file authentication.properties . È possibile aggiungere altri ambiti, ad esempio User.Read.

  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 a questo endpoint contiene un codice di autorizzazione.

  3. L'istanza ConfidentialClientApplication scambia quindi questo codice di autorizzazione per un token ID e un token di accesso 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:

    • AuthorizationCodeParameters: parametri che devono essere impostati per scambiare il codice di autorizzazione per un ID e/o un token di accesso.
    • authCode: codice di autorizzazione ricevuto nell'endpoint di reindirizzamento.
    • REDIRECT_URI: l'URI di reindirizzamento usato nel passaggio precedente deve essere passato di nuovo.
    • SCOPES: gli ambiti usati nel passaggio precedente devono essere passati di nuovo.

  4. Se acquireToken ha esito positivo, vengono estratte le attestazioni del token. Se il controllo nonce viene superato, i risultati vengono inseriti in context , un'istanza di IdentityContextData , e salvati nella sessione. L'applicazione può quindi creare un'istanza IdentityContextData di dalla sessione tramite un'istanza di IdentityContextAdapterServlet ogni volta che deve accedervi, come illustrato 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());

// handle groups overage if it has occurred.
handleGroupsOverage(contextAdapter);

  5. Dopo il passaggio precedente, è possibile estrarre le appartenenze ai gruppi chiamando context.getGroups() usando un'istanza di IdentityContextData.

  6. Se l'utente è membro di troppi gruppi, più di 200, una chiamata a context.getGroups() potrebbe essere vuota se non per la chiamata a handleGroupsOverage(). Nel frattempo, context.getGroupsOverage() restituisce true, segnalando che si è verificata un'eccedenza e che il recupero dell'elenco completo dei gruppi richiede una chiamata a Microsoft Graph. Vedere il handleGroupsOverage() metodo in AuthHelper.java per vedere come questa applicazione usa context.setGroups() quando si verifica un sovraccarico.

Proteggere le route

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

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

Le route elencate nei set di regole delimitate da virgole ai app.protect.groups sensi di sono inoltre off-limits agli utenti autenticati non autenticati, come illustrato nell'esempio seguente. Tuttavia, queste route contengono anche un elenco separato da spazi di appartenenze ai gruppi. Solo gli utenti appartenenti ad almeno uno dei gruppi corrispondenti possono accedere a queste route dopo l'autenticazione.

# define short names for group IDs here for the app. This is useful in the next property (app.protect.groups).
# EXCLUDE the curly braces, they are in this file only as delimiters.
# example:
# app.groups=groupA abcdef-qrstuvw-xyz groupB abcdef-qrstuv-wxyz
app.groups=admin {enter-your-admins-group-id-here}, user {enter-your-users-group-id-here}

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

Ambiti

Gli ambiti indicano a Microsoft Entra ID il livello di accesso richiesto dall'applicazione.

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ù ambiti e ottiene un token, gli ambiti con consenso vengono codificati nell'oggetto risultante access_token.

Per gli ambiti richiesti dall'applicazione, vedere authentication.properties. Per impostazione predefinita, l'applicazione imposta il valore degli ambiti su GroupMember.Read.All. Questo particolare ambito dell'API Microsoft Graph è necessario nel caso in cui l'applicazione debba chiamare Graph per ottenere le appartenenze ai gruppi dell'utente.

Ulteriori informazioni