Zabezpieczanie aplikacji Java Tomcat przy użyciu ról i oświadczeń ról

W tym artykule przedstawiono aplikację Java działającą w serwerze Tomcat, która używa OpenID Connect do logowania użytkowników oraz ról aplikacji Microsoft Entra ID (ról aplikacji) do autoryzacji.

Ta aplikacja realizuje kontrolę dostępu opartą na rolach (RBAC) przy użyciu ról aplikacji oraz funkcji oświadczeń o rolach w usłudze Microsoft Entra ID. Innym podejściem jest wykorzystanie grup Microsoft Entra ID i oświadczeń grupowych. Grupy Microsoft Entra ID i role aplikacji nie wykluczają się wzajemnie. Można ich użyć do zapewnienia szczegółowej kontroli dostępu.

Funkcję RBAC można również używać z rolami aplikacji i oświadczeniami ról, aby bezpiecznie wymuszać zasady autoryzacji.

Aby obejrzeć film omawiający ten scenariusz i ten przykład, zobacz Implementowanie autoryzacji w aplikacjach przy użyciu ról aplikacji, grup zabezpieczeń, zakresów i ról katalogu.

Aby uzyskać więcej informacji na temat działania protokołów w tym scenariuszu i w innych scenariuszach, zobacz Uwierzytelnianie a autoryzacja.

Ta aplikacja używa MSAL dla języka Java (MSAL4J) do logowania użytkownika i uzyskiwania tokenu ID z usługi Microsoft Entra ID.

W tym przykładzie najpierw użyto biblioteki MSAL dla języka Java (MSAL4J) do zalogowania użytkownika. Na stronie głównej wyświetla użytkownikowi opcję wyświetlania oświadczeń w tokenach identyfikatorów. Ta aplikacja umożliwia również użytkownikom wyświetlanie uprzywilejowanej strony administratora lub strony zwykłego użytkownika w zależności od przypisanej przez nich roli aplikacji. Chodzi o przedstawienie przykładu sposobu, w jaki w aplikacji dostęp do niektórych funkcji lub stron jest ograniczony do podzbiorów użytkowników w zależności od roli, do której należą.

Ten rodzaj autoryzacji jest realizowany przy użyciu mechanizmu RBAC. W przypadku kontroli dostępu opartej na rolach administrator udziela uprawnień do ról, a nie poszczególnym użytkownikom ani grupom. Administrator może następnie przypisywać role do różnych użytkowników i grup, aby kontrolować, kto ma dostęp do określonej zawartości i funkcji.

Ta przykładowa aplikacja definiuje następujące dwie role aplikacji:

• : Ma uprawnienia dostępu do stron Tylko administratorzy i Zwykli użytkownicy.
• : Ma uprawnienia dostępu do strony Zwykli użytkownicy.

Te role aplikacji są definiowane w portalu Azure w manifeście rejestracji aplikacji. Gdy użytkownik loguje się do aplikacji, identyfikator Entra firmy Microsoft emituje oświadczenie ról dla każdej roli przyznanej indywidualnie użytkownikowi w formie członkostwa w rolach.

Użytkownicy i grupy można przypisywać do ról za pośrednictwem witryny Azure Portal.

Uwaga

Roszczenia ról nie są dostępne dla użytkowników gościnnych w dzierżawie, jeśli punkt końcowy jest używany jako punkt autoryzacji do logowania użytkowników. Musisz zalogować użytkownika do punktu końcowego specyficznego dla dzierżawy, takiego jak .

Wymagania wstępne

• JDK w wersji 8 lub nowszej
• Maven 3
• Dzierżawa Microsoft Entra ID. Aby uzyskać więcej informacji, zobacz Jak uzyskać dzierżawę Microsoft Entra ID.
• Konto użytkownika we własnej dzierżawie usługi Microsoft Entra ID, jeśli chcesz pracować tylko z kontami w katalogu organizacyjnym — czyli w trybie pojedynczej dzierżawy. Jeśli nie utworzyłeś jeszcze konta użytkownika w swojej dzierżawie, powinieneś to zrobić, zanim przejdziesz dalej. Więcej informacji można znaleźć w artykule Jak tworzyć, zapraszać i usuwać użytkowników.

• Tomcat 9
• Visual Studio Code
• Narzędzia platformy Azure dla programu Visual Studio Code

Zalecenia

• Podstawowa znajomość serwletów Java / Jakarta.
• Pewna znajomość terminalu systemu Linux/OSX.
• jwt.ms do inspekcji tokenów.
• Fiddler do monitorowania aktywności sieciowej i diagnozowania problemów.
• Śledź blog Microsoft Entra, aby być na bieżąco z najnowszymi informacjami.

Skonfiguruj przykład

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

Alternatywnie, przejdź do repozytorium ms-identity-msal-java-samples, a następnie pobierz je jako plik .zip i rozpakuj na dysku twardym.

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.

Zarejestruj przykładową aplikację w dzierżawie Microsoft Entra ID

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ć swoje aplikacje

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

1. Zaloguj się do portalu Azure.

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

Zarejestruj aplikację (java-servlet-webapp-roles)

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

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

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

2. Wybierz opcjęNowa rejestracja.

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

   • W sekcji Name wprowadź sensowną nazwę aplikacji wyświetlaną użytkownikom aplikacji — na przykład .

   • W obszarze Obsługiwane typy kont wybierz jedną z następujących opcji:

     • Wybierz Konta tylko w tym katalogu organizacyjnym, jeśli tworzysz aplikację przeznaczoną do użytku wyłącznie przez użytkowników w Twojej dzierżawie — czyli aplikację z jedną dzierżawą.

   • W sekcji Identyfikator URI przekierowania wybierz Web w polu kombi i wprowadź następujący identyfikator URI przekierowania: .

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. Używasz tej wartości w pliku konfiguracyjnym aplikacji lub w plikach konfiguracyjnych aplikacji.

6. Wybierz Zapisz, aby zapisać zmiany.

7. Na stronie rejestracji aplikacji wybierz pozycję Certificates & secrets w panelu nawigacyjnym, aby otworzyć stronę, na której można wygenerować klucze tajne i przekazać certyfikaty.

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

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

10. Wybierz datę wygaśnięcia klucza tajnego lub określ niestandardowy okres ważności. Klucze tajne klienta mogą mieć maksymalny okres ważności wynoszący 24 miesiące, a firma Microsoft zaleca okres ważności krótszy niż 12 miesięcy. W przypadku aplikacji produkcyjnych preferuj certyfikat lub poświadczenie federacyjne tożsamości zamiast klucza tajnego klienta.

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.

Definiowanie ról aplikacji

Aby zdefiniować role aplikacji, wykonaj następujące kroki:

1. Nadal w tej samej rejestracji aplikacji wybierz pozycję App roles w panelu nawigacji.

2. Wybierz pozycję Utwórz rolę aplikacji, a następnie wprowadź następujące wartości:

   • W polu Nazwa wyświetlana wprowadź odpowiednią nazwę — na przykład PrivilegedAdmin.
   • W polu Dozwolone typy członków wybierz Użytkownik.
   • Dla Wartość wprowadź PrivilegedAdmin.
   • W polu Opis wpisz PrivilegedAdmins, którzy mogą wyświetlić stronę administratora.

3. Wybierz pozycję Utwórz rolę aplikacji, a następnie wprowadź następujące wartości:

   • W polu Nazwa wyświetlana wpisz odpowiednią nazwę — na przykład RegularUser.
   • W polu Dozwolone typy członków wybierz Użytkownik.
   • W polu Wartość wprowadź RegularUser.
   • W polu Opis wprowadź RegularUsers, którzy mogą wyświetlić stronę użytkownika.

4. Wybierz pozycję Zastosuj, aby zapisać zmiany.

Przypisywanie użytkowników do ról aplikacji

Aby dodać użytkowników do zdefiniowanej wcześniej roli aplikacji, postępuj zgodnie ze wskazówkami podanymi tutaj: Przypisywanie użytkowników i grup do ról.

---

Skonfiguruj aplikację (java-servlet-webapp-roles) tak, aby korzystała z rejestracji aplikacji

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

Uwaga

W poniższych krokach oznacza to samo co lub .

1. Otwórz projekt w środowisku IDE.

2. Otwórz plik authentication.properties.

3. Znajdź ciąg znaków . Zastąp istniejącą wartość identyfikatorem dzierżawy w usłudze Microsoft Entra ID.

4. Znajdź ciąg i zastąp istniejącą wartość identyfikatorem aplikacji lub aplikacji , skopiowanym z portalu Azure.

5. Znajdź ciąg znaków i zastąp istniejącą wartość wartością zapisaną podczas tworzenia aplikacji w witrynie Azure Portal.

6. Znajdź właściwość i upewnij się, że wartość jest ustawiona na , albo zastąp ją nazwami swoich konkretnych ról.

Skompiluj przykład

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 przedstawiono, jak wdrożyć przykład do usługi Azure App Service.

Wymagania wstępne

• Wtyczka Maven dla aplikacji Azure App Service

  Jeśli narzędzie Maven nie jest preferowanym narzędziem programistycznym, zobacz następujące podobne samouczki korzystające z innych narzędzi:

  • IntelliJ IDEA
  • Eclipse
  • Visual Studio Code

Konfigurowanie wtyczki Maven

Podczas wdrażania do usługi Azure App Service wdrożenie automatycznie używa poświadczeń platformy Azure z Azure CLI. 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 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 umożliwia skonfigurowanie systemu operacyjnego usługi Azure App Service, wersji języka Java i wersji serwera Tomcat.

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

2. Dla Utwórz nową konfigurację uruchomienia 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. Dla Zdefiniuj wartość dla javaVersion naciśnij 2, aby wybrać Java 11, a następnie naciśnij Enter.

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

6. Dla Zdefiniuj wartość parametru 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 wtyczki i ustawienia do pliku projektu pom.xml, aby skonfigurować aplikację do uruchamiania w usłudze Azure App 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	Wymagane	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 . Obsługiwane regiony znajdziesz w sekcji Obsługiwane regiony.
pricingTier	fałsz	Poziom cenowy Twojej aplikacji. Wartość domyślna to dla obciążenia produkcyjnego. Zalecana minimalna wartość dla programowania i testowania w języku Java to . 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. Informacje na temat tych konfiguracji można znaleźć w sekcji Typowe konfiguracje. Informacje o konfiguracjach dotyczących usługi Azure App Service można znaleźć w artykule Azure app: Configuration Details.

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

Przygotowywanie aplikacji do wdrożenia

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

1. Przejdź do pliku authentication.properties Twojej aplikacji i zmień wartość na nazwę domenową wdrożonej aplikacji, jak pokazano w poniższym przykładzie. Jeśli na przykład w poprzednim kroku jako nazwę aplikacji wybrano , teraz musisz użyć dla wartości . Upewnij się, że zmieniono także protokół z na .

   # 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 . Wdrożenie tej wartości w usłudze App Service nie jest dobrym rozwiązaniem. Nie jest też dobrą praktyką pozostawianie tej wartości w kodzie i potencjalne wypchnięcie jej do repozytorium Git. Aby usunąć tę wartość tajną z kodu, więcej szczegółowych wskazówek znajdziesz w sekcji Wdrażanie do usługi App Service — usuwanie wpisu tajnego. Te wskazówki dodają dodatkowe kroki dotyczące przekazywania wartości wpisu tajnego do Key Vault oraz korzystania z odwołań do usługi Key Vault.

Aktualizowanie rejestracji aplikacji Microsoft Entra ID

Ponieważ adres URI przekierowania zmienia się na adres wdrożonej aplikacji w Azure App Service, musisz również zmienić adres URI przekierowania w rejestracji aplikacji w Microsoft Entra ID. Aby wprowadzić tę zmianę, wykonaj następujące czynności:

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

2. Użyj pola wyszukiwania, aby znaleźć rejestrację aplikacji — na przykład .

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

4. Wybierz Uwierzytelnianie z menu.

5. W sekcji WebIdentyfikatory URI przekierowania wybierz pozycję Dodaj identyfikator URI.

6. Wpisz identyfikator URI Twojej aplikacji, dodając na końcu — na przykład .

7. Wybierz Zapisz.

Wdrażanie aplikacji

Możesz teraz wdrożyć swoją aplikację w usłudze Azure App Service. Użyj następującego polecenia, aby upewnić się, że zalogowano się do środowiska platformy Azure w celu wykonania wdrożenia:

az login

Mając już gotową całą konfigurację w pliku pom.xml, możesz teraz użyć następującego polecenia, aby wdrożyć aplikację w języku Java na platformie Azure:

mvn package azure-webapp:deploy

Po zakończeniu wdrożenia Twoja aplikacja jest dostępna pod adresem . Otwórz adres URL w lokalnej przeglądarce, w której powinna zostać wyświetlona strona początkowa aplikacji .

Aby uruchomić przykład na serwerze Tomcat, wykonaj następujące kroki:

1. W instalacji serwera Tomcat upewnij się, że istnieje wpis w pliku tomcat/conf/server.xml dla adresu, na którym chcesz hostować aplikację.

   Domyślnie przykłady zakładają połączenie z , zgodnie z definicją w wartości w pliku authentication.properties.

2. Skopiuj plik .war wygenerowany za pomocą Maven do katalogu /webapps/ w instalacji Tomcat, a następnie uruchom serwer Tomcat.

3. Po uruchomieniu serwera Tomcat otwórz przeglądarkę i przejdź do dowolnego adresu URL zdefiniowanego w kroku 1. Powinno być możliwe uzyskanie dostępu do aplikacji.

Poznaj przykład

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 ma napis Zaloguj się przy 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 zobaczyć niektóre zdekodowane oświadczenia tokenu identyfikatora.
7. Wybierz Tylko administratorzy, aby wyświetlić stronę . Tylko użytkownicy z rolą aplikacji mogą wyświetlać tę stronę. W przeciwnym razie zostanie wyświetlony komunikat o niepowodzeniu autoryzacji.
8. Wybierz Regular Users, aby wyświetlić stronę . Tylko użytkownicy z rolą aplikacji lub mogą wyświetlać tę stronę. W przeciwnym razie zostanie wyświetlony komunikat o niepowodzeniu autoryzacji.
9. Użyj przycisku w rogu, aby się wylogować.

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 ról. Na podstawie obecnego oświadczenia claim dotyczącego ról zalogowany użytkownik może nie mieć dostępu do żadnej, mieć dostęp do jednej albo do obu chronionych stron, i .

Jeśli chcesz odtworzyć działanie tego przykładu, możesz skopiować plik pom.xml oraz zawartość folderów helpers i authservlets znajdujących się 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/roles/	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 Języka Java z nazwami kończącymi się na Servlet.
src/main/java/com/microsoft/azuresamples/msal4j/helpers/	Klasy pomocnicze do uwierzytelniania.
AuthenticationFilter.java	Przekierowuje nieuwierzytelnione żądania kierowane do chronionych punktów końcowych na stronę błędu 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 wnoszenia wkładu do przykładu.
LICENCJA	Licencja przykładu.

Przetwarzaj oświadczenie o rolach w tokenie ID

Oświadczenie ról tokenu zawiera nazwy ról przypisanych do zalogowanego użytkownika, jak pokazano w poniższym przykładzie:

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

ConfidentialClientApplication

Instancja jest tworzona w pliku AuthHelper.java, jak pokazano w poniższym przykładzie. Ten obiekt pomaga utworzyć adres URL autoryzacji Microsoft Entra, a także wymienić token uwierzytelniający na token 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 instancji:

• Identyfikator klienta aplikacji.
• Klucz 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 wartości te 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 punktu końcowego w dzierżawie Microsoft Entra ID. Instancja MSAL4J służy do tworzenia 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:

   • : Parametry, które należy ustawić, aby utworzyć obiekt AuthorizationRequestUrl.
   • : Miejsce, do którego Microsoft Entra ID przekierowuje przeglądarkę — wraz z kodem autoryzacyjnym — po zebraniu poświadczeń użytkownika. Musi być zgodny z adresem URI przekierowania w rejestracji aplikacji Microsoft Entra ID w portalu Azure.
   • : Zakresy są uprawnieniami żądanymi przez aplikację.
     • Zwykle trzy zakresy wystarczą do otrzymania odpowiedzi zawierającej token identyfikacyjny.
     • Pełną listę zakresów żądanych przez aplikację można znaleźć w pliku authentication.properties . Możesz dodać więcej zakresów, takich jak .

2. Użytkownikowi jest wyświetlany monit 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 autoryzacyjny.

3. Instancja następnie wymienia ten kod autoryzacyjny na token identyfikacyjny i token dostępu z usługi Microsoft Entra ID.

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

   • : Parametry, które muszą zostać ustawione, aby wymienić kod autoryzacyjny na token identyfikacyjny i/lub token dostępu.
   • : Kod autoryzacji otrzymany w punkcie końcowym przekierowania.
   • : URI przekierowania użyty w poprzednim kroku należy ponownie przekazać.
   • : Zakresy użyte w poprzednim kroku należy ponownie przekazać.

4. Jeśli zakończy się pomyślnie, oświadczenia tokenu zostaną wyodrębnione. Jeśli weryfikacja nonce powiedzie się, wyniki są umieszczane w — instancji — i zapisywane w sesji. Aplikacja może następnie utworzyć instancję elementu z sesji za pośrednictwem instancji zawsze, gdy potrzebuje do niego dostępu, 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());
   

Ochrona tras

Aby uzyskać informacje na temat sposobu filtrowania dostępu do tras przez przykładową aplikację, zobacz AuthenticationFilter.java. W pliku authentication.properties właściwość zawiera rozdzielone przecinkami ścieżki, do których dostęp mają 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 roles claim(s)
app.protect.authenticated=/token_details

Każda z tras wymienionych w oddzielonych przecinkami zestawach reguł pod jest również niedostępna dla nieuwierzytelnionych użytkowników, jak pokazano na poniższym przykładzie. Jednak te ścieżki zawierają również oddzieloną spacjami listę przypisań do ról aplikacji: po uwierzytelnieniu dostęp do tych ścieżek mogą uzyskać tylko użytkownicy mający co najmniej jedną z odpowiednich ról.

# 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

Zakresy

Zakresy określają poziom dostępu, o który żąda aplikacja Microsoft Entra ID.

Na podstawie żądanych zakresów identyfikator Entra firmy Microsoft przedstawia użytkownikowi okno dialogowe zgody po zalogowaniu. Jeśli użytkownik wyrazi zgodę na co najmniej jeden zakres i uzyska token, zakresy, na które wyrażono zgodę, zostaną zakodowane w wynikowym .

Zakresy żądane przez aplikację znajdują się w pliku authentication.properties. Te trzy zakresy są domyślnie żądane przez MSAL i przyznawane przez Microsoft Entra ID.

Więcej informacji

• Biblioteka Microsoft Authentication Library (MSAL) dla języka Java
• Platforma tożsamości firmy Microsoft
• Szybki start: Rejestrowanie aplikacji w platformie tożsamości firmy Microsoft
• Opis procesu wyrażania zgody na aplikację Microsoft Entra ID
• Informacje o zgodzie użytkownika i administratora
• Przykłady kodu MSAL
• Jak: dodawać role aplikacji do aplikacji i odbierać je w tokenie
• Zarządzanie przypisywaniem użytkowników do aplikacji w Microsoft Entra ID