Bejelentkezés engedélyezése Java Tomcat-alkalmazásokhoz a Microsoft Entra ID használatával

  • Cikk

Ez a cikk egy Java Tomcat-alkalmazást mutat be, amely a Java Microsoft Authentication Library (MSAL) használatával jelentkezik be a felhasználókba a Microsoft Entra ID-bérlőbe.

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 az MSAL for Java (MSAL4J) használatával bejelentkezik a felhasználókba a saját Microsoft Entra ID-bérlőjéhez, és beszerez egy azonosító jogkivonatot a Microsoft Entra ID-ból. Az azonosító jogkivonat igazolja, hogy a felhasználó hitelesítése ezzel a bérlővel történik. Az alkalmazás a felhasználó hitelesítési állapota alapján védi az útvonalait.

Előfeltételek

  • JDK 8-os vagy újabb verzió
  • Maven 3
  • Egy Microsoft Entra ID-bérlő. További információ: Microsoft Entra ID-bérlő lekérése.
  • Egy felhasználói fiók a saját Microsoft Entra-azonosítójú bérlőjében, ha csak a szervezeti címtárban lévő fiókokkal szeretne dolgozni , azaz egybérlős módban. Ha még nem hozott létre felhasználói fiókot a Microsoft Entra ID-bérlőjében, ezt a folytatás előtt tegye meg. További információ: Felhasználók létrehozása, meghívása és törlése.
  • Egy felhasználói fiók bármely szervezet Microsoft Entra-azonosítójú bérlőjében, ha bármilyen szervezeti címtárban , azaz több-bérlős módban szeretné használni a fiókokat. Ezt a mintát úgy kell módosítania, hogy személyes Microsoft-fiókkal működjön. Ha még nem hozott létre felhasználói fiókot a Microsoft Entra ID-bérlőjében, ezt a folytatás előtt tegye meg. További információ: Felhasználók létrehozása, meghívása és törlése.
  • Személyes Microsoft-fiók – például Xbox, Hotmail, Live stb. – akkor, ha személyes Microsoft-fiókkal szeretne dolgozni.

Ajánlások

  • Néhány ismerős a Java / Jakarta Servlets.
  • 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-servlet-webapp-authentication.git
cd 1-Authentication/sign-in

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

Fontos

A Windows fájlelérési útvonalának korlátozásainak elkerülése érdekében klónozza vagy bontsa ki az adattárat a merevlemez gyökerének közelében található könyvtárba.

A mintaalkalmazás 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 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 a ./src/main/resources/authentication.properties fájlt.

  3. Keresse meg a sztringet {enter-your-tenant-id-here}. Cserélje le a meglévő értéket az alábbi értékek egyikére:

    • A Microsoft Entra-azonosító bérlőazonosítója, ha az alkalmazást csak ebben a szervezeti címtárban lévő Fiókok lehetőséggel regisztrálta.
    • Az a szó organizations , ha bármilyen szervezeti címtárban regisztrálta az alkalmazást a Fiókok mappában .
    • Az a szócommon, ha az alkalmazást bármely szervezeti címtárban és személyes Microsoft-fiókban regisztrálta a Fiókok mappában.
    • Az a szó consumers , ha az alkalmazást a Személyes Microsoft-fiókok lehetőséggel regisztrálta .

  4. Keresse meg a sztringet {enter-your-client-id-here} , és cserélje le a meglévő értéket az alkalmazásazonosítóra vagy clientId az java-servlet-webapp-authentication Azure Portalról másolt alkalmazásra.

  5. Keresse meg a sztringet {enter-your-client-secret-here} , és cserélje le a meglévő értéket az alkalmazás létrehozása során mentett értékre az java-servlet-webapp-authentication Azure Portalon.

A minta összeállítása

Ha a mintát a Maven használatával szeretné létrehozni, keresse meg a minta pom.xml fájljának könyvtárát, majd futtassa a következő parancsot:

mvn clean package

Ez a parancs létrehoz egy .war fájlt, amelyet számos alkalmazáskiszolgálón futtathat.

Minta futtatása

Az alábbi szakaszok bemutatják, hogyan helyezheti üzembe a mintát Azure-alkalmazás szolgáltatásban.

Előfeltételek

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

A Azure-alkalmazás Szolgáltatásban való üzembe helyezéskor az üzembe helyezés automatikusan az Azure CLI-ből származó Azure-hitelesítő adatokat használja. Ha az Azure CLI nincs helyileg telepítve, akkor a Maven beépülő modul az OAuth vagy az eszköz bejelentkezésével hitelesít. További információ: Hitelesítés a Maven beépülő modulokkal.

A beépülő modul konfigurálásához kövesse az alábbi lépéseket:

  1. Futtassa a következő parancsot az üzembe helyezés konfigurálásához. Ez a parancs segít a Azure-alkalmazás szolgáltatás operációs rendszerének, a Java-verziónak és a Tomcat-verziónak a beállításában.

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

  2. Új futtatási konfiguráció létrehozásához nyomja le az Y billentyűt, majd nyomja le az Enter billentyűt.

  3. Az operációs rendszer értékének definiálásához nyomja le az 1 billentyűt a Windowshoz, a Linuxhoz pedig 2 billentyűt, majd nyomja le az Enter billentyűt.

  4. A JavaVersion értékének definiálásához nyomja le a 2 billentyűt a Java 11-hez, majd nyomja le az Enter billentyűt.

  5. A webContainer értékének definiálásához nyomja le a 4 billentyűt a Tomcat 9.0-hoz, majd nyomja le az Enter billentyűt.

  6. A pricingTier értékének meghatározásához nyomja le az Enter billentyűt az alapértelmezett P1v2 szint kiválasztásához.

  7. A megerősítéshez nyomja le az Y billentyűt, majd nyomja le az Enter billentyűt.

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

Please confirm webapp properties
AppName : msal4j-servlet-auth-1707209552268
ResourceGroup : msal4j-servlet-auth-1707209552268-rg
Region : centralus
PricingTier : P1v2
OS : Linux
Java Version: Java 11
Web server stack: Tomcat 9.0
Deploy to slot : false
Confirm (Y/N) [Y]: [INFO] Saving configuration to pom.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  37.112 s
[INFO] Finished at: 2024-02-06T08:53:02Z
[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 a Azure-alkalmazás Szolgáltatásban való futtatásra.

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

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

Az App Service konfigurációit közvetlenül a pom.xml 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 alkalmazás Azure-erőforráscsoportja.
appName true Az alkalmazás neve.
region false Az a régió, amelyben az alkalmazást üzemeltetni szeretné. Az alapértelmezett érték centralus. Érvényes régiókért lásd: Támogatott régiók.
pricingTier false Az alkalmazás tarifacsomagja. Az alapértelmezett érték egy éles számítási feladathoz tartozik P1v2 . A Java-fejlesztés és -tesztelés ajánlott minimális értéke a B2. További információkért tekintse meg az App Service díjszabását.
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. A Azure-alkalmazás Service-hez kapcsolódó konfigurációkért lásd: Azure-alkalmazás: Konfiguráció részletei.

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

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

Amikor üzembe helyezi az alkalmazást az App Service-ben, az átirányítási URL-cím az üzembe helyezett alkalmazáspéldány átirányítási URL-címére változik. A tulajdonságok fájljában a következő lépésekkel módosíthatja ezeket a beállításokat:

  1. Keresse meg az alkalmazás authentication.properties fájlját, és módosítsa a app.homePage telepített alkalmazás tartománynevére az alábbi példában látható módon. Ha például az előző lépésben az alkalmazás nevét választotta example-domain , akkor most már használnia https://example-domain.azurewebsites.net kell az app.homePage értéket. Győződjön meg arról, hogy a protokollt is módosította a másikra httphttps.

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

Ugyanebben a authentication.properties fájlban van egy beállítás az Ön aad.secretszámára. Nem ajánlott ezt az értéket az App Service-ben üzembe helyezni. Nem ajánlott ezt az értéket a kódban hagyni, és potenciálisan leküldni a git-adattárba. Ha el szeretné távolítani ezt a titkos értéket a kódból, részletesebb útmutatást az App Service-ben való üzembe helyezés – Titkos kódok eltávolítása című szakaszban talál. Ez az útmutató további lépéseket tartalmaz a titkos kulcs értékének a Key Vaultba való leküldéséhez és a Key Vault-referenciák használatához.

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

Mivel az átirányítási URI Azure-alkalmazás Szolgáltatásra változik, a Microsoft Entra ID alkalmazásregisztrációjában is módosítania kell az átirányítási URI-t. 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 /auth/redirect például https://<your-app-name>.azurewebsites.net/auth/redirect.

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

Az alkalmazás üzembe helyezése

Most már készen áll az alkalmazás üzembe helyezésére Azure-alkalmazás Service-ben. Az alábbi paranccsal győződjön meg arról, hogy bejelentkezett az Azure-környezetbe az üzembe helyezés végrehajtásához:

az login

Ha az összes konfiguráció készen áll a pom.xml fájlban, a következő paranccsal telepítheti a Java-alkalmazást az Azure-ban:

mvn package azure-webapp:deploy

Az üzembe helyezés befejezése után az alkalmazás készen áll a .http://<your-app-name>.azurewebsites.net/ Nyissa meg az URL-címet a helyi webböngészővel, ahol meg kell jelennie az msal4j-servlet-auth alkalmazás kezdőlapjának.

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.
  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. Figyelje meg, hogy a környezetfüggő gomb most kijelentkezik , és megjeleníti a felhasználónevét.
  6. Válassza az Azonosító jogkivonat részletei lehetőséget az azonosító jogkivonat egyes dekódolt jogcímeinek megtekintéséhez.
  7. A kijelentkezéshez használja a sarokban lévő gombot.
  8. A kijelentkezés után válassza az Azonosító jogkivonat részletei lehetőséget , és figyelje meg, hogy az alkalmazás hibaüzenetet 401: unauthorized jelenít meg az azonosító jogkivonat jogcímei helyett, ha a felhasználó nincs engedélyezve.

Tudnivalók a kódról

Ez a minta bemutatja, hogyan lehet az MSAL for Java (MSAL4J) használatával bejelentkezni a felhasználókba a Microsoft Entra ID-bérlőbe. Ha saját alkalmazásaiban szeretné használni az MSAL4J-t, akkor azt a Maven használatával kell hozzáadnia a projektjeihez.

Ha replikálni szeretné a minta viselkedését, az src/main/java/com/microsoft/azuresamples/msal4j mappába másolhatja a pom.xml fájlt, valamint a segítők és authservlets mappák tartalmát. Szüksége van a authentication.properties fájlra is. Ezek az osztályok és fájlok általános kódot tartalmaznak, amelyeket számos alkalmazásban használhat. A minta többi részét is másolhatja, de a többi osztály és fájl kifejezetten a minta céljának megfelelően van létrehozva.

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.
src/main/java/com/microsoft/azuresamples/msal4j/authwebapp/ Ez a könyvtár tartalmazza azokat az osztályokat, amelyek meghatározzák az alkalmazás háttérbeli üzleti logikáját.
src/main/java/com/microsoft/azuresamples/msal4j/authservlets/ Ez a könyvtár tartalmazza a bejelentkezéshez és a végpontok kijelentkezéshez használt osztályokat.
____Servlet.java Az összes elérhető végpont .java ____Servlet.java. osztályban van definiálva.
src/main/java/com/microsoft/azuresamples/msal4j/helpers/ Segédosztályok hitelesítéshez.
AuthenticationFilter.java A nem hitelesített kéréseket átirányítja a védett végpontokra egy 401-es lapra.
src/main/resources/authentication.properties Microsoft Entra-azonosító és programkonfiguráció.
src/main/webapp/ Ez a könyvtár tartalmazza a felhasználói felület – JSP-sablonokat
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.

ConfidentialClientApplication

A rendszer létrehoz egy ConfidentialClientApplication példányt a AuthHelper.java fájlban, ahogy az az alábbi példában is látható. Ez az objektum segít a Microsoft Entra-azonosító engedélyezési URL-címének elkészítésében, valamint a hitelesítési jogkivonatok hozzáférési jogkivonatra való cseréjében.

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

A rendszer a következő paramétereket használja a példányosításhoz:

  • Az alkalmazás ügyfélazonosítója.
  • Az ügyfél titkos kódja, amely a bizalmas ügyfélalkalmazások követelménye.
  • A Microsoft Entra ID-szolgáltató, amely tartalmazza a Microsoft Entra-azonosító bérlőazonosítóját.

Ebben a mintában ezeket az értékeket a rendszer a authentication.properties fájlból olvassa be a Config.java fájl egyik tulajdonságolvasójának használatával.

Útmutató lépésről lépésre

Az alábbi lépések bemutatja az alkalmazás funkcióit:

  1. A bejelentkezési folyamat első lépése egy kérés küldése a végpontra a /authorize Microsoft Entra ID-bérlőhöz. Az MSAL4J-példány ConfidentialClientApplication egy engedélyezési kérelem URL-címének létrehozására szolgál. Az alkalmazás átirányítja a böngészőt erre az URL-címre, ahol a felhasználó bejelentkezik.

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

    Az alábbi lista a kód funkcióit ismerteti:

    • AuthorizationRequestUrlParameters: Az AuthorizationRequestUrl létrehozásához be kell állítani paramétereket.

    • REDIRECT_URI: Ahol a Microsoft Entra ID átirányítja a böngészőt – a hitelesítési kóddal együtt – a felhasználói hitelesítő adatok gyűjtése után. Meg kell egyeznie az átirányítási URI-val a Microsoft Entra ID alkalmazásregisztrációjában az Azure Portalon.

    • SCOPES: A hatókörök az alkalmazás által kért engedélyek. Általában a három hatókör openid profile offline_access elegendő az azonosító jogkivonat-válaszának fogadásához.

      Az alkalmazás által kért hatókörök teljes listáját a authentication.properties fájlban találja. További hatóköröket is hozzáadhat, például User.Read.

  2. A microsoft Entra ID egy bejelentkezési kérést jelenít meg a felhasználó számára. Ha a bejelentkezési kísérlet sikeres, a rendszer átirányítja a felhasználó böngészőjét az alkalmazás átirányítási végpontjára. A végpontra irányuló érvényes kérések engedélyezési kódot tartalmaznak.

  3. A ConfidentialClientApplication példány ezután kicseréli ezt az engedélyezési kódot egy azonosító jogkivonatra, és hozzáférési jogkivonatot a Microsoft Entra ID-ból.

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

    Az alábbi lista a kód funkcióit ismerteti:

    • AuthorizationCodeParameters: Olyan paraméterek, amelyeket be kell állítani az engedélyezési kód azonosítóra és/vagy hozzáférési jogkivonatra való cseréjéhez.
    • authCode: Az átirányítási végponton kapott engedélyezési kód.
    • REDIRECT_URI: Az előző lépésben használt átirányítási URI-t ismét át kell adni.
    • SCOPES: Az előző lépésben használt hatóköröket ismét át kell adni.

  4. Ha acquireToken a jogkivonat sikeres, a rendszer kinyeri a jogkivonat-jogcímeket. Ha a nem megfelelő ellenőrzés sikeres, az eredmények bekerülnek a munkamenetbe context – egy példányba IdentityContextData – és mentve lesznek. Az alkalmazás ezután példányosíthatja a IdentityContextData munkamenetből egy példányt IdentityContextAdapterServlet , amikor hozzá kell férnie, ahogy az a következő kódban is látható:

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

Az útvonalak védelme

További információ arról, hogy a mintaalkalmazás hogyan szűri az útvonalakhoz való hozzáférést: AuthenticationFilter.java. A authentication.properties fájlban a app.protect.authenticated tulajdonság tartalmazza azokat a vesszővel tagolt útvonalakat, amelyekhez csak a hitelesített felhasználók férhetnek hozzá, ahogyan az alábbi példában látható:

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

Hatókörök

A hatókörök közlik a Microsoft Entra-azonosítóval az alkalmazás által kért hozzáférési szintet.

A kért hatókörök alapján a Microsoft Entra ID hozzájárulási párbeszédet jelenít meg a felhasználónak bejelentkezéskor. Ha a felhasználó egy vagy több hatókörhöz járul hozzá, és jogkivonatot szerez be, a hatókörök hozzájárulásával a rendszer az eredményül kapott access_tokenkódba kódolja a hatóköröket.

Az alkalmazás által kért hatókörökért lásd : authentication.properties. Ezt a három hatókört az MSAL kéri, és alapértelmezés szerint a Microsoft Entra ID adja meg.

További információ