Sdílet prostřednictvím

Povolení aplikací Java Spring Boot pro přihlášení uživatelů a přístup k Microsoft Graphu

  • Článek

Tento článek ukazuje webovou aplikaci Java Spring Boot, která přihlašuje uživatele a získává přístupový token pro volání Microsoft Graphu. Pro ověřování, autorizaci a získání tokenu používá klientskou knihovnu Microsoft Entra ID Spring Boot Starter pro Javu . K získání dat z Graphu používá sadu Microsoft Graph SDK pro Javu .

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

Diagram that shows the topology of the app.Diagram znázorňující topologii aplikace

Aplikace používá klientskou knihovnu Microsoft Entra ID Spring Boot Starter pro Javu k získání přístupového tokenu pro Microsoft Graph z Microsoft Entra ID. Přístupový token potvrzuje, že uživatel má oprávnění pro přístup ke koncovému bodu rozhraní Microsoft Graph API, jak je definováno v oboru.

Požadavky

Doporučení

  • Znalost spring frameworku
  • Znalost terminálu Linux/OSX
  • 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-msal-java-samples.git
cd 4-spring-web-app/2-Authorization-I/call-graph

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

Důležité

Abyste se vyhnuli omezením délky cesty k souboru ve Windows, naklonujte nebo extrahujte úložiště do adresáře poblíž kořenového adresáře pevného disku.

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

V této ukázce je jeden projekt. V následujících částech se dozvíte, jak aplikaci zaregistrovat pomocí webu Azure Portal.

Zvolte tenanta Microsoft Entra ID, ve kterém chcete vytvářet aplikace.

Pokud chcete zvolit tenanta, postupujte následovně:

  1. Přihlaste se k portálu Azure.

  2. Pokud je váš účet ve více než jednom tenantovi Microsoft Entra ID, vyberte svůj profil v rohu webu Azure Portal a pak vyberte Přepnout adresář a změňte relaci na požadovaného tenanta Microsoft Entra ID.

Registrace aplikace (java-spring-webapp-call-graph)

Aplikaci zaregistrujete pomocí následujících kroků:

  1. Přejděte na web Azure Portal a vyberte ID Microsoft Entra.

  2. V navigačním podokně vyberte Registrace aplikací a pak vyberte Nová registrace.

  3. Na stránce Zaregistrovat aplikaci, která se zobrazí, zadejte následující informace o registraci aplikace:

    • V části Název zadejte smysluplný název aplikace pro zobrazení uživatelům aplikace , java-spring-webapp-call-graphnapříklad .
    • V části Podporované typy účtů vyberte Pouze účty v tomto organizačním adresáři.
    • V části Identifikátor URI přesměrování (volitelné) vyberte v poli se seznamem web a zadejte následující identifikátor URI přesměrování: http://localhost:8080/login/oauth2/code/.

  4. Výběrem možnosti Registrovat aplikaci vytvořte.

  5. Na stránce registrace aplikace vyhledejte a zkopírujte hodnotu ID aplikace (klienta), kterou chcete použít později. Tuto hodnotu použijete v konfiguračním souboru nebo souborech vaší aplikace.

  6. Na registrační stránce aplikace vyberte v navigačním podokně certifikáty a tajné kódy a otevřete stránku, kde můžete vygenerovat tajné kódy a nahrát certifikáty.

  7. V části Tajné klíče klienta vyberte Nový tajný klíč klienta.

  8. Zadejte popis – například tajný kód aplikace.

  9. Vyberte jednu z dostupných dob trvání: Za 1 rok, Za 2 roky nebo Nikdy nevyprší platnost.

  10. Vyberte Přidat. Zobrazí se vygenerovaná hodnota.

  11. Zkopírujte a uložte vygenerovanou hodnotu pro použití v dalších krocích. Tuto hodnotu potřebujete pro konfigurační soubory kódu. Tato hodnota se znovu nezobrazí a nemůžete ji načíst žádným jiným způsobem. Před přechodem na jinou obrazovku nebo podokno si ho proto nezapomeňte uložit z webu Azure Portal.

  12. Na registrační stránce aplikace vyberte podokno oprávnění rozhraní API v navigačním podokně a otevřete stránku pro přístup k rozhraním API, která vaše aplikace potřebuje.

  13. Vyberte Přidat oprávnění a ujistěte se, že je vybraná karta Rozhraní API Microsoftu.

  14. V části Běžně používané rozhraní MICROSOFT API vyberte Microsoft Graph.

  15. V části Delegovaná oprávnění vyberte v seznamu User.Read. V případě potřeby použijte vyhledávací pole.

  16. Vyberte Přidat oprávnění.

Konfigurace aplikace (java-spring-webapp-call-graph) 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-call-graph 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-call-graph zkopírovaného z webu Azure Portal.

Spuštění ukázky

Následující části ukazují, jak nasadit ukázku do Azure Container 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 verify

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

    mvn spring-boot:run

Nastavení

Pokud se chcete přihlásit k Azure z rozhraní příkazového řádku, spusťte následující příkaz a podle pokynů dokončete proces ověřování.

az login

Pokud chcete zajistit, že používáte nejnovější verzi rozhraní příkazového řádku, spusťte příkaz upgrade.

az upgrade

Dále nainstalujte nebo aktualizujte rozšíření Azure Container Apps pro rozhraní příkazového řádku.

Pokud se při spouštění az containerapp příkazů v Azure CLI zobrazí chyby týkající se chybějících parametrů, ujistěte se, že máte nainstalovanou nejnovější verzi rozšíření Azure Container Apps.

az extension add --name containerapp --upgrade

Poznámka:

Od května 2024 už rozšíření Azure CLI ve výchozím nastavení nepovolují funkce ve verzi Preview. Pokud chcete získat přístup k funkcím Container Apps ve verzi Preview, nainstalujte rozšíření Container Apps pomocí --allow-preview truenástroje .

az extension add --name containerapp --upgrade --allow-preview true

Teď, když je nainstalované aktuální rozšíření nebo modul, zaregistrujte obory Microsoft.App názvů a Microsoft.OperationalInsights obory názvů.

Poznámka:

Prostředky Azure Container Apps se migrovaly z Microsoft.Web oboru názvů do Microsoft.App oboru názvů. Další podrobnosti najdete v tématu Migrace oboru názvů z webu Microsoft.Web na Microsoft.App v březnu 2022 .

az provider register --namespace Microsoft.App
az provider register --namespace Microsoft.OperationalInsights

Vytvoření prostředí Azure Container Apps

Po dokončení nastavení Azure CLI můžete definovat proměnné prostředí, které se používají v tomto článku.

Definujte následující proměnné v prostředí Bash.

export RESOURCE_GROUP="ms-identity-containerapps"
export LOCATION="canadacentral"
export ENVIRONMENT="env-ms-identity-containerapps"
export API_NAME="ms-identity-api"
export JAR_FILE_PATH_AND_NAME="./target/ms-identity-spring-boot-webapp-0.0.1-SNAPSHOT.jar"

Vytvořte skupinu prostředků.

az group create  \
    --name $RESOURCE_GROUP \
    --location $LOCATION \

Vytvořte prostředí s automaticky vygenerovaným pracovním prostorem služby Log Analytics.

az containerapp env create \
    --name $ENVIRONMENT \
    --resource-group $RESOURCE_GROUP \
    --location $LOCATION

Zobrazí výchozí doménu prostředí kontejnerové aplikace. Poznamenejte si tuto doménu, abyste ji mohli použít v dalších částech.

az containerapp env show \
    --name $ENVIRONMENT \
    --resource-group $RESOURCE_GROUP \
    --query properties.defaultDomain

Příprava aplikace na nasazení

Když nasadíte aplikaci do Azure Container Apps, adresa URL pro přesměrování se změní na adresu URL pro přesměrování nasazené instance aplikace v Azure Container 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. Nezapomeňte nahradit <API_NAME> a <default-domain-of-container-app-environment> nahradit skutečnými hodnotami. Například s výchozí doménou pro prostředí Azure Container App z předchozího kroku a ms-identity-api s názvem vaší aplikace byste tuto hodnotu použili https://ms-identity-api.<default-domain>post-logout-redirect-uri .

    post-logout-redirect-uri: https://<API_NAME>.<default-domain-of-container-app-environment>

  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. Pokud soubor potvrdíte do úložiště Git, může se stát, že riskujete. Doporučený přístup najdete v tématu Správa tajných kódů v Azure Container Apps.

Aktualizace registrace aplikace Microsoft Entra ID

Vzhledem k tomu, že se identifikátor URI přesměrování změní v nasazené aplikaci v Azure Container 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://<containerapp-name>.<default domain of container app environment>/login/oauth2/code/například .

  7. Zvolte Uložit.

Nasazení aplikace

Nasaďte balíček JAR do Azure Container Apps.

Poznámka:

V případě potřeby můžete v proměnných prostředí sestavení Java zadat verzi sady JDK. Další informace najdete v tématu Vytváření proměnných prostředí pro Javu v Azure Container Apps.

Teď můžete soubor WAR nasadit pomocí příkazu ROZHRANÍ příkazového az containerapp up řádku.

az containerapp up \
    --name $API_NAME \
    --resource-group $RESOURCE_GROUP \
    --location $LOCATION \
    --environment $ENVIRONMENT \
    --artifact <JAR_FILE_PATH_AND_NAME> \
    --ingress external \
    --target-port 8080 \
    --query properties.configuration.ingress.fqdn

Poznámka:

Výchozí verze sady JDK je 17. Pokud potřebujete změnit verzi sady JDK kvůli kompatibilitě s aplikací, můžete pomocí argumentu --build-env-vars BP_JVM_VERSION=<YOUR_JDK_VERSION> upravit číslo verze.

Další proměnné prostředí sestavení najdete v tématu Vytváření proměnných prostředí pro Javu v Azure Container Apps.

Ověření aplikace

V tomto příkladu containerapp up--query properties.configuration.ingress.fqdn příkaz obsahuje argument, který vrátí plně kvalifikovaný název domény (FQDN), označovaný také jako adresa URL 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 služby Azure Container 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 nebo graf volání. 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 jednu z dalších stránek 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. Výběrem možnosti Volat Graph provedete volání koncového bodu /me v Microsoft Graphu a zobrazí se výběr získaných podrobností o uživateli.
  9. 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 a získání přístupového tokenu pro volání Microsoft Graphu. Ukázka také využívá úvodní sady Spring Oauth2 Client a Spring Web Boot.

Obsah

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

Soubor nebo složka Popis
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í podrobnosti tokenu ID a stránky Graphu volání, aby k nim mohli přistupovat jenom přihlášení uživatelé. Aplikace nakonfiguruje tyto trasy z app.protect.authenticated vlastnosti ze souboru application.yml . Pokud chcete nakonfigurovat specifické požadavky vaší aplikace, můžete rozšířit AADWebSecurityConfigurationAdapter jednu z vašich tříd. Příklad najdete v této třídě SecurityConfig této aplikace, jak je znázorněno v následujícím kódu:

@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class SecurityConfig extends AADWebSecurityConfigurerAdapter{
  @Value( "${app.protect.authenticated}" )
  private String[] protectedRoutes;

    @Override
    public void configure(HttpSecurity http) throws Exception {
    // use required configuration form AADWebSecurityAdapter.configure:
    super.configure(http);
    // add custom configuration:
    http.authorizeRequests()
      .antMatchers(protectedRoutes).authenticated()     // limit these pages to authenticated users (default: /token_details, /call_graph)
      .antMatchers("/**").permitAll();                  // allow all other routes.
    }
}

Graf volání

Když uživatel přejde na /call_graph, aplikace vytvoří instanci GraphServiceClient pomocí spouštěcího Oauth2AuthorizedClientgraphAuthorizedClient startu Microsoft Entra ID. Aplikace požádá GraphServiceClient o volání koncového /me bodu a zobrazí podrobnosti pro aktuálního přihlášeného uživatele. GraphServiceClient je ze sady Microsoft Graph SDK pro Javu verze 3.

Musí Oauth2AuthorizedClient být připraven se správnými obory. Podívejte se na soubor application.yml a následující část Obory . Slouží Oauth2AuthorizedClient k zobrazení přístupového tokenu a jeho umístění do Authorization hlavičky GraphServiceClient požadavků, jak je znázorněno v následujícím příkladu:

//see SampleController.java
@GetMapping(path = "/call_graph")
public String callGraph(@RegisteredOAuth2AuthorizedClient("graph") OAuth2AuthorizedClient graphAuthorizedClient) {
  // See the Utilities.graphUserProperties() method for the full example of the following operation:
  GraphServiceClient graphServiceClient = Utilities.getGraphServiceClient(graphAuthorizedClient);
  User user = graphServiceClient.me().buildRequest().get();
  return user.displayName;
}

Následující příklad ze souboru application.yml ukazuje požadované obory:

# see application.yml file
authorization-clients:
  graph:
    # Specifies the Microsoft Graph scopes that your app needs access to:
    scopes: https://graph.microsoft.com/User.Read

Rozsahy

Obory říkají Microsoft Entra ID úrovně přístupu, kterou aplikace požaduje. Rozsahy Microsoft Graphu požadované touto aplikací najdete v application.yml.

Ve výchozím nastavení aplikace nastaví hodnotu oborů na https://graph.microsoft.com/User.Read. Obor User.Read je určený pro přístup k informacím aktuálního přihlášeného uživatele z koncového bodu /me. Platné požadavky na koncový bod /me musí obsahovat User.Read obor.

Když se uživatel přihlásí, Microsoft Entra ID zobrazí uživateli dialog souhlasu na základě rozsahů požadovaných aplikací. Pokud uživatel souhlasí s jedním nebo více obory a získá token, jsou obory se souhlasem zakódovány do výsledného přístupového tokenu.

V této aplikaci se zobrazí přístupový token, graphAuthorizedClient který prokáže, k jakým oborům uživatel souhlasil. Aplikace používá tento token k vytvoření instance GraphServiceClient , která zpracovává požadavky Graphu.

Použití GraphServiceClient.me().buildRequest().get(), žádost je sestavena a provedena v https://graph.microsoft.com/v1.0/me. Přístupový token se umístí do Authorization hlavičky požadavku.

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.