Sdílet prostřednictvím

Zabezpečení aplikací Quarkus pomocí Microsoft Entra ID pomocí OpenID Connect

  • Článek

Tento článek ukazuje, jak zabezpečit aplikace Red Hat Quarkus pomocí Microsoft Entra ID pomocí OpenID Connect (OIDC).

V tomto článku získáte informace o těchto tématech:

  • Nastavte zprostředkovatele OpenID Connect s ID Microsoft Entra.
  • Chraňte aplikaci Quarkus pomocí OpenID Connect.
  • Spusťte a otestujte aplikaci Quarkus.

Požadavky

  • Předplatné Azure. Pokud ještě nemáte předplatné Azure, vytvořte si bezplatný účet před tím, než začnete.
  • Identita Azure s alespoň rolí Microsoft Entra správce cloudových aplikací. Další informace naleznete v tématu Seznam přiřazení rolí Microsoft Entra a předdefinovaných rolí Microsoft Entra.
  • Tenant Microsoft Entra. Pokud ještě tenanta nemáte, přečtěte si článek Rychlý start: Nastavení tenanta.
  • Místní počítač s nainstalovaným operačním systémem Unix , například Ubuntu, macOS nebo Subsystém Windows pro Linux.
  • Git
  • Implementace Java SE verze 21 nebo novější – například sestavení OpenJDK od Microsoftu.
  • Maven verze 3.9.3 nebo novější.

Nastavení zprostředkovatele OpenID Connect s ID Microsoft Entra

V této části nastavíte zprostředkovatele OpenID Connect s Microsoft Entra ID pro použití s vaší aplikací Quarkus. V další části nakonfigurujete aplikaci Quarkus pomocí OpenID Connect k ověřování a autorizaci uživatelů ve vašem tenantovi Microsoft Entra.

Vytváření uživatelů v tenantovi Microsoft Entra

Nejprve ve svém tenantovi Microsoft Entra vytvořte dva uživatele pomocí postupu v tématu Vytvoření, pozvání a odstranění uživatelů. Potřebujete jenom oddíl Vytvořit nového uživatele . Při procházení článku použijte následující pokyny a po vytvoření uživatelů v tenantovi Microsoft Entra se vraťte k tomuto článku.

Pokud chcete v aplikaci vytvořit uživatele, který bude sloužit jako správce, postupujte následovně:

  1. Když se dostanete na kartu Základy v části Vytvořit nového uživatele , postupujte následovně:

    1. Jako hlavní název uživatele zadejte správce. Uložte hodnotu, abyste ji mohli později použít při přihlášení k aplikaci.

    2. V části Poštovní přezdívka vyberte Možnost Odvodit z hlavního názvu uživatele

    3. Jako zobrazované jméno zadejte správce.

    4. Jako heslo vyberte Automaticky vygenerovat heslo. Zkopírujte a uložte hodnotu Heslo , která se použije později při přihlášení k aplikaci.

    5. Vyberte Účet povolený.

      Snímek obrazovky webu Azure Portal s podoknem Základy vytvoření nového uživatele pro uživatele s rolí správce

    6. Vyberte Zkontrolovat a vytvořit>Vytvořit. Počkejte, až se uživatel vytvoří.

    7. Počkejte minutu nebo tak a vyberte Aktualizovat. V seznamu by se měl zobrazit nový uživatel.

Pokud chcete v aplikaci vytvořit uživatele, který bude sloužit jako uživatel, zopakujte tento postup, ale použijte následující hodnoty:

  • Jako hlavní název uživatele zadejte uživatele.
  • Do pole Zobrazované jméno zadejte uživatele.

Snímek obrazovky webu Azure Portal znázorňující podokno Vytvořit nového uživatele – Základy pro běžného uživatele

Registrace aplikace v Microsoft Entra ID

V dalším kroku zaregistrujte aplikaci podle kroků v rychlém startu: Registrace aplikace na platformě Microsoft Identity Platform. Při procházení článku použijte následující pokyny a po registraci a konfiguraci aplikace se vraťte k tomuto článku.

  1. Když se dostanete do části Registrace aplikace , postupujte následovně:
    1. U podporovaných typů účtů vyberte Pouze účty v tomto adresáři organizace (pouze výchozí adresář – Jeden tenant).
    2. Po dokončení registrace uložte hodnoty ID aplikace (klienta) a ID adresáře (tenanta) pro pozdější použití v konfiguraci aplikace.
  2. Až se dostanete do části Přidat identifikátor URI přesměrování, přeskočte kroky, jak je vidět. Identifikátor URI přesměrování přidáte později při spuštění a otestování ukázkové aplikace místně v tomto článku.
  3. Když se dostanete do části Přidat přihlašovací údaje , vyberte kartu Přidat tajný klíč klienta.
  4. Když přidáte tajný klíč klienta, poznamenejte si hodnotu tajného klíče klienta, která se použije později v konfiguraci aplikace.

Přidání aplikačních rolí do aplikace

Potom do aplikace přidejte role aplikace pomocí postupu v části Přidání rolí aplikace do aplikace a jejich přijetí v tokenu. Potřebujete jenom oddíly Deklarovat role pro aplikaci a přiřadit uživatele a skupiny k rolím Microsoft Entra. Při procházení článku použijte následující pokyny a po deklarování rolí pro aplikaci se vraťte k tomuto článku.

  1. Když se dostanete k části Deklarace rolí pro aplikaci , použijte uživatelské rozhraní role aplikace k vytvoření rolí pro správce a běžného uživatele.

    1. Pomocí následujících hodnot vytvořte roli uživatele správce:

      • Jako zobrazované jméno zadejte správce.
      • V seznamu Povolené typy členů vyberte Uživatelé/skupiny.
      • Jako hodnotu zadejte správce.
      • Jako popis zadejte správce.
      • Vyberte Chcete povolit tuto roli aplikace?

      Snímek obrazovky webu Azure Portal s podoknem Vytvořit roli aplikace pro uživatele s rolí správce

    2. Vyberte Použít. Počkejte, až se role vytvoří.

    3. Pomocí stejných kroků vytvořte běžnou roli uživatele, ale s následujícími hodnotami:

      • Do pole Zobrazované jméno zadejte uživatele.
      • Do pole Hodnota zadejte uživatele.
      • Jako popis zadejte uživatele.

      Snímek obrazovky webu Azure Portal znázorňující podokno Vytvořit roli aplikace pro běžného uživatele

  2. Když se dostanete k rolím Přiřadit uživatele a skupiny k rolím Microsoft Entra, postupujte následovně:

    1. Vyberte Přidat uživatele nebo skupinu.

    2. V podokně Přidat přiřazení v části Uživatelé vyberte správce uživatele a jako možnost Vybrat roli vyberte Správce role. Pak vyberte Přiřadit. Počkejte, až přiřazení aplikace proběhne úspěšně. Možná budete muset posunout tabulku bokem, abyste viděli sloupec přiřazený rolím.

    3. Opakováním předchozích kroků přiřaďte roli Uživatele uživateli.

    4. Vyberte Aktualizovat a měli byste vidět uživatele a role přiřazené v podokně Uživatelé a skupiny .

      Snímek obrazovky webu Azure Portal s přiřazenými uživateli a rolemi

      Možná budete muset upravit šířku záhlaví sloupců, aby zobrazení vypadalo jako obrázek.

Nepoužívejte žádné další kroky v části Přidání rolí aplikace do aplikace a jejich příjem v tokenu.

Ochrana aplikace Quarkus pomocí OpenID Connect

V této části zabezpečíte aplikaci Quarkus, která ověřuje a autorizuje uživatele ve vašem tenantovi Microsoft Entra pomocí OpenID Connect. Dozvíte se také, jak uživatelům udělit přístup k určitým částem aplikace pomocí řízení přístupu na základě role (RBAC).

Ukázková aplikace Quarkus pro tento rychlý start je na GitHubu v úložišti quarkus-azure a nachází se v adresáři entra-id-quarkus .

Povolení ověřování a autorizace pro zabezpečení aplikace

Aplikace má prostředek úvodní stránky definovaný v WelcomePage.java, který je zobrazený v následujícím ukázkovém kódu. Tato stránka je přístupná pro neověřené uživatele. Kořenová cesta úvodní stránky je na /adrese .

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

}

Na úvodní stránce se uživatelé můžou přihlásit k aplikaci, aby mohli získat přístup ke stránce profilu. Úvodní stránka obsahuje odkazy na přihlášení jako uživatel nebo jako správce. Odkazy jsou na /profile/user adrese a /profile/adminv uvedeném pořadí. Uživatelské rozhraní úvodní stránky je definováno v welcome.qute.html a je znázorněno v následujícím příkladu:

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

Odkazy /profile/user ukazují /profile/admin na prostředek stránky profilu definovaný v ProfilePage.java, jak je znázorněno v následujícím ukázkovém kódu. Tato stránka je přístupná pouze ověřeným uživatelům pomocí poznámky @RolesAllowed("**")jakarta.annotation.security.RolesAllowed z balíčku. Poznámka @RolesAllowed("**") určuje, že k cestě /profile mají přístup pouze ověření uživatelé.

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

}

Prostředek stránky profilu umožňuje RBAC pomocí poznámky @RolesAllowed . Argumenty poznámky @RolesAllowed určují, že k cestě mají přístup admin jenom uživatelé s /profile/admin rolí a uživatelé s useradmin touto rolí mají přístup k cestě/profile/user.

/profile/admin Stránka profilu i /profile/user koncové body vrátí. Uživatelské rozhraní stránky profilu je definováno v profile.qute.html, jak je znázorněno v následujícím příkladu. Na této stránce se zobrazí jméno, role a obory uživatele. Stránka profilu má také odkaz na /logoutodhlášení , který přesměruje uživatele na poskytovatele OIDC, aby se odhlasil. Stránka profilu se zapisuje pomocí modulu šablon Qute. Všimněte si použití {} výrazů na stránce. Tyto výrazy používají hodnoty předané TemplateInstance metodě data() . Další informace o qute naleznete v tématu Modul šablon 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>

Po odhlášení se uživatel přesměruje na úvodní stránku a může se znovu přihlásit.

Spuštění a otestování aplikace Quarkus

V této části spustíte a otestujete aplikaci Quarkus, abyste zjistili, jak funguje s ID Microsoft Entra jako poskytovatele OpenID Connect.

Přidání identifikátoru URI přesměrování do registrace aplikace

Pokud chcete aplikaci úspěšně spustit a otestovat místně, musíte do registrace aplikace přidat identifikátor URI přesměrování. Postupujte podle pokynů v části Rychlý start Pro přidání identifikátoru URI přesměrování: Zaregistrujte aplikaci na platformě Microsoft Identity Platform a použijte následující hodnoty:

  • Pro konfiguraci platforem vyberte Web.
  • Pro identifikátory URI pro přesměrování zadejte http://localhost:8080.

Příprava ukázky

Pomocí následujících kroků připravte ukázkovou aplikaci Quarkus:

  1. Pomocí následujících příkazů naklonujte ukázkovou aplikaci Quarkus z GitHubu a přejděte do adresáře entra-id-quarkus:

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

    Pokud se zobrazí zpráva o tom, že je v odpojeném stavu HEAD , je tato zpráva v bezpečí ignorovat. Vzhledem k tomu, že tento článek nevyžaduje potvrzení, je vhodné odpojit stav HEAD.

  2. Pomocí následujících příkazů definujte následující proměnné prostředí s hodnotami, které jste si napsali dříve:

    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

    Tyto proměnné prostředí poskytují hodnoty pro integrovanou podporu OpenID Connect v Quarkus. Odpovídající vlastnosti jsou application.properties uvedeny v následujícím příkladu.

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

    Pokud je hodnota vlastnosti prázdná v application.properties, Quarkus převede název vlastnosti na proměnnou prostředí a přečte hodnotu z prostředí. Podrobnosti o převodu názvů najdete ve specifikaci konfigurace MicroProfile.

Spuštění aplikace Quarkus

Aplikaci Quarkus můžete spustit v různých režimech. Vyberte jednu z následujících metod pro spuštění aplikace Quarkus. Pokud chcete, aby se Quarkus mohl připojit k Microsoft Entra ID, spusťte příkaz v prostředí, ve kterém jste definovali proměnné prostředí uvedené v předchozí části.

  • Spusťte aplikaci Quarkus ve vývojovém režimu:

    mvn quarkus:dev

  • Spusťte aplikaci Quarkus v režimu JVM:

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

  • Spusťte aplikaci Quarkus v nativním režimu:

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

Pokud chcete vyzkoušet různé režimy, pomocí ctrl+C zastavte aplikaci Quarkus a pak spusťte aplikaci Quarkus v jiném režimu.

Testování aplikace Quarkus

Po spuštění aplikace Quarkus otevřete webový prohlížeč s privátní kartou a přejděte na http://localhost:8080. Měla by se zobrazit úvodní stránka s odkazy pro přihlášení jako uživatel nebo jako správce. Použití soukromé karty zabraňuje znečisťování stávající aktivity Microsoft Entra ID, které můžete mít v běžném prohlížeči.

Snímek obrazovky ukázkové aplikace, která zobrazuje úvodní stránku

Shromáždění přihlašovacích údajů pro dva uživatele

V tomto článku používá Microsoft Entra ID e-mailovou adresu každého uživatele jako ID uživatele pro přihlášení. Pomocí následujícího postupu získejte e-mailovou adresu uživatele s rolí správce a běžného uživatele:

  1. Přihlaste se do Centra pro správu Microsoft Entra jako alespoň správce cloudových aplikací.
  2. Pokud máte přístup k více tenantům, pomocí ikony Nastavení () v horní nabídce přepněte na tenanta, ve kterém chcete aplikaci zaregistrovat z nabídky Adresáře a předplatná.
  3. Přejděte k identitě > Uživatelé > všichni uživatelé.
  4. Vyhledejte uživatele správce v seznamu a vyberte ho.
  5. Vyhledejte pole Hlavní název uživatele.
  6. Pomocí ikony kopírování vedle hodnoty pole uložte e-mailovou adresu uživatele do schránky. Uložte hodnotu pro pozdější použití.
  7. Pokud chcete získat e-mailovou adresu pro běžného uživatele, postupujte stejně.

Použijte hesla pro uživatele správce a běžného uživatele, který jste nastavili při vytváření uživatelů.

Cvičení funkcí aplikace

Pomocí následujících kroků procvičte funkčnost:

  1. Vyberte odkaz Přihlásit se jako uživatel. Přihlaste se pomocí běžného uživatele, který jste vytvořili dříve. Po přihlášení vás Microsoft Entra ID přesměruje na stránku profilu, kde se zobrazí vaše jméno, role a obory.

    Snímek obrazovky ukázkové aplikace, která zobrazuje profil uživatele

  2. Pokud se přihlašujete poprvé, zobrazí se výzva k aktualizaci hesla. Podle pokynů aktualizujte heslo.

  3. Pokud se zobrazí výzva k zadání informací o zabezpečení ve vaší organizaci, potřebujete další informace o zabezpečení. Postupujte podle pokynů a stáhněte a nastavte aplikaci Microsoft Authenticator a pokračujte v testování výběrem možnosti Požádat později .

  4. Pokud se zobrazí výzva s požadovanými oprávněními, zkontrolujte oprávnění požadovaná aplikací. Výběrem možnosti Přijmout pokračujte v testu.

  5. Pokud se chcete odhlásit z aplikace Quarkus, vyberte Odhlásit se. Id Microsoft Entra provede odhlášení. Po odhlášení vás Microsoft Entra ID přesměruje na úvodní stránku.

  6. Vyberte odkaz Přihlásit se jako správce. Microsoft Entra ID vás přesměruje na přihlašovací stránku. Přihlaste se pomocí uživatele správce, který jste vytvořili dříve. Po přihlášení vás Microsoft Entra ID přesměruje na podobnou stránku profilu s jinou rolí admin.

    Snímek obrazovky s ukázkovou aplikací, která zobrazuje profil správce

  7. Znovu se odhlaste a zkuste se přihlásit jako správce s běžným uživatelem, který jste vytvořili dříve. Měla by se zobrazit chybová zpráva, protože běžný uživatel tuto roli nemá admin .

    Snímek obrazovky ukázkové aplikace, která zobrazuje zprávu o odepření přístupu

Vyčištění prostředků

Tento článek vás nesměruje na nasazení aplikace v Azure. Pro aplikaci se nedají vyčistit žádné prostředky Azure, i když existují prostředky Microsoft Entra ID. Pokud chcete nasadit aplikaci v Azure, můžete postupovat podle pokynů uvedených v další části.

Jakmile dokončíte prostředky pro tuto ukázkovou aplikaci, pomocí následujících kroků vyčistíte prostředky Microsoft Entra ID. Odebrání nepoužívaných prostředků Microsoft Entra ID je důležitým osvědčeným postupem zabezpečení.

  1. Odeberte registraci aplikace, kterou jste vytvořili, podle kroků v části Odebrání aplikace zaregistrované na platformě Microsoft Identity Platform. Stačí postupovat podle kroků v části Odebrání aplikace vytvořené vaší organizací.
  2. Odebrání registrace aplikace by také mělo odstranit podnikovou aplikaci. Další informace o odstraňování podnikových aplikací najdete v tématu Odstranění podnikové aplikace.
  3. Odstraňte uživatele, které jste vytvořili, podle pokynů v tématu Vytvoření, pozvání a odstranění uživatelů.

Další kroky

V tomto rychlém startu chráníte aplikace Quarkus pomocí Microsoft Entra ID pomocí OpenID Connect. Další informace najdete v následujících zdrojích informací: