Java Spring Boot-alkalmazások védelme a Microsoft Entra ID használatával

  • Cikk

Ez a cikk egy Java Spring Boot-webalkalmazást mutat be, amely a Java-hoz készült Microsoft Entra ID Spring Boot Starter ügyfélkódtár használatával jelentkezik be a felhasználókba a Microsoft Entra ID-bérlőn. Az OpenID Csatlakozás protokollt használja.

Az alábbi ábrán az alkalmazás topológiája látható:

Az alkalmazás topológiáját bemutató diagram.

Az ügyfélalkalmazás a Java-hoz készült Microsoft Entra ID Spring Boot Starter ügyfélkódtár használatával jelentkezik be egy felhasználóba, és beszerez egy azonosító jogkivonatot a Microsoft Entra ID-ból. Az azonosító jogkivonat igazolja, hogy a felhasználó a Microsoft Entra-azonosítóval van hitelesítve, és lehetővé teszi a felhasználó számára a védett útvonalak elérését.

Előfeltételek

Ajánlások

  • A Spring Framework néhány ismerete
  • A Linux/OSX terminál vagy a Windows PowerShell ismerete
  • jwt.ms a jogkivonatok vizsgálatához.
  • A Fiddler a hálózati tevékenység figyeléséhez és a hibaelhárításhoz.
  • Kövesse a Microsoft Entra ID blogot , hogy naprakész maradjon a legújabb fejlesztésekkel kapcsolatban.

A minta beállítása

Az alábbi szakaszok bemutatják, hogyan állíthatja be a mintaalkalmazást.

A mintaadattár klónozása vagy letöltése

A minta klónozásához nyisson meg egy Bash-ablakot, és használja a következő parancsot:

git clone https://github.com/Azure-Samples/ms-identity-java-spring-tutorial.git
cd ms-identity-java-spring-tutorial
cd 1-Authentication/sign-in

Másik lehetőségként keresse meg az ms-identity-java-spring-tutorial adattárat, majd töltse le .zip fájlként, és bontsa ki a merevlemezre.

Fontos

A Windows útvonalhossz-korlátozásainak elkerülése érdekében javasoljuk, hogy a meghajtó gyökerének közelében lévő könyvtárba klónozza a klónozást.

Mintaalkalmazások regisztrálása a Microsoft Entra ID-bérlővel

Ebben a mintában egy projekt szerepel. Ha regisztrálni szeretné az alkalmazást az Azure Portalon, kövesse a manuális konfigurációs lépéseket, vagy használjon PowerShell-szkriptet. A szkript a következő feladatokat hajtja végre:

  • Létrehozza a Microsoft Entra ID-alkalmazásokat és a kapcsolódó objektumokat, például jelszavakat, engedélyeket és függőségeket.
  • Módosítja a projektkonfigurációs fájlokat.
  • Alapértelmezés szerint beállít egy olyan alkalmazást, amely csak a szervezeti címtárban lévő fiókokkal működik.

A PowerShell-szkript futtatásához kövesse az alábbi lépéseket:

  1. Windows rendszeren nyissa meg a PowerShellt, és keresse meg a klónozott könyvtár gyökerét.

  2. A PowerShell végrehajtási szabályzatának beállításához használja a következő parancsot:

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force

  3. A konfigurációs szkript futtatásához használja az alábbi parancsokat:

    cd .\AppCreationScripts\
.\Configure.ps1

    Feljegyzés

    A szkriptek futtatásának egyéb módjait az alkalmazáslétrehozási szkriptek ismertetik. A szkriptek emellett útmutatást nyújtanak az automatikus alkalmazásregisztrációhoz, konfiguráláshoz és eltávolításhoz, ami segíthet a CI/CD-forgatókönyvekben.

Az alkalmazás (java-spring-webapp-auth) konfigurálása az alkalmazásregisztráció használatára

Az alkalmazás konfigurálásához kövesse az alábbi lépéseket:

Feljegyzés

A következő lépésekben ugyanaz, ClientID mint Application ID vagy AppId.

  1. Nyissa meg a projektet az IDE-ben.

  2. Nyissa meg az src\main\resources\application.yml fájlt.

  3. Keresse meg a helyőrzőt Enter_Your_Tenant_ID_Here , és cserélje le a meglévő értéket a Microsoft Entra-bérlőazonosítóra.

  4. Keresse meg a helyőrzőt Enter_Your_Client_ID_Here , és cserélje le a meglévő értéket az alkalmazásazonosítóra vagy clientId az java-spring-webapp-auth Azure Portalról másolt alkalmazásra.

  5. Keresse meg a helyőrzőt Enter_Your_Client_Secret_Here , és cserélje le a meglévő értéket az Azure Portalról másolt példány létrehozása java-spring-webapp-auth során mentett értékre.

Minta futtatása

Az alábbi szakaszok bemutatják, hogyan helyezheti üzembe a mintát az Azure Spring Appsben.

Előfeltételek

A Spring projekt előkészítése

A projekt előkészítéséhez kövesse az alábbi lépéseket:

  1. A projekt létrehozásához használja a következő Maven-parancsot :

    mvn clean package

  2. Futtassa helyileg a mintaprojektet az alábbi paranccsal:

    mvn spring-boot:run

A Maven beépülő moduljának konfigurálása

Futtassa az alábbi parancsot a projekt gyökerében az alkalmazás Azure Spring Appshez készült Maven beépülő modullal való konfigurálásához:

mvn com.microsoft.azure:azure-spring-apps-maven-plugin:1.19.0:config

Az alábbi lista a parancsok interakcióit ismerteti:

  • OAuth2-bejelentkezés: Engedélyeznie kell a bejelentkezést az Azure-ba az OAuth2 protokoll alapján.
  • Előfizetés kiválasztása: Válassza ki azt az előfizetési listaszámot, ahol létre szeretné hozni az Azure Spring Apps-példányt, amely alapértelmezés szerint a lista első előfizetése. Ha az alapértelmezett számot szeretné használni, nyomja le az Enter billentyűt.
  • Adja meg az Azure Spring Apps nevét: Adja meg a létrehozni kívánt Spring Apps-példány nevét. Ha az alapértelmezett nevet szeretné használni, nyomja le az Enter billentyűt.
  • Adja meg az erőforráscsoport nevét: Adja meg annak az erőforráscsoportnak a nevét, amelyben létre szeretné hozni a spring apps-példányt. Ha az alapértelmezett nevet szeretné használni, nyomja le az Enter billentyűt.
  • Termékváltozat: Válassza ki a spring apps-példányhoz használni kívánt termékváltozatot. Ha az alapértelmezett számot szeretné használni, nyomja le az Enter billentyűt.
  • Adja meg az alkalmazás nevét (bemutató): Adjon meg egy alkalmazásnevet. Ha az alapértelmezett projektösszetevő-azonosítót szeretné használni, nyomja le az Enter billentyűt.
  • Futtatókörnyezetek: Válassza ki a spring apps-példányhoz használni kívánt futtatókörnyezetet. Ebben az esetben az alapértelmezett számot kell használnia, ezért nyomja le az Enter billentyűt.
  • Nyilvános hozzáférés közzététele ehhez az alkalmazáshoz (boot-for-azure): Nyomja le az y billentyűt.
  • Ellenőrizze, hogy menti-e a fenti konfigurációkat: Nyomja le az y billentyűt. Ha az n billentyűt lenyomja, a konfiguráció nem lesz mentve a .pom fájlba.

Az alábbi példa az üzembehelyezési folyamat kimenetét mutatja be:

Summary of properties:
Subscription id   : 12345678-1234-1234-1234-123456789101
Resource group name : rg-ms-identity-spring-boot-webapp
Azure Spring Apps name : cluster-ms-identity-spring-boot-webapp
Runtime Java version : Java 11
Region            : eastus
Sku               : Standard
App name          : ms-identity-spring-boot-webapp
Public access     : true
Instance count/max replicas : 1
CPU count         : 1
Memory size(GB)   : 2
Confirm to save all the above configurations (Y/n):
[INFO] Configurations are saved to: /home/user/ms-identity-java-spring-tutorial/1-Authentication/sign-in/pom.    xml
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  01:57 min
[INFO] Finished at: 2024-02-14T13:50:44Z
[INFO] ------------------------------------------------------------------------

Miután megerősítette a választási lehetőségeket, a beépülő modul hozzáadja a szükséges beépülő modulelemet és -beállításokat a projekt pom.xml fájljához, hogy konfigurálja az alkalmazást az Azure Spring Appsben való futtatásra.

A pom.xml fájl releváns részének az alábbi példához hasonlóan kell kinéznie:

<plugin>
    <groupId>com.microsoft.azure</groupId>
    <artifactId>azure-spring-apps-maven-plugin</artifactId>
    <version>1.19.0</version>
    <configuration>
        <subscriptionId>12345678-1234-1234-1234-123456789101</subscriptionId>
        <resourceGroup>rg-ms-identity-spring-boot-webapp</resourceGroup>
        <clusterName>cluster-ms-identity-spring-boot-webapp</clusterName>
        <region>eastus</region>
        <sku>Standard</sku>
        <appName>ms-identity-spring-boot-webapp</appName>
        <isPublic>true</isPublic>
        <deployment>
            <cpu>1</cpu>
            <memoryInGB>2</memoryInGB>
            <instanceCount>1</instanceCount>
            <runtimeVersion>Java 11</runtimeVersion>
            <resources>
                <resource>
                    <directory>${project.basedir}/target</directory>
                    <includes>
                        <include>*.jar</include>
                    </includes>
                </resource>
            </resources>
        </deployment>
    </configuration>
</plugin>

Az Azure Spring Apps konfigurációit közvetlenül a pom.xml fájlban módosíthatja. Néhány gyakori konfiguráció az alábbi táblázatban található:

Tulajdonság Kötelező Leírás
subscriptionId false Az előfizetés azonosítója.
resourceGroup true Az Azure Spring Apps-példány Azure-erőforráscsoportja.
clusterName true Az Azure Spring Apps-fürt neve. Ha olyan előfizetést és erőforráscsoportot használ, amely már üzembe helyezett Egy Azure Spring Apps-példányt, ezt a meglévő fürtöt is használhatja az üzembe helyezéshez.
appName true Az alkalmazás neve az Azure Spring Appsben.
region false Az a régió, amelyben az Azure Spring Apps-példányt üzemeltetni szeretné. Az alapértelmezett érték eastus. Érvényes régiókért lásd: Támogatott régiók.
sku false Az Azure Spring Apps-példány tarifacsomagja. Az alapértelmezett érték , Basicamely csak fejlesztési és tesztelési környezetekhez használható.
runtime false A futtatókörnyezet konfigurációja. További információ: Konfiguráció részletei.
deployment false Az üzembehelyezési konfiguráció. További információ: Konfiguráció részletei.

A konfigurációk teljes listáját a beépülő modul referenciadokumentációjában találja. Az Összes Azure Maven beépülő modul közös konfigurációkat használ. Ezekről a konfigurációkról a Gyakori konfigurációk című témakörben olvashat. Az Azure Spring Appsre vonatkozó konfigurációkat az Azure Spring Apps: Configuration Details című témakörben találja.

Ügyeljen arra, hogy a későbbi használatra félretehesse az értékeket és appName az clusterName értékeket.

Az alkalmazás előkészítése az üzembe helyezéshez

Amikor üzembe helyezi az alkalmazást az Azure Spring Appsben, az átirányítási URL-cím megváltozik az Azure Spring Appsben üzembe helyezett alkalmazáspéldány átirányítási URL-címére. A következő lépésekkel módosíthatja ezeket a beállításokat a application.yml fájlban:

  1. Lépjen az alkalmazás src\main\resources\application.yml fájljára, és módosítsa a telepített alkalmazás tartománynevére az post-logout-redirect-uri alábbi példában látható módon. Ha például az előző lépésben ms-identity-spring-boot-webapp az Azure Spring Apps-példányt és az alkalmazás nevét választottacluster-ms-identity-spring-boot-webapp, akkor most már használnia https://cluster-ms-identity-spring-boot-webapp-ms-identity-spring-boot-webapp.azuremicroservices.io kell az post-logout-redirect-uri értéket.

    post-logout-redirect-uri: https://<cluster-name>-<app-name>.azuremicroservices.io

  2. A fájl mentése után használja az alábbi parancsot az alkalmazás újraépítéséhez:

    mvn clean package

Fontos

Az alkalmazás application.yml fájlja jelenleg az ügyfél titkos kódjának értékét tartalmazza a client-secret paraméterben. Ez az érték nem ajánlott ebben a fájlban tartani. Kockázatot is vállalhat, ha véglegesíti azt egy Git-adattárban.

További biztonsági lépésként tárolhatja ezt az értéket az Azure Key Vaultban, és betöltheti a titkos kulcsot a Key Vaultból, hogy elérhetővé tegye az alkalmazásban.

A Microsoft Entra ID alkalmazásregisztráció frissítése

Mivel az átirányítási URI módosul az Azure Spring Appsben üzembe helyezett alkalmazásra, az átirányítási URI-t is módosítania kell a Microsoft Entra ID-alkalmazásregisztrációjában. A módosítás végrehajtásához kövesse az alábbi lépéseket:

  1. Lépjen a Microsoft Identitásplatform fejlesztőknek Alkalmazásregisztrációk lapra.

  2. A keresőmező használatával keresse meg az alkalmazásregisztrációt – például java-servlet-webapp-authentication.

  3. Nyissa meg az alkalmazásregisztrációt a nevének kiválasztásával.

  4. Válassza a Hitelesítés lehetőséget a menüben.

  5. A Webes - átirányítási URI-k szakaszban válassza az URI hozzáadása lehetőséget.

  6. Töltse ki az alkalmazás URI-ját, hozzáfűzve /login/oauth2/code/ például https://<cluster-name>-<app-name>.azuremicroservices.io/login/oauth2/code/.

  7. Válassza a Mentés lehetőséget.

Az alkalmazás üzembe helyezése

Az alkalmazás üzembe helyezéséhez használja a következő parancsot:

mvn azure-spring-apps:deploy

Az alábbi lista a parancsok közötti interakciót ismerteti:

  • OAuth2-bejelentkezés: Engedélyeznie kell a bejelentkezést az Azure-ba az OAuth2 protokoll alapján.

A parancs végrehajtása után a következő naplóüzenetekből láthatja, hogy az üzembe helyezés sikeres volt:

[INFO] Deployment(default) is successfully created
[INFO] Starting Spring App after deploying artifacts...
[INFO] Deployment Status: Running
[INFO]   InstanceName:demo-default-x-xxxxxxxxxx-xxxxx  Status:Running Reason:null       DiscoverStatus:UNREGISTERED
[INFO]   InstanceName:demo-default-x-xxxxxxxxx-xxxxx  Status:Terminating Reason:null       DiscoverStatus:UNREGISTERED
[INFO] Getting public url of app(demo)...
[INFO] Application url: https://<your-Azure-Spring-Apps-instance-name>-demo.azuremicroservices.io

Az alkalmazás ellenőrzése

Az üzembe helyezés befejezése után a kimeneti alkalmazás URL-címével érheti el az alkalmazást. Az alábbi lépésekkel ellenőrizheti az alkalmazás naplóit az üzembehelyezési problémák kivizsgálásához:

  1. A kimeneti alkalmazás URL-címét az Üzembe helyezés szakasz Kimenetek lapján érheti el.

  2. Az Azure Spring Apps-példány áttekintési lapján válassza a Naplók lehetőséget az alkalmazás naplóinak ellenőrzéséhez.

A minta vizsgálata

A minta megismeréséhez kövesse az alábbi lépéseket:

  1. Figyelje meg a bejelentkezett vagy kijelentkezett állapotot a képernyő közepén.
  2. Válassza a sarokban található környezetérzékeny gombot. Ez a gomb beolvassa a bejelentkezést az alkalmazás első futtatásakor. Másik lehetőségként válassza ki a jogkivonat részleteit. Mivel ez a lap védett, és hitelesítést igényel, a rendszer automatikusan átirányítja a bejelentkezési lapra.
  3. A következő lapon kövesse az utasításokat, és jelentkezzen be egy fiókkal a Microsoft Entra ID-bérlőben.
  4. A hozzájárulási képernyőn figyelje meg a kért hatóköröket.
  5. A bejelentkezési folyamat sikeres befejezése után a rendszer átirányítja a kezdőlapra – amely a bejelentkezési állapotot jeleníti meg – vagy a jogkivonat részleteit tartalmazó lapra, attól függően, hogy melyik gomb váltotta ki a bejelentkezési folyamatot.
  6. Figyelje meg, hogy a környezetfüggő gomb most kijelentkezik , és megjeleníti a felhasználónevet.
  7. Ha a kezdőlapon van, válassza az Azonosító jogkivonat részletei lehetőséget az azonosító jogkivonat egyes dekódolt jogcímeinek megtekintéséhez.
  8. A kijelentkezéshez használja a sarokban lévő gombot. Az állapotlap az új állapotot tükrözi.

Tudnivalók a kódról

Ez a minta bemutatja, hogyan használhatja a Java-hoz készült Microsoft Entra ID Spring Boot Starter ügyféloldali kódtárat a felhasználók Microsoft Entra ID-bérlőbe való bejelentkezéséhez. A minta a Spring Oauth2-ügyfél- és Spring Web-rendszerindítókat is használja. A minta a Microsoft Entra-azonosítóból beszerzett azonosító jogkivonatból származó jogcímeket használja a bejelentkezett felhasználó adatainak megjelenítéséhez.

Tartalom

Az alábbi táblázat a mintaprojekt mappájának tartalmát mutatja be:

Fájl/mappa Leírás
AppCreationScripts/ Szkriptek a Microsoft Entra ID-alkalmazásregisztrációk automatikus konfigurálásához.
pom.xml Alkalmazásfüggőségek.
src/main/resources/templates/ Thymeleaf Templates for UI.
src/main/resources/application.yml Az alkalmazás és a Microsoft Entra ID rendszerindítási kezdőkönyvtárának konfigurációja.
src/main/java/com/microsoft/azuresamples/msal4j/msidentityspringbootwebapp/ Ez a könyvtár tartalmazza a fő alkalmazásbeléptetési pontot, vezérlőt és konfigurációs osztályokat.
.../MsIdentitySpringBootWebappApplication.java Főosztály.
.../SampleController.java Vezérlő végpontleképezésekkel.
.../SecurityConfig.java Biztonsági konfiguráció – például, hogy mely útvonalak igényelnek hitelesítést.
.../Utilities.java Segédprogramosztály – például szűrőazonosító-jogkivonat jogcímek.
CHANGELOG.md A minta módosításainak listája.
CONTRIBUTING.md Útmutató a mintához való hozzájáruláshoz.
LICEN Standard kiadás A minta licence.

Azonosító jogkivonat jogcíme

A jogkivonat részleteinek kinyeréséhez az alkalmazás a Spring Security AuthenticationPrincipal és OidcUser az objektum használatát használja egy kérésleképezésben, ahogyan az az alábbi példában is látható. Az alkalmazás azonosítójogkivonat-jogcímek használatának részletes részleteiért tekintse meg a mintavezérlőt.

import org.springframework.security.oauth2.core.oidc.user.OidcUser;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
//...
@GetMapping(path = "/some_path")
public String tokenDetails(@AuthenticationPrincipal OidcUser principal) {
    Map<String, Object> claims = principal.getIdToken().getClaims();
}

Bejelentkezés esetén az alkalmazás kérést küld a Microsoft Entra ID bejelentkezési végpontra, amelyet a Java-hoz készült Microsoft Entra ID Spring Boot Starter ügyfélkódtár automatikusan konfigurál, ahogyan az alábbi példában látható:

<a class="btn btn-success" href="/oauth2/authorization/azure">Sign In</a>

Kijelentkezés esetén az alkalmazás POST kérést küld a logout végpontra, ahogyan az a következő példában is látható:

<form action="#" th:action="@{/logout}" method="post">
  <input class="btn btn-warning" type="submit" value="Sign Out" />
</form>

Hitelesítéstől függő felhasználói felületi elemek

Az alkalmazás néhány egyszerű logikával rendelkezik a felhasználói felület sablonlapjain a megjelenítendő tartalom meghatározásához annak alapján, hogy a felhasználó hitelesítése megtörtént-e, ahogy az alábbi példában is látható, a Spring Security Thymeleaf-címkékkel:

<div sec:authorize="isAuthenticated()">
  this content only shows to authenticated users
</div>
<div sec:authorize="isAnonymous()">
  this content only shows to not-authenticated users
</div>

Útvonalak védelme az AADWebSecurityConfigurerAdapterrel

Alapértelmezés szerint az alkalmazás védi az Azonosító jogkivonat részletei lapot, hogy csak a bejelentkezett felhasználók férhessenek hozzá. Az alkalmazás ezeket az útvonalakat a app.protect.authenticated application.yml fájl tulajdonságával konfigurálja. Az alkalmazás konkrét követelményeinek konfigurálásához alkalmazza a metódust AadWebApplicationHttpSecurityConfigurer#aadWebApplication a HttpSecurity példányra. Például tekintse meg az alkalmazás SecurityConfig osztályát, amely az alábbi kódban látható:

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig  {
    
    @Value("${app.protect.authenticated}")
    private String[] allowedOrigins;
    
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        // @formatter:off
        http.apply(AadWebApplicationHttpSecurityConfigurer.aadWebApplication())
            .and()
            .authorizeHttpRequests(auth -> auth
                .requestMatchers(allowedOrigins).authenticated()
                .anyRequest().permitAll()
                );
        // @formatter:on
        return http.build();
    }

    @Bean
    @RequestScope
    public ServletUriComponentsBuilder urlBuilder() {
        return ServletUriComponentsBuilder.fromCurrentRequest();
    }    
}

További információ

További információ az OAuth 2.0 protokollok működéséről ebben a forgatókönyvben és más forgatókönyvekben: Hitelesítési forgatókönyvek a Microsoft Entra ID-hoz.