Zabezpečení aplikací Spring Boot v Javě pomocí Microsoft Entra ID

  • Článek

Tento článek ukazuje webovou aplikaci Java Spring Boot, která přihlašuje uživatele v tenantovi Microsoft Entra ID pomocí klientské knihovny Microsoft Entra ID Spring Boot Starter pro Javu. Používá protokol OpenID Připojení.

Následující diagram znázorňuje topologii aplikace:

Diagram znázorňující topologii aplikace

Klientská aplikace používá klientskou knihovnu Microsoft Entra ID Spring Boot Starter pro Javu k přihlášení uživatele a získání tokenu ID z Microsoft Entra ID. Token ID prokáže, že se uživatel ověřuje pomocí Microsoft Entra ID a umožňuje uživateli přístup k chráněným trasám.

Požadavky

Doporučení

  • Znalost spring frameworku
  • Znalost terminálu Linux/OSX nebo Windows PowerShellu
  • jwt.ms pro kontrolu tokenů.
  • Fiddler pro monitorování síťové aktivity a řešení potíží.
  • Sledujte blog Microsoft Entra ID a sledujte aktuální informace o nejnovějším vývoji.

Nastavení ukázky

Následující části ukazují, jak nastavit ukázkovou aplikaci.

Klonování nebo stažení ukázkového úložiště

Pokud chcete ukázku naklonovat, otevřete okno Bash a použijte následující příkaz:

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

Případně přejděte do úložiště ms-identity-java-spring-tutorial , stáhněte si ho jako .zip soubor a extrahujte ho na pevný disk.

Důležité

Pokud se chcete vyhnout omezením délky cest ve Windows, doporučujeme klonování do adresáře poblíž kořenového adresáře jednotky.

Registrace ukázkových aplikací v tenantovi Microsoft Entra ID

V této ukázce je jeden projekt. Pokud chcete aplikaci zaregistrovat na webu Azure Portal, můžete postupovat podle ručních kroků konfigurace nebo použít skript PowerShellu. Skript provede následující úlohy:

  • Vytvoří aplikace Microsoft Entra ID a související objekty, jako jsou hesla, oprávnění a závislosti.
  • Upraví konfigurační soubory projektu.
  • Ve výchozím nastavení nastavíte aplikaci, která funguje jenom s účty v adresáři organizace.

Ke spuštění skriptu PowerShellu použijte následující kroky:

  1. Ve Windows otevřete PowerShell a přejděte do kořenového adresáře klonovaného adresáře.

  2. Pomocí následujícího příkazu nastavte zásady spouštění pro PowerShell:

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force

  3. Ke spuštění konfiguračního skriptu použijte následující příkazy:

    cd .\AppCreationScripts\
.\Configure.ps1

    Poznámka:

    Další způsoby spouštění skriptů jsou popsány ve skriptech pro vytváření aplikací. Skripty také poskytují průvodce automatickou registrací, konfigurací a odebráním aplikací, které vám můžou pomoct ve scénářích CI/CD.

Konfigurace aplikace (java-spring-webapp-auth) pro použití registrace aplikace

Ke konfiguraci aplikace použijte následující postup:

Poznámka:

V následujících krocích ClientID je stejný jako Application ID nebo AppId.

  1. Otevřete projekt v integrovaném vývojovém prostředí (IDE).

  2. Otevřete soubor src\main\resources\application.yml.

  3. Vyhledejte zástupný symbol Enter_Your_Tenant_ID_Here a nahraďte existující hodnotu id vašeho tenanta Microsoft Entra.

  4. Vyhledejte zástupný symbol Enter_Your_Client_ID_Here a nahraďte existující hodnotu ID aplikace nebo clientIdjava-spring-webapp-auth aplikace zkopírovanou z webu Azure Portal.

  5. Vyhledejte zástupný symbol Enter_Your_Client_Secret_Here a nahraďte existující hodnotu hodnotou, kterou jste uložili při vytváření java-spring-webapp-auth zkopírovaného z webu Azure Portal.

Spuštění ukázky

Následující části ukazují, jak nasadit ukázku do Azure Spring Apps.

Požadavky

Příprava projektu Spring

Pomocí následujících kroků připravte projekt:

  1. K sestavení projektu použijte následující příkaz Mavenu :

    mvn clean package

  2. Spusťte ukázkový projekt místně pomocí následujícího příkazu:

    mvn spring-boot:run

Konfigurace modulu plug-in Maven

Spuštěním následujícího příkazu v kořenovém adresáři projektu nakonfigurujte aplikaci pomocí modulu plug-in Maven pro Azure Spring Apps:

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

Následující seznam popisuje interakce příkazů:

  • Přihlášení OAuth2: Musíte autorizovat přihlášení k Azure na základě protokolu OAuth2.
  • Vyberte předplatné: Vyberte číslo seznamu předplatných, ve kterém chcete vytvořit instanci Azure Spring Apps, která je ve výchozím nastavení prvním předplatným v seznamu. Pokud chcete použít výchozí číslo, stiskněte Enter.
  • Zadejte název aplikace Azure Spring: Zadejte název instance spring apps, kterou chcete vytvořit. Pokud chcete použít výchozí název, stiskněte Enter.
  • Zadejte název skupiny prostředků: Zadejte název skupiny prostředků, ve které chcete vytvořit instanci aplikace Spring. Pokud chcete použít výchozí název, stiskněte Enter.
  • Skladové položky: Vyberte skladovou položku, kterou chcete použít pro instanci aplikace Spring. Pokud chcete použít výchozí číslo, stiskněte Enter.
  • Zadejte název aplikace (ukázka):Zadejte název aplikace. Pokud chcete použít výchozí ID artefaktu projektu, stiskněte Enter.
  • Moduly runtime: Vyberte modul runtime, který chcete použít pro instanci aplikace Spring. V tomto případě byste měli použít výchozí číslo, takže stiskněte Enter.
  • Zveřejnění veřejného přístupu pro tuto aplikaci (boot-for-azure): Stiskněte y.
  • Potvrďte uložení všech výše uvedených konfigurací: Stiskněte y. Pokud stisknete klávesu n, konfigurace se neuloží do souboru .pom .

Následující příklad ukazuje výstup procesu nasazení:

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

Jakmile potvrdíte volby, modul plug-in přidá do souboru pom.xml projektu požadovaný prvek modulu plug-in a nakonfiguruje aplikaci tak, aby běžela v Azure Spring Apps.

Relevantní část souboru pom.xml by měla vypadat podobně jako v následujícím příkladu:

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

Konfigurace pro Azure Spring Apps můžete upravit přímo v souboru pom.xml . Některé běžné konfigurace jsou uvedeny v následující tabulce:

Vlastnost Požadováno Popis
subscriptionId false (nepravda) ID předplatného.
resourceGroup true Skupina prostředků Azure pro vaši instanci Azure Spring Apps.
clusterName true Název clusteru Azure Spring Apps Pokud používáte předplatné a skupinu prostředků, které už mají nasazenou instanci Azure Spring Apps, můžete k nasazení použít také tento existující cluster.
appName true Název aplikace v Azure Spring Apps
region false (nepravda) Oblast, ve které se má hostovat instance Azure Spring Apps. Výchozí hodnota je eastus. Platné oblasti najdete v tématu Podporované oblasti.
sku false (nepravda) Cenová úroveň vaší instance Azure Spring Apps. Výchozí hodnota je Basic, která je vhodná pouze pro vývojová a testovací prostředí.
runtime false (nepravda) Konfigurace prostředí runtime. Další informace najdete v tématu Podrobnosti o konfiguraci.
deployment false (nepravda) Konfigurace nasazení. Další informace najdete v tématu Podrobnosti o konfiguraci.

Úplný seznam konfigurací najdete v referenční dokumentaci k modulu plug-in. Všechny moduly plug-in Azure Maven sdílejí společnou sadu konfigurací. Informace o těchto konfiguracích najdete v tématu Běžné konfigurace. Informace o konfiguracích specifických pro Azure Spring Apps najdete v tématu Azure Spring Apps: Podrobnosti konfigurace.

Nezapomeňte uložit stranou clusterName a appName hodnoty pro pozdější použití.

Příprava aplikace na nasazení

Když nasadíte aplikaci do Azure Spring Apps, adresa URL pro přesměrování se změní na adresu URL pro přesměrování vaší nasazené instance aplikace v Azure Spring Apps. Pomocí následujícího postupu změňte tato nastavení v souboru application.yml :

  1. Přejděte do souboru src\main\resources\application.yml vaší aplikace a změňte hodnotu post-logout-redirect-uri na název domény nasazené aplikace, jak je znázorněno v následujícím příkladu. Pokud jste například v předchozím kroku zvolili cluster-ms-identity-spring-boot-webapp instanci Azure Spring Apps a ms-identity-spring-boot-webapp jako název aplikace, musíte tuto hodnotu použít https://cluster-ms-identity-spring-boot-webapp-ms-identity-spring-boot-webapp.azuremicroservices.iopost-logout-redirect-uri .

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

  2. Po uložení tohoto souboru pomocí následujícího příkazu znovu sestavte aplikaci:

    mvn clean package

Důležité

Soubor application.yml aplikace aktuálně obsahuje hodnotu tajného klíče klienta v parametru client-secret . Tuto hodnotu v tomto souboru není vhodné zachovat. Můžete také riskovat, pokud ho potvrdíte do úložiště Git.

Jako další krok zabezpečení můžete tuto hodnotu uložit ve službě Azure Key Vault a načíst tajný klíč ze služby Key Vault , aby byla dostupná ve vaší aplikaci.

Aktualizace registrace aplikace Microsoft Entra ID

Vzhledem k tomu, že se identifikátor URI přesměrování změní na nasazenou aplikaci v Azure Spring Apps, musíte také změnit identifikátor URI přesměrování v registraci aplikace Microsoft Entra ID. K provedení této změny použijte následující postup:

  1. Přejděte na stránku Microsoft identity platform pro vývojáře Registrace aplikací.

  2. Pomocívyhledávacího java-servlet-webapp-authentication

  3. Výběrem jejího názvu otevřete registraci aplikace.

  4. Zvolte Ověřování z nabídky příkazů.

  5. V části Identifikátory URI pro přesměrování webu - vyberte Přidat identifikátor URI.

  6. Vyplňte identifikátor URI aplikace a připojte /login/oauth2/code/ ho , https://<cluster-name>-<app-name>.azuremicroservices.io/login/oauth2/code/například .

  7. Zvolte Uložit.

Nasazení aplikace

K nasazení aplikace použijte následující příkaz:

mvn azure-spring-apps:deploy

Následující seznam popisuje interakci s příkazy:

  • Přihlášení OAuth2: Musíte autorizovat přihlášení k Azure na základě protokolu OAuth2.

Po spuštění příkazu se zobrazí následující zprávy protokolu, které nasazení proběhlo úspěšně:

[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

Ověření aplikace

Po dokončení nasazení přejděte k aplikaci pomocí adresy URL výstupní aplikace. Pomocí následujících kroků zkontrolujte protokoly aplikace a prozkoumejte případné problémy s nasazením:

  1. Přejděte na adresu URL výstupní aplikace ze stránky Výstupy v části Nasazení.

  2. V navigačním podokně na stránce Přehled instance Azure Spring Apps vyberte Protokoly a zkontrolujte protokoly aplikace.

Zkoumání ukázky

Ukázku můžete prozkoumat pomocí následujících kroků:

  1. Všimněte si stavu přihlášení nebo odhlášení, který se zobrazuje uprostřed obrazovky.
  2. Vyberte tlačítko citlivé na kontext v rohu. Toto tlačítko přečte přihlášení při prvním spuštění aplikace. Případně vyberte podrobnosti o tokenu. Vzhledem k tomu, že je tato stránka chráněná a vyžaduje ověření, budete automaticky přesměrováni na přihlašovací stránku.
  3. Na další stránce postupujte podle pokynů a přihlaste se pomocí účtu v tenantovi Microsoft Entra ID.
  4. Na obrazovce souhlasu si všimněte požadovaných oborů.
  5. Po úspěšném dokončení toku přihlášení byste měli být přesměrováni na domovskou stránku , která zobrazuje stav přihlášení , nebo na stránku s podrobnostmi o tokenu v závislosti na tom, které tlačítko aktivovalo tok přihlášení.
  6. Všimněte si, že kontextové tlačítko se teď zobrazuje odhlásit a zobrazit vaše uživatelské jméno.
  7. Pokud jste na domovské stránce, vyberte podrobnosti tokenu ID a zobrazte některé dekódované deklarace identity tokenu ID.
  8. Pomocí tlačítka v rohu se odhlaste. Stavová stránka odráží nový stav.

O kódu

Tato ukázka ukazuje, jak používat klientskou knihovnu Microsoft Entra ID Spring Boot Starter pro Javu k přihlášení uživatelů do tenanta Microsoft Entra ID. Ukázka také využívá úvodní sady Spring Oauth2 Client a Spring Web Boot. Ukázka používá deklarace identity z tokenu ID získaného z ID Microsoft Entra k zobrazení podrobností přihlášeného uživatele.

Obsah

Následující tabulka ukazuje obsah složky ukázkového projektu:

Soubor nebo složka Popis
AppCreationScripts/ Skripty pro automatickou konfiguraci registrací aplikací Microsoft Entra ID
pom.xml Závislosti aplikací
src/main/resources/templates/ Šablony thymeleaf pro uživatelské rozhraní.
src/main/resources/application.yml Konfigurace úvodní knihovny spouštění aplikace a Microsoft Entra ID.
src/main/java/com/microsoft/azuresamples/msal4j/msidentityspringbootwebapp/ Tento adresář obsahuje hlavní vstupní bod aplikace, kontroler a třídy konfigurace.
.../MsIdentitySpringBootWebappApplication.java Hlavní třída.
.../SampleController.java Kontroler s mapováním koncových bodů.
.../SecurityConfig.java Konfigurace zabezpečení – například trasy vyžadují ověření.
.../Utilities.java Třída utility – například deklarace identity tokenu ID filtru.
CHANGELOG.md Seznam změn v ukázce
CONTRIBUTING.md Pokyny pro přispívání do ukázky
LICENCE Licence pro ukázku.

Deklarace identity tokenů ID

K extrahování podrobností o tokenech aplikace používá spring security AuthenticationPrincipal a OidcUser objekt v mapování požadavků, jak je znázorněno v následujícím příkladu. Úplné podrobnosti o tom, jak tato aplikace využívá deklarace identity tokenů ID, najdete v ukázkovém kontroleru .

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

Pro přihlášení aplikace odešle žádost do koncového bodu přihlášení k Microsoft Entra ID automaticky nakonfigurované klientskou knihovnou Spring Boot Starter pro Microsoft Entra ID pro Javu, jak je znázorněno v následujícím příkladu:

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

Pro odhlášení aplikace odešle do koncového logout bodu požadavek POST, jak je znázorněno v následujícím příkladu:

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

Prvky uživatelského rozhraní závislé na ověřování

Aplikace má na stránkách šablony uživatelského rozhraní nějakou jednoduchou logiku pro určení obsahu, který se má zobrazit na základě toho, jestli je uživatel ověřený, jak je znázorněno v následujícím příkladu pomocí značek Spring Security Thymeleaf:

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

Ochrana tras pomocí AADWebSecurityConfigurerAdapter

Aplikace ve výchozím nastavení chrání stránku podrobností tokenu ID, aby k ní mohli přistupovat jenom přihlášení uživatelé. Aplikace tyto trasy nakonfiguruje pomocí app.protect.authenticated vlastnosti ze souboru application.yml . Pokud chcete nakonfigurovat specifické požadavky vaší aplikace, použijte AadWebApplicationHttpSecurityConfigurer#aadWebApplication metodu HttpSecurity na instanci. Příklad najdete v této třídě SecurityConfig této aplikace, jak je znázorněno v následujícím kódu:

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

Více informací

Další informace o fungování protokolů OAuth 2.0 v tomto scénáři a dalších scénářích najdete v tématu Scénáře ověřování pro Microsoft Entra ID.