Freigeben über

Sichern von Java WebSphere-Apps mithilfe von Gruppen und Gruppenansprüchen

  • Artikel

In diesem Artikel erfahren Sie, wie Sie eine WebSphere-App erstellen, die Benutzer mit Microsoft Authentication Library (MSAL) für Java anmeldet. Die App beschränkt auch den Zugriff auf Seiten basierend auf der Sicherheitsgruppenmitgliedschaft von Microsoft Entra ID.

In der folgenden Abbildung wird die Topologie für diese App veranschaulicht:

Diagramm mit einer Übersicht über die Topologie der App.

Die Client-App verwendet MSAL für Java (MSAL4J), um Benutzer bei einem Microsoft Entra ID-Mandanten anzumelden und ein ID-Token von Microsoft Entra ID abzurufen. Das ID-Token beweist, dass ein Benutzer bei diesem Mandanten authentifiziert wird. Die App schützt ihre Routen entsprechend dem Authentifizierungsstatus und der Gruppenmitgliedschaft des Benutzers.

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

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

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

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-groups).
    • Wählen Sie unter Unterstützte Kontotypen die Option Nur Konten in diesem Organisationsverzeichnis aus.
    • 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-groups/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.

  13. Wählen Sie auf der Registrierungsseite der App API-Berechtigungen im Navigationsbereich aus, um die Seite zu öffnen, auf der Sie Zugriff auf die von Ihrer Anwendung benötigten APIs hinzufügen können.

  14. Wählen Sie Berechtigung hinzufügen aus.

  15. Stellen Sie sicher, dass die Registerkarte Microsoft-APIs ausgewählt ist.

  16. Wählen Sie im Abschnitt Häufig verwendete Microsoft-APIs die Option Microsoft Graph aus.

  17. Wählen Sie im Abschnitt Delegierte Berechtigungen die Optionen User.Read und GroupMember.Read.All aus. Verwenden Sie bei Bedarf das Suchfeld.

  18. Wählen Sie Berechtigungen hinzufügen aus.

  19. GroupMember.Read.All erfordert die Zustimmung des Administrators, wählen Sie also Administratoreinwilligung für {Mandant} erteilen/widerrufen und dann Ja aus, wenn Sie gefragt werden, ob Sie die Zustimmung für die angeforderten Berechtigungen für alle Konten im Mandanten erteilen möchten. Sie müssen ein Microsoft Entra ID-Mandantenadministrator sein, um diese Aktion auszuführen.

Konfigurieren der App (java-servlet-webapp-groups) 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 ./src/main/resources/authentication.properties.

  3. Suchen Sie die Zeichenfolge {enter-your-tenant-id-here}. Ersetzen Sie den vorhandenen Wert durch Ihre Microsoft Entra Mandanten-ID, wenn Sie Ihre App mit der Option Konten nur in diesem Organisationsverzeichnis registriert haben.

  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-groups-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-groups-App im Azure-Portal gespeichert haben.

Sicherheitsgruppen konfigurieren

Sie haben die folgenden Optionen, wie Sie Ihre Anwendungen weiter konfigurieren können, um den Gruppenanspruch zu erhalten:

Hinweis

Informationen zum Abrufen von samAccountName oder On Premises Group Security Identifier der anstelle der Gruppen-ID finden Sie im Abschnitt Voraussetzungen für die Verwendung von Gruppenattributen, die aus Active Directory synchronisiert werden in Konfigurieren von Gruppenansprüchen für Anwendungen mithilfe der Microsoft Entra-ID.

Konfigurieren der Anwendung für den Empfang aller Gruppen, denen der angemeldete Benutzer zugewiesen ist, einschließlich geschachtelter Gruppen

Führen Sie zum Konfigurieren der Anwendung die folgenden Schritte aus:

  1. Wählen Sie auf der Registrierungsseite der App im Navigationsbereich Tokenkonfiguration aus, um die Seite zu öffnen, auf der Sie die für Ihre Anwendung ausgestellten Ansprüche konfigurieren können.

  2. Wählen Sie Gruppenanspruch hinzufügen aus, um den Bildschirm Gruppenanspruch bearbeiten zu öffnen.

  3. Wählen Sie Sicherheitsgruppen ODER Alle Gruppen (einschließlich Verteilungslisten, jedoch nicht der der Anwendung zugewiesenen Gruppen) aus. Wenn Sie beide Optionen auswählen, wird die Auswirkung der Option Sicherheitsgruppen aufgehoben.

  4. Wählen Sie im Abschnitt ID die Option Gruppen-ID aus. Diese Auswahl bewirkt, dass die Microsoft Entra-ID die Objekt-ID der Gruppen sendet, denen der Benutzer in den Gruppenansprüchen des ID-Tokens zugewiesen ist, das Ihre App nach der Anmeldung eines Benutzers erhält.

Konfigurieren Sie Ihre Anwendung so, dass sie die Gruppenanspruchswerte aus einer gefilterten Gruppe von Gruppen empfängt, denen ein Benutzer möglicherweise zugewiesen ist.

Diese Option ist nützlich, wenn die folgenden Fälle zutreffen:

  • Ihre Anwendung ist an einer ausgewählten Gruppe von Gruppen interessiert, denen ein Anmeldebenutzer möglicherweise zugewiesen wird.
  • Ihre Anwendung ist nicht an jeder Sicherheitsgruppe interessiert, der dieser Benutzer im Mandanten zugewiesen ist.

Diese Option hilft Ihrer Anwendung, das Überlastungsproblem zu vermeiden.

Hinweis

Diese Funktion ist in der Microsoft Entra ID Free Edition nicht verfügbar.

Geschachtelte Gruppenzuweisungen sind nicht verfügbar, wenn Sie diese Option verwenden.

Befolgen Sie die folgenden Schritte, um diese Option in Ihrer App zu aktivieren:

  1. Wählen Sie auf der Registrierungsseite der App im Navigationsbereich Tokenkonfiguration aus, um die Seite zu öffnen, auf der Sie die für Ihre Anwendung ausgestellten Ansprüche konfigurieren können.

  2. Wählen Sie Gruppenanspruch hinzufügen aus, um den Bildschirm Gruppenanspruch bearbeiten zu öffnen.

  3. Wählen Sie Der Anwendung zugewiesene Gruppen aus.

    Wenn Sie andere Optionen auswählen, beispielsweise Sicherheitsgruppen oder Alle Gruppen (einschließlich Verteilerlisten, aber nicht Gruppen, die der Anwendung zugewiesen sind),, Vorteile, die Ihre App aus der Wahl dieser Option zieht, verworfen.

  4. Wählen Sie im Abschnitt ID die Option Gruppen-ID aus. Diese Auswahl führt dazu, dass die Microsoft Entra-ID die Objekt-ID der Gruppen sendet, denen der Benutzer im Gruppenanspruch des ID-Tokens zugewiesen ist.

  5. Wenn Sie eine Web-API mithilfe der Option API verfügbar machen verfügbar machen, können Sie auch die Option Gruppen-ID im Abschnitt Zugriff auswählen. Diese Auswahl führt dazu, dass die Microsoft Entra-ID die Objekt-ID der Gruppen sendet, denen der Benutzer im Gruppenanspruch des Zugriffstokens zugewiesen ist.

  6. Wählen Sie auf der Registrierungsseite der App im Navigationsbereich die Option Übersicht aus, um den App-Übersichtsbildschirm zu öffnen.

  7. Wählen Sie unter Verwaltete Anwendung in lokalem Verzeichnis den Hyperlink mit dem Namen Ihrer App aus. Dieser Feldtitel kann abgeschnitten sein, beispielsweise Managed application in .... Wenn Sie diesen Link auswählen, navigieren Sie zur Seite Übersicht über die Unternehmensanwendung, die dem Dienstprinzipal für Ihre Anwendung in dem Mandanten zugeordnet ist, in dem Sie sie erstellt haben. Über die Schaltfläche „Zurück“ in Ihrem Browser können Sie wieder zur App-Registrierungsseite navigieren.

  8. Wählen Sie im Navigationsbereich Benutzer und Gruppen aus, um die Seite zu öffnen, auf der Sie Ihrer Anwendung Benutzer und Gruppen zuweisen können.

  9. Wählen Sie Benutzer hinzufügen.

  10. Wählen Sie auf dem daraufhin angezeigten Bildschirm Benutzer und Gruppen aus.

  11. Wählen Sie die Gruppen aus, die Sie dieser Anwendung zuweisen möchten.

  12. Klicken Sie auf Auswählen, um die Auswahl der Gruppen abzuschließen.

  13. Wählen Sie Zuweisen aus, um den Gruppenzuweisungsprozess abzuschließen.

    Ihre Anwendung empfängt jetzt diese ausgewählten Gruppen in den Gruppenansprüchen, wenn ein Benutzer, der sich bei Ihrer App anmeldet, Mitglied einer oder mehrerer dieser zugewiesenen Gruppen ist.

  14. Wählen Sie im Navigationsbereich Eigenschaften aus, um die Seite zu öffnen, auf der die grundlegenden Eigenschaften Ihrer Anwendung aufgelistet sind. Legen Sie das Falg Benutzerzuweisung erforderlich? auf Ja fest.

Wichtig

Wenn Sie Benutzerzuweisung erforderlich? auf Ja festlegen, überprüft Microsoft Entra ID, dass nur die Ihrer Anwendung zugewiesenen Benutzer im Bereich Benutzer und Gruppen sich bei Ihrer App anmelden können. Sie können Benutzer direkt oder durch Zuweisen von Sicherheitsgruppen zuweisen, denen sie angehören, zuweisen.

Konfigurieren der App (java-servlet-webapp-groups) zum Erkennen von Gruppen-IDs

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

Wichtig

Wenn Sie auf der Seite Tokenkonfiguration eine andere Option als groupID (z. B. DNSDomain\sAMAccountName) ausgewählt haben, sollten Sie den Gruppennamen in den folgenden Schritten eingeben, Beispiel: contoso.com\Test Group anstelle der Objekt-ID:

  1. Öffnen Sie die Datei ./src/main/resources/authentication.properties.

  2. Suchen Sie die Zeichenfolge {enter-your-admins-group-id-here}, und ersetzen Sie den vorhandenen Wert durch die Objekt-ID der GroupAdmin-Gruppe, die Sie aus dem Azure-Portal kopiert haben. Entfernen Sie auch die geschweiften Klammern aus dem Platzhalterwert.

  3. Suchen Sie die Zeichenfolge {enter-your-users-group-id-here}, und ersetzen Sie den vorhandenen Wert durch die Objekt-ID der GroupMember-Gruppe, die Sie aus dem Azure-Portal kopiert haben. Entfernen Sie auch die geschweiften Klammern aus dem Platzhalterwert.

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

Bei diesen Anweisungen wird davon ausgegangen, dass Sie WebSphere installiert und einen Server eingerichtet haben. Sie können die Anleitungen unter Bereitstellen des (herkömmlichen )WebSphere Application Server Clusters auf virtuellen Azure-Computern für eine einfache Servereinrichtung verwenden.

Bevor Sie in WebSphere bereitstellen können, führen Sie die folgenden Schritte aus, um einige Konfigurationsänderungen im Beispiel selbst vorzunehmen und dann das Paket zu erstellen oder neu zu erstellen:

  1. Navigieren Sie zur Datei authentication.properties, und ändern Sie den Wert von app.homePage in die Server-URL und Portnummer, die Sie verwenden möchten, wie im folgenden Beispiel gezeigt:

    # 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://<server-url>:<port-number>/msal4j-servlet-auth/

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

    mvn clean package

  3. Nachdem der Code die Erstellung abgeschlossen hat, kopieren Sie die .war-Datei auf das Dateisystem des Zielservers.

Außerdem müssen Sie dieselbe Änderung in der Azure-App-Registrierung vornehmen, bei der Sie sie im Azure-Portal als Umleitungs-URI-Wert auf der Registerkarte Authentifizierung festlegen.

  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://<server-url>:<port-number>/auth/redirect.

  7. Wählen Sie Speichern.

Führen Sie die folgenden Schritte aus, um das Beispiel mithilfe der Integrated Solutions Console von WebSphere bereitzustellen:

  1. Wählen Sie auf der Registerkarte Anwendungen die Option Neue Anwendung und dann Neue Unternehmensanwendung aus.

  2. Wählen Sie die von Ihnen erstellte .war-Datei und dann Weiter aus, bis Sie zum Installationsschritt Zuordnen von Kontextstämmen für Webmodule gelangen. Die anderen Standardeinstellungen sollten so belassen werden.

  3. Legen Sie für den Kontextstamm denselben Wert wie nach der Portnummer im „Umleitungs-URI“ fest, den Sie in der Beispielkonfiguration/Azure-App-Registrierung festgelegt haben. Das heißt, wenn der Umleitungs-URI http://<server-url>:9080/msal4j-servlet-auth/ lautet, sollte msal4j-servlet-auth der Kontextstamm sein.

  4. Wählen Sie Fertig stellenaus.

  5. Wechseln Sie nach Abschluss der Installation der Anwendung zum Abschnitt WebSphere-Unternehmensanwendungen auf der Registerkarte Anwendungen.

  6. Wählen Sie die .war-Datei aus der Liste der Anwendungen und dann Start für die Bereitstellung aus.

  7. Navigieren Sie nach Abschluss der Bereitstellung zu http://<server-url>:9080/{whatever you set as the context root}, und die Anwendung sollte nun angezeigt werden.

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 Gruppen aus, um alle Informationen zur Sicherheitsgruppenmitgliedschaft für den angemeldeten Benutzer anzuzeigen.
  8. Wählen Sie Nur Administrator oder Regulärer Benutzer aus, um auf die gruppengeschützten Endpunkte zuzugreifen.
    • Wenn sich ihr angemeldeter Benutzer in der GroupAdmin-Gruppe befindet, kann der Benutzer beide Seiten eingeben.
    • Wenn sich Ihr angemeldeter Benutzer in der GroupMember-Gruppe befindet, kann der Benutzer nur die Seite Regulärer Benutzer eingeben.
    • Wenn sich Ihr angemeldeter Benutzer in keiner Gruppe befindet, kann der Benutzer nicht auf eine der beiden Seiten zugreifen.
  9. Verwenden Sie die Schaltfläche in der Ecke, um sich abzumelden.
  10. Nachdem Sie sich abgemeldet haben, wählen Sie ID-Tokendetails aus, um zu beobachten, dass die App einen 401: unauthorized-Fehler anstelle der ID-Tokenansprüche anzeigt, wenn der Benutzer nicht autorisiert ist.

Informationen zum Code

In diesem Beispiel wird MSAL für Java (MSAL4J) verwendet, um einen Benutzer anzumelden und ein ID-Token abzurufen, das den Gruppenanspruch enthalten kann. Wenn im ID-Token zu viele Gruppen zur Emission vorhanden sind, verwendet das Beispiel Microsoft Graph SDK für Java, um die Gruppenmitgliedschaftsdaten von Microsoft Graph abzurufen. Basierend auf den Gruppen, zu der der Benutzer gehört, kann der angemeldete Benutzer entweder auf keine, eine oder beide der geschützten Seiten Admins Only und Regular Users zugreifen.

Wenn Sie das Verhalten dieses Beispiels replizieren möchten, müssen Sie MSAL4J und Microsoft Graph SDK Ihren Projekten mit Maven hinzufügen. Sie können die pom.xml-Datei und den Inhalt der Hilfs- und authservlets-Ordner im 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/groupswebapp/ 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 Gruppenanspruchs in Token, einschließlich der Handhabung von Überlastungen

In den folgenden Abschnitten wird beschrieben, wie die App einen Gruppenanspruch verarbeitet.

Der Gruppenanspruch

Die Objekt-ID der Sicherheitsgruppen, bei der der angemeldete Benutzer Mitglied ist, wird im Gruppenanspruch des Tokens zurückgegeben, wie im folgenden Beispiel gezeigt:

{
  ...
  "groups": [
    "0bbe91cc-b69e-414d-85a6-a043d6752215",
    "48931dac-3736-45e7-83e8-015e6dfd6f7c",]
  ...
}

Der Gruppenüberlastungsanspruch

Um sicherzustellen, dass die Tokengröße die Grenzwerte für HTTP-Header nicht überschreitet, schränkt die Microsoft Identity Platform die Anzahl der im Gruppenanspruch enthaltenen Objekt-IDs ein.

Die Überschreitungsgrenze beträgt 150 für SAML-Token, 200 für JWT-Token und 6 für Single-Page-Anwendungen. Wenn ein Benutzer Mitglied von mehr Gruppen ist, als die Obergrenze zulässt, gibt die Microsoft Identity Platform die Gruppen-IDs nicht im Gruppenanspruch im Token aus. Stattdessen ist ein Überschreitungsanspruch im Token enthalten, der der Anwendung anzeigt, dass die Microsoft Graph-API abgefragt werden soll, um die Gruppenmitgliedschaft des Benutzers abzurufen, wie im folgenden Beispiel gezeigt:

{
  ...
  "_claim_names": {
    "groups": "src1"
    },
    {
   "_claim_sources": {
    "src1": {
        "endpoint":"[Graph Url to get this user's group membership from]"
        }
    }
  ...
}

Erstellen des Überlastungsszenarios in diesem Beispiel zu Testzwecken

Zum Erstellen des Überlastungsszenarios können Sie die folgenden Schritte ausführen:

  1. Sie können die BulkCreateGroups.ps1-Datei im Ordner AppCreationScripts verwenden, um eine große Anzahl von Gruppen zu erstellen und ihnen Benutzer zuzuweisen. Diese Datei hilft beim Testen von Überlastungsszenarien während der Entwicklung. Denken Sie daran, die Benutzer-objectId im Skript BulkCreateGroups.ps1 zu ändern.

  2. Wenn Sie dieses Beispiel ausführen und eine Überlastung auftritt, wird auf der Startseite _claim_names angezeigt, nachdem sich der Benutzer angemeldet hat.

  3. Wir empfehlen dringend, dass Sie , wenn möglich, die Gruppenfilterfunktion, um Gruppenüberschreitung zu vermeiden. Weitere Informationen finden Sie im Abschnitt Konfigurieren der Anwendung für den Empfang der Gruppenanspruchswerte aus einem gefilterten Satz von Gruppen, denen ein Benutzer möglicherweise zugewiesen ist.

  4. Falls Sie eine Gruppenüberschreitung nicht vermeiden können, empfehlen wir Ihnen, die folgenden Schritte zu befolgen, um den Gruppenanspruch auf Ihrem Token zu bearbeiten:

    1. Suchen Sie nach dem Anspruch _claim_names mit einem der Werte Gruppen. Dieser Anspruch gibt eine Überschreitung an.
    2. Falls gefunden, rufen Sie den Endpunkt auf, der in _claim_sources angegeben ist, um die Gruppen des Benutzers abzurufen.
    3. Wenn nicht gefunden, sehen Sie sich den Gruppenanspruch für die Gruppen an.

Hinweis

Für die Verarbeitung von Überschreitungen ist ein Aufruf von Microsoft Graph erforderlich, um die Gruppenmitgliedschaften des angemeldeten Benutzers zu lesen. Daher muss Ihre App über die Berechtigung GroupMember.Read.All verfügen, damit die getMemberObjects-Funktion erfolgreich ausgeführt werden kann.

Weitere Informationen zur Programmierung für Microsoft Graph finden Sie im Video Eine Einführung in Microsoft Graph für Entwickler.

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

// handle groups overage if it has occurred.
handleGroupsOverage(contextAdapter);

  5. Nach dem vorherigen Schritt können Sie Gruppenmitgliedschaften extrahieren, indem Sie context.getGroups() eine Instanz von IdentityContextData verwenden.

  6. Wenn der Benutzer Mitglied von zu vielen Gruppen ist (mehr als 200) ist ein Aufruf an context.getGroups() möglicherweise leer, wenn es nicht der Aufruf von handleGroupsOverage() ist. In der Zwischenzeit context.getGroupsOverage() gibt true zurück und signalisiert damit, dass eine Überschreitung aufgetreten ist und das Abrufen der vollständigen Liste von Gruppen einen Aufruf von Microsoft Graph erfordert. Sehen Sie sich die handleGroupsOverage()-Methode in AuthHelper.java an, um zu sehen, wie diese Anwendung context.setGroups() verwendet, wenn eine Überschreitung vorhanden ist.

Schützen der Routen

Sehen Sie sich AuthenticationFilter.java an, um zu sehen, wie die Beispiel-App den Zugriff auf Routen filtert. 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 groups claim
app.protect.authenticated=/token_details

Alle Routen, die in den durch Trennzeichen getrennten Regelsätzen unter app.protect.groups 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 von Gruppenmitgliedschaften. Nur Benutzer, die mindestens einer der entsprechenden Gruppen angehören, können nach der Authentifizierung auf diese Routen zugreifen.

# define short names for group IDs here for the app. This is useful in the next property (app.protect.groups).
# EXCLUDE the curly braces, they are in this file only as delimiters.
# example:
# app.groups=groupA abcdef-qrstuvw-xyz groupB abcdef-qrstuv-wxyz
app.groups=admin {enter-your-admins-group-id-here}, user {enter-your-users-group-id-here}

# A route and its corresponding group(s) that can view it, <space-separated>; the start of the next route & its group(s) is delimited by a <comma-and-space-separator>
# this says: /admins_only can be accessed by admin group, /regular_user can be accessed by admin group and user group
app.protect.groups=/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. Standardmäßig legt die Anwendung den Bereichswert auf GroupMember.Read.All. Dieser spezielle Microsoft Graph-API-Bereich ist erforderlich, falls die Anwendung Graph aufrufen muss, um die Gruppenmitgliedschaften des Benutzers abzurufen.

Weitere Informationen

Nächster Schritt

Bereitstellen von Java WebSphere-Apps auf herkömmlichem WebSphere auf virtuellen Azure-Computern