Udostępnij za pośrednictwem

Zabezpieczanie aplikacji Java Tomcat przy użyciu grup i oświadczeń grup

  • Artykuł

W tym artykule pokazano, jak utworzyć aplikację Java Tomcat, która loguje użytkowników przy użyciu biblioteki Microsoft Authentication Library (MSAL) dla języka Java. Aplikacja ogranicza również dostęp do stron na podstawie członkostwa w grupie zabezpieczeń Microsoft Entra ID.

Na poniższym diagramie przedstawiono topologię aplikacji:

Diagram przedstawiający topologię aplikacji.

Aplikacja kliencka używa biblioteki MSAL dla języka Java (MSAL4J), aby logować użytkowników do dzierżawy microsoft Entra ID i uzyskiwać token identyfikatora z identyfikatora Entra firmy Microsoft. Token identyfikatora potwierdza, że użytkownik jest uwierzytelniany w tej dzierżawie. Aplikacja chroni swoje trasy zgodnie ze stanem uwierzytelniania użytkownika i członkostwem w grupie.

Aby zapoznać się z filmem wideo obejmującym ten scenariusz, zobacz Implementowanie autoryzacji w aplikacjach przy użyciu ról aplikacji, grup zabezpieczeń, zakresów i ról katalogu.

Wymagania wstępne

Zalecenia

  • Znajomość serwletów Java/Dżakarta.
  • Pewna znajomość terminalu systemu Linux/OSX.
  • jwt.ms na potrzeby inspekcji tokenów.
  • Program Fiddler do monitorowania aktywności sieci i rozwiązywania problemów.
  • Postępuj zgodnie z blogiem Microsoft Entra ID, aby być na bieżąco z najnowszymi wydarzeniami.

Konfigurowanie przykładu

W poniższych sekcjach pokazano, jak skonfigurować przykładową aplikację.

Klonowanie lub pobieranie przykładowego repozytorium

Aby sklonować przykład, otwórz okno powłoki Bash i użyj następującego polecenia:

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

Alternatywnie przejdź do repozytorium ms-identity-msal-java-samples , a następnie pobierz go jako plik .zip i wyodrębnij go na dysk twardy.

Ważne

Aby uniknąć ograniczeń długości ścieżki pliku w systemie Windows, sklonuj lub wyodrębnij repozytorium do katalogu w pobliżu katalogu głównego dysku twardego.

Rejestrowanie przykładowej aplikacji w dzierżawie identyfikatora entra firmy Microsoft

W tym przykładzie istnieje jeden projekt. W poniższych sekcjach pokazano, jak zarejestrować aplikację przy użyciu witryny Azure Portal.

Wybierz dzierżawę microsoft Entra ID, w której chcesz utworzyć aplikacje

Aby wybrać dzierżawę, wykonaj następujące kroki:

  1. Zaloguj się w witrynie Azure Portal.

  2. Jeśli Twoje konto znajduje się w więcej niż jednej dzierżawie identyfikatora entra firmy Microsoft, wybierz swój profil w rogu witryny Azure Portal, a następnie wybierz pozycję Przełącz katalog , aby zmienić sesję na żądaną dzierżawę identyfikatora Entra firmy Microsoft.

Rejestrowanie aplikacji (java-servlet-webapp-groups)

Najpierw zarejestruj nową aplikację w witrynie Azure Portal, postępując zgodnie z instrukcjami w przewodniku Szybki start: rejestrowanie aplikacji przy użyciu Platforma tożsamości Microsoft.

Następnie wykonaj następujące kroki, aby ukończyć rejestrację:

  1. Przejdź do strony Platforma tożsamości Microsoft dla deweloperów Rejestracje aplikacji.

  2. Wybierz opcjęNowa rejestracja.

  3. Na wyświetlonej stronie Rejestrowanie aplikacji wprowadź następujące informacje o rejestracji aplikacji:

    • W sekcji Nazwa wprowadź zrozumiałą nazwę aplikacji do wyświetlania użytkownikom aplikacji — na przykład java-servlet-webapp-groups.
    • W obszarze Obsługiwane typy kont wybierz pozycję Konta tylko w tym katalogu organizacyjnym.
    • W sekcji Identyfikator URI przekierowania wybierz pozycję Sieć Web w polu kombi i wprowadź następujący identyfikator URI przekierowania: http://localhost:8080/msal4j-servlet-groups/auth/redirect.

  4. Wybierz pozycję Zarejestruj, aby utworzyć aplikację.

  5. Na stronie rejestracji aplikacji znajdź i skopiuj wartość Identyfikator aplikacji (klienta), aby użyć jej później. Ta wartość jest używana w pliku konfiguracji aplikacji lub plikach.

  6. Wybierz Zapisz, aby zapisać zmiany.

  7. Na stronie rejestracji aplikacji wybierz pozycję Certyfikaty i wpisy tajne w okienku nawigacji, aby otworzyć stronę, na której można wygenerować wpisy tajne i przekazać certyfikaty.

  8. W sekcji Klucze tajne klienta wybierz pozycję Nowy klucz tajny klienta.

  9. Wpisz opis — na przykład wpis tajny aplikacji.

  10. Wybierz jeden z dostępnych czasów trwania: W ciągu 1 roku w ciągu 2 lat lub Nigdy nie wygasa.

  11. Wybierz Dodaj. Zostanie wyświetlona wygenerowana wartość.

  12. Skopiuj i zapisz wygenerowaną wartość do użycia w kolejnych krokach. Ta wartość jest potrzebna dla plików konfiguracji kodu. Ta wartość nie jest ponownie wyświetlana i nie można jej pobrać w żaden inny sposób. Dlatego przed przejściem do innego ekranu lub okienka pamiętaj, aby zapisać go w witrynie Azure Portal.

  13. Na stronie rejestracji aplikacji wybierz pozycję Uprawnienia interfejsu API w okienku nawigacji, aby otworzyć stronę, aby dodać dostęp do interfejsów API wymaganych przez aplikację.

  14. Wybierz Dodaj uprawnienie.

  15. Upewnij się, że wybrano kartę Interfejsy API firmy Microsoft.

  16. W sekcji Często używane interfejsy API firmy Microsoft wybierz pozycję Microsoft Graph.

  17. W sekcji Uprawnienia delegowane wybierz pozycję User.Read i GroupMember.Read.Read.All z listy. W razie potrzeby użyj pola wyszukiwania.

  18. Wybierz Przyznaj uprawnienia.

  19. GroupMember.Read.All wymaga zgody administratora, dlatego wybierz pozycję Udziel/odwołaj zgodę administratora dla {tenant}, a następnie wybierz pozycję Tak , gdy zostanie wyświetlony monit o udzielenie zgody dla żądanych uprawnień dla wszystkich kont w dzierżawie. Aby wykonać tę akcję, musisz być administratorem dzierżawy identyfikatora entra firmy Microsoft.

Konfigurowanie aplikacji (java-servlet-webapp-groups) w celu korzystania z rejestracji aplikacji

Aby skonfigurować aplikację, wykonaj następujące kroki:

Uwaga

W poniższych krokach ClientID jest to samo co Application ID lub AppId.

  1. Otwórz projekt w środowisku IDE.

  2. Otwórz plik ./src/main/resources/authentication.properties.

  3. Znajdź ciąg {enter-your-tenant-id-here}. Zastąp istniejącą wartość identyfikatorem dzierżawy Microsoft Entra, jeśli zarejestrowano aplikację przy użyciu opcji Tylko konta w tym katalogu organizacyjnym.

  4. Znajdź ciąg {enter-your-client-id-here} i zastąp istniejącą wartość identyfikatorem aplikacji lub clientId java-servlet-webapp-groups aplikacją skopiowaną z witryny Azure Portal.

  5. Znajdź ciąg {enter-your-client-secret-here} i zastąp istniejącą wartość wartością zapisaną podczas tworzenia java-servlet-webapp-groups aplikacji w witrynie Azure Portal.

Konfigurowanie grup zabezpieczeń usługi

Dostępne są następujące opcje konfigurowania aplikacji w celu odbierania oświadczenia grup:

Uwaga

Aby uzyskać identyfikator grupy samAccountName lokalnej lub On Premises Group Security Identifier zamiast identyfikatora grupy, zobacz sekcję Wymagania wstępne dotyczące używania atrybutów grupy synchronizowane z usługi Active Directory w temacie Konfigurowanie oświadczeń grupy dla aplikacji przy użyciu identyfikatora Entra firmy Microsoft.

Skonfiguruj aplikację, aby otrzymywać wszystkie grupy przypisane do zalogowanego użytkownika, w tym grupy zagnieżdżone

Aby skonfigurować aplikację, wykonaj następujące kroki:

  1. Na stronie rejestracji aplikacji wybierz pozycję Konfiguracja tokenu w okienku nawigacji, aby otworzyć stronę, na której można skonfigurować oświadczenia dostarczone tokeny wystawione dla aplikacji.

  2. Wybierz pozycję Dodaj oświadczenie grup, aby otworzyć ekran Edytowanie oświadczeń grup.

  3. Wybierz opcję Grupy zabezpieczeń LUB Wszystkie grupy (w tym listy dystrybucyjne, ale nie grupy przypisane do aplikacji). Wybranie obu opcji neguje efekt opcji Grupy zabezpieczeń.

  4. W sekcji Identyfikator wybierz pozycję Identyfikator grupy. To zaznaczenie powoduje, że identyfikator Entra firmy Microsoft wysyła identyfikator obiektu grup, do których użytkownik jest przypisany w oświadczeniu grup tokenu identyfikatora odbieranego przez aplikację po zalogowaniu użytkownika.

Skonfiguruj aplikację, aby otrzymywać wartości oświadczeń grup z filtrowanego zestawu grup, do których może zostać przypisany użytkownik

Ta opcja jest przydatna, gdy spełnione są następujące przypadki:

  • Twoja aplikacja jest zainteresowana wybranym zestawem grup, do których może zostać przypisany użytkownik logowania.
  • Twoja aplikacja nie jest zainteresowana każdą grupą zabezpieczeń, do której ten użytkownik jest przypisany w dzierżawie.

Ta opcja pomaga aplikacji uniknąć problemu z nadwyżką .

Uwaga

Ta funkcja nie jest dostępna w wersji Microsoft Entra ID Free.

Przy użyciu tej opcji zagnieżdżone przypisania grup nie są dostępne.

Aby włączyć tę opcję w aplikacji, wykonaj następujące kroki:

  1. Na stronie rejestracji aplikacji wybierz pozycję Konfiguracja tokenu w okienku nawigacji, aby otworzyć stronę, na której można skonfigurować oświadczenia dostarczone tokeny wystawione dla aplikacji.

  2. Wybierz pozycję Dodaj oświadczenie grup, aby otworzyć ekran Edytowanie oświadczeń grup.

  3. Wybierz pozycję Grupy przypisane do aplikacji.

    Wybieranie innych opcji — takich jak Grupy zabezpieczeń lub Wszystkie grupy (w tym listy dystrybucyjne, ale nie przypisane do aplikacji) — neguje korzyści wynikające z korzystania z tej opcji przez aplikację.

  4. W sekcji Identyfikator wybierz pozycję Identyfikator grupy. Ten wybór powoduje, że identyfikator Entra firmy Microsoft wysyłający identyfikator obiektu grup, do których użytkownik jest przypisany w oświadczeniu grup tokenu identyfikatora.

  5. Jeśli udostępniasz internetowy interfejs API przy użyciu opcji Uwidaczniaj interfejs API , możesz również wybrać opcję Identyfikator grupy w sekcji Dostęp . Ta opcja powoduje, że identyfikator Entra firmy Microsoft wysyłający identyfikator obiektu grup, do których użytkownik jest przypisany w oświadczeniu grup tokenu dostępu.

  6. Na stronie rejestracji aplikacji wybierz pozycję Przegląd w okienku nawigacji, aby otworzyć ekran przeglądu aplikacji.

  7. Wybierz hiperlink z nazwą aplikacji w aplikacji zarządzanej w katalogu lokalnym. Ten tytuł pola może zostać obcięty — na przykład Managed application in .... Po wybraniu tego linku przejdź do strony Przegląd aplikacji dla przedsiębiorstw skojarzonej z jednostką usługi dla aplikacji w dzierżawie, w której została utworzona. Możesz wrócić do strony rejestracji aplikacji przy użyciu przycisku Wstecz przeglądarki.

  8. Wybierz pozycję Użytkownicy i grupy w okienku nawigacji, aby otworzyć stronę, na której można przypisać użytkowników i grupy do aplikacji.

  9. Wybierz Dodaj użytkownika.

  10. Wybierz pozycję Użytkownicy i grupy na ekranie wynikowym.

  11. Wybierz grupy, które chcesz przypisać do tej aplikacji.

  12. Wybierz pozycję Wybierz, aby zakończyć wybieranie grup.

  13. Wybierz pozycję Przypisz , aby zakończyć proces przypisywania grupy.

    Aplikacja odbiera teraz wybrane grupy w oświadczeniach grup, gdy użytkownik logujący się do aplikacji jest członkiem jednej lub kilku przypisanych grup.

  14. Wybierz pozycję Właściwości w okienku nawigacji, aby otworzyć stronę zawierającą podstawowe właściwości aplikacji. Ustaw flagę Wymagane przypisanie użytkownika? na Wartość Tak.

Ważne

Po ustawieniu wymaganego przypisania użytkownika? na wartość Tak, identyfikator entra firmy Microsoft sprawdza, czy tylko użytkownicy przypisani do aplikacji w okienku Użytkownicy i grupy będą mogli zalogować się do aplikacji. Możesz przypisywać użytkowników bezpośrednio lub przypisując grupy zabezpieczeń, do których należą.

Konfigurowanie aplikacji (java-servlet-webapp-groups) w celu rozpoznawania identyfikatorów grup

Aby skonfigurować aplikację, wykonaj następujące kroki:

Ważne

Na stronie Konfiguracja tokenu, jeśli wybrano dowolną opcję inną niż groupID — na przykład DNSDomain\sAMAccountName — należy wprowadzić nazwę grupy w następujących krokach — na przykład contoso.com\Test Group — zamiast identyfikatora obiektu:

  1. Otwórz plik ./src/main/resources/authentication.properties.

  2. Znajdź ciąg {enter-your-admins-group-id-here} i zastąp istniejącą wartość identyfikatorem GroupAdmin obiektu grupy skopiowaną z witryny Azure Portal. Usuń nawiasy klamrowe z wartości symbolu zastępczego.

  3. Znajdź ciąg {enter-your-users-group-id-here} i zastąp istniejącą wartość identyfikatorem GroupMember obiektu grupy skopiowaną z witryny Azure Portal. Usuń nawiasy klamrowe z wartości symbolu zastępczego.

Tworzenie przykładu

Aby skompilować przykład przy użyciu narzędzia Maven, przejdź do katalogu zawierającego plik pom.xml dla przykładu, a następnie uruchom następujące polecenie:

mvn clean package

To polecenie generuje plik war , który można uruchomić na różnych serwerach aplikacji.

Uruchamianie aplikacji przykładowej

W poniższych sekcjach pokazano, jak wdrożyć przykład w usłudze aplikacja systemu Azure Service.

Wymagania wstępne

Konfigurowanie wtyczki Maven

Podczas wdrażania w usłudze aplikacja systemu Azure wdrożenie automatycznie używa poświadczeń platformy Azure z poziomu interfejsu wiersza polecenia platformy Azure. Jeśli interfejs wiersza polecenia platformy Azure nie jest zainstalowany lokalnie, wtyczka Maven uwierzytelnia się przy użyciu protokołu OAuth lub logowania urządzenia. Aby uzyskać więcej informacji, zobacz authentication with Maven plugins (Uwierzytelnianie za pomocą wtyczek maven).

Aby skonfigurować wtyczkę, wykonaj następujące czynności:

  1. Uruchom następujące polecenie, aby skonfigurować wdrożenie. To polecenie pomaga skonfigurować system operacyjny usługi aplikacja systemu Azure, wersję języka Java i wersję serwera Tomcat.

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

  2. W obszarze Utwórz nową konfigurację przebiegu naciśnij Y, a następnie naciśnij Enter.

  3. W polu Zdefiniuj wartość dla systemu operacyjnego naciśnij 1 dla systemu Windows lub 2 dla systemu Linux, a następnie naciśnij Enter.

  4. W polu Zdefiniuj wartość dla javaVersion naciśnij 2 dla języka Java 11, a następnie naciśnij Enter.

  5. W polu Zdefiniuj wartość dla elementu webContainer naciśnij 4 dla serwera Tomcat 9.0, a następnie naciśnij Enter.

  6. W polu Zdefiniuj wartość dla wartości pricingTier naciśnij Enter , aby wybrać domyślną warstwę P1v2 .

  7. Aby potwierdzić, naciśnij Y, a następnie naciśnij Enter.

W poniższym przykładzie przedstawiono dane wyjściowe procesu wdrażania:

Please confirm webapp properties
AppName : msal4j-servlet-auth-1707209552268
ResourceGroup : msal4j-servlet-auth-1707209552268-rg
Region : centralus
PricingTier : P1v2
OS : Linux
Java Version: Java 11
Web server stack: Tomcat 9.0
Deploy to slot : false
Confirm (Y/N) [Y]: [INFO] Saving configuration to pom.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  37.112 s
[INFO] Finished at: 2024-02-06T08:53:02Z
[INFO] ------------------------------------------------------------------------

Po potwierdzeniu wybranych opcji wtyczka dodaje wymagany element i ustawienia wtyczki do pliku pom.xml projektu w celu skonfigurowania aplikacji do uruchamiania w usłudze aplikacja systemu Azure Service.

Odpowiednia część pliku pom.xml powinna wyglądać podobnie do poniższego przykładu:

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

Konfiguracje usługi App Service można modyfikować bezpośrednio w pom.xml. Niektóre typowe konfiguracje są wymienione w poniższej tabeli:

Właściwości Wymagania opis
subscriptionId fałsz Identyfikator subskrypcji.
resourceGroup prawda Grupa zasobów platformy Azure dla aplikacji.
appName prawda Nazwa aplikacji.
region fałsz Region, w którym ma być hostowana aplikacja. Domyślna wartość to centralus. Aby zapoznać się z prawidłowymi regionami, zobacz Obsługiwane regiony.
pricingTier fałsz Warstwa cenowa aplikacji. Wartość domyślna dotyczy P1v2 obciążenia produkcyjnego. Zalecaną minimalną wartością dla programowania i testowania języka Java jest B2. Aby uzyskać więcej informacji, zobacz Cennik usługi App Service.
runtime fałsz Konfiguracja środowiska uruchomieniowego. Aby uzyskać więcej informacji, zobacz Szczegóły konfiguracji.
deployment fałsz Konfiguracja wdrożenia. Aby uzyskać więcej informacji, zobacz Szczegóły konfiguracji.

Pełną listę konfiguracji można znaleźć w dokumentacji referencyjnej wtyczki. Wszystkie wtyczki usługi Azure Maven mają wspólny zestaw konfiguracji. Aby uzyskać te konfiguracje, zobacz Typowe konfiguracje. Aby uzyskać konfiguracje specyficzne dla usługi aplikacja systemu Azure, zobacz Azure app: Configuration Details (Aplikacja platformy Azure: szczegóły konfiguracji).

Pamiętaj, aby zapisać wartości i resourceGroup do późniejszego appName użycia.

Przygotowywanie aplikacji do wdrożenia

Podczas wdrażania aplikacji w usłudze App Service adres URL przekierowania zmieni się na adres URL przekierowania wdrożonego wystąpienia aplikacji. Aby zmienić te ustawienia w pliku właściwości, wykonaj następujące czynności:

  1. Przejdź do pliku authentication.properties aplikacji i zmień wartość app.homePage na nazwę domeny wdrożonej aplikacji, jak pokazano w poniższym przykładzie. Jeśli na przykład wybrano example-domain nazwę aplikacji w poprzednim kroku, musisz teraz użyć https://example-domain.azurewebsites.net wartości app.homePage . Upewnij się, że protokół został również zmieniony z http na https.

    # 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. Po zapisaniu tego pliku użyj następującego polecenia, aby ponownie skompilować aplikację:

    mvn clean package

Ważne

W tym samym pliku authentication.properties masz ustawienie dla pliku aad.secret. Wdrożenie tej wartości w usłudze App Service nie jest dobrym rozwiązaniem. Nie jest dobrym rozwiązaniem, aby pozostawić tę wartość w kodzie i potencjalnie wypchnąć ją do repozytorium Git. Aby usunąć tę wartość wpisu tajnego z kodu, możesz znaleźć bardziej szczegółowe wskazówki w sekcji Wdrażanie w usłudze App Service — Usuwanie wpisu tajnego . Te wskazówki dodają dodatkowe kroki wypychania wartości wpisu tajnego do usługi Key Vault i używania odwołań usługi Key Vault.

Aktualizowanie rejestracji aplikacji Microsoft Entra ID

Ponieważ identyfikator URI przekierowania zmienia się w wdrożonej aplikacji w usłudze aplikacja systemu Azure, musisz również zmienić identyfikator URI przekierowania w rejestracji aplikacji Microsoft Entra ID. Aby wprowadzić tę zmianę, wykonaj następujące czynności:

  1. Przejdź do strony Platforma tożsamości Microsoft dla deweloperów Rejestracje aplikacji.

  2. Użyj pola wyszukiwania, aby wyszukać rejestrację aplikacji — na przykład java-servlet-webapp-authentication.

  3. Otwórz rejestrację aplikacji, wybierając jej nazwę.

  4. Wybierz Uwierzytelnianie z menu poleceń.

  5. W sekcji Identyfikatory URI przekierowania sieci Web - wybierz pozycję Dodaj identyfikator URI.

  6. Wypełnij identyfikator URI aplikacji, dołączając /auth/redirect na przykład https://<your-app-name>.azurewebsites.net/auth/redirect.

  7. Wybierz pozycję Zapisz.

Wdrażanie aplikacji

Teraz możesz przystąpić do wdrażania aplikacji w usłudze aplikacja systemu Azure Service. Użyj następującego polecenia, aby upewnić się, że zalogowano się do środowiska platformy Azure w celu wykonania wdrożenia:

az login

Po korzystaniu ze wszystkich konfiguracji gotowych w pliku pom.xml możesz teraz użyć następującego polecenia, aby wdrożyć aplikację Java na platformie Azure:

mvn package azure-webapp:deploy

Po zakończeniu wdrażania aplikacja jest gotowa pod adresem http://<your-app-name>.azurewebsites.net/. Otwórz adres URL w lokalnej przeglądarce internetowej, gdzie powinna zostać wyświetlona strona początkowa msal4j-servlet-auth aplikacji.

Eksplorowanie przykładu

Aby zapoznać się z przykładem, wykonaj następujące czynności:

  1. Zwróć uwagę na stan logowania lub wylogowania wyświetlany na środku ekranu.
  2. Wybierz przycisk kontekstowy w rogu. Ten przycisk odczytuje pozycję Zaloguj po pierwszym uruchomieniu aplikacji.
  3. Na następnej stronie postępuj zgodnie z instrukcjami i zaloguj się przy użyciu konta w dzierżawie Microsoft Entra ID.
  4. Na ekranie zgody zwróć uwagę na żądane zakresy.
  5. Zwróć uwagę, że przycisk kontekstowy zawiera teraz pozycję Wyloguj się i wyświetla swoją nazwę użytkownika.
  6. Wybierz pozycję Szczegóły tokenu identyfikatora, aby wyświetlić niektóre zdekodowane oświadczenia tokenu identyfikatora.
  7. Wybierz pozycję Grupy , aby wyświetlić wszelkie informacje o członkostwie w grupie zabezpieczeń dla zalogowanego użytkownika.
  8. Wybierz pozycję Tylko administrator lub Zwykły użytkownik , aby uzyskać dostęp do chronionych punktów końcowych oświadczeń grup.
    • Jeśli zalogowany użytkownik znajduje się w GroupAdmin grupie, użytkownik może wprowadzić obie strony.
    • Jeśli zalogowany użytkownik znajduje się w GroupMember grupie, użytkownik może wprowadzić tylko stronę Zwykły użytkownik .
    • Jeśli zalogowany użytkownik nie znajduje się w żadnej grupie, użytkownik nie może uzyskać dostępu do żadnej z dwóch stron.
  9. Użyj przycisku w rogu, aby się wylogować.
  10. Po wylogowaniu wybierz pozycję Szczegóły tokenu identyfikatora, aby zobaczyć, że aplikacja wyświetla 401: unauthorized błąd zamiast oświadczeń tokenu identyfikatora, gdy użytkownik nie jest autoryzowany.

Informacje o kodzie

W tym przykładzie użyto biblioteki MSAL dla języka Java (MSAL4J), aby zalogować użytkownika i uzyskać token identyfikatora, który może zawierać oświadczenie grup. Jeśli w tokenie identyfikatora istnieje zbyt wiele grup emisji, w przykładzie użyto zestawu Microsoft Graph SDK dla języka Java w celu uzyskania danych członkostwa w grupie z programu Microsoft Graph. Na podstawie grup, do których należy użytkownik, zalogowany użytkownik może uzyskać dostęp do żadnej, jednej lub obu stron Admins Only chronionych oraz Regular Users.

Jeśli chcesz replikować zachowanie tego przykładu, musisz dodać zestaw MSAL4J i zestaw Microsoft Graph SDK do projektów przy użyciu narzędzia Maven. Możesz skopiować plik pom.xml i zawartość folderów pomocników i authservlets w folderze src/main/java/com/microsoft/azuresamples/msal4j . Potrzebny jest również plik authentication.properties . Te klasy i pliki zawierają kod ogólny, którego można użyć w szerokiej gamie aplikacji. Możesz również skopiować resztę przykładu, ale inne klasy i pliki są kompilowane specjalnie w celu rozwiązania tego przykładu celu.

Zawartość

W poniższej tabeli przedstawiono zawartość przykładowego folderu projektu:

Plik/folder opis
src/main/java/com/microsoft/azuresamples/msal4j/groupswebapp/ Ten katalog zawiera klasy definiujące logikę biznesową zaplecza aplikacji.
src/main/java/com/microsoft/azuresamples/msal4j/authservlets/ Ten katalog zawiera klasy używane do logowania i wylogowyywania punktów końcowych.
____Servlet.java Wszystkie dostępne punkty końcowe są definiowane w klasach .java kończących się na ____Servlet.java.
src/main/java/com/microsoft/azuresamples/msal4j/helpers/ Klasy pomocnika na potrzeby uwierzytelniania.
AuthenticationFilter.java Przekierowuje nieuwierzytelnione żądania do chronionych punktów końcowych do strony 401.
src/main/resources/authentication.properties Microsoft Entra ID i konfiguracja programu.
src/main/webapp/ Ten katalog zawiera szablony interfejsu użytkownika — JSP
CHANGELOG.md Lista zmian w przykładzie.
CONTRIBUTING.md Wskazówki dotyczące współtworzenia przykładu.
LICENCJA Licencja dla przykładu.

Przetwarzanie oświadczeń grup w tokenach, w tym obsługa nadwyżki

W poniższych sekcjach opisano sposób przetwarzania oświadczenia grup przez aplikację.

Oświadczenie grup

Identyfikator obiektu grup zabezpieczeń zalogowany użytkownik jest członkiem jest zwracany w oświadczeniach grup tokenu, jak pokazano w poniższym przykładzie:

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

Oświadczenie dotyczące nadwyżki grup

Aby upewnić się, że rozmiar tokenu nie przekracza limitów rozmiaru nagłówka HTTP, Platforma tożsamości Microsoft ogranicza liczbę identyfikatorów obiektów uwzględnionych w oświadczeniach grup.

Limit nadwyżki wynosi 150 dla tokenów SAML, 200 dla tokenów JWT i 6 dla aplikacji jednostronicowych. Jeśli użytkownik należy do większej liczby grup niż limit nadwyżki, Platforma tożsamości Microsoft nie emituje identyfikatorów grup w oświadczeniach grup w tokenie. Zamiast tego zawiera oświadczenie nadwyżkowe w tokenie, który wskazuje aplikacji na wykonywanie zapytań względem interfejsu API programu Microsoft Graph w celu pobrania członkostwa w grupie użytkownika, jak pokazano w poniższym przykładzie:

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

Tworzenie scenariusza nadwyżkowego w tym przykładzie na potrzeby testowania

Aby utworzyć scenariusz nadwyżki, możesz wykonać następujące kroki:

  1. Możesz użyć pliku BulkCreateGroups.ps1 udostępnionego w folderze AppCreationScripts , aby utworzyć dużą liczbę grup i przypisać do nich użytkowników. Ten plik pomaga przetestować scenariusze nadwyżkowe podczas programowania. Pamiętaj, aby zmienić ustawienia podane przez użytkownika objectId w skrypcie BulkCreateGroups.ps1 .

  2. Po uruchomieniu tego przykładu i wystąpieniu nadwyżki zobaczysz _claim_names na stronie głównej po zalogowaniu się użytkownika.

  3. Zdecydowanie zalecamy użycie funkcji filtrowania grup, jeśli jest to możliwe, aby uniknąć nadmiernego użycia grup. Aby uzyskać więcej informacji, zobacz sekcję Konfigurowanie aplikacji w celu odbierania wartości oświadczeń grup z filtrowanego zestawu grup, do których może zostać przypisany użytkownik.

  4. Jeśli nie możesz uniknąć nadmiernego użycia grup, zalecamy wykonanie następujących kroków w celu przetworzenia oświadczenia grup w tokenie:

    1. Sprawdź oświadczenie _claim_names z jedną z wartości, które są grupami. To oświadczenie wskazuje nadwyżkę.
    2. Jeśli zostanie znaleziona, wykonaj wywołanie punktu końcowego określonego w _claim_sources pliku w celu pobrania grup użytkowników.
    3. Jeśli żadna z nich nie zostanie znaleziona, zapoznaj się z oświadczeniem grup dla grup użytkowników.

Uwaga

Obsługa nadwyżki wymaga wywołania programu Microsoft Graph w celu odczytania członkostwa w grupach zalogowanego użytkownika, więc aplikacja musi mieć uprawnienie GroupMember.Read.All do pomyślnego wykonania funkcji getMemberObjects.

Aby uzyskać więcej informacji na temat programowania dla programu Microsoft Graph, zobacz wideo Wprowadzenie do programu Microsoft Graph dla deweloperów.

ConfidentialClientApplication

Wystąpienie ConfidentialClientApplication jest tworzone w pliku AuthHelper.java , jak pokazano w poniższym przykładzie. Ten obiekt pomaga utworzyć adres URL autoryzacji entra firmy Microsoft, a także ułatwia wymianę tokenu uwierzytelniania dla tokenu dostępu.

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

Następujące parametry są używane do tworzenia wystąpień:

  • Identyfikator klienta aplikacji.
  • Wpis tajny klienta, który jest wymagany w przypadku poufnych aplikacji klienckich.
  • Urząd Microsoft Entra ID, który zawiera identyfikator dzierżawy firmy Microsoft Entra.

W tym przykładzie te wartości są odczytywane z pliku authentication.properties przy użyciu czytnika właściwości w pliku Config.java .

Przewodnik krok po kroku

Poniższe kroki zawierają przewodnik po funkcjonalności aplikacji:

  1. Pierwszym krokiem procesu logowania jest wysłanie żądania do /authorize punktu końcowego dla dzierżawy microsoft Entra ID. Wystąpienie MSAL4J ConfidentialClientApplication służy do konstruowania adresu URL żądania autoryzacji. Aplikacja przekierowuje przeglądarkę do tego adresu URL, w którym loguje się użytkownik.

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

    Poniższa lista zawiera opis funkcji tego kodu:

    • AuthorizationRequestUrlParameters: parametry, które należy ustawić w celu utworzenia elementu AuthorizationRequestUrl.
    • REDIRECT_URI: Gdzie firma Microsoft Entra przekierowuje przeglądarkę — wraz z kodem uwierzytelniania — po zebraniu poświadczeń użytkownika. Musi być zgodny z identyfikatorem URI przekierowania w rejestracji aplikacji Microsoft Entra ID w witrynie Azure Portal.
    • SCOPES: Zakresy są uprawnieniami żądanymi przez aplikację.
      • Zwykle trzy zakresy openid profile offline_access są wystarczające do otrzymania odpowiedzi tokenu identyfikatora.
      • Pełną listę zakresów żądanych przez aplikację można znaleźć w pliku authentication.properties . Możesz dodać więcej zakresów, takich jak User.Read.

  2. Użytkownik jest wyświetlany z monitem logowania przez microsoft Entra ID. Jeśli próba logowania zakończy się pomyślnie, przeglądarka użytkownika zostanie przekierowana do punktu końcowego przekierowania aplikacji. Prawidłowe żądanie do tego punktu końcowego zawiera kod autoryzacji.

  3. Następnie ConfidentialClientApplication wystąpienie wymienia ten kod autoryzacji dla tokenu identyfikatora i tokenu dostępu z identyfikatora entra firmy Microsoft.

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

    Poniższa lista zawiera opis funkcji tego kodu:

    • AuthorizationCodeParameters: Parametry, które należy ustawić w celu wymiany kodu autoryzacji dla identyfikatora i/lub tokenu dostępu.
    • authCode: kod autoryzacji, który został odebrany w punkcie końcowym przekierowania.
    • REDIRECT_URI: Identyfikator URI przekierowania użyty w poprzednim kroku musi zostać ponownie przekazany.
    • SCOPES: zakresy używane w poprzednim kroku muszą zostać ponownie przekazane.

  4. W przypadku acquireToken pomyślnego wyodrębnienia oświadczeń tokenu. Jeśli sprawdzanie nie jest sprawdzane, wyniki są umieszczane w context — wystąpieniu IdentityContextData — i zapisywane w sesji. Następnie aplikacja może utworzyć wystąpienie IdentityContextData z sesji za pomocą wystąpienia IdentityContextAdapterServlet zawsze, gdy potrzebuje dostępu do niej, jak pokazano w poniższym kodzie:

    // 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. Po poprzednim kroku można wyodrębnić członkostwa w grupach, wywołując context.getGroups() wystąpienie klasy IdentityContextData.

  6. Jeśli użytkownik jest członkiem zbyt wielu grup — więcej niż 200 — wywołanie context.getGroups() może być puste, jeśli nie wywołanie metody handleGroupsOverage(). W międzyczasie context.getGroupsOverage() zwraca wartość true, sygnalizując, że wystąpiła nadwyżka i że uzyskanie pełnej listy grup wymaga wywołania programu Microsoft Graph. Zobacz metodę handleGroupsOverage() w AuthHelper.java , aby zobaczyć, jak ta aplikacja używa context.setGroups() , gdy występuje nadwyżka.

Ochrona tras

Zobacz AuthenticationFilter.java , aby zobaczyć, jak przykładowa aplikacja filtruje dostęp do tras. W pliku authentication.properties właściwość zawiera rozdzielane przecinkami trasy, app.protect.authenticated do których mogą uzyskiwać dostęp tylko uwierzytelnieni użytkownicy, jak pokazano w poniższym przykładzie:

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

Wszystkie trasy wymienione w zestawach app.protect.groups reguł rozdzielanych przecinkami są również poza limitami dla nieuwierzytelnionego uwierzytelnionego użytkownika, jak pokazano w poniższym przykładzie. Jednak te trasy zawierają również rozdzielaną spacjami listę członkostwa w grupach. Tylko użytkownicy należący do co najmniej jednej z odpowiednich grup mogą uzyskiwać dostęp do tych tras po uwierzytelnieniu.

# 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

Zakresy

Zakresy informują microsoft Entra ID o poziomie dostępu, którego żąda aplikacja.

Na podstawie żądanych zakresów identyfikator Entra firmy Microsoft przedstawia użytkownikowi okno dialogowe zgody po zalogowaniu. Jeśli użytkownik wyraża zgodę na co najmniej jeden zakres i uzyskuje token, wyrażenie zgody zakresów zostanie zakodowane w wynikowym access_tokenobiekcie .

Aby uzyskać zakresy żądane przez aplikację, zobacz authentication.properties. Domyślnie aplikacja ustawia wartość zakresów na GroupMember.Read.Allwartość . Ten konkretny zakres interfejsu API programu Microsoft Graph jest wymagany w przypadku, gdy aplikacja musi wywołać program Graph w celu uzyskania członkostwa w grupach użytkownika.

Więcej informacji