Condividi tramite

Proteggere le applicazioni Quarkus con Microsoft Entra ID con OpenID Connect

  • Articolo

Questo articolo illustra come proteggere le applicazioni Red Hat Quarkus con l'ID Microsoft Entra usando OpenID Connect (OIDC).

In questo articolo vengono illustrate le operazioni seguenti:

  • Configurare un provider OpenID Connect con Microsoft Entra ID.
  • Proteggere un'app Quarkus usando OpenID Connect.
  • Eseguire e testare l'app Quarkus.

Prerequisiti

Configurare un provider OpenID Connect con Microsoft Entra ID

In questa sezione viene configurato un provider OpenID Connect con Microsoft Entra ID da usare con l'app Quarkus. In una sezione successiva si configura l'app Quarkus usando OpenID Connect per autenticare e autorizzare gli utenti nel tenant di Microsoft Entra.

Creare utenti nel tenant di Microsoft Entra

Prima di tutto, creare due utenti nel tenant di Microsoft Entra seguendo la procedura descritta in Come creare, invitare ed eliminare utenti. È sufficiente la sezione Crea un nuovo utente . Usare le istruzioni seguenti durante l'articolo, quindi tornare a questo articolo dopo aver creato gli utenti nel tenant di Microsoft Entra.

Per creare un utente da usare come "amministratore" nell'app, seguire questa procedura:

  1. Quando si raggiunge la scheda Informazioni di base nella sezione Crea un nuovo utente , seguire questa procedura:

    1. Per Nome entità utente immettere admin. Salvare il valore in modo da poterlo usare in un secondo momento quando si accede all'app.

    2. Per Nome alternativo posta selezionare Deriva dal nome dell'entità utente

    3. Per Nome visualizzato immettere Admin.

    4. Per Password selezionare Genera automaticamente la password. Copiare e salvare il valore password da usare in un secondo momento quando si accede all'app.

    5. Selezionare Account abilitato.

      Screenshot del portale di Azure che mostra il riquadro Crea nuovo utente Informazioni di base per un utente amministratore.

    6. Selezionare Rivedi e crea>Crea. Attendere fino a quando l'utente non viene creato.

    7. Attendere un minuto o così via e selezionare Aggiorna. Verrà visualizzato il nuovo utente nell'elenco.

Per creare un utente da usare come "utente" nell'app, ripetere questi passaggi, ma usare i valori seguenti:

  • In Nome entità utente immettere user.
  • In Nome visualizzato immettere User.

Screenshot del portale di Azure che mostra il riquadro Crea nuovo utente Informazioni di base per un utente normale.

Registrare un’applicazione in Microsoft Entra ID

Registrare quindi un'applicazione seguendo la procedura descritta in Avvio rapido: Registrare un'applicazione con Microsoft Identity Platform. Usare le istruzioni seguenti durante l'articolo, quindi tornare a questo articolo dopo la registrazione e la configurazione dell'applicazione.

  1. Quando si raggiunge la sezione Registra un'applicazione , seguire questa procedura:
    1. Per Tipi di account supportati selezionare Account solo in questa directory organizzativa (solo directory predefinita - Tenant singolo).
    2. Al termine della registrazione, salvare i valori ID applicazione (client) e ID directory (tenant) da usare in un secondo momento nella configurazione dell'app.
  2. Quando si raggiunge la sezione Aggiungi un URI di reindirizzamento, ignorare i passaggi per il momento. Aggiungere l'URI di reindirizzamento in un secondo momento quando si esegue e si testa l'app di esempio in locale in questo articolo.
  3. Quando si raggiunge la sezione Aggiungi credenziali , selezionare la scheda Aggiungi un segreto client.
  4. Quando si aggiunge un segreto client, annotare il valore del segreto client da usare in un secondo momento nella configurazione dell'app.

Aggiungere i ruoli dell'app all'applicazione

Aggiungere quindi i ruoli dell'app all'applicazione seguendo la procedura descritta in Aggiungere ruoli dell'app all'applicazione e riceverli nel token. Sono necessarie solo le sezioni Dichiarare i ruoli per un'applicazione e Assegnare utenti e gruppi ai ruoli di Microsoft Entra. Usare le istruzioni seguenti durante l'articolo, quindi tornare a questo articolo dopo aver dichiarato i ruoli per l'applicazione.

  1. Quando si raggiunge la sezione Dichiara ruoli per un'applicazione , usare l'interfaccia utente Ruoli app per creare ruoli per l'amministratore e l'utente normale.

    1. Creare un ruolo utente amministratore usando i valori seguenti:

      • Per Nome visualizzato immettere Admin.
      • In Tipi di membri consentiti selezionare Utenti/Gruppi.
      • Per Valore immettere admin.
      • Per Descrizione immettere Admin.For Description, enter Admin.
      • Selezionare Vuoi abilitare questo ruolo dell'app?

      Screenshot del portale di Azure che mostra il riquadro Crea ruolo app per l'utente amministratore.

    2. Selezionare Applica. Attendere la creazione del ruolo.

    3. Creare un ruolo utente normale usando gli stessi passaggi, ma con i valori seguenti:

      • In Nome visualizzato immettere User.
      • In Valore immettere user.
      • Per Descrizione immettere User.

      Screenshot del portale di Azure che mostra il riquadro Crea ruolo app per l'utente normale.

  2. Quando si raggiunge la sezione Assegnare utenti e gruppi ai ruoli di Microsoft Entra, seguire questa procedura:

    1. Selezionare Aggiungi utente/gruppo.

    2. Nel riquadro Aggiungi assegnazione selezionare Amministratore utente e selezionare Amministratore ruolo per Selezionare un ruolo. Selezionare quindi Assegna. Attendere che l'assegnazione dell'applicazione abbia esito positivo. Potrebbe essere necessario scorrere la tabella lateralmente per visualizzare la colonna Role assigned .

    3. Ripetere i passaggi precedenti per assegnare il ruolo Utente all'utente.

    4. Selezionare Aggiorna e verranno visualizzati gli utenti e i ruoli assegnati nel riquadro Utenti e gruppi .

      Screenshot del portale di Azure che mostra gli utenti e i ruoli assegnati.

      Potrebbe essere necessario modificare la larghezza delle intestazioni di colonna per fare in modo che la visualizzazione sia simile all'immagine.

Non seguire altri passaggi in Aggiungere ruoli dell'app all'applicazione e riceverli nel token.

Proteggere un'app Quarkus usando OpenID Connect

In questa sezione si protegge un'app Quarkus che autentica e autorizza gli utenti nel tenant di Microsoft Entra usando OpenID Connect. Si apprenderà anche come concedere agli utenti l'accesso a determinate parti dell'app usando il controllo degli accessi in base al ruolo.

L'app Quarkus di esempio per questa guida introduttiva si trova in GitHub nel repository quarkus-azure e si trova nella directory entra-id-quarkus .

Abilitare l'autenticazione e l'autorizzazione per proteggere l'app

L'app ha una risorsa della pagina iniziale definita in WelcomePage.java, come illustrato nel codice di esempio seguente. Questa pagina è accessibile agli utenti non autenticati. Il percorso radice della pagina di benvenuto si trova in /.

@Path("/")
public class WelcomePage {

    private final Template welcome;

    public WelcomePage(Template welcome) {
        this.welcome = requireNonNull(welcome, "welcome page is required");
    }

    @GET
    @Produces(MediaType.TEXT_HTML)
    public TemplateInstance get() {
        return welcome.instance();
    }

}

Dalla pagina iniziale gli utenti possono accedere all'app per accedere alla pagina del profilo. La pagina iniziale contiene collegamenti per accedere come utente o come amministratore. I collegamenti si trovano rispettivamente in /profile/user e /profile/admin. L'interfaccia utente della pagina iniziale è definita in welcome.qute.html e mostrata nell'esempio seguente:

<html>
    <head>
        <meta charset="UTF-8">
        <title>Greeting</title>
    </head>
    <body>
        <h1>Hello, welcome to Quarkus and Microsoft Entra ID integration!</h1>
        <h1>
            <a href="/profile/user">Sign in as user</a>
        </h1>
        <h1>
            <a href="/profile/admin">Sign in as admin</a>
        </h1>
    </body>
</html>

Sia /profile/user che /profile/admin i collegamenti puntano alla risorsa della pagina del profilo, definita in ProfilePage.java, come illustrato nel codice di esempio seguente. Questa pagina è accessibile solo agli utenti autenticati usando l'annotazione @RolesAllowed("**") del jakarta.annotation.security.RolesAllowed pacchetto. L'annotazione @RolesAllowed("**") specifica che solo gli utenti autenticati possono accedere al /profile percorso.

@Path("/profile")
@RolesAllowed("**")
public class ProfilePage {

    private final Template profile;

    @Inject
    SecurityIdentity identity;

    @Inject
    JsonWebToken accessToken;

    public ProfilePage(Template profile) {
        this.profile = requireNonNull(profile, "profile page is required");
    }

    @Path("/admin")
    @GET
    @Produces(MediaType.TEXT_HTML)
    @RolesAllowed("admin")
    public TemplateInstance getAdmin() {
        return getProfile();
    }

    @Path("/user")
    @GET
    @Produces(MediaType.TEXT_HTML)
    @RolesAllowed({"user","admin"})
    public TemplateInstance getUser() {
        return getProfile();
    }

    private TemplateInstance getProfile() {
        return profile
                .data("name", identity.getPrincipal().getName())
                .data("roles", identity.getRoles())
                .data("scopes", accessToken.getClaim("scp"));
    }

}

La risorsa della pagina del profilo abilita il controllo degli accessi in base al ruolo usando l'annotazione @RolesAllowed . Gli argomenti dell'annotazione @RolesAllowed specificano che solo gli utenti con il admin ruolo possono accedere al /profile/admin percorso e gli utenti con il user ruolo o admin possono accedere al /profile/user percorso.

Sia gli /profile/admin endpoint che /profile/user restituiscono la pagina del profilo. L'interfaccia utente della pagina del profilo è definita in profile.qute.html, come illustrato nell'esempio seguente. In questa pagina vengono visualizzati il nome, i ruoli e gli ambiti dell'utente. La pagina del profilo include anche un collegamento di disconnessione in /logout, che reindirizza l'utente al provider OIDC per disconnettersi. La pagina del profilo viene scritta usando il motore di creazione modelli Qute. Si noti l'uso di {} espressioni nella pagina. Queste espressioni usano i valori passati all'oggetto TemplateInstance utilizzando il data() metodo . Per altre informazioni su Qute, vedere Qute templating engine .For more information on Qute templating engine.

<html>
    <head>
        <meta charset="UTF-8">
        <title>Profile</title>
    </head>
    <body>
        <h1>Hello, {name}</h1>
        <h2>Roles</h2>
        <ul>
            {#if roles}
                {#for role in roles}
                    <li>{role}</li>
                {/for}
            {#else}
                <li>No roles found!</li>
            {/if}
        </ul>
        <h2>Scopes</h2>
        <p>
            {scopes}
        </p>
        <h1>
            <b><a href="/logout">Sign out</a></b>
        </h1>
    </body>
</html>

Dopo la disconnessione, l'utente viene reindirizzato alla pagina di benvenuto e può accedere di nuovo.

Eseguire e testare l'app Quarkus

In questa sezione si esegue e si testa l'app Quarkus per vedere come funziona con Microsoft Entra ID come provider OpenID Connect.

Aggiungere un URI di reindirizzamento alla registrazione dell'app

Per eseguire e testare correttamente l'app in locale, è necessario aggiungere un URI di reindirizzamento alla registrazione dell'app. Seguire le istruzioni nella sezione Aggiungere un URI di reindirizzamento di Avvio rapido: Registrare un'applicazione con Microsoft Identity Platform e usare i valori seguenti:

  • Per Configura piattaforme selezionare Web.
  • Per URI di reindirizzamento immettere http://localhost:8080.

Preparare l'esempio

Usare la procedura seguente per preparare l'app Quarkus di esempio:

  1. Usare i comandi seguenti per clonare l'app Quarkus di esempio da GitHub e passare alla directory entra-id-quarkus:

    git clone https://github.com/Azure-Samples/quarkus-azure
cd quarkus-azure/entra-id-quarkus
git checkout 2024-09-26

    Se visualizzi un messaggio relativo allo stato HEAD scollegato, questo messaggio è sicuro da ignorare. Poiché questo articolo non richiede commit, lo stato HEAD scollegato è appropriato.

  2. Usare i comandi seguenti per definire le variabili di ambiente seguenti con i valori annoti in precedenza:

    export QUARKUS_OIDC_CLIENT_ID=<application/client-ID>
export QUARKUS_OIDC_CREDENTIALS_SECRET=<client-secret>
export QUARKUS_OIDC_AUTH_SERVER_URL=https://login.microsoftonline.com/<directory/tenant-ID>/v2.0

    Queste variabili di ambiente forniscono i valori per il supporto predefinito di OpenID Connect in Quarkus. Le proprietà corrispondenti in application.properties sono illustrate nell'esempio seguente.

    quarkus.oidc.client-id=
quarkus.oidc.credentials.secret=
quarkus.oidc.auth-server-url=

    Se il valore di una proprietà è vuoto in application.properties, Quarkus converte il nome della proprietà in una variabile di ambiente e legge il valore dall'ambiente. Per informazioni dettagliate sulla conversione dei nomi, vedere la specifica di Configurazione microProfile.

Eseguire l'app Quarkus

È possibile eseguire l'app Quarkus in modalità diverse. Selezionare uno dei metodi seguenti per eseguire l'app Quarkus. Per consentire a Quarkus di connettersi all'ID di Microsoft Entra, assicurarsi di eseguire il comando nella shell in cui sono state definite le variabili di ambiente illustrate nella sezione precedente.

  • Eseguire l'app Quarkus in modalità di sviluppo:

    mvn quarkus:dev

  • Eseguire l'app Quarkus in modalità JVM:

    mvn install
java -jar target/quarkus-app/quarkus-run.jar

  • Eseguire l'app Quarkus in modalità nativa:

    mvn install -Dnative -Dquarkus.native.container-build
./target/quarkus-ad-1.0.0-SNAPSHOT-runner

Se vuoi provare diverse modalità, usa CTRL+C per arrestare l'app Quarkus e quindi esegui l'app Quarkus in un'altra modalità.

Testare l'app Quarkus

Dopo aver eseguito l'app Quarkus, aprire un Web browser con una scheda privata e passare a http://localhost:8080. Verrà visualizzata la pagina iniziale con collegamenti per accedere come utente o come amministratore. L'uso di una scheda privata consente di evitare di inquinare qualsiasi attività esistente di Microsoft Entra ID nel browser normale.

Screenshot dell'applicazione di esempio che mostra la pagina iniziale.

Raccogliere le credenziali per i due utenti

In questo articolo, Microsoft Entra ID usa l'indirizzo di posta elettronica di ogni utente come ID utente per l'accesso. Usare la procedura seguente per ottenere l'indirizzo di posta elettronica per l'utente amministratore e l'utente normale:

  1. Accedere all'Interfaccia di amministrazione di Microsoft Entra almeno come Amministratore applicazione cloud.
  2. Se si ha accesso a più tenant, usare l'icona Impostazioni ( ) nel menu in alto per passare al tenant in cui si vuole registrare l'applicazione dal menu Directory e sottoscrizioni.
  3. Passare a Identity Users All Users .Browse to >.
  4. Individuare l'utente amministratore nell'elenco e selezionarlo.
  5. Individuare il campo Nome entità utente.
  6. Usare l'icona di copia accanto al valore del campo per salvare l'indirizzo di posta elettronica dell'utente negli Appunti. Salvare il valore per usarlo in un secondo momento.
  7. Per ottenere l'indirizzo di posta elettronica per l'utente normale, seguire la stessa procedura.

Usare le password per l'utente amministratore e l'utente normale impostati durante la creazione degli utenti.

Esercizio della funzionalità dell'app

Per eseguire l'esercizio delle funzionalità, seguire questa procedura:

  1. Selezionare il collegamento Accedi come utente . Accedere con l'utente normale creato in precedenza. Dopo l'accesso, Microsoft Entra ID reindirizza l'utente alla pagina del profilo, in cui vengono visualizzati il nome, i ruoli e gli ambiti.

    Screenshot dell'applicazione di esempio che mostra il profilo utente.

  2. Se è la prima volta che si esegue l'accesso, viene richiesto di aggiornare la password. Seguire le istruzioni per aggiornare la password.

  3. Se viene richiesto all'organizzazione sono necessarie informazioni di sicurezza aggiuntive. Seguire le istruzioni per scaricare e configurare l'app Microsoft Authenticator, è possibile selezionare Chiedi in un secondo momento per continuare il test.

  4. Se viene richiesto l'opzione Autorizzazioni, esaminare le autorizzazioni richieste dall'app. Selezionare Accetta per continuare il test.

  5. Selezionare Disconnetti per disconnettersi dall'app Quarkus. Microsoft Entra ID esegue la disconnessa. Dopo la disconnessione, Microsoft Entra ID reindirizza l'utente alla pagina di benvenuto.

  6. Selezionare il collegamento Accedi come amministratore . Microsoft Entra ID reindirizza l'utente alla pagina di accesso. Accedere con l'utente amministratore creato in precedenza. Dopo l'accesso, Microsoft Entra ID reindirizza l'utente alla pagina del profilo simile, con un ruolo admindiverso.

    Screenshot dell'applicazione di esempio che mostra il profilo di amministratore.

  7. Disconnettersi di nuovo e provare ad accedere come amministratore con l'utente normale creato in precedenza. Verrà visualizzato un messaggio di errore perché l'utente normale non ha il admin ruolo.

    Screenshot dell'applicazione di esempio che mostra il messaggio di accesso negato.

Pulire le risorse

Questo articolo non indirizza la distribuzione dell'app in Azure. Non ci sono risorse di Azure da pulire per l'app, anche se sono presenti risorse id Microsoft Entra. Per distribuire un'app in Azure, è possibile seguire le indicazioni a cui si fa riferimento nella sezione successiva.

Al termine delle risorse per questa app di esempio, seguire questa procedura per pulire le risorse di Microsoft Entra ID. La rimozione delle risorse microsoft Entra ID inutilizzate è una procedura consigliata importante per la sicurezza.

  1. Rimuovere la registrazione dell'app creata seguendo la procedura descritta in Rimuovere un'applicazione registrata con Microsoft Identity Platform. È sufficiente seguire la procedura descritta nella sezione Rimuovere un'applicazione creata dall'organizzazione.
  2. L'atto di rimuovere la registrazione dell'app deve anche eliminare l'applicazione aziendale. Per altre informazioni sull'eliminazione di applicazioni aziendali, vedere Eliminare un'applicazione aziendale.
  3. Eliminare gli utenti creati seguendo la procedura descritta in Come creare, invitare ed eliminare utenti.

Passaggi successivi

In questa guida introduttiva si proteggono le applicazioni Quarkus con Microsoft Entra ID usando OpenID Connect. Per altre informazioni, esplorare le risorse seguenti: