Sichern von Quarkus-Anwendungen mit Microsoft Entra ID mithilfe von OpenID Connect

Artikel
10/07/2024

In diesem Artikel erfahren Sie, wie Sie Red Hat Quarkus-Anwendungen mit Microsoft Entra ID mithilfe von OpenID Connect (OIDC) sichern.

In diesem Artikel werden folgende Vorgehensweisen behandelt:

Richten Sie einen OpenID Connect-Anbieter mit Microsoft Entra ID ein.
Schützen Sie eine Quarkus-App mithilfe von OpenID Connect.
Führen Sie die Quarkus-App aus, und testen Sie sie.

Voraussetzungen

Ein Azure-Abonnement. Wenn Sie kein Azure-Abonnement besitzen, erstellen Sie ein kostenloses Konto, bevor Sie beginnen.
Eine Azure-Identität mit mindestens der Microsoft Entra-Rolle „Cloudanwendungsadministrator“. Weitere Informationen finden Sie unter Auflisten von Microsoft Entra-Rollenzuweisungen und Integrierte Microsoft Entra-Rollen.
Ein Microsoft Entra-Mandant. Wenn Sie nicht über einen vorhandenen Mandanten verfügen, lesen Sie Schnellstart: Einrichten eines Mandanten.
Ein lokaler Computer mit einem installierten UNIX-ähnlichen Betriebssystem (z. B. Ubuntu, macOS, Windows-Subsystem für Linux).
Git.
Eine Java SE-Implementierung, Version 21 oder höher, z. B. der Microsoft-Build von OpenJDK.
Maven, Version 3.9.3 oder höher.

Einrichten eines OpenID Connect-Anbieters mit Microsoft Entra ID

In diesem Abschnitt richten Sie einen OpenID Connect-Anbieter mit Microsoft Entra ID für die Verwendung mit Ihrer Quarkus-App ein. In einem späteren Abschnitt konfigurieren Sie die Quarkus-App mithilfe von OpenID Connect, um Benutzer in Ihrem Microsoft Entra-Mandanten zu authentifizieren und zu autorisieren.

Erstellen voon Benutzern im Microsoft Entra-Mandanten

Erstellen Sie zunächst zwei Benutzer in Ihrem Microsoft Entra-Mandanten, indem Sie die Schritte zum Erstellen, Einladen und Löschen von Benutzern ausführen. Sie benötigen lediglich den Abschnitt Neuen Benutzer erstellen. Verwenden Sie die folgenden Anweisungen, während Sie den Artikel durchgehen, und kehren Sie dann zu diesem Artikel zurück, nachdem Sie Benutzer in Ihrem Microsoft Entra-Mandanten erstellt haben.

Führen Sie die folgenden Schritte aus, um einen Benutzer als „Administrator“ in der App zu erstellen:

Wenn Sie die Registerkarte Grundlagen im Abschnitt Einen neuen Benutzer erstellen erreicht haben, gehen Sie wie folgt vor:
1. Geben Sie unter Benutzerprinzipalname die Zeichenfolge admin ein. Speichern Sie den Wert, damit Sie ihn später für die Anmeldung bei der App verwenden können.
2. Bei E-Mail-Spitznamen wählen Sie Vom Benutzerprinzipalnamen ableiten aus.
3. Geben Sie Admin für Anzeigename ein.
4. Wählen Sie für Kennwort Kennwort automatisch generieren aus. Kopieren und speichern Sie den Wert für Kennwort zur späteren Verwendung bei der Anmeldung bei der App.
5. Wählen Sie Konto aktiviert aus.
6. Wählen Sie Bewerten + erstellen>Erstellen aus. Warten Sie, bis der Benutzer erstellt wurde.
7. Warten Sie etwa eine Minute, und wählen Sie Aktualisieren aus. Der neue Benutzer sollte in der Liste angezeigt werden.

Wenn Sie einen Benutzer erstellen möchten, der in der App als „Benutzer“ fungiert, wiederholen Sie diese Schritte, verwenden Sie dabei jedoch die folgenden Werte:

Geben Sie für Benutzerprinzipalname Benutzer ein.
Geben Sie für Anzeigename Benutzer ein.

Registrieren einer Anwendung in Microsoft Entra ID

Registrieren Sie dann eine Anwendung gemäß der Anleitung unter Schnellstart: Registrieren einer Anwendung mit der Microsoft Identity-Plattform. Befolgen Sie die folgenden Anweisungen, während Sie den Artikel durchgehen, kehren Sie nach der Registrierung zu diesem Artikel zurück, und konfigurieren Sie die Anwendung.

Wenn Sie den Abschnitt Registrieren einer Anwendung erreichen, gehen Sie wie folgt vor:
1. Wählen Sie für Unterstützte Kontotypen Nur Konten in diesem Organisationsverzeichnis (nur Standardverzeichnis – einzelner Mandant).
2. Wenn die Registrierung abgeschlossen ist, speichern Sie die Werte für Anwendungs-ID (Client) und Verzeichnis-ID (Mandant) zur späteren Verwendung in der App-Konfiguration.
Wenn Sie den Abschnitt Hinzufügen eines Umleitungs-URI erreichen, überspringen Sie die Schritte vorerst. Sie fügen den Umleitungs-URI später hinzu, wenn Sie die Beispiel-App in diesem Artikel lokal ausführen und testen.
Wenn Sie den Abschnitt Anmeldeinformationen hinzufügen erreichen, wählen Sie die Registerkarte Geheimen Clientschlüssel hinzufügen aus.
Wenn Sie einen geheimen Clientschlüssel hinzufügen, notieren Sie sich den Wert für Geheimer Clientschlüssel zur späteren Verwendung in der App-Konfiguration.

Hinzufügen von App-Rollen zu Ihrer Anwendung

Fügen Sie dann Ihrer Anwendung App-Rollen hinzu, indem Sie die Schritte unter Hinzufügen von App-Rollen zu Ihrer Anwendung" ausführen und diese im Token befolgen. Sie benötigen lediglich die Abschnitte Deklarieren von Rollen für eine Anwendung und Zuweisen von Benutzern und Gruppen zu Microsoft Entra-Rollen. Befolgen Sie die folgenden Anweisungen, während Sie den Artikel durchgehen, und kehren Sie nach dem Deklarieren der Rollen für die Anwendung zu diesem Artikel zurück.

Wenn Sie den Abschnitt Deklarieren von Rollen für eine Anwendung erreichen, verwenden Sie die App-Rollen-UI zum Erstellen von Rollen für den Administrator und den regulären Benutzer.
1. Erstellen Sie mithilfe der folgenden Werte eine Administratorbenutzerrolle:
  - Geben Sie Admin für Anzeigename ein.
  - Wählen Sie für Zugelassene Mitgliedertypen Benutzer/Gruppen aus.
  - Geben Sie in Wert den Wert admin ein.
  - Geben Sie für Beschreibung Admin ein.
  - Wählen Sie Möchten Sie diese App-Rolle aktivieren?
2. Wählen Sie Übernehmen. Warten Sie, bis die Rolle erstellt wurde.
3. Erstellen Sie die Rolle eines regulären Benutzers mithilfe der gleichen Schritte, aber mit den folgenden Werten:
  - Geben Sie für Anzeigename Benutzer ein.
  - Geben Sie für Wert Benutzer ein.
  - Geben Sie für Beschreibung Benutzer ein.
Wenn Sie den Abschnitt Benutzer und Gruppen für Microsoft Entra zuweisen erreichen, gehen Sie wie folgt vor:
1. Wählen Sie Benutzer/Gruppe hinzufügen aus.
2. Wählen Sie im Bereich Zuweisung hinzufügen für Benutzer den Benutzer Admin, und wählen Sie für Rolle auswählen die Rolle Admin. Wählen Sie dann Zuweisen aus. Warten Sie, bis die Anwendungszuweisung erfolgreich ist. Möglicherweise müssen Sie in der Tabelle seitwärts scrollen, um die Spalte Rolle zugewiesen anzuzeigen.
3. Wiederholen Sie die vorherigen Schritte, um die Rolle Benutzer dem Benutzer Benutzer zuzuweisen.
4. Wählen Sie Aktualisieren aus. Sie sollten jetzt im Bereich Benutzer und Gruppen die zugewiesenen Benutzer und Rollen sehen.
  
  Möglicherweise müssen Sie die Breite der Spaltenüberschriften anpassen, damit die Ansicht wie das Bild aussieht.

Befolgen Sie keine der weiteren Schritte unter Hinzufügen von App-Rollen zu Ihrer Anwendung und Empfangen der Rollen im Token.

Schützen einer Quarkus-App mithilfe von OpenID Connect

In diesem Abschnitt sichern Sie eine Quarkus-App, die Benutzer in Ihrem Microsoft Entra-Mandanten mithilfe von OpenID Connect authentifiziert und autorisiert. Außerdem erfahren Sie, wie Sie Benutzern mithilfe der rollenbasierten Zugriffssteuerung (RBAC) Zugriff auf bestimmte Teile der App gewähren.

Die Beispiel-Quarkus-App für diese Schnellstartanleitung befindet sich auf GitHub im Repository quarkus-azure im Verzeichnis entra-id-quarkus.

Aktivieren der Authentifizierung und Autorisierung zum Schutz einer App

Die App verfügt über eine Begrüßungsseitenressource, die in WelcomePage.java definiert ist und im folgenden Beispielcode dargestellt wird. Diese Seite ist für nicht authentifizierte Benutzer zugänglich. Der Stammpfad der Begrüßungsseite befindet sich unter /.

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

}

Auf der Begrüßungsseite können sich Benutzer bei der App anmelden, um auf die Profilseite zuzugreifen. Die Begrüßungsseite enthält Links zum Anmelden als Benutzer oder als Administrator. Die Links befinden unter /profile/user und /profile/admin. Die Benutzeroberfläche der Begrüßungsseite ist in welcome.qute.html definiert und im folgenden Beispiel dargestellt:

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

Die Links /profile/user und /profile/admin führen zur Profilseitenressource, definiert unter ProfilePage.java, wie im folgenden Beispielcode illustriert. Auf diese Seite können nur authentifizierte Benutzer über die @RolesAllowed("**") Anmerkung aus dem jakarta.annotation.security.RolesAllowed-Paket zugreifen. Die @RolesAllowed("**")-Anmerkung gibt an, dass nur authentifizierte Benutzer auf den /profile-Pfad zugreifen können.

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

}

Die Profilseitenressource ermöglicht RBAC mithilfe der @RolesAllowed-Anmerkung. Die Argumente der @RolesAllowed-Anmerkung geben an, dass nur Benutzer mit der admin-Rolle auf den /profile/admin-Pfad zugreifen können, und dass Benutzer mit der Rolle user oder admin auf den /profile/user-Pfad zugreifen können.

Die Endpunkte /profile/admin und /profile/user geben beide die Profilseite zurück. Die Profilseiten-UI ist in profile.qute.html definiert, wie im folgenden Beispiel gezeigt. Auf dieser Seite werden der Name, die Rollen und Bereiche des Benutzers angezeigt. Die Profilseite verfügt auch über einen Abmeldelink /logout, der den Benutzer zur Abmeldung an den OIDC-Anbieter weiterleitet. Die Profilseite ist mithilfe des Qute-Vorlagenmoduls geschrieben. Beachten Sie die Verwendung von {}-Ausdrücken auf der Seite. Diese Ausdrücke verwenden die Werte, die an TemplateInstance mit der data()-Methode übergeben wurden. Weitere Informationen zu Qute finden Sie unter Qute-Vorlagenengine.

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

Nach der Abmeldung wird der Benutzer zur Begrüßungsseite umgeleitet und kann sich erneut anmelden.

Ausführen und Testen der Quarkus-App

In diesem Abschnitt führen Sie die Quarkus-App aus und testen sie, um zu sehen, wie sie mit Microsoft Entra ID als OpenID Connect-Anbieter funktioniert.

Hinzufügen eines Umleitungs-URI zur App-Registrierung

Um die App erfolgreich auszuführen und lokal zu testen, müssen Sie der App-Registrierung einen Umleitungs-URI hinzufügen. Befolgen Sie die Anweisungen im Abschnitt Hinzufügen eines Umleitungs-URI unter Schnellstart: Registrieren einer Anwendung bei Microsoft Identity Platform, und verwenden Sie die folgenden Werte:

Wählen Sie für Plattformen konfigurieren Web aus.
Geben Sie in URIs umleiten den Wert http://localhost:8080 ein.

Vorbereiten des Beispiels

Führen Sie die folgenden Schritte aus, um die Quarkus-Beispiel-App vorzubereiten:

Verwenden Sie die folgenden Befehle zum Klonen der Quarkus-Beispiel-App von GitHub aus, und navigieren Sie zum Verzeichnis entra-id-quarkus:
```
git clone https://github.com/Azure-Samples/quarkus-azure
cd quarkus-azure/entra-id-quarkus
git checkout 2024-09-26
```
Wenn eine Meldung darüber angezeigt wird, dass Sie sich in einem Zustand HEAD getrennt befinden, kann diese Nachricht problemlos ignoriert werden. Da in diesem Artikel keine Commits erforderlich sind, eignet sich der Status „detached HEAD“ (losgelöster Head).
Verwenden Sie die folgenden Befehle, um die folgenden Umgebungsvariablen mit den Werten zu definieren, die Sie sich zuvor notiert haben:
```
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
```
Diese Umgebungsvariablen stellen die Werte für die integrierte Unterstützung von OpenID Connect in Quarkus bereit. Die entsprechenden Eigenschaften in application.properties werden im folgenden Beispiel gezeigt.
```
quarkus.oidc.client-id=
quarkus.oidc.credentials.secret=
quarkus.oidc.auth-server-url=
```
Wenn der Wert einer Eigenschaft in application.properties leer ist, konvertiert Quarkus den Eigenschaftsnamen in eine Umgebungsvariable und liest den Wert aus der Umgebung. Ausführliche Informationen zur Benennungskonvertierung finden Sie in der MicroProfile Config-Spezifikation.

Ausführen der Quarkus-App

Sie können die Quarkus-App in verschiedenen Modi ausführen. Wählen Sie eine der folgenden Methoden aus, um die Quarkus-App auszuführen. Um Quarkus zu ermöglichen, eine Verbindung mit Microsoft Entra ID herzustellen, müssen Sie den Befehl in der Shell ausführen, in der Sie die im vorherigen Abschnitt gezeigten Umgebungsvariablen definiert haben.

Führen Sie die Quarkus-App im Entwicklungsmodus aus:
```
mvn quarkus:dev
```

Führen Sie die Quarkus-App im JVM-Modus aus:

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

Führen Sie die Quarkus-App im nativen Modus aus:

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

Wenn Sie verschiedene Modi ausprobieren möchten, verwenden Sie STRG+C, um die Quarkus-App zu beenden und sie dann in einem anderen Modus auszuführen.

Testen der Quarkus-App

Wenn die Quarkus-App läuft, öffnen Sie einen Webbrowser mit einer privaten Registerkarte, und navigieren Sie zu http://localhost:8080. Sie sollten die Begrüßungsseite mit Links sehen, um sich als Benutzer oder als Administrator anzumelden. Die Verwendung einer privaten Registerkarte verhindert, dass vorhandene Microsoft Entra ID-Aktivitäten, die Sie möglicherweise in Ihrem normalen Browser haben, kontaminieren.

Erfassen der Anmeldeinformationen für die beiden Benutzer

In diesem Artikel verwendet die Microsoft Entra ID die E-Mail-Adresse jedes Benutzers als Benutzer-ID für die Anmeldung. Führen Sie die folgenden Schritte aus, um die E-Mail-Adresse für den Administratorbenutzer und den regulären Benutzer abzurufen:

Melden Sie sich beim Microsoft Entra Admin Center mindestens als Cloudanwendungsadministrator an.
Wenn Sie Zugriff auf mehrere Mandanten haben, verwenden Sie das Symbol Einstellungen ( ) im oberen Menü, um zu dem Mandanten zu wechseln, den Sie in der Anwendung registrieren möchten, über das Menü Verzeichnisse + Abonnements menu.
Navigieren Sie zu Identität > Benutzer > Alle Benutzer.
Suchen Sie den Administratorbenutzer in der Liste, und wählen Sie ihn aus.
Suchen Sie das Feld Benutzerprinzipalname.
Verwenden Sie das Symbol „Kopieren“ neben dem Wert des Felds, um die E-Mail-Adresse des Benutzers in der Zwischenablage zu speichern. Speichern Sie den Wert zur späteren Verwendung.
Führen Sie die gleichen Schritte aus, um die E-Mail-Adresse für den regulären Benutzer abzurufen.

Verwenden Sie die Kennwörter für den Administratorbenutzer und den regulären Benutzer, den Sie beim Erstellen der Benutzer festgelegt haben.

Prüfen der Funktionalität der App

Führen Sie die folgenden Schritte aus, um die Funktionalität zu prüfen:

Wählen Sie den Link Als Benutzer anmelden aus. Melden Sie sich mit dem regulären Benutzer an, den Sie zuvor erstellt haben. Nachdem Sie sich angemeldet haben, leitet die Microsoft Entra ID Sie an die Profilseite weiter, auf der Ihr Name, Ihre Rollen und Bereiche angezeigt werden.
Wenn Sie sich zum ersten Mal anmelden, werden Sie aufgefordert, Ihr Kennwort zu aktualisieren. Folgen Sie den Anweisungen, um Ihr Kennwort zu aktualisieren.
Wenn Sie die Aufforderung Ihre Organisation benötigt zusätzliche Sicherheitsinformationen. Folgen Sie den Anweisungen zum Herunterladen und Einrichten der Microsoft Authenticator-App. sehen, können Sie Später fragen auswählen, um mit dem Test fortzufahren.
Wenn Sie die Aufforderung Berechtigungen erforderlich sehen, prüfen Sie die Berechtigungen, die die App verlangt. Wählen Sie Zustimmen aus, um den Test fortzusetzen.
Wählen Sie Abmelden , um sich von der Quarkus-App abzumelden. Microsoft Entra ID führt die Abmeldung durch. Nachdem Sie sich abgemeldet haben, leitet Sie die Microsoft Entra ID zur Begrüßungsseite weiter.
Wählen Sie den Link Als Admin anmelden aus. Microsoft Entra ID leitet Sie zur Anmeldeseite weiter. Melden Sie sich mit dem Administratorbenutzer an, den Sie zuvor erstellt haben. Nachdem Sie sich angemeldet haben, leitet Microsoft Entra ID Sie zu der ähnlichen Profilseite weiter, mit einer anderen Rolle admin.
Melden Sie sich erneut ab, und versuchen Sie, sich mit dem zuvor erstellten regulären Benutzer Als Admin anzumelden. Es sollte eine Fehlermeldung angezeigt werden, da der reguläre Benutzer nicht über die admin-Rolle verfügt.

Bereinigen von Ressourcen

Dieser Artikel erläutert nicht die Bereitstellung Ihrer App in Azure. Es gibt keine Azure-Ressourcen, die für die App bereinigt werden müssen, obwohl Microsoft Entra ID-Ressourcen vorhanden sind. Um eine App in Azure bereitzustellen, können Sie die Anleitungen befolgen, auf die im nächsten Abschnitt verwiesen wird.

Wenn Sie mit den Ressourcen für diese Beispiel-App fertig sind, führen Sie die folgenden Schritte aus, um die Microsoft Entra ID-Ressourcen zu bereinigen. Das Entfernen nicht verwendeter Microsoft Entra ID-Ressourcen ist eine wichtige bewährte Methode für die Sicherheit.

Entfernen Sie die App-Registrierung, die Sie erstellt haben, indem Sie die Schritte unter Entfernen einer Anwendung, die bei der Microsoft Identity Platform registriert ist. Sie müssen lediglich die Schritte im Abschnitt Entfernen einer von Ihrer Organisation erstellten Anwendung ausführen.
Durch das Entfernen der App-Registrierung sollte auch die Unternehmensanwendung gelöscht werden. Weitere Informationen zum Löschen von Unternehmensanwendungen finden Sie unter Löschen einer Unternehmensanwendung.
Löschen Sie die Benutzer, die Sie erstellt haben, indem Sie die Schritte unter Erstellen, Einladen und Löschen von Benutzern ausführen.

Nächste Schritte

Diese Schnellstartanleitung zeigt, wie Sie Quarkus-Anwendungen mit Microsoft Entra ID unter Verwendung von OpenID Connect schützen. Weitere Informationen finden Sie in den folgenden Ressourcen:

Freigeben über