Zabezpieczanie aplikacji Quarkus przy użyciu identyfikatora Entra firmy Microsoft przy użyciu protokołu OpenID Connect

W tym artykule pokazano, jak zabezpieczyć aplikacje Red Hat Quarkus za pomocą identyfikatora Entra firmy Microsoft przy użyciu protokołu OpenID Connect (OIDC).

W tym artykule omówiono sposób wykonywania następujących zadań:

• Skonfiguruj dostawcę openID Connect przy użyciu identyfikatora Entra firmy Microsoft.
• Chroń aplikację Quarkus przy użyciu protokołu OpenID Connect.
• Uruchom i przetestuj aplikację Quarkus.

Wymagania wstępne

• Subskrypcja platformy Azure. Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto.
• Tożsamość platformy Azure z co najmniej rolą Administratora aplikacji w chmurze firmy Microsoft. Aby uzyskać więcej informacji, zobacz List Microsoft Entra role assignments and Microsoft Entra built-in roles (Wyświetlanie listy przypisań ról firmy Microsoft entra) i Microsoft Entra wbudowanych ról.
• Dzierżawa firmy Microsoft Entra. Jeśli nie masz istniejącej dzierżawy, zobacz Szybki start: Konfigurowanie dzierżawy.
• Maszyna lokalna z zainstalowanym systemem operacyjnym przypominającym system Unix — na przykład Ubuntu, macOS lub Podsystem Windows dla systemu Linux.
• Git.
• Implementacja środowiska Java SE w wersji 21 lub nowszej — na przykład kompilacja microsoft openJDK.
• Maven, wersja 3.9.3 lub nowsza.

Konfigurowanie dostawcy openID Connect za pomocą identyfikatora entra firmy Microsoft

W tej sekcji skonfigurujesz dostawcę openID Connect z identyfikatorem Entra firmy Microsoft do użycia z aplikacją Quarkus. W późniejszej sekcji skonfigurujesz aplikację Quarkus przy użyciu protokołu OpenID Connect, aby uwierzytelnić i autoryzować użytkowników w dzierżawie firmy Microsoft Entra.

Tworzenie użytkowników w dzierżawie firmy Microsoft Entra

Najpierw utwórz dwóch użytkowników w dzierżawie firmy Microsoft Entra, wykonując kroki opisane w temacie Jak utworzyć, zaprosić i usunąć użytkowników. Potrzebujesz tylko sekcji Tworzenie nowego użytkownika . Skorzystaj z poniższych wskazówek, przechodząc przez ten artykuł, a następnie wróć do tego artykułu po utworzeniu użytkowników w dzierżawie firmy Microsoft Entra.

Aby utworzyć użytkownika, który będzie służył jako "administrator" w aplikacji, wykonaj następujące kroki:

1. Po dotarciu do karty Podstawowe w sekcji Tworzenie nowego użytkownika wykonaj następujące kroki:

   1. W polu Główna nazwa użytkownika wprowadź wartość admin. Zapisz wartość, aby można było jej użyć później podczas logowania się do aplikacji.

   2. W polu Pseudonim poczty wybierz pozycję Pochodne od głównej nazwy użytkownika

   3. W polu Nazwa wyświetlana wprowadź wartość Administrator.

   4. W polu Hasło wybierz pozycję Automatycznie generuj hasło. Skopiuj i zapisz wartość Hasło , która będzie używana później podczas logowania się do aplikacji.

   5. Wybierz pozycję Konto włączone.

      

   6. Wybierz pozycję Przeglądanie + tworzenie>Utwórz. Poczekaj na utworzenie użytkownika.

   7. Poczekaj minutę i wybierz pozycję Odśwież. Na liście powinien zostać wyświetlony nowy użytkownik.

Aby utworzyć użytkownika, który będzie służył jako "użytkownik" w aplikacji, powtórz następujące kroki, ale użyj następujących wartości:

• W polu Główna nazwa użytkownika wprowadź wartość user.
• W polu Nazwa wyświetlana wprowadź wartość User (Użytkownik).

Rejestrowanie aplikacji w identyfikatorze Entra firmy Microsoft

Następnie zarejestruj aplikację, wykonując kroki opisane w przewodniku Szybki start: rejestrowanie aplikacji przy użyciu Platforma tożsamości Microsoft. Skorzystaj z poniższych wskazówek, przechodząc przez ten artykuł, a następnie wróć do tego artykułu po zarejestrowaniu i skonfigurowaniu aplikacji.

1. Po dotarciu do sekcji Rejestrowanie aplikacji wykonaj następujące kroki:
   1. W obszarze Obsługiwane typy kont wybierz pozycję Konta tylko w tym katalogu organizacyjnym (tylko katalog domyślny — pojedyncza dzierżawa).
   2. Po zakończeniu rejestracji zapisz wartości identyfikatora aplikacji (klienta) i identyfikatora katalogu (dzierżawy), które będą używane w dalszej części konfiguracji aplikacji.
2. Po dotarciu do sekcji Dodawanie identyfikatora URI przekierowania pomiń kroki tak jak na razie. Identyfikator URI przekierowania zostanie dodany później podczas uruchamiania i testowania przykładowej aplikacji lokalnie w tym artykule.
3. Po dotarciu do sekcji Dodawanie poświadczeń wybierz kartę Dodaj klucz tajny klienta.
4. Po dodaniu wpisu tajnego klienta zapisz wartość klucza tajnego klienta do późniejszego użycia w konfiguracji aplikacji.

Dodawanie ról aplikacji do aplikacji

Następnie dodaj role aplikacji do aplikacji, wykonując kroki opisane w temacie Dodawanie ról aplikacji do aplikacji i odbieranie ich w tokenie. Potrzebujesz tylko sekcji Deklarowanie ról dla aplikacji oraz Przypisywanie użytkowników i grup do ról firmy Microsoft Entra. Skorzystaj z poniższych wskazówek, przechodząc przez ten artykuł, a następnie wróć do tego artykułu po zadeklarowaniu ról dla aplikacji.

1. Po dotarciu do sekcji Deklarowanie ról dla aplikacji użyj interfejsu użytkownika ról aplikacji, aby utworzyć role dla administratora i zwykłego użytkownika.

   1. Utwórz rolę użytkownika administratora przy użyciu następujących wartości:

      • W polu Nazwa wyświetlana wprowadź wartość Administrator.
      • W obszarze Dozwolone typy elementów członkowskich wybierz pozycję Użytkownicy/grupy.
      • W polu Wartość wprowadź wartość admin.
      • W polu Opis wprowadź wartość Administrator.
      • Wybierz pozycję Czy chcesz włączyć tę rolę aplikacji?.

      

   2. Wybierz Zastosuj. Poczekaj na utworzenie roli.

   3. Utwórz zwykłą rolę użytkownika przy użyciu tych samych kroków, ale z następującymi wartościami:

      • W polu Nazwa wyświetlana wprowadź wartość User (Użytkownik).
      • W polu Wartość wprowadź wartość użytkownika.
      • W polu Opis wprowadź wartość User (Użytkownik).

      

2. Gdy dotrzesz do sekcji Przypisywanie użytkowników i grup do ról firmy Microsoft Entra, wykonaj następujące kroki:

   1. Wybierz pozycję Dodaj użytkownika/grupę.

   2. W okienku Dodawanie przypisania w obszarze Użytkownicy wybierz pozycję Administrator użytkownika, a w obszarze Wybierz rolę wybierz pozycję Administrator roli. Następnie wybierz pozycję Przypisz. Poczekaj, aż przypisanie aplikacji zakończy się pomyślnie. Może być konieczne przewinięcie tabeli w bok, aby wyświetlić kolumnę Przypisana rola .

   3. Powtórz poprzednie kroki, aby przypisać rolę Użytkownika użytkownikowi.

   4. Wybierz pozycję Odśwież , a użytkownicy i role przypisane w okienku Użytkownicy i grupy .

      

      Może być konieczne dostosowanie szerokości nagłówków kolumn, aby widok wyglądał jak obraz.

Nie należy wykonywać żadnych innych kroków w temacie Dodawanie ról aplikacji do aplikacji i odbieranie ich w tokenie.

Ochrona aplikacji Quarkus przy użyciu protokołu OpenID Connect

W tej sekcji zabezpieczysz aplikację Quarkus, która uwierzytelnia i autoryzuje użytkowników w dzierżawie firmy Microsoft Entra przy użyciu protokołu OpenID Connect. Dowiesz się również, jak zapewnić użytkownikom dostęp do niektórych części aplikacji przy użyciu kontroli dostępu opartej na rolach (RBAC).

Przykładowa aplikacja Quarkus dla tego przewodnika Szybki start znajduje się w witrynie GitHub w repozytorium quarkus-azure i znajduje się w katalogu entra-id-quarkus .

Włączanie uwierzytelniania i autoryzacji w celu zabezpieczenia aplikacji

Aplikacja ma zasób strony powitalnej zdefiniowany w WelcomePage.java, który jest wyświetlany w poniższym przykładowym kodzie. Ta strona jest dostępna dla nieuwierzytelnionych użytkowników. Ścieżka główna strony powitalnej znajduje się pod adresem /.

@Path("/")
public class WelcomePage {

    private final Template welcome;

    public WelcomePage(Template welcome) {
        this.welcome = requireNonNull(welcome, "welcome page is required");
    }

    @GET
    @Produces(MediaType.TEXT_HTML)
    public TemplateInstance get() {
        return welcome.instance();
    }

}

Na stronie powitalnej użytkownicy mogą zalogować się do aplikacji, aby uzyskać dostęp do strony profilu. Strona powitalna zawiera linki do logowania się jako użytkownik lub jako administrator. Linki znajdują się odpowiednio pod adresem /profile/user i /profile/admin. Interfejs użytkownika strony powitalnej jest zdefiniowany w welcome.qute.html i pokazany w poniższym przykładzie:

<html>
    <head>
        <meta charset="UTF-8">
        <title>Greeting</title>
    </head>
    <body>
        <h1>Hello, welcome to Quarkus and Microsoft Entra ID integration!</h1>
        <h1>
            <a href="/profile/user">Sign in as user</a>
        </h1>
        <h1>
            <a href="/profile/admin">Sign in as admin</a>
        </h1>
    </body>
</html>

Oba /profile/user linki /profile/admin wskazują zasób strony profilu zdefiniowany w ProfilePage.java, jak pokazano w poniższym przykładowym kodzie. Ta strona jest dostępna tylko dla uwierzytelnionych użytkowników przy użyciu @RolesAllowed("**") adnotacji z jakarta.annotation.security.RolesAllowed pakietu. Adnotacja @RolesAllowed("**") określa, że tylko uwierzytelnieni użytkownicy mogą uzyskiwać dostęp do ścieżki /profile .

@Path("/profile")
@RolesAllowed("**")
public class ProfilePage {

    private final Template profile;

    @Inject
    SecurityIdentity identity;

    @Inject
    JsonWebToken accessToken;

    public ProfilePage(Template profile) {
        this.profile = requireNonNull(profile, "profile page is required");
    }

    @Path("/admin")
    @GET
    @Produces(MediaType.TEXT_HTML)
    @RolesAllowed("admin")
    public TemplateInstance getAdmin() {
        return getProfile();
    }

    @Path("/user")
    @GET
    @Produces(MediaType.TEXT_HTML)
    @RolesAllowed({"user","admin"})
    public TemplateInstance getUser() {
        return getProfile();
    }

    private TemplateInstance getProfile() {
        return profile
                .data("name", identity.getPrincipal().getName())
                .data("roles", identity.getRoles())
                .data("scopes", accessToken.getClaim("scp"));
    }

}

Zasób strony profilu umożliwia kontrolę dostępu opartą na rolach przy użyciu adnotacji @RolesAllowed . Argumenty @RolesAllowed adnotacji określają, że tylko użytkownicy z admin rolą mogą uzyskać dostęp do /profile/admin ścieżki, a użytkownicy z user rolą lub admin mogą uzyskać dostęp do ścieżki /profile/user .

Zarówno punkty końcowe, jak /profile/admin i /profile/user zwracają stronę profilu. Interfejs użytkownika strony profilu jest zdefiniowany w profile.qute.html, jak pokazano w poniższym przykładzie. Na tej stronie są wyświetlane nazwy, role i zakresy użytkownika. Strona profilu zawiera również link wylogowania pod /logoutadresem , który przekierowuje użytkownika do dostawcy OIDC w celu wylogowania się. Strona profilu jest zapisywana przy użyciu aparatu tworzenia szablonów Qute. Zwróć uwagę na użycie {} wyrażeń na stronie. Te wyrażenia korzystają z wartości przekazanych do TemplateInstance metody przy użyciu data() metody . Aby uzyskać więcej informacji na temat rozwiązania Qute, zobacz Aparat tworzenia szablonów Qute.

<html>
    <head>
        <meta charset="UTF-8">
        <title>Profile</title>
    </head>
    <body>
        <h1>Hello, {name}</h1>
        <h2>Roles</h2>
        <ul>
            {#if roles}
                {#for role in roles}
                    <li>{role}</li>
                {/for}
            {#else}
                <li>No roles found!</li>
            {/if}
        </ul>
        <h2>Scopes</h2>
        <p>
            {scopes}
        </p>
        <h1>
            <b><a href="/logout">Sign out</a></b>
        </h1>
    </body>
</html>

Po wylogowaniu użytkownik jest przekierowywany do strony powitalnej i może zalogować się ponownie.

Uruchamianie i testowanie aplikacji Quarkus

W tej sekcji uruchomisz i przetestujesz aplikację Quarkus, aby zobaczyć, jak działa z identyfikatorem Entra firmy Microsoft jako dostawcą OpenID Connect.

Dodawanie identyfikatora URI przekierowania do rejestracji aplikacji

Aby pomyślnie uruchomić i przetestować aplikację lokalnie, musisz dodać identyfikator URI przekierowania do rejestracji aplikacji. Postępuj zgodnie z instrukcjami w sekcji Dodawanie identyfikatora URI przekierowania w przewodniku Szybki start: rejestrowanie aplikacji przy użyciu Platforma tożsamości Microsoft i używanie następujących wartości:

• W obszarze Konfigurowanie platform wybierz pozycję Sieć Web.
• W polu Identyfikatory URI przekierowania wprowadź .http://localhost:8080

Przygotowywanie przykładu

Aby przygotować przykładową aplikację Quarkus, wykonaj następujące kroki:

1. Użyj następujących poleceń, aby sklonować przykładową aplikację Quarkus z usługi GitHub i przejść do katalogu entra-id-quarkus:

   git clone https://github.com/Azure-Samples/quarkus-azure
   cd quarkus-azure/entra-id-quarkus
   git checkout 2024-09-26
   

   Jeśli zostanie wyświetlony komunikat o odłączeniu stanu HEAD , ten komunikat jest bezpieczny do zignorowania. Ponieważ ten artykuł nie wymaga żadnych zatwierdzeń, odłączony stan HEAD jest odpowiedni.

2. Użyj następujących poleceń, aby zdefiniować następujące zmienne środowiskowe z wartościami zanotowymi wcześniej:

   export QUARKUS_OIDC_CLIENT_ID=<application/client-ID>
   export QUARKUS_OIDC_CREDENTIALS_SECRET=<client-secret>
   export QUARKUS_OIDC_AUTH_SERVER_URL=https://login.microsoftonline.com/<directory/tenant-ID>/v2.0
   

   Te zmienne środowiskowe zapewniają wartości wbudowanej obsługi programu OpenID Connect w aplikacji Quarkus. Odpowiednie właściwości w pliku application.properties są wyświetlane w poniższym przykładzie.

   quarkus.oidc.client-id=
   quarkus.oidc.credentials.secret=
   quarkus.oidc.auth-server-url=
   

   Jeśli wartość właściwości jest pusta w application.propertiespliku , Quarkus konwertuje nazwę właściwości na zmienną środowiskową i odczytuje wartość ze środowiska. Aby uzyskać szczegółowe informacje na temat konwersji nazewnictwa, zobacz specyfikację konfiguracji microProfile.

Uruchamianie aplikacji Quarkus

Aplikację Quarkus można uruchomić w różnych trybach. Wybierz jedną z następujących metod, aby uruchomić aplikację Quarkus. Aby włączyć aplikację Quarkus w celu nawiązania połączenia z identyfikatorem Entra firmy Microsoft, pamiętaj, aby uruchomić polecenie w powłoce, w której zdefiniowano zmienne środowiskowe pokazane w poprzedniej sekcji.

• Uruchom aplikację Quarkus w trybie programowania:

  mvn quarkus:dev
  

• Uruchom aplikację Quarkus w trybie JVM:

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

• Uruchom aplikację Quarkus w trybie natywnym:

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

Jeśli chcesz wypróbować różne tryby, użyj Ctrl+C, aby zatrzymać aplikację Quarkus, a następnie uruchomić aplikację Quarkus w innym trybie.

Testowanie aplikacji Quarkus

Po uruchomieniu aplikacji Quarkus otwórz przeglądarkę internetową z prywatną kartą i przejdź do http://localhost:8080strony . Powinna zostać wyświetlona strona powitalna z linkami umożliwiającymi zalogowanie się jako użytkownik lub administrator. Korzystanie z karty prywatnej pozwala uniknąć zanieczyszczania wszelkich istniejących działań microsoft Entra ID, które mogą być używane w regularnej przeglądarce.

Zbieranie poświadczeń dla dwóch użytkowników

W tym artykule identyfikator Entra firmy Microsoft używa adresu e-mail każdego użytkownika jako identyfikatora użytkownika do logowania. Wykonaj następujące kroki, aby uzyskać adres e-mail użytkownika administratora i zwykłego użytkownika:

1. Zaloguj się do centrum administracyjnego firmy Microsoft Entra co najmniej jako administrator aplikacji w chmurze.
2. Jeśli masz dostęp do wielu dzierżaw, użyj ikony Ustawienia ( ) w górnym menu, aby przełączyć się do dzierżawy, w której chcesz zarejestrować aplikację z menu Katalogi i subskrypcje .
3. Przejdź do pozycji Użytkownicy tożsamości >> Wszyscy użytkownicy.
4. Znajdź użytkownika administratora na liście i wybierz go.
5. Znajdź pole Główna nazwa użytkownika.
6. Użyj ikony kopiowania obok wartości pola, aby zapisać adres e-mail użytkownika w schowku. Zapisz wartość do późniejszego użycia.
7. Aby uzyskać adres e-mail dla zwykłego użytkownika, wykonaj te same kroki.

Użyj haseł dla użytkownika administratora i zwykłego użytkownika ustawionego podczas tworzenia użytkowników.

Ćwiczenie funkcjonalności aplikacji

Aby wykonać działanie funkcji, wykonaj następujące czynności:

1. Wybierz link Zaloguj się jako użytkownik. Zaloguj się przy użyciu utworzonego wcześniej zwykłego użytkownika. Po zalogowaniu identyfikator Entra firmy Microsoft przekierowuje Cię do strony profilu, na której zobaczysz swoją nazwę, role i zakresy.

   

2. Jeśli po raz pierwszy zalogujesz się, zostanie wyświetlony monit o zaktualizowanie hasła. Postępuj zgodnie z instrukcjami, aby zaktualizować hasło.

3. Jeśli zostanie wyświetlony monit o podanie w organizacji dodatkowych informacji zabezpieczających. Postępuj zgodnie z monitami, aby pobrać i skonfigurować aplikację Microsoft Authenticator, możesz wybrać pozycję Zapytaj później , aby kontynuować test.

4. Jeśli zostanie wyświetlony monit o podanie żądanych uprawnień, zapoznaj się z uprawnieniami żądanymi przez aplikację. Wybierz pozycję Akceptuj , aby kontynuować test.

5. Wybierz pozycję Wyloguj się, aby wylogować się z aplikacji Quarkus. Identyfikator Entra firmy Microsoft wykonuje wylogowanie. Po wylogowaniu identyfikator Entra firmy Microsoft przekierowuje Cię do strony powitalnej.

6. Wybierz link Zaloguj się jako administrator. Identyfikator Entra firmy Microsoft przekierowuje Cię do strony logowania. Zaloguj się przy użyciu utworzonego wcześniej użytkownika administratora. Po zalogowaniu identyfikator Entra firmy Microsoft przekierowuje Cię do podobnej strony profilu z inną rolą admin.

   

7. Wyloguj się ponownie i spróbuj zalogować się jako administrator przy użyciu utworzonego wcześniej zwykłego użytkownika. Powinien zostać wyświetlony komunikat o błędzie, ponieważ zwykły użytkownik nie ma admin roli.

   

Czyszczenie zasobów

Ten artykuł nie kieruje Cię do wdrażania aplikacji na platformie Azure. Nie ma zasobów platformy Azure do oczyszczenia aplikacji, chociaż istnieją zasoby identyfikatora Entra firmy Microsoft. Aby wdrożyć aplikację na platformie Azure, możesz postępować zgodnie ze wskazówkami podanymi w następnej sekcji.

Po zakończeniu pracy z zasobami dla tej przykładowej aplikacji wykonaj następujące kroki, aby wyczyścić zasoby identyfikatora Entra firmy Microsoft. Usuwanie nieużywanych zasobów identyfikatora Entra firmy Microsoft jest ważnym najlepszym rozwiązaniem w zakresie zabezpieczeń.

1. Usuń rejestrację aplikacji utworzoną, wykonując kroki opisane w temacie Usuwanie aplikacji zarejestrowanej w Platforma tożsamości Microsoft. Wystarczy wykonać kroki opisane w sekcji Usuwanie aplikacji utworzonej przez organizację.
2. Czynność usuwania rejestracji aplikacji powinna również usunąć aplikację dla przedsiębiorstw. Aby uzyskać więcej informacji na temat usuwania aplikacji dla przedsiębiorstw, zobacz Usuwanie aplikacji dla przedsiębiorstw.
3. Usuń utworzonych użytkowników, wykonując kroki opisane w temacie Tworzenie, zapraszanie i usuwanie użytkowników.

Następne kroki

W tym przewodniku Szybki start chronisz aplikacje Quarkus przy użyciu identyfikatora Entra firmy Microsoft przy użyciu protokołu OpenID Connect. Aby dowiedzieć się więcej, zapoznaj się z następującymi zasobami:

• Wdrażanie aplikacji Java za pomocą aplikacji Quarkus w usłudze Azure Container Apps
• Uwierzytelnianie OpenID Connect za pomocą identyfikatora Entra firmy Microsoft
• Platforma tożsamości Microsoft a przepływ kodu autoryzacji OAuth 2.0
• Ochrona aplikacji internetowej przy użyciu przepływu kodu autoryzacji OpenId Connect (OIDC)
• Mechanizm przepływu kodu autoryzacji OpenID Connect do ochrony aplikacji internetowych
• Właściwości konfiguracji openID Connect (OIDC)