Freigeben über

Sichern von Java JBoss-EAP-Apps mithilfe von Rollen und Rollenansprüchen

  • Artikel

In diesem Artikel wird eine Java JBoss EAP-App veranschaulicht, die OpenID Connect zum Anmelden von Benutzern und Microsoft Entra ID-Anwendungsrollen (App-Rollen) für die Autorisierung verwendet.

Diese Anwendung implementiert die rollenbasierte Zugriffssteuerung (RBAC) mithilfe der Anwendungsrollen und Rollenansprüche-Funktion von Microsoft Entra ID. Eine andere Herangehensweise besteht in der Verwendung von Microsoft Entra ID-Gruppen und -Gruppenansprüchen. Microsoft Entra-ID-Gruppen und Anwendungsrollen schließen sich nicht gegenseitig aus. Sie können beide verwenden, um eine differenzierte Zugriffssteuerung bereitzustellen.

Sie können auch RBAC mit Anwendungsrollen und Rollenansprüchen verwenden, um Autorisierungsrichtlinien sicher zu erzwingen.

Ein Video, das dieses Szenario und dieses Beispiel behandelt, finden Sie unter Implementieren der Autorisierung in Ihren Anwendungen mithilfe von App-Rollen, Sicherheitsgruppen, Bereichen und Verzeichnisrollen.

Weitere Informationen dazu, wie die Protokolle in diesem Szenario und in anderen Szenarien funktionieren, finden Sie unter Authentifizierung und Autorisierung.

Diese Anwendung verwendet MSAL für Java (MSAL4J),, um sich bei einem Benutzer anzumelden und ein ID-Token von Microsoft Entra ID abzurufen.

In diesem Beispiel wird zunächst MSAL für Java (MSAL4J) verwendet, um sich beim Benutzer anzumelden. Auf der Startseite wird eine Option angezeigt, mit der der Benutzer die Ansprüche in ihren ID-Token anzeigen kann. Diese Anwendung ermöglicht es den Benutzern auch, je nach App-Rolle, der sie zugewiesen wurden, eine privilegierte Administratorseite oder eine normale Benutzerseite anzuzeigen. Die Idee ist, ein Beispiel dafür zu geben, wie innerhalb einer Anwendung der Zugriff auf bestimmte Funktionen oder Seiten auf Untergruppen von Benutzern beschränkt wird, je nachdem, welcher Rolle sie angehören.

Diese Art von Autorisierung wird mithilfe von RBAC implementiert. Bei der Verwendung der RBAC gewährt ein Administrator Berechtigungen für Rollen und nicht für einzelne Benutzer oder Gruppen. Der Administrator kann anschließend verschiedenen Benutzern und Gruppen Rollen zuweisen, um zu steuern, wer auf bestimmte Inhalte und Funktionen zugreifen kann.

Diese Beispielanwendung definiert die folgenden beiden Anwendungsrollen:

  • PrivilegedAdmin: Autorisiert für den Zugriff auf die Seiten Nur Administratoren und Reguläre Benutzer.
  • RegularUser: Autorisiert für den Zugriff auf die Seite Reguläre Benutzer.

Diese Anwendungsrollen werden im Azure-Portal im Registrierungsmanifest der Anwendung definiert. Wenn sich ein Benutzer bei der Anwendung anmeldet, gibt Microsoft Entra ID für jede Rolle, die dem Benutzer einzeln in Form einer Rollenmitgliedschaft gewährt wird, einen Rollenanspruch aus.

Sie können Benutzern und Gruppen über das Azure-Portal Rollen zuweisen.

Hinweis

Rollenansprüche sind für Gastbenutzer in einem Mandanten nicht vorhanden, wenn der https://login.microsoftonline.com/common/-Endpunkt als Autorität zum Anmelden von Benutzern verwendet wird. Sie müssen einen Benutzer bei einem Endpunkt mit Mandanten anmelden, z. B. https://login.microsoftonline.com/tenantid.

Voraussetzungen

Empfehlungen

  • Vertrautheit mit den Java / Jakarta Servlets.
  • Vertrautheit mit Linux/OSX-Terminal.
  • jwt.ms zum Überprüfen Ihrer Token.
  • Fiddler zur Überwachung Ihrer Netzwerkaktivität und Problembehandlung.
  • Lesen Sie den Microsoft Entra ID-Blog, um mit den neuesten Entwicklungen auf dem neuesten Stand zu bleiben.

Einrichten des Beispiels

Die folgenden Abschnitte zeigen Ihnen, wie der Beispielcode für die Anwendung eingerichtet wird.

Klonen oder Herunterladen des Beispielrepositorys

Um das Beispiel zu klonen, öffnen Sie ein Bash-Fenster, und verwenden Sie den folgenden Befehl:

git clone https://github.com/Azure-Samples/ms-identity-msal-java-samples.git
cd 3-java-servlet-web-app/3-Authorization-II/roles

Wechseln Sie alternativ zum Repository ms-identity-msal-java-samples, laden Sie es dann als .zip-Datei herunter, und extrahieren Sie diese auf Ihre Festplatte.

Wichtig

Um Längenbeschränkungen für Dateipfade unter Windows zu vermeiden, klonen oder extrahieren Sie das Repository in ein Verzeichnis in der Nähe des Stamms Ihrer Festplatte.

Registrieren der Beispielanwendung bei Ihrem Microsoft Entra ID-Mandanten

Dieses Beispiel enthält ein einzelnes Projekt. In den folgenden Abschnitten wird gezeigt, wie Sie die App mithilfe des Azure-Portals registrieren.

Auswählen des Microsoft Entra ID-Mandanten, in dem Sie Ihre Anwendungen erstellen möchten

Verwenden Sie die folgenden Schritte, um den Mandanten auszuwählen:

  1. Melden Sie sich beim Azure-Portal an.

  2. Gehen Sie wie folgt vor, wenn Ihr Konto in mehr als einem Microsoft Entra ID-Mandanten vorhanden ist: Wählen Sie Ihr Profil in der Ecke des Azure-Portals und anschließend die Option Verzeichnis wechseln aus, um für Ihre Portalsitzung zum gewünschten Microsoft Entra ID-Mandanten zu wechseln.

Registrieren der App (java-servlet-webapp-roles)

Registrieren Sie zunächst eine neue App im Azure-Portal, indem Sie die Anweisungen unter Schnellstart: Registrieren einer Anwendung bei Microsoft Identity Platform befolgen.

Führen Sie anschließend die folgenden Schritte zum Abschließen der Registrierung aus:

  1. Navigieren Sie zur Seite App-Registrierungen von Microsoft Identity Platform für Entwickler.

  2. Wählen Sie Neue Registrierung aus.

  3. Geben Sie auf der daraufhin angezeigten Seite Anwendung registrieren die folgenden Registrierungsinformationen Ihrer App ein:

    • Geben Sie im Abschnitt Name einen aussagekräftigen Anwendungsnamen ein, der den Benutzern der App angezeigt wird (beispielsweise java-servlet-webapp-roles).

    • Wählen Sie unter Unterstützte Kontotypen eine der folgenden Optionen aus:

      • Wählen Sie Nur Konten in diesem Organisationsverzeichnis aus, wenn Sie eine Anwendung erstellen, die nur von Benutzern im Organisationsmandanten (einzelner Mandant) verwendet werden soll.

    • Wählen Sie im Abschnitt Umleitungs-URI (optional) im Kombinationsfeld die Option Web aus, und geben Sie die folgenden Umleitungs-URIs ein: http://localhost:8080/msal4j-servlet-roles/auth/redirect

  4. Wählen Sie Registrieren aus, um die Anwendung zu erstellen.

  5. Suchen Sie auf der Registrierungsseite der App den Wert Anwendungsclient-ID, und notieren Sie ihn zur späteren Verwendung. Sie verwenden diesen Wert in den Konfigurationsdateien Ihrer App.

  6. Wählen Sie Speichern aus, um Ihre Änderungen zu speichern.

  7. Wählen Sie auf der Registrierungsseite der App Zertifikate & Geheimnisse aus, um die Seite zu öffnen, in dem Sie Geheimnisse generieren und Zertifikate hochladen können.

  8. Wählen Sie im Abschnitt Geheime Clientschlüssel die Option Neuer geheimer Clientschlüssel aus.

  9. Geben Sie eine Beschreibung ein (z. B. App-Geheimnis).

  10. Wählen Sie eine der verfügbaren Laufzeiten aus: In 1 Jahr, In 2 Jahren oder Läuft nie ab.

  11. Wählen Sie Hinzufügen. Der generierte Wert wird angezeigt.

  12. Kopieren und speichern Sie den generierten Wert zur Verwendung in späteren Schritten. Sie benötigen diesen Wert für die Konfigurationsdateien des Codes. Dieser Schlüsselwert wird nicht erneut angezeigt, und Sie können ihn auch nicht auf andere Weise abrufen. Achten Sie daher darauf, ihn aus dem Azure-Portal zu speichern, bevor Sie zu einem anderen Bildschirm oder Bereich navigieren.

Definieren der Anwendungsrollen

Befolgen Sie zum Definieren der App-Rollen die folgenden Schritte aus:

  1. Wählen Sie weiterhin in derselben App-Registrierung Im Navigationsbereich App-Rollen aus.

  2. Wählen Sie App-Rolle erstellen aus, und geben Sie dann die folgenden Werte ein:

    • Geben Sie für den Anzeigenamen einen geeigneten Namen ein, z. B. PrivilegedAdmin.
    • Wählen Sie für Zulässige Membertypen die Option Benutzer.
    • Geben Sie für Wert die Option PrivilegedAdmin ein.
    • Geben Sie für Beschreibung die Option PrivilegedAdmins, die die Administratorseite anzeigen können ein.

  3. Wählen Sie App-Rolle erstellen aus, und geben Sie dann die folgenden Werte ein:

    • Geben Sie für den Anzeigenamen einen geeigneten Namen ein, z. B. RegularUser.
    • Wählen Sie für Zulässige Membertypen die Option Benutzer.
    • Geben Sie für Wert die Option RegularUser ein.
    • Geben Sie für Beschreibung die Option RegularUsers, die die Benutzerseite anzeigen können ein.

  4. Wählen Sie Übernehmen aus, um die Änderungen zu speichern.

Zuweisen von Benutzern zu Anwendungsrollen

Wenn Sie der zuvor definierten App-Rolle Benutzer hinzufügen möchten, befolgen Sie die hier aufgeführten Richtlinien: Zuweisen von Benutzern und Gruppen zu Rollen.

Konfigurieren der App (java-servlet-webapp-roles) für die Verwendung Ihrer App-Registrierung

Führen Sie die folgenden Schritte aus, um die App zu konfigurieren:

Hinweis

In den folgenden Schritten ist ClientID identisch mit Application ID oder AppId.

  1. Öffnen Sie das Projekt in Ihrem IDE.

  2. Öffnen Sie die Datei authentication.properties.

  3. Suchen Sie die Zeichenfolge {enter-your-tenant-id-here}. Ersetzen Sie den vorhandenen Wert durch Ihre Microsoft Entra ID-Mandanten-ID.

  4. Suchen Sie die Zeichenfolge {enter-your-client-id-here}, und ersetzen Sie den vorhandenen Wert durch die Anwendungs-ID clientId der java-servlet-webapp-call-graph-Anwendung, die Sie aus dem Azure-Portal kopiert haben.

  5. Suchen Sie die Zeichenfolge {enter-your-client-secret-here}, und ersetzen Sie den vorhandenen Wert durch den Wert, den Sie beim Erstellen derjava-servlet-webapp-roles-App im Azure-Portal gespeichert haben.

  6. Suchen Sie die app.roles-Eigenschaft, und stellen Sie sicher, dass der Wert auf app.roles=admin PrivilegedAdmin, user RegularUser festgelegt ist, oder ersetzen Sie die Namen Ihrer spezifischen Rollen.

Erstellen des Beispiels

Um das Beispiel mit Maven zu erstellen, navigieren Sie zu dem Verzeichnis, das die pom.xml-Datei für das Beispiel enthält, und führen Sie dann den folgenden Befehl aus:

mvn clean package

Dieser Befehl generiert eine .war-Datei, die Sie auf verschiedenen Anwendungsservern ausführen können.

Ausführen des Beispiels

In den folgenden Abschnitten wird veranschaulicht, wie Sie das Beispiel in Azure App Service bereitstellen.

Voraussetzungen

Konfigurieren des Maven-Plug-Ins

Der Bereitstellungsprozess für Azure App Service verwendet automatisch Ihre Azure-Anmeldeinformation aus der Azure CLI. Wenn die Azure CLI nicht lokal installiert ist, führt das Maven-Plug-In die Authentifizierung über OAuth oder die Geräteanmeldung durch. Weitere Informationen finden Sie unter Authentifizierung mit Maven-Plug-Ins.

Gehen Sie wie folgt vor, um das Plug-In zu konfigurieren:

  1. Führen Sie den als nächstes gezeigten Maven-Befehl aus, um die Bereitstellung zu konfigurieren. Dieser Befehl unterstützt Sie beim Einrichten des App Service-Betriebssystems, der Java-Version und der Tomcat-Version.

    mvn com.microsoft.azure:azure-webapp-maven-plugin:2.12.0:config

  2. Drücken Sie für Neue Ausführungskonfiguration erstellen die Taste Y und dann die Eingabetaste.

  3. Drücken Sie für Wert für Betriebssystem die Taste 2 für Linux und dann die Eingabetaste.

  4. Drücken Sie für Wert für javaVersion definieren die Taste 2 für Java 11 und dann die Eingabetaste.

  5. Drücken Sie für Wert definieren für webContainer die Taste 1 für JBosseap7 und dann die Eingabetaste.

  6. Drücken Sie für Wert definieren für pricingTier die Eingabetaste, um die P1v3-Standardschicht auszuwählen.

  7. Drücken Sie zum Bestätigen die Taste Y und dann die Eingabetaste.

Das folgende Beispiel zeigt die Ausgabe des Bereitstellungsprozesses:

Please confirm webapp properties
AppName : msal4j-servlet-auth-1707220080695
ResourceGroup : msal4j-servlet-auth-1707220080695-rg
Region : centralus
PricingTier : P1v3
OS : Linux
Java Version: Java 11
Web server stack: JBosseap 7
Deploy to slot : false
Confirm (Y/N) [Y]:
[INFO] Saving configuration to pom.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  26.196 s
[INFO] Finished at: 2024-02-06T11:48:16Z
[INFO] ------------------------------------------------------------------------

Nachdem Sie Ihre Auswahl bestätigt haben, fügt das Plug-in die Plug-in-Konfiguration und die erforderlichen Einstellungen in der pom.xml-Datei Ihres Projekts hinzu, um Ihre App zur Ausführung in Azure App Service zu konfigurieren.

Der relevante Teil der pom.xml-Datei sollte ähnlich wie im folgenden Beispiel aussehen.

<build>
    <plugins>
        <plugin>
            <groupId>com.microsoft.azure</groupId>
            <artifactId>>azure-webapp-maven-plugin</artifactId>
            <version>x.xx.x</version>
            <configuration>
                <schemaVersion>v2</schemaVersion>
                <resourceGroup>your-resourcegroup-name</resourceGroup>
                <appName>your-app-name</appName>
            ...
            </configuration>
        </plugin>
    </plugins>
</build>

Sie können die Konfigurationen für App Service direkt in der Datei pom.xml ändern. Einige gängige Konfigurationen sind in der folgenden Tabelle aufgeführt:

Eigenschaft Erforderlich Beschreibung Version
schemaVersion false Die Version des Konfigurationsschemas. Unterstützte Werte: v1 und v2. 1.5.2
subscriptionId false Die Abonnement-ID. 0.1.0+
resourceGroup true Die Azure-Ressourcengruppe für Ihre App. 0.1.0+
appName true Der Name Ihrer App. 0.1.0+
region false Die Region, in der Ihre App gehostet werden soll. Der Standardwert ist centralus. Gültige Regionen finden Sie unter Unterstützte Regionen. 0.1.0+
pricingTier false Der Tarif für Ihre App. Der Standardwert ist P1v2 für eine Produktionsworkload. Der empfohlene Mindestwert für die Java-Entwicklung und -Tests ist B2. Weitere Informationen finden Sie unter App Service – Preise. 0.1.0+
runtime false Die Laufzeitumgebungskonfiguration. Weitere Informationen finden Sie unter Konfigurationsdetails. 0.1.0+
deployment false Die Bereitstellungskonfiguration. Weitere Informationen finden Sie unter Konfigurationsdetails. 0.1.0+

Eine vollständige Liste der Konfigurationen finden Sie in der Dokumentation zur Plug-In-Referenz. Alle Azure Maven-Plug-ins verwenden einen gemeinsamen Satz von Konfigurationen. Diese Konfigurationen finden Sie unter Allgemeine Konfigurationen. Azure App Service-spezifische Konfigurationen finden Sie unter Azure-App: Konfigurationsdetails.

Denken Sie daran, die Werte für appName und resourceGroup zur späteren Verwendung zu speichern.

Vorbereiten der App zur Bereitstellung

Wenn Sie Ihre Anwendung in App Service bereitstellen, ändert sich ihre Umleitungs-URL in die Umleitungs-URL Ihrer bereitgestellten App-Instanz. Führen Sie die folgenden Schritte aus, um diese Einstellungen in der Eigenschaftsdatei zu ändern:

  1. Navigieren Sie zur Datei authentication.properties, und ändern Sie den Wert app.homePage des Domänennamens Ihrer bereitgestellten App hinzu, wie im folgenden Beispiel gezeigt. Wenn Sie beispielsweise example-domain als den App-Namen ausgewählt haben, müssen Sie jetzt https://example-domain.azurewebsites.net für den Wert app.homePage verwenden. Stellen Sie sicher, dass Sie das Protokoll auch von http in https geändert haben.

    # app.homePage is by default set to dev server address and app context path on the server
# for apps deployed to azure, use https://your-sub-domain.azurewebsites.net
app.homePage=https://<your-app-name>.azurewebsites.net

  2. Verwenden Sie nach dem Speichern dieser Datei den folgenden Befehl, um Ihre App neu zu erstellen:

    mvn clean package

Wichtig

In derselben Datei authentication.properties haben Sie eine Einstellung für aad.secret. Es empfiehlt sich nicht, diesen Wert für App Service bereitzustellen. Ebenso wenig ist es eine bewährte Methode, diesen Wert in Ihrem Code zu belassen und ihn möglicherweise an Ihr Git-Repository zu übertragen. Wenn Sie diesen geheimen Wert aus Ihrem Code entfernen möchten, finden Sie ausführlichere Anleitungen im Abschnitt Bereitstellen in App Service – Geheimwert entfernen ". Diese Anleitung fügt zusätzliche Schritte zum Pushen des geheimen Werts an Key Vault und zum Verwenden von Key Vault-Verweisen hinzu.

Aktualisieren Sie die Registrierung Ihrer Microsoft Entra ID-App.

Da sich der Umleitungs-URI in Ihrer bereitgestellten App in Azure App Service ändert, müssen Sie auch den Umleitungs-URI in Ihrer Microsoft Entra ID-App-Registrierung ändern. Durchlaufen Sie folgende Schritte, um diese Änderung wirksam zu machen:

  1. Navigieren Sie zur Seite App-Registrierungen von Microsoft Identity Platform für Entwickler.

  2. Verwenden Sie das Suchfeld, um nach Ihrer App-Registrierung zu suchen. Beispiel: java-servlet-webapp-authentication.

  3. Öffnen Sie die App-Registrierung, indem Sie den Namen auswählen.

  4. Wählen Sie im oberen Menü Authentifizierung aus.

  5. Wählen Sie unter Web - Umleitungs-URIs die Option URI hinzufügen aus.

  6. Füllen Sie den URI Ihrer App aus, indem Sie /auth/redirect anfügen. Beispiel: https://<your-app-name>.azurewebsites.net/auth/redirect.

  7. Wählen Sie Speichern.

Bereitstellen der App

Sie können Ihre App jetzt in Azure App Service bereitstellen. Verwenden Sie den folgenden Befehl, um sicherzustellen, dass Sie bei Ihrer Azure-Umgebung angemeldet sind, um die Bereitstellung auszuführen:

az login

Wenn alle Konfigurationseinstellungen in Ihrer pom.xml-Datei eingerichtet sind, können Sie Ihre Java-App mit einem einzigen Befehl in Azure bereitstellen:

mvn package azure-webapp:deploy

Nach Abschluss der Bereitstellung steht Ihre Anwendung unter http://<your-app-name>.azurewebsites.net/ bereit. Öffnen Sie die URL mit Ihrem lokalen Webbrowser, in dem die Startseite der msal4j-servlet-auth-Anwendung angezeigt werden soll.

Untersuchen des Beispiels

Gehen Sie folgendermaßen vor, um das Beispiel zu erkunden:

  1. Beachten Sie den angemeldeten oder abgemeldeten Status, der in der Mitte des Bildschirms angezeigt wird.
  2. Wählen Sie in der Ecke die Schaltfläche „Kontextsensitiv“ aus. Diese Schaltfläche lautet Anmelden, wenn Sie die App zum ersten Mal ausführen.
  3. Folgen Sie auf der nächsten Seite den Anweisungen, und melden Sie sich mit einem Konto im Microsoft Entra ID-Mandanten an.
  4. Beachten Sie auf dem Einwilligungsbildschirm die angeforderten Bereiche.
  5. Beachten Sie, dass die kontextsensitive Schaltfläche jetzt Abmelden lautet und Ihren Benutzernamen anzeigt.
  6. Klicken Sie auf ID-Tokendetails, um die decodierten Ansprüche des ID-Tokens anzuzeigen.
  7. Wählen Sie Nur Administratoren aus, um die /admin_only-Seite anzuzeigen. Nur Benutzer mit der App-Rolle PrivilegedAdmin können diese Seite anzeigen. Andernfalls wird eine Meldung zu Autorisierungsfehlern angezeigt.
  8. Wählen Sie Reguläre Benutzer aus, um die /regular_user-Seite anzuzeigen. Nur Benutzer mit der App-Rolle RegularUser oder PrivilegedAdmin können diese Seite anzeigen. Andernfalls wird eine Meldung zu Autorisierungsfehlern angezeigt.
  9. Verwenden Sie die Schaltfläche in der Ecke, um sich abzumelden.

Informationen zum Code

In diesem Beispiel wird MSAL für Java (MSAL4J) verwendet, um einen Benutzer anzumelden und ein ID-Token abzurufen, das den Rollenanspruch enthalten kann. Basierend auf dem vorhandenen Rollenanspruch kann der angemeldete Benutzer auf keine, eine oder beide der geschützten Seiten Admins Only und Regular Users zugreifen.

Wenn Sie das Verhalten dieses Beispiels replizieren möchten, können Sie die pom.xml-Datei und den Inhalt der Hilfs- und authservlets--Ordner im Ordner src/main/java/com/microsoft/azuresamples/msal4j kopieren. Außerdem benötigen Sie die authentication.properties-Datei. Diese Klassen und Dateien enthalten generischen Code, den Sie in einer breiten Palette von Anwendungen verwenden können. Sie können auch den Rest des Beispiels kopieren, aber die anderen Klassen und Dateien werden speziell für das Ziel dieses Beispiels erstellt.

Contents

Die folgende Tabelle zeigt den Inhalt des Beispielprojektordners:

Datei/Ordner Beschreibung
src/main/java/com/microsoft/azuresamples/msal4j/roles/ Dieses Verzeichnis enthält die Klassen, die die Back-End-Geschäftslogik der App definieren.
src/main/java/com/microsoft/azuresamples/msal4j/authservlets/ Dieses Verzeichnis enthält die Klassen, die für Anmelde- und Abmeldeendpunkte verwendet werden.
____Servlet.java Alle verfügbaren Endpunkte werden in .java Klassen definiert, die auf ____Servlet.java enden.
src/main/java/com/microsoft/azuresamples/msal4j/helpers/ Hilfsklassen für die Authentifizierung.
AuthenticationFilter.java Leitet nicht authentifizierte Anforderungen an geschützte Endpunkte auf eine 401-Seite um.
src/main/resources/authentication.properties Microsoft Entra ID und Programmkonfiguration.
src/main/webapp/ Dieses Verzeichnis enthält die Benutzeroberfläche – JSP-Vorlagen
CHANGELOG.md Liste der Änderungen am Beispiel.
CONTRIBUTING.md Richtlinien für einen Beitrag zum Beispiel.
LIZENZ Die Lizenz für das Beispiel.

Verarbeiten eines Rollenanspruchs im ID-Token

Der Rollenanspruch des Tokens enthält die Namen der Rollen, denen der angemeldete Benutzer zugewiesen ist, wie im folgenden Beispiel gezeigt:

{
  ...
  "roles": [
    "Role1",
    "Role2",]
  ...
}

ConfidentialClientApplication

Eine ConfidentialClientApplication Instanz wird in der AuthHelper.java-Datei erstellt, wie im folgenden Beispiel gezeigt. Dieses Objekt hilft beim Erstellen der Microsoft Entra-Autorisierungs-URL und auch beim Austauschen des Authentifizierungstokens für ein Zugriffstoken.

// getConfidentialClientInstance method
IClientSecret secret = ClientCredentialFactory.createFromSecret(SECRET);
confClientInstance = ConfidentialClientApplication
                     .builder(CLIENT_ID, secret)
                     .authority(AUTHORITY)
                     .build();

Es werden die folgenden Parameter für die Instanziierung verwendet:

  • Die Client-ID der App.
  • Der geheime Clientschlüssel, der eine Anforderung für vertrauliche Clientanwendungen ist.
  • Die Microsoft Entra ID Authority, die Ihre Microsoft Entra-Mandanten-ID enthält.

In diesem Beispiel werden diese Werte aus der Datei authentication.properties mithilfe eines Eigenschaftenlesers in der Config.java-Datei gelesen.

Ausführliche exemplarische Vorgehensweise

Die folgenden Schritte bieten eine exemplarische Vorgehensweise für die Funktionalität der App:

  1. Der erste Schritt des Anmeldeprozesses besteht darin, eine Anforderung an den /authorize-Endpunkt des Microsoft Entra ID-Mandanten zu senden. Die ConfidentialClientApplication-Instanz von MSAL4J wird verwendet, um eine Autorisierungsanforderungs-URL zu erstellen. Die App leitet den Browser an diese URL um, über die der Benutzer sich dann anmeldet.

    final ConfidentialClientApplication client = getConfidentialClientInstance();
AuthorizationRequestUrlParameters parameters = AuthorizationRequestUrlParameters.builder(Config.REDIRECT_URI, Collections.singleton(Config.SCOPES))
        .responseMode(ResponseMode.QUERY).prompt(Prompt.SELECT_ACCOUNT).state(state).nonce(nonce).build();

final String authorizeUrl = client.getAuthorizationRequestUrl(parameters).toString();
contextAdapter.redirectUser(authorizeUrl);

    In der folgenden Liste werden die Features dieses Codes beschrieben:

    • AuthorizationRequestUrlParameters: Diese Parameter müssen zum Erstellen einer AuthorizationRequestUrl-Klasse festgelegt werden.
    • REDIRECT_URI: Wo Microsoft Entra ID den Browser - zusammen mit dem Authentifizierungscode - umleitet, nachdem Benutzeranmeldeinformationen gesammelt wurden. Er muss mit dem Umleitungs-URI in der Microsoft Entra ID-App-Registrierung im Azure-Portal übereinstimmen.
    • SCOPES: Bereiche stellen die Berechtigungen dar, die von der Anwendung angefordert wurden.
      • Normalerweise reichen die drei Bereiche openid profile offline_access aus, um eine ID-Token-Antwort zu erhalten.
      • Vollständige Liste der von der App angeforderten Bereiche finden Sie in der Datei authentication.properties. Sie können weitere Bereiche hinzufügen, Beispiel: User.Read.

  2. Microsoft Entra ID zeigt der*dem Benutzer*in eine Anmeldeeingabeaufforderung an. Wenn der Anmeldeversuch erfolgreich ist, wird der Browser des Benutzers zum Umleitungsendpunkt dieser App umgeleitet. Eine erfolgreiche Anforderung an diesen Endpunkt enthält einen Autorisierungscode.

  3. Die ConfidentialClientApplication-Instanz tauscht diesen Autorisierungscode dann für ein ID-Token und ein Zugriffstoken von Microsoft Entra ID aus.

    // First, validate the state, then parse any error codes in response, then extract the authCode. Then:
// build the auth code params:
final AuthorizationCodeParameters authParams = AuthorizationCodeParameters
        .builder(authCode, new URI(Config.REDIRECT_URI)).scopes(Collections.singleton(Config.SCOPES)).build();

// Get a client instance and leverage it to acquire the token:
final ConfidentialClientApplication client = AuthHelper.getConfidentialClientInstance();
final IAuthenticationResult result = client.acquireToken(authParams).get();

    In der folgenden Liste werden die Features dieses Codes beschrieben:

    • AuthorizationCodeParameters: Diese Parameter müssen festgelegt werden, damit der Autorisierungscode für ein ID- und/oder ein Zugriffstoken ausgetauscht werden kann.
    • authCode: Hierbei handelt es sich um den Autorisierungscode, der am Umleitungsendpunkt empfangen wurde.
    • REDIRECT_URI: Der im vorherigen Schritt verwendete Umleitungs-URI muss noch mal übergeben werden.
    • SCOPES: Die im vorherigen Schritt verwendeten Bereiche müssen noch einmal übergeben werden.

  4. Wenn acquireToken erfolgreich ausgeführt wird, werden die Tokenansprüche extrahiert. Wenn die Nonce-Überprüfung erfolgreich ist, werden die Ergebnisse in context (eine Instanz von IdentityContextData) platziert und in der Sitzung gespeichert. Die Anwendung kann IdentityContextData dann aus der Sitzung (mithilfe einer IdentityContextAdapterServlet-Instanz) instanziieren, wenn sie Zugriff benötigt, wie im folgenden Code gezeigt:

    // parse IdToken claims from the IAuthenticationResult:
// (the next step - validateNonce - requires parsed claims)
context.setIdTokenClaims(result.idToken());

// if nonce is invalid, stop immediately! this could be a token replay!
// if validation fails, throws exception and cancels auth:
validateNonce(context);

// set user to authenticated:
context.setAuthResult(result, client.tokenCache().serialize());

Schützen der Routen

Informationen dazu, wie die Beispiel-App den Zugriff auf Routen filtert, finden Sie unter AuthenticationFilter.java. In der Datei authentication.properties enthält die Eigenschaft app.protect.authenticated die durch Trennzeichen getrennten Routen, auf die nur authentifizierte Benutzer zugreifen können, wie im folgenden Beispiel gezeigt:

# for example, /token_details requires any user to be signed in and does not require special roles claim(s)
app.protect.authenticated=/token_details

Alle Routen, die in den durch Trennzeichen getrennten Regelsätzen unter app.protect.roles aufgelistet sind, sind auch für nicht authentifizierte Benutzer nicht verwendbar, wie im folgenden Beispiel gezeigt. Diese Routen enthalten jedoch auch eine durch Leerzeichen getrennte Liste der App-Rollenmitgliedschaften: Nach der Authentifizierung können nur Benutzer mit mindestens einer der entsprechenden Rollen auf diese Routen zugreifen.

# local short names for app roles - for example, sets admin to mean PrivilegedAdmin (useful for long rule sets defined in the next key, app.protect.roles)
app.roles=admin PrivilegedAdmin, user RegularUser

# A route and its corresponding <space-separated> role(s) that can access it; the start of the next route & its role(s) is delimited by a <comma-and-space-separator>
# this says: /admins_only can be accessed by PrivilegedAdmin, /regular_user can be accessed by PrivilegedAdmin role and the RegularUser role
app.protect.roles=/admin_only admin, /regular_user admin user

Bereiche

Bereiche teilen Microsoft Entra ID die Zugriffsebene mit, die die Anwendung anfordert.

Auf Grundlage der angeforderten Bereiche zeigt Microsoft Entra ID dem Benutzer bei der Anmeldung ein Einwilligungsdialogfeld an. Wenn der Benutzer in einen oder mehrere Bereiche einwilligt und ein Token erhält, werden die Bereiche in das resultierende access_token codiert.

Die von der Anwendung angeforderten Bereiche finden Sie unter authentication.properties. Diese drei Bereiche werden von MSAL angefordert und standardmäßig von Microsoft Entra ID angegeben.

Weitere Informationen