Skydda Quarkus-program med Microsoft Entra-ID med OpenID Connect

2024-10-07

Den här artikeln visar hur du skyddar Red Hat Quarkus-program med Microsoft Entra-ID med Hjälp av OpenID Connect (OIDC).

I den här artikeln kan du se hur du:

Konfigurera en OpenID Connect-provider med Microsoft Entra-ID.
Skydda en Quarkus-app med hjälp av OpenID Connect.
Kör och testa Quarkus-appen.

Förutsättningar

En Azure-prenumeration. Om du inte har en Azure-prenumeration kan du skapa ettkostnadsfritt konto innan du börjar.
En Azure-identitet med minst rollen Molnprogramadministratör Microsoft Entra. Mer information finns i Lista microsoft entra-rolltilldelningar och inbyggda Microsoft Entra-roller.
En Microsoft Entra-klientorganisation. Om du inte har någon befintlig klient kan du läsa Snabbstart: Konfigurera en klientorganisation.
En lokal dator med ett Unix-liknande operativsystem installerat , till exempel Ubuntu, macOS eller Windows-undersystem för Linux.
Git.
En Java SE-implementering, version 21 eller senare – till exempel Microsoft-versionen av OpenJDK.
Maven, version 3.9.3 eller senare.

Konfigurera en OpenID Connect-provider med Microsoft Entra-ID

I det här avsnittet konfigurerar du en OpenID Connect-provider med Microsoft Entra-ID för användning med din Quarkus-app. I ett senare avsnitt konfigurerar du Quarkus-appen med hjälp av OpenID Connect för att autentisera och auktorisera användare i din Microsoft Entra-klientorganisation.

Skapa användare i Microsoft Entra-klientorganisationen

Skapa först två användare i din Microsoft Entra-klient genom att följa stegen i Skapa, bjuda in och ta bort användare. Du behöver bara avsnittet Skapa en ny användare . Använd följande anvisningar när du går igenom artikeln och gå sedan tillbaka till den här artikeln när du har skapat användare i din Microsoft Entra-klientorganisation.

Använd följande steg för att skapa en användare som ska fungera som "administratör" i appen:

När du kommer till fliken Grundläggande i avsnittet Skapa en ny användare använder du följande steg:
1. För Användarens huvudnamn anger du administratör. Spara värdet så att du kan använda det senare när du loggar in på appen.
2. För E-post smeknamn väljer du Härled från användarens huvudnamn
3. Som Visningsnamn anger du Admin.
4. Som Lösenord väljer du Generera lösenord automatiskt. Kopiera och spara värdet Lösenord som ska användas senare när du loggar in på appen.
5. Välj Konto aktiverat.
6. Välj Granska + skapa>Skapa. Vänta tills användaren har skapats.
7. Vänta en minut eller så och välj Uppdatera. Du bör se den nya användaren i listan.

Om du vill skapa en användare som ska fungera som en "användare" i appen upprepar du de här stegen, men använder följande värden:

För Användarens huvudnamn anger du användaren.
Som Visningsnamn anger du Användare.

Registrera ett program i Microsoft Entra-ID

Registrera sedan ett program genom att följa stegen i Snabbstart: Registrera ett program med Microsofts identitetsplattform. Använd följande anvisningar när du går igenom artikeln och gå sedan tillbaka till den här artikeln när du har registrerat och konfigurerat programmet.

När du kommer till avsnittet Registrera ett program använder du följande steg:
1. För Kontotyper som stöds väljer du Endast Konton i den här organisationskatalogen (endast standardkatalog – enskild klient).
2. När registreringen är klar sparar du värdena program-ID och katalog-ID (klientorganisation) som ska användas senare i appkonfigurationen.
När du kommer till avsnittet Lägg till en omdirigerings-URI hoppar du över stegen som för tillfället. Du lägger till omdirigerings-URI:n senare när du kör och testar exempelappen lokalt i den här artikeln.
När du kommer till avsnittet Lägg till autentiseringsuppgifter väljer du fliken Lägg till en klienthemlighet .
När du lägger till en klienthemlighet skriver du ned värdet Klienthemlighet som ska användas senare i appkonfigurationen.

Lägga till approller i ditt program

Lägg sedan till approller i ditt program genom att följa stegen i Lägg till approller i ditt program och ta emot dem i token. Du behöver bara avsnitten Deklarera roller för ett program och Tilldela användare och grupper till Microsoft Entra-roller. Använd följande anvisningar när du går igenom artikeln och gå sedan tillbaka till den här artikeln när du har deklarerat roller för programmet.

När du når avsnittet Deklarera roller för ett program använder du användargränssnittet för approller för att skapa roller för administratören och den vanliga användaren.
1. Skapa en administratörsanvändarroll med hjälp av följande värden:
  - Som Visningsnamn anger du Admin.
  - För Tillåtna medlemstyper väljer du Användare/grupper.
  - För Värde anger du administratör.
  - Som Beskrivning anger du Admin.
  - Välj Vill du aktivera den här approllen?.
2. Välj Använd. Vänta tills rollen har skapats.
3. Skapa en vanlig användarroll med hjälp av samma steg, men med följande värden:
  - Som Visningsnamn anger du Användare.
  - För Värde anger du användare.
  - Som Beskrivning anger du Användare.
När du når avsnittet Tilldela användare och grupper till Microsoft Entra-roller använder du följande steg:
1. Välj Lägg till användare/grupp.
2. I fönstret Lägg till tilldelning för Användare väljer du Användaradministratör och för Välj en roll väljer du rolladministratör. Välj sedan Tilldela. Vänta tills programtilldelningen har slutförts. Du kan behöva rulla tabellen i sidled för att se kolumnen Rolltilldelad .
3. Upprepa föregående steg för att tilldela användarrollen till användaren Användare.
4. Välj Uppdatera så bör du se de användare och roller som tilldelats i fönstret Användare och grupper .
  
  Du kan behöva justera bredden på kolumnrubrikerna så att vyn ser ut som bilden.

Följ inte några andra steg i Lägg till approller i ditt program och ta emot dem i token.

Skydda en Quarkus-app med hjälp av OpenID Connect

I det här avsnittet skyddar du en Quarkus-app som autentiserar och auktoriserar användare i din Microsoft Entra-klientorganisation med hjälp av OpenID Connect. Du får också lära dig hur du ger användarna åtkomst till vissa delar av appen med hjälp av rollbaserad åtkomstkontroll (RBAC).

Quarkus-exempelappen för den här snabbstarten finns på GitHub på lagringsplatsen quarkus-azure och finns i katalogen entra-id-quarkus.

Aktivera autentisering och auktorisering för att skydda appen

Appen har en välkomstsida som definierats i WelcomePage.java, som visas i följande exempelkod. Den här sidan är tillgänglig för oautentiserade användare. Rotsökvägen till välkomstsidan finns på /.

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

}

Från välkomstsidan kan användare logga in på appen för att komma åt profilsidan. Välkomstsidan har länkar för att logga in som användare eller administratör. Länkarna finns på /profile/user respektive /profile/admin. Användargränssnittet för välkomstsidan definieras i welcome.qute.html och visas i följande exempel:

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

Både /profile/user och /profile/admin länkar pekar på profilsidans resurs, definierad i ProfilePage.java, enligt följande exempelkod. Den här sidan är endast tillgänglig för autentiserade användare med hjälp av kommentaren @RolesAllowed("**")jakarta.annotation.security.RolesAllowed från paketet. Kommentaren @RolesAllowed("**") anger att endast autentiserade /profile användare kan komma åt sökvägen.

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

}

Profilsidans resurs aktiverar RBAC med hjälp av anteckningen @RolesAllowed . Argumenten i kommentaren @RolesAllowed anger att endast användare med admin rollen kan komma åt /profile/admin sökvägen och att användare med user rollen eller admin kan komma åt /profile/user sökvägen.

Både slutpunkterna /profile/admin och /profile/user returnerar profilsidan. Användargränssnittet för profilsidan definieras i profile.qute.html, enligt följande exempel. På den här sidan visas användarens namn, roller och omfång. Profilsidan har också en utloggningslänk på /logout, som omdirigerar användaren till OIDC-providern för att logga ut. Profilsidan skrivs med hjälp av Qute-mallmotorn. Observera användningen av {} uttryck på sidan. Dessa uttryck använder de värden som skickas TemplateInstance till med hjälp av data() metoden. Mer information om Qute finns i Qute-templatingmotorn.

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

Efter utloggningen omdirigeras användaren till välkomstsidan och kan logga in igen.

Köra och testa Quarkus-appen

I det här avsnittet kör och testar du Quarkus-appen för att se hur den fungerar med Microsoft Entra ID som OpenID Connect-provider.

Lägga till en omdirigerings-URI i appregistreringen

Om du vill köra och testa appen lokalt måste du lägga till en omdirigerings-URI i appregistreringen. Följ anvisningarna i avsnittet Lägg till en omdirigerings-URI i Snabbstart: Registrera ett program med Microsofts identitetsplattform och använd följande värden:

För Konfigurera plattformar väljer du Webb.
För omdirigerings-URI:er anger du http://localhost:8080.

Förbereda exemplet

Använd följande steg för att förbereda Quarkus-exempelappen:

Använd följande kommandon för att klona Quarkus-exempelappen från GitHub och navigera till katalogen entra-id-quarkus:
```
git clone https://github.com/Azure-Samples/quarkus-azure
cd quarkus-azure/entra-id-quarkus
git checkout 2024-09-26
```
Om du ser ett meddelande om att vara i frånkopplat HEAD-tillstånd är det här meddelandet säkert att ignorera. Eftersom den här artikeln inte kräver några incheckningar är frånkopplat HEAD-tillstånd lämpligt.
Använd följande kommandon för att definiera följande miljövariabler med de värden som du skrev ned tidigare:
```
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
```
Dessa miljövariabler ger värdena för det inbyggda stödet för OpenID Connect i Quarkus. Motsvarande egenskaper i application.properties visas i följande exempel.
```
quarkus.oidc.client-id=
quarkus.oidc.credentials.secret=
quarkus.oidc.auth-server-url=
```
Om värdet för en egenskap är tomt i application.propertieskonverterar Quarkus egenskapsnamnet till en miljövariabel och läser värdet från miljön. Mer information om namngivningskonverteringen finns i MicroProfile Config-specifikationen.

Kör Quarkus-appen

Du kan köra Quarkus-appen i olika lägen. Välj någon av följande metoder för att köra Quarkus-appen. Om du vill göra det möjligt för Quarkus att ansluta till Microsoft Entra-ID ska du köra kommandot i gränssnittet där du definierade miljövariablerna som visas i föregående avsnitt.

Kör Quarkus-appen i utvecklingsläge:
```
mvn quarkus:dev
```

Kör Quarkus-appen i JVM-läge:

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

Kör Quarkus-appen i internt läge:

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

Om du vill prova olika lägen använder du Ctrl+C för att stoppa Quarkus-appen och kör sedan Quarkus-appen i ett annat läge.

Testa Quarkus-appen

När Quarkus-appen har körts öppnar du en webbläsare med en privat flik och navigerar till http://localhost:8080. Du bör se välkomstsidan med länkar för att logga in som användare eller administratör. Om du använder en privat flik kan du undvika att förorena befintliga Microsoft Entra-ID-aktiviteter som du kan ha i din vanliga webbläsare.

Samla in autentiseringsuppgifterna för de två användarna

I den här artikeln använder Microsoft Entra-ID:t varje användares e-postadress som användar-ID för inloggning. Använd följande steg för att hämta e-postadressen för administratörsanvändaren och den vanliga användaren:

Logga in på administrationscentret för Microsoft Entra som minst molnprogramadministratör.
Om du har åtkomst till flera klienter använder du ikonen Inställningar ( ) på den översta menyn för att växla till den klientorganisation där du vill registrera programmet från menyn Kataloger + prenumerationer.
Bläddra till Identitetsanvändare >> Alla användare.
Leta upp administratörsanvändaren i listan och välj den.
Leta upp fältet Användarens huvudnamn .
Använd kopieringsikonen bredvid värdet för fältet för att spara användarens e-postadress i Urklipp. Spara värdet för senare användning.
Följ samma steg för att hämta e-postadressen för den vanliga användaren.

Använd lösenorden för administratörsanvändaren och den vanliga användare som du anger när du skapar användarna.

Använda appens funktioner

Använd följande steg för att använda funktionerna:

Välj länken Logga in som användare. Logga in med den vanliga användare som du skapade tidigare. När du har loggat in omdirigerar Microsoft Entra-ID dig till profilsidan, där du ser ditt namn, dina roller och omfång.
Om det är första gången du loggar in uppmanas du att uppdatera lösenordet. Följ anvisningarna för att uppdatera lösenordet.
Om du uppmanas med Din organisation krävs ytterligare säkerhetsinformation. Följ anvisningarna för att ladda ned och konfigurera Microsoft Authenticator-appen. Du kan välja Be senare om du vill fortsätta testet.
Om du uppmanas med begärda behörigheter granskar du de behörigheter som begärs av appen. Välj Acceptera för att fortsätta testet.
Välj Logga ut för att logga ut från Quarkus-appen. Microsoft Entra ID utför utloggningen. När du har loggat ut omdirigerar Microsoft Entra ID dig till välkomstsidan.
Välj länken Logga in som administratör. Microsoft Entra ID omdirigerar dig till inloggningssidan. Logga in med administratörsanvändaren som du skapade tidigare. När du har loggat in omdirigerar Microsoft Entra-ID dig till liknande profilsida med en annan roll admin.
Logga ut igen och försök logga in som administratör med den vanliga användare som du skapade tidigare. Du bör se ett felmeddelande eftersom den vanliga användaren inte har rollen admin .

Rensa resurser

Den här artikeln instruerar dig inte att distribuera din app i Azure. Det finns inga Azure-resurser att rensa för appen, även om det finns Microsoft Entra-ID-resurser. Om du vill distribuera en app i Azure kan du följa de riktlinjer som beskrivs i nästa avsnitt.

När du är klar med resurserna för den här exempelappen använder du följande steg för att rensa Microsoft Entra-ID-resurserna. Det är viktigt att ta bort oanvända Microsoft Entra-ID-resurser.

Ta bort appregistreringen som du skapade genom att följa stegen i Ta bort ett program som registrerats med Microsofts identitetsplattform. Du behöver bara följa stegen i avsnittet Ta bort ett program som skapats av din organisation.
Åtgärden att ta bort appregistreringen bör också ta bort företagsappen. Mer information om hur du tar bort företagsprogram finns i Ta bort ett företagsprogram.
Ta bort de användare som du skapade genom att följa stegen i Skapa, bjuda in och ta bort användare.

Nästa steg

I den här snabbstarten skyddar du Quarkus-program med Microsoft Entra-ID med OpenID Connect. Mer information finns i följande resurser:

Feedback

Var den här sidan till hjälp?