Share via

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

  • Článek

Tento článek ukazuje aplikaci Java JBoss EAP, která přihlásí uživatele a získá přístupový token pro volání Microsoft Graphu. Používá knihovnu MICROSOFT Authentication Library (MSAL) pro Javu.

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

Diagram znázorňující topologii aplikace

Klientská aplikace používá msAL pro Javu (MSAL4J) k přihlášení uživatele a 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

  • Java 8 nebo vyšší
  • Maven 3
  • Tenant Microsoft Entra ID. Další informace naleznete v tématu Získání tenanta Microsoft Entra ID.
  • Uživatelský účet ve vašem vlastním tenantovi Microsoft Entra ID, pokud chcete pracovat jenom s účty v adresáři organizace – to znamená režim s jedním tenantem. Pokud jste ještě ve svém tenantovi nevytvořili uživatelský účet, měli byste to udělat předtím, než budete pokračovat. Další informace najdete v tématu Vytváření, pozvání a odstraňování uživatelů.
  • Uživatelský účet v tenantovi Microsoft Entra ID jakékoli organizace, pokud chcete pracovat s účty v libovolném organizačním adresáři – to znamená v režimu s více tenanty. Tato ukázka musí být upravena tak, aby fungovala s osobním účtem Microsoft. Pokud jste ještě ve svém tenantovi nevytvořili uživatelský účet, měli byste to udělat předtím, než budete pokračovat. Další informace najdete v tématu Vytváření, pozvání a odstraňování uživatelů.
  • Osobní účet Microsoft – například Xbox, Hotmail, Live atd., pokud chcete pracovat s osobními účty Microsoft.

Doporučení

  • Znalost Javy / Jakarta Servlets.
  • 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-servlet-webapp-authentication.git
cd 2-Authorization-I/call-graph

Případně přejděte do úložiště ms-identity-java-servlet-webapp-authentication , 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é aplikace 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-servlet-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/authentication.properties.

  3. Vyhledejte řetězec {enter-your-tenant-id-here}. Nahraďte existující hodnotu jednou z následujících hodnot:

    • ID tenanta Microsoft Entra ID, pokud jste aplikaci zaregistrovali jenom s účty v tomto organizačním adresáři .
    • Slovo organizations , pokud jste aplikaci zaregistrovali u účtů v libovolné možnosti adresáře organizace.
    • Slovo common , pokud jste aplikaci zaregistrovali pomocí účtů v libovolném organizačním adresáři a osobních účtech Microsoft.
    • Slovo consumers , pokud jste aplikaci zaregistrovali pomocí možnosti Osobní účty Microsoft

  4. Vyhledejte řetězec {enter-your-client-id-here} a nahraďte existující hodnotu ID aplikace nebo clientIdjava-servlet-webapp-call-graph aplikace zkopírovanou z webu Azure Portal.

  5. Najděte řetězec {enter-your-client-secret-here} a nahraďte existující hodnotu hodnotou, kterou jste uložili při vytváření java-servlet-webapp-call-graph aplikace, na webu Azure Portal.

Sestavení ukázky

Pokud chcete vytvořit ukázku pomocí Mavenu, přejděte do adresáře obsahujícího soubor pom.xml ukázky a spusťte následující příkaz:

mvn clean package

Tento příkaz vygeneruje soubor .war , který můžete spustit na různých aplikačních serverech.

Spuštění ukázky

Následující části ukazují, jak nasadit ukázku do služby Aplikace Azure Service.

Požadavky

Konfigurace modulu plug-in Maven

Proces nasazení do služby Aplikace Azure Service používá vaše přihlašovací údaje Azure z Azure CLI automaticky. Pokud se Azure CLI nenainstaluje místně, pak se modul plug-in Maven ověří pomocí OAuth nebo přihlášení zařízení. Další informace najdete v tématu ověřování pomocí modulů plug-in Maven.

Ke konfiguraci modulu plug-in použijte následující postup:

  1. Spuštěním příkazu Maven zobrazeného vedle konfigurace nasazení Tento příkaz vám pomůže nastavit operační systém služby App Service, verzi Javy a verzi Tomcat.

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

  2. Pokud chcete vytvořit novou konfiguraci spuštění, stiskněte Y a pak stiskněte Enter.

  3. Pro definování hodnoty pro operační systém stiskněte 2 pro Linux a pak stiskněte Enter.

  4. Pro definici hodnoty javaVersion stiskněte 2 pro Javu 11 a pak stiskněte Enter.

  5. Pro define value for webContainer, press 1 for JBosseap7, then press Enter.

  6. Pokud chcete definovat hodnotu pro pricingTier, stiskněte Enter a vyberte výchozí úroveň P1v3 .

  7. Potvrďte akci stisknutím klávesy Y a pak stiskněte Enter.

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

Please confirm webapp properties
AppName : msal4j-servlet-auth-1707220080695
ResourceGroup : msal4j-servlet-auth-1707220080695-rg
Region : centralus
PricingTier : P1v3
OS : Linux
Java Version: Java 11
Web server stack: JBosseap 7
Deploy to slot : false
Confirm (Y/N) [Y]:
[INFO] Saving configuration to pom.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  26.196 s
[INFO] Finished at: 2024-02-06T11:48:16Z
[INFO] ------------------------------------------------------------------------

Jakmile potvrdíte volby, modul plug-in přidá konfiguraci modulu plug-in a požadované nastavení do souboru pom.xml projektu a nakonfiguruje aplikaci tak, aby běžela ve službě Aplikace Azure Service.

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

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

Konfigurace služby App Service můžete upravit přímo ve vašem pom.xml. Některé běžné konfigurace jsou uvedeny v následující tabulce:

Vlastnost Požadováno Popis Verze
schemaVersion false (nepravda) Verze schématu konfigurace. Podporované hodnoty jsou v1 a v2. 1.5.2
subscriptionId false (nepravda) ID předplatného. 0.1.0+
resourceGroup true Skupina prostředků Azure pro vaši aplikaci. 0.1.0+
appName true Název aplikace. 0.1.0+
region false (nepravda) Oblast, ve které se má aplikace hostovat. Výchozí hodnota je centralus. Platné oblasti najdete v tématu Podporované oblasti. 0.1.0+
pricingTier false (nepravda) Cenová úroveň vaší aplikace. Výchozí hodnota je P1v2 pro produkční úlohu. Doporučená minimální hodnota pro vývoj a testování v Javě je B2. Další informace najdete v tématu Ceny služby App Service. 0.1.0+
runtime false (nepravda) Konfigurace prostředí runtime. Další informace najdete v tématu Podrobnosti o konfiguraci. 0.1.0+
deployment false (nepravda) Konfigurace nasazení. Další informace najdete v tématu Podrobnosti o konfiguraci. 0.1.0+

Ú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 službu Aplikace Azure Najdete v tématu Aplikace Azure: Podrobnosti konfigurace.

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

Příprava aplikace na nasazení

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

  1. Přejděte do souboru authentication.properties vaší aplikace a změňte hodnotu app.homePage 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 example-domain název aplikace, musíte tuto hodnotu použít https://example-domain.azurewebsites.netapp.homePage . Ujistěte se, že jste také změnili protokol z http na https.

    # 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 uložení tohoto souboru pomocí následujícího příkazu znovu sestavte aplikaci:

    mvn clean package

Důležité

V tomto souboru authentication.properties máte nastavení pro svůj aad.secret. Není vhodné tuto hodnotu nasadit do služby App Service. Ani to není vhodné nechat tuto hodnotu v kódu a potenciálně ji odeslat do úložiště Git. Pokud chcete tuto hodnotu tajného kódu odebrat, najdete podrobnější pokyny v části Nasazení do služby App Service – Odebrání tajného kódu . Tyto pokyny přidávají další kroky pro nasdílení hodnoty tajného kódu do služby Key Vault a použití odkazů služby Key Vault.

Aktualizace registrace aplikace Microsoft Entra ID

Vzhledem k tomu, že identifikátor URI přesměrování se změní na nasazenou aplikaci na službu Aplikace Azure Service, 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 /auth/redirect ho , https://<your-app-name>.azurewebsites.net/auth/redirectnapříklad .

  7. Zvolte Uložit.

Nasazení aplikace

Teď jste připraveni nasadit aplikaci do služby Aplikace Azure Service. Pomocí následujícího příkazu se ujistěte, že jste přihlášení ke svému prostředí Azure a spusťte nasazení:

az login

S veškerou konfigurací připravenou v souboru pom.xml teď můžete pomocí následujícího příkazu nasadit aplikaci v Javě do Azure:

mvn package azure-webapp:deploy

Po dokončení nasazení je vaše aplikace připravená na http://<your-app-name>.azurewebsites.net/adrese . Otevřete adresu URL v místním webovém prohlížeči, kde byste měli vidět úvodní stránku msal4j-servlet-auth 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.
  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. Všimněte si, že kontextové tlačítko se teď zobrazuje odhlásit a zobrazit vaše uživatelské jméno.
  6. Výběrem podrobností o tokenu ID zobrazíte některé dekódované deklarace identity tokenu ID.
  7. 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.
  8. Pomocí tlačítka v rohu se odhlaste.

O kódu

Tato ukázka používá MSAL pro Javu (MSAL4J) k přihlášení uživatele a získání tokenu pro rozhraní Microsoft Graph API. K získání dat z Graphu používá sadu Microsoft Graph SDK pro Javu . Tyto knihovny musíte přidat do svých projektů pomocí Mavenu.

Pokud chcete replikovat chování této ukázky, můžete zkopírovat soubor pom.xml a obsah pomocných rutin a složek authservlets ve složce src/main/java/com/microsoft/azuresamples/msal4j. Potřebujete také soubor authentication.properties . Tyto třídy a soubory obsahují obecný kód, který můžete použít v široké škále aplikací. Zbývající část ukázky můžete také zkopírovat, ale ostatní třídy a soubory jsou vytvořené speciálně tak, aby řešily cíl této ukázky.

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
src/main/java/com/microsoft/azuresamples/msal4j/callgraphwebapp/ Tento adresář obsahuje třídy definující back-endovou obchodní logiku aplikace.
src/main/java/com/microsoft/azuresamples/msal4j/authservlets/ Tento adresář obsahuje třídy, které se používají k přihlášení a odhlášení koncových bodů.
____Servlet.java Všechny dostupné koncové body jsou definovány ve třídách .java končících na ____Servlet.java..
src/main/java/com/microsoft/azuresamples/msal4j/helpers/ Pomocné třídy pro ověřování.
AuthenticationFilter.java Přesměruje neověřené požadavky na chráněné koncové body na stránku 401.
src/main/resources/authentication.properties Microsoft Entra ID a konfigurace programu.
src/main/webapp/ Tento adresář obsahuje uživatelské rozhraní – šablony JSP.
CHANGELOG.md Seznam změn v ukázce
CONTRIBUTING.md Pokyny pro přispívání do ukázky
LICENCE Licence pro ukázku.

ConfidentialClientApplication

Instance ConfidentialClientApplication se vytvoří v souboru AuthHelper.java , jak je znázorněno v následujícím příkladu. Tento objekt pomáhá vytvořit autorizační adresu URL microsoft Entra ID a také pomáhá vyměnit ověřovací token pro přístupový token.

// getConfidentialClientInstance method
IClientSecret secret = ClientCredentialFactory.createFromSecret(SECRET);
confClientInstance = ConfidentialClientApplication
                     .builder(CLIENT_ID, secret)
                     .authority(AUTHORITY)
                     .build();

Pro vytváření instancí se používají následující parametry:

  • ID klienta aplikace.
  • Tajný klíč klienta, což je požadavek na důvěrné klientské aplikace.
  • Autorita MICROSOFT Entra ID, která zahrnuje ID vašeho tenanta Microsoft Entra.

V této ukázce se tyto hodnoty čtou ze souboru authentication.properties pomocí čtečky vlastností v souboru Config.java .

Ukázka krok za krokem

Následující kroky poskytují návod k funkcím aplikace:

  1. Prvním krokem procesu přihlášení je odeslání požadavku na /authorize koncový bod pro vašeho tenanta Microsoft Entra ID. Instance MSAL4J ConfidentialClientApplication slouží k vytvoření adresy URL žádosti o autorizaci. Aplikace přesměruje prohlížeč na tuto adresu URL, což je místo, kde se uživatel přihlásí.

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

    Následující seznam popisuje funkce tohoto kódu:

    • AuthorizationRequestUrlParameters: Parametry, které musí být nastaveny pro sestavení AuthorizationRequestUrl.
    • REDIRECT_URI: Kde Microsoft Entra ID přesměruje prohlížeč – spolu s ověřovacím kódem – po shromáždění přihlašovacích údajů uživatele. Musí odpovídat identifikátoru URI přesměrování v registraci aplikace Microsoft Entra ID na webu Azure Portal.
    • SCOPES: Obory jsou oprávnění požadovaná aplikací.
      • Za normálních okolností stačí tři obory openid profile offline_access pro příjem odpovědi tokenu ID.
      • Úplný seznam oborů požadovaných aplikací najdete v souboru authentication.properties . Můžete přidat další obory, jako je User.Read atd.

  2. Uživateli se zobrazí výzva k přihlášení pomocí ID Microsoft Entra. Pokud je pokus o přihlášení úspěšný, prohlížeč uživatele se přesměruje do koncového bodu přesměrování aplikace. Platný požadavek na tento koncový bod obsahuje autorizační kód.

  3. Instance ConfidentialClientApplication pak tento autorizační kód pro token ID a přístupový token vymění z 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();

    Následující seznam popisuje funkce tohoto kódu:

    • AuthorizationCodeParameters: Parametry, které musí být nastaveny pro výměnu autorizačního kódu pro ID nebo přístupový token.
    • authCode: Autorizační kód přijatý v koncovém bodu přesměrování.
    • REDIRECT_URI: Identifikátor URI přesměrování použitý v předchozím kroku musí být znovu předán.
    • SCOPES: Obory použité v předchozím kroku musí být předány znovu.

  4. Pokud acquireToken je deklarace identity tokenu úspěšné, extrahují se. Pokud kontrola nesouvisení projde, výsledky se umístí do context instance IdentityContextData relace a uloží se do relace. Aplikace pak může vytvořit IdentityContextData instanci z relace prostřednictvím instance IdentityContextAdapterServlet , kdy k ní potřebuje přístup, jak je znázorněno v následujícím kódu:

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

Ochrana tras

Informace o tom, jak ukázková aplikace filtruje přístup k trasám, najdete v tématu AuthenticationFilter.java. V souboru app.protect.authenticated authentication.properties vlastnost obsahuje trasy oddělené čárkami, ke kterým mají přístup pouze ověření uživatelé, jak je znázorněno v následujícím příkladu:

# for example, /token_details requires any user to be signed in and does not require special roles or groups claim(s)
app.protect.authenticated=/token_details, /call_graph

Graf volání

Když uživatel přejde na /call_graph, aplikace vytvoří instanci IGraphServiceClient sady Java Graph SDK , která předává přístupový token přihlášeného uživatele. Klient Graphu umístí přístupový token do Authorization hlaviček svých požadavků. Aplikace pak požádá klienta Graphu, aby volal /me koncový bod, aby poskytl podrobnosti pro aktuálně přihlášeného uživatele.

Následující kód je vše, co vývojář aplikace potřebuje k zápisu pro přístup ke koncovému /me bodu za předpokladu, že už má platný přístupový token pro Službu Graph Service s oborem User.Read .

//CallGraphServlet.java
User user = GraphHelper.getGraphClient(contextAdapter).me().buildRequest().get();

Rozsahy

Obory říkají Microsoft Entra ID úrovně přístupu, kterou aplikace požaduje.

V závislosti na požadovaných oborech zobrazí ID Microsoft Entra dialog pro vyjádření souhlasu uživateli při přihlášení. Pokud uživatel souhlasí s jedním nebo více obory a získá token, jsou obory s souhlasem zakódovány do výsledného access_token.

Obory požadované aplikací najdete v tématu authentication.properties. Ve výchozím nastavení aplikace nastaví hodnotu oborů na User.Read. Tento konkrétní obor rozhraní Microsoft Graph API je určený pro přístup k informacím aktuálního přihlášeného uživatele. Koncový bod grafu pro přístup k tomuto informacím je https://graph.microsoft.com/v1.0/me. Všechny platné požadavky provedené v tomto koncovém bodu musí obsahovat access_token obor User.Read v Authorization hlavičce.

Více informací