Secure Quarkus-toepassingen met Microsoft Entra ID met behulp van OpenID Connect

In dit artikel leest u hoe u Red Hat Quarkus-toepassingen beveiligt met Microsoft Entra ID met behulp van OpenID Connect (OIDC).

In dit artikel leert u het volgende:

• Stel een OpenID Connect-provider in met Microsoft Entra ID.
• Een Quarkus-app beveiligen met behulp van OpenID Connect.
• Voer de Quarkus-app uit en test deze.

Vereisten

• Een Azure-abonnement. Als u geen Azure-abonnement hebt, maakt u een gratis account voordat u begint.
• Een Azure-identiteit met ten minste de rol Cloud Application Administrator Microsoft Entra. Zie Roltoewijzingen van Microsoft Entra en ingebouwde Rollen van Microsoft Entra weergeven voor meer informatie.
• Een Microsoft Entra-tenant. Als u geen bestaande tenant hebt, raadpleegt u quickstart: Een tenant instellen.
• Een lokale computer waarop een Unix-achtig besturingssysteem is geïnstalleerd, bijvoorbeeld Ubuntu, macOS of Windows-subsysteem voor Linux.
• Git.
• Een Java SE-implementatie, versie 21 of hoger, bijvoorbeeld de Microsoft-build van OpenJDK.
• Maven, versie 3.9.3 of hoger.

Een OpenID Connect-provider instellen met Microsoft Entra-id

In deze sectie stelt u een OpenID Connect-provider in met Microsoft Entra-id voor gebruik met uw Quarkus-app. In een latere sectie configureert u de Quarkus-app met behulp van OpenID Connect om gebruikers in uw Microsoft Entra-tenant te verifiëren en autoriseren.

Gebruikers maken in Microsoft Entra-tenant

Maak eerst twee gebruikers in uw Microsoft Entra-tenant door de stappen te volgen in Het maken, uitnodigen en verwijderen van gebruikers. U hebt alleen de sectie Een nieuwe gebruiker maken nodig. Gebruik de volgende aanwijzingen terwijl u het artikel doorloopt en ga vervolgens terug naar dit artikel nadat u gebruikers in uw Microsoft Entra-tenant hebt gemaakt.

Als u een gebruiker wilt maken die als beheerder in de app moet fungeren, gebruikt u de volgende stappen:

1. Wanneer u bij het tabblad Basisbeginselen in de sectie Een nieuwe gebruiker maken bent, voert u de volgende stappen uit:

   1. Voer de beheerder in voor de principal-naam van de gebruiker. Sla de waarde op zodat u deze later kunt gebruiken wanneer u zich aanmeldt bij de app.

   2. Voor de bijnaam van Mail selecteert u Afleiden van de principal-naam van de gebruiker

   3. Voer beheerder in bij Weergavenaam.

   4. Selecteer voor Wachtwoord automatisch wachtwoord genereren. Kopieer en sla de wachtwoordwaarde op die u later wilt gebruiken wanneer u zich aanmeldt bij de app.

   5. Selecteer Account ingeschakeld.

      

   6. Selecteer Beoordelen en maken>Maken. Wacht totdat de gebruiker is gemaakt.

   7. Wacht een minuut of zo en selecteer Vernieuwen. U ziet nu de nieuwe gebruiker in de lijst.

Als u een gebruiker wilt maken die als gebruiker in de app moet fungeren, herhaalt u deze stappen, maar gebruikt u de volgende waarden:

• Voer de gebruiker in voor user principal name.
• Voer gebruiker in bij Weergavenaam.

Een toepassing registreren in Microsoft Entra-id

Registreer vervolgens een toepassing door de stappen in quickstart te volgen: Een toepassing registreren bij het Microsoft Identity Platform. Gebruik de volgende aanwijzingen tijdens het doorlopen van het artikel en ga vervolgens terug naar dit artikel nadat u de toepassing hebt geregistreerd en geconfigureerd.

1. Wanneer u de sectie Een toepassing registreren bereikt, voert u de volgende stappen uit:
   1. Voor ondersteunde accounttypen selecteert u alleen Accounts in deze organisatiemap (alleen standaardmap - één tenant).
   2. Wanneer de registratie is voltooid, slaat u de waarden voor de toepassings-id (client) en de map-id (tenant) op voor later gebruik in de app-configuratie.
2. Wanneer u de sectie Een omleidings-URI toevoegen bereikt, slaat u de stappen over zoals nu. U voegt de omleidings-URI later toe wanneer u de voorbeeld-app lokaal in dit artikel uitvoert en test.
3. Wanneer u bij de sectie Referenties toevoegen bent, selecteert u het tabblad Een clientgeheim toevoegen.
4. Wanneer u een clientgeheim toevoegt, schrijft u de waarde van het clientgeheim op voor later gebruik in de app-configuratie.

App-rollen toevoegen aan uw toepassing

Voeg vervolgens app-rollen toe aan uw toepassing door de stappen in App-rollen toevoegen aan uw toepassing toe te voegen en deze in het token te ontvangen. U hebt alleen de secties Rollen declareren voor een toepassing nodig en gebruikers en groepen toewijzen aan Microsoft Entra-rollen. Gebruik de volgende aanwijzingen terwijl u het artikel doorloopt en ga vervolgens terug naar dit artikel nadat u rollen voor de toepassing hebt declareren.

1. Wanneer u de rollen Declare voor een toepassingssectie bereikt, gebruikt u de gebruikersinterface van app-rollen om rollen te maken voor de beheerder en de gewone gebruiker.

   1. Maak een gebruikersrol beheerder met behulp van de volgende waarden:

      • Voer beheerder in bij Weergavenaam.
      • Voor toegestane lidtypen selecteert u Gebruikers/groepen.
      • Voer voor Waarde de beheerder in.
      • Voer beheerder in bij Beschrijving.
      • Selecteer Wilt u deze app-rol inschakelen?

      

   2. Selecteer Toepassen. Wacht totdat de rol is gemaakt.

   3. Maak een gewone gebruikersrol met dezelfde stappen, maar met de volgende waarden:

      • Voer gebruiker in bij Weergavenaam.
      • Voer voor Waarde de gebruiker in.
      • Voer bij Beschrijving gebruiker in.

      

2. Wanneer u de sectie Gebruikers en groepen toewijzen aan Microsoft Entra-rollen bereikt, gebruikt u de volgende stappen:

   1. Selecteer Gebruiker/groep toevoegen.

   2. Selecteer in het deelvenster Toewijzing toevoegen voor gebruikers de optie Gebruikersbeheerder en selecteer rolbeheerder voor Een rol selecteren. Selecteer vervolgens Toewijzen. Wacht totdat de toepassingstoewijzing is voltooid. Mogelijk moet u de tabel sideways schuiven om de kolom Toegewezen rollen te zien.

   3. Herhaal de vorige stappen om de gebruikersrol toe te wijzen aan de gebruiker.

   4. Selecteer Vernieuwen en u ziet de gebruikers en rollen die zijn toegewezen in het deelvenster Gebruikers en groepen .

      

      Mogelijk moet u de breedte van de kolomkoppen aanpassen om de weergave eruit te laten zien als de afbeelding.

Volg geen andere stappen in App-rollen toevoegen aan uw toepassing en ontvang deze in het token.

Een Quarkus-app beveiligen met behulp van OpenID Connect

In deze sectie beveiligt u een Quarkus-app die gebruikers in uw Microsoft Entra-tenant verifieert en autoriseert met behulp van OpenID Connect. U leert ook hoe u gebruikers toegang geeft tot bepaalde onderdelen van de app met behulp van op rollen gebaseerd toegangsbeheer (RBAC).

De voorbeeld-Quarkus-app voor deze quickstart bevindt zich op GitHub in de quarkus-azure-opslagplaats en bevindt zich in de map entra-id-quarkus .

Verificatie en autorisatie inschakelen om de app te beveiligen

De app heeft een welkomstpaginaresource gedefinieerd in WelcomePage.java, die wordt weergegeven in de volgende voorbeeldcode. Deze pagina is toegankelijk voor niet-geverifieerde gebruikers. Het hoofdpad van de welkomstpagina bevindt zich op /.

@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();
    }

}

Vanaf de welkomstpagina kunnen gebruikers zich aanmelden bij de app om toegang te krijgen tot de profielpagina. De welkomstpagina bevat koppelingen om u aan te melden als gebruiker of als beheerder. De koppelingen bevinden zich respectievelijk op /profile/user en /profile/admin, respectievelijk. De gebruikersinterface van de welkomstpagina is gedefinieerd in welcome.qute.html en wordt weergegeven in het volgende voorbeeld:

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

Zowel /profile/user als /profile/admin koppelingen verwijzen naar de resource van de profielpagina, gedefinieerd in ProfilePage.java, zoals wordt weergegeven in de volgende voorbeeldcode. Deze pagina is alleen toegankelijk voor geverifieerde gebruikers met behulp van de @RolesAllowed("**") aantekening van het jakarta.annotation.security.RolesAllowed pakket. De @RolesAllowed("**") aantekening geeft aan dat alleen geverifieerde gebruikers toegang hebben tot het /profile pad.

@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"));
    }

}

De resource van de profielpagina maakt RBAC mogelijk met behulp van de @RolesAllowed aantekening. De argumenten voor de @RolesAllowed aantekening geven aan dat alleen gebruikers met de admin rol toegang hebben tot het /profile/admin pad en dat gebruikers met de user of admin rol toegang hebben tot het /profile/user pad.

Zowel de als /profile/user de /profile/admin eindpunten retourneren de profielpagina. De gebruikersinterface van de profielpagina wordt gedefinieerd in profile.qute.html, zoals wordt weergegeven in het volgende voorbeeld. Op deze pagina worden de naam, rollen en bereiken van de gebruiker weergegeven. De profielpagina heeft ook een afmeldingskoppeling op /logout, waarmee de gebruiker wordt omgeleid naar de OIDC-provider om zich af te melden. De profielpagina wordt geschreven met behulp van de Qute-sjabloonengine. Let op het gebruik van {} expressies op de pagina. Deze expressies maken gebruik van de waarden die aan de TemplateInstance data() methode worden doorgegeven. Zie de Qute-sjabloonengine voor meer informatie over Qute.

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

Nadat u zich hebt afgemeld, wordt de gebruiker omgeleid naar de welkomstpagina en kan deze zich opnieuw aanmelden.

De Quarkus-app uitvoeren en testen

In deze sectie voert u de Quarkus-app uit en test u deze om te zien hoe deze werkt met Microsoft Entra ID als de OpenID Connect-provider.

Een omleidings-URI toevoegen aan de app-registratie

Als u de app lokaal wilt uitvoeren en testen, moet u een omleidings-URI toevoegen aan de app-registratie. Volg de instructies in de sectie Een omleidings-URI van quickstart toevoegen: Registreer een toepassing bij het Microsoft Identity Platform en gebruik de volgende waarden:

• Voor Platformen configureren selecteert u Web.
• Voer voor omleidings-URI's de tekst in http://localhost:8080.

Het voorbeeld voorbereiden

Gebruik de volgende stappen om de quarkus-voorbeeld-app voor te bereiden:

1. Gebruik de volgende opdrachten om de voorbeeld-Quarkus-app te klonen vanuit GitHub en navigeer naar de entra-id-quarkus map:

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

   Als u een bericht ziet over een losgekoppelde HEAD-status , is dit bericht veilig te negeren. Omdat voor dit artikel geen doorvoeringen nodig zijn, is de losgekoppelde HEAD-status geschikt.

2. Gebruik de volgende opdrachten om de volgende omgevingsvariabelen te definiëren met de waarden die u eerder hebt geschreven:

   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
   

   Deze omgevingsvariabelen bieden de waarden voor de ingebouwde ondersteuning van OpenID Connect in Quarkus. De bijbehorende eigenschappen application.properties worden weergegeven in het volgende voorbeeld.

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

   Als de waarde van een eigenschap leeg is in application.properties, converteert Quarkus de naam van de eigenschap naar een omgevingsvariabele en leest de waarde uit de omgeving. Zie de Configuratiespecificatie van MicroProfile voor meer informatie over de naamgevingsconversie.

De Quarkus-app uitvoeren

U kunt de Quarkus-app uitvoeren in verschillende modi. Selecteer een van de volgende methoden om de Quarkus-app uit te voeren. Als u Quarkus wilt inschakelen om verbinding te maken met Microsoft Entra ID, moet u de opdracht uitvoeren in de shell waarin u de omgevingsvariabelen hebt gedefinieerd die in de vorige sectie worden weergegeven.

• Voer de Quarkus-app uit in de ontwikkelmodus:

  mvn quarkus:dev
  

• Voer de Quarkus-app uit in de JVM-modus:

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

• Voer de Quarkus-app uit in de systeemeigen modus:

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

Als u verschillende modi wilt proberen, gebruikt u Ctrl+C om de Quarkus-app te stoppen en vervolgens de Quarkus-app uit te voeren in een andere modus.

De Quarkus-app testen

Nadat de Quarkus-app is uitgevoerd, opent u een webbrowser met een privétabblad en navigeert u naar http://localhost:8080. U ziet de welkomstpagina met koppelingen om u aan te melden als een gebruiker of als beheerder. Als u een privétabblad gebruikt, voorkomt u dat bestaande Microsoft Entra ID-activiteiten die u in uw gewone browser hebt, vervuilen.

De referenties voor de twee gebruikers verzamelen

In dit artikel gebruikt Microsoft Entra ID het e-mailadres van elke gebruiker als de gebruikers-id voor aanmelding. Gebruik de volgende stappen om het e-mailadres voor de gebruiker met beheerdersrechten en gewone gebruiker op te halen:

1. Meld u als cloudtoepassingsbeheerder aan bij het Microsoft Entra-beheercentrum.
2. Als u toegang hebt tot meerdere tenants, gebruikt u het pictogram Instellingen () in het bovenste menu om over te schakelen naar de tenant waarin u de toepassing wilt registreren in het menu Mappen en abonnementen.
3. Blader naar identiteitsgebruikers > > alle gebruikers.
4. Zoek de gebruiker met beheerdersrechten in de lijst en selecteer deze.
5. Zoek het veld User Principal Name .
6. Gebruik het kopieerpictogram naast de waarde van het veld om het e-mailadres van de gebruiker op het klembord op te slaan. Sla de waarde op voor later gebruik.
7. Volg dezelfde stappen om het e-mailadres voor de gewone gebruiker op te halen.

Gebruik de wachtwoorden voor de gebruiker met beheerdersrechten en de gewone gebruiker die u instelt bij het maken van de gebruikers.

De functionaliteit van de app oefenen

Gebruik de volgende stappen om de functionaliteit uit te oefenen:

1. Selecteer de koppeling Aanmelden als gebruiker . Meld u aan met de gewone gebruiker die u eerder hebt gemaakt. Nadat u zich hebt aangemeld, wordt u door Microsoft Entra ID omgeleid naar de profielpagina, waar u uw naam, rollen en bereiken ziet.

   

2. Als dit de eerste keer is dat u zich aanmeldt, wordt u gevraagd uw wachtwoord bij te werken. Volg de instructies om uw wachtwoord bij te werken.

3. Als u wordt gevraagd bij Uw organisatie, zijn aanvullende beveiligingsgegevens vereist. Volg de aanwijzingen om de Microsoft Authenticator-app te downloaden en in te stellen. U kunt Vragen later selecteren om door te gaan met de test.

4. Als u wordt gevraagd om machtigingen die zijn aangevraagd, controleert u de machtigingen die door de app zijn aangevraagd. Selecteer Accepteren om door te gaan met de test.

5. Selecteer Afmelden om u af te melden bij de Quarkus-app. Microsoft Entra ID voert de afmelding uit. Nadat u zich hebt afgemeld, wordt u door Microsoft Entra ID omgeleid naar de welkomstpagina.

6. Selecteer de koppeling Aanmelden als beheerder . Microsoft Entra ID leidt u om naar de aanmeldingspagina. Meld u aan met de beheerdergebruiker die u eerder hebt gemaakt. Nadat u zich hebt aangemeld, wordt u door Microsoft Entra ID omgeleid naar de vergelijkbare profielpagina, met een andere rol admin.

   

7. Meld u opnieuw af en probeer u aan te melden als beheerder met de gewone gebruiker die u eerder hebt gemaakt. Er wordt een foutbericht weergegeven omdat de gewone gebruiker niet over de admin rol beschikt.

   

Resources opschonen

In dit artikel wordt u niet omgestuurd om uw app te implementeren in Azure. Er zijn geen Azure-resources om op te schonen voor de app, hoewel er Microsoft Entra ID-resources zijn . Als u een app in Azure wilt implementeren, kunt u de richtlijnen volgen waarnaar in de volgende sectie wordt verwezen.

Wanneer u klaar bent met de resources voor deze voorbeeld-app, gebruikt u de volgende stappen om de Microsoft Entra ID-resources op te schonen. Het verwijderen van ongebruikte Microsoft Entra ID-resources is een belangrijke aanbevolen procedure voor beveiliging.

1. Verwijder de app-registratie die u hebt gemaakt door de stappen in Een toepassing verwijderen die is geregistreerd bij het Microsoft Identity Platform. U hoeft alleen de stappen te volgen in de sectie Een toepassing verwijderen die is geschreven door uw organisatie.
2. De handeling van het verwijderen van de app-registratie moet ook de bedrijfstoepassing verwijderen. Zie Een bedrijfstoepassing verwijderen voor meer informatie over het verwijderen van bedrijfstoepassingen.
3. Verwijder de gebruikers die u hebt gemaakt door de stappen te volgen in Het maken, uitnodigen en verwijderen van gebruikers.

Volgende stappen

In deze quickstart beveiligt u Quarkus-toepassingen met Microsoft Entra ID met behulp van OpenID Connect. Bekijk de volgende bronnen voor meer informatie:

• Een Java-toepassing implementeren met Quarkus in een Azure Container Apps
• OpenID Connect-verificatie met Microsoft Entra-id
• Microsoft identity platform en OAuth 2.0-autorisatiecodestroom
• Een webtoepassing beveiligen met behulp van de autorisatiecodestroom van OpenId Connect (OIDC)
• OpenID Connect-autorisatiecodestroommechanisme voor het beveiligen van webtoepassingen
• Configuratie-eigenschappen van OpenID Connect (OIDC)