Java Tomcat-apps beveiligen met behulp van rollen en rolclaims

In dit artikel wordt een Java Tomcat-app gedemonstreerd die OpenID Connect gebruikt om gebruikers aan te melden en Microsoft Entra ID-toepassingsrollen (app-rollen) gebruikt voor autorisatie.

Deze toepassing implementeert op rollen gebaseerd toegangsbeheer (RBAC) met behulp van de toepassingsrollen en functie voor rolclaims van Microsoft Entra ID. Een andere benadering is het gebruik van Microsoft Entra-id-groepen en groepsclaims. Microsoft Entra ID-groepen en toepassingsrollen sluiten elkaar niet wederzijds uit. U kunt ze beide gebruiken om gedetailleerd toegangsbeheer te bieden.

U kunt RBAC ook gebruiken met toepassingsrollen en rolclaims om veilig autorisatiebeleid af te dwingen.

Zie Autorisatie implementeren in uw toepassingen met app-rollen, beveiligingsgroepen, machtigingen en maprollen voor een video waarin dit scenario en dit voorbeeld worden behandeld.

Zie Authenticatie versus autorisatie voor meer informatie over hoe de protocollen werken in dit scenario en in andere scenario’s.

Deze toepassing maakt gebruik van MSAL voor Java (MSAL4J) om een gebruiker aan te melden en een ID-token op te halen van Microsoft Entra ID.

In dit voorbeeld wordt eerst MSAL voor Java (MSAL4J) gebruikt om de gebruiker aan te melden. Op de startpagina wordt een optie weergegeven voor de gebruiker om de claims in hun id-tokens weer te geven. Met deze toepassing kunnen gebruikers ook een bevoegde beheerderspagina of een gewone gebruikerspagina bekijken, afhankelijk van de app-rol waaraan ze zijn toegewezen. Het idee is om een voorbeeld te geven van hoe toegang binnen een toepassing tot bepaalde functionaliteit of pagina's wordt beperkt tot subsets van gebruikers, afhankelijk van de rol waartoe ze behoren.

Dit type autorisatie wordt geïmplementeerd met RBAC. Met RBAC verleent een beheerder machtigingen aan rollen, niet aan afzonderlijke gebruikers of groepen. De beheerder kan vervolgens rollen toewijzen aan verschillende gebruikers en groepen om te bepalen wie toegang heeft tot bepaalde inhoud en functionaliteit.

Deze voorbeeldtoepassing definieert de volgende twee toepassingsrollen:

• : Heeft toegang tot de pagina's Alleen beheerders en Normale gebruikers.
• : Geautoriseerd om de Reguliere gebruikers-pagina te openen.

Deze toepassingsrollen worden gedefinieerd in het Azure-portal in het registratiemanifest van de toepassing. Wanneer een gebruiker zich aanmeldt bij de toepassing, verzendt Microsoft Entra ID een rolclaim voor elke rol die afzonderlijk aan de gebruiker wordt verleend in de vorm van rollidmaatschap.

U kunt gebruikers en groepen toewijzen aan rollen via Azure Portal.

Vereisten

• JDK versie 8 of hoger
• Maven 3
• Een Microsoft Entra ID-tenant. Zie Een Microsoft Entra ID-tenant verkrijgen voor meer informatie.
• Een gebruikersaccount in uw eigen Microsoft Entra ID-tenant als u alleen met accounts in uw organisatiedirectory wilt werken, dat wil zeggen de modus voor één tenant. Als u nog geen gebruikersaccount in uw tenant hebt gemaakt, moet u dit doen voordat u doorgaat. Zie Gebruikers maken, uitnodigen en verwijderen voor meer informatie.

• Tomcat 9
• Visual Studio Code
• Azure Tools voor Visual Studio Code

Aanbevelingen

• Enige vertrouwdheid met de Java / Jakarta Servlets.
• Enige bekendheid met Linux/OSX-terminal.
• jwt.ms om uw tokens te inspecteren.
• Fiddler om uw netwerkactiviteit te controleren en problemen op te lossen.
• Volg de Microsoft Entra-blog om up-to-date te blijven met de nieuwste ontwikkelingen.

Het voorbeeld instellen

In de volgende secties ziet u hoe u de voorbeeldtoepassing instelt.

De voorbeeldopslagplaats klonen of downloaden

Als u het voorbeeld wilt klonen, opent u een Bash-venster en gebruikt u de volgende opdracht:

git clone https://github.com/Azure-Samples/ms-identity-msal-java-samples.git
cd 3-java-servlet-web-app/3-Authorization-II/roles

U kunt ook naar de ms-identity-msal-java-samples-repository gaan, deze vervolgens als een .zip-bestand downloaden en op uw harde schijf uitpakken.

De voorbeeldtoepassing registreren bij uw Microsoft Entra ID-tenant

Er is één project in dit voorbeeld. In de volgende secties ziet u hoe u de app registreert met behulp van Azure Portal.

Kies de Microsoft Entra ID-tenant waar u uw toepassingen wilt maken

Gebruik de volgende stappen om uw tenant te kiezen:

1. Meld u aan bij de Azure Portal.

2. Als uw account zich in meer dan één Microsoft Entra ID-tenant bevindt, selecteert u uw profiel in de hoek van de Azure-portal en selecteert u vervolgens Switch directory om uw sessie over te schakelen naar de gewenste Microsoft Entra ID-tenant.

Registreer de app (java-servlet-webapp-roles)

Registreer eerst een nieuwe app in de Azure-portal door de instructies te volgen in Quickstart: Een toepassing registreren met het Microsoft-identiteitsplatform.

Gebruik vervolgens de volgende stappen om de registratie te voltooien:

1. Ga naar de pagina App-registraties in het Microsoft identity platform voor ontwikkelaars.

2. Selecteer Nieuwe registratie.

3. Voer op de pagina Een toepassing registreren die wordt weergegeven de volgende app-registratiegegevens in:

   • Voer in de sectie Naam een duidelijke toepassingsnaam in die aan gebruikers van de app wordt weergegeven, bijvoorbeeld .

   • Selecteer onder Ondersteunde accounttypen een van de volgende opties:

     • Selecteer Alleen accounts in deze organisatiemap als u een toepassing maakt die alleen wordt gebruikt door gebruikers in uw tenant - dat wil zeggen een single-tenant-toepassing.

   • Selecteer in de sectie Omleidings-URI de optie Web in de keuzelijst en voer de volgende omleidings-URI in: .

4. Selecteer Registreren om de toepassing te maken.

5. Ga op de registratiepagina van de app naar de waarde van Toepassings-id (client) en kopieer deze om later te gebruiken. U gebruikt deze waarde in het configuratiebestand of de bestanden van uw app.

6. Selecteer Opslaan om uw wijzigingen op te slaan.

7. Selecteer certificaten en geheimen op de registratiepagina van de app in het navigatiedeelvenster om de pagina te openen waar u geheimen kunt genereren en certificaten kunt uploaden.

8. Selecteer in de sectie Clientgeheimen de optie Nieuw clientgeheim.

9. Typ een beschrijving, bijvoorbeeld app-geheim.

10. Selecteer een vervaldatum voor het geheim of geef een aangepaste levensduur op. Clientgeheimen zijn beperkt tot een maximale levensduur van 24 maanden en Microsoft adviseert een vervaldatum van minder dan 12 maanden. Voor productie-apps gebruikt u bij voorkeur een certificaat of federatieve identiteitsreferentie in plaats van een clientgeheim.

11. Selecteer Toevoegen. De gegenereerde waarde wordt weergegeven.

12. Kopieer en sla de gegenereerde waarde op voor gebruik in latere stappen. U hebt deze waarde nodig voor de configuratiebestanden van uw code. Deze waarde wordt niet opnieuw weergegeven en u kunt deze niet op een andere manier ophalen. Zorg er dus voor dat u deze opslaat in Azure Portal voordat u naar een ander scherm of deelvenster navigeert.

De toepassingsrollen definiëren

Gebruik de volgende stappen om de app-rollen te definiëren:

1. Selecteer in dezelfde app-registratie nog steeds App roles in het navigatievenster.

2. Selecteer App-rol maken en voer vervolgens de volgende waarden in:

   • Voer voor Weergavenaam een geschikte naam in, bijvoorbeeld PrivilegedAdmin.
   • Kies voor Toegestane lidtypen de optie Gebruiker.
   • Voor Value voert u PrivilegedAdmin in.
   • Voer voor Beschrijving PrivilegedAdmins die de beheerderspagina kunnen bekijken in.

3. Selecteer App-rol maken en voer vervolgens de volgende waarden in:

   • Voer voor Weergavenaam een geschikte naam in, bijvoorbeeld RegularUser.
   • Kies voor Toegestane lidtypen de optie Gebruiker.
   • Voer bij Waarde RegularUser in.
   • Voer bij Description RegularUsers die de User Page kunnen bekijken in.

4. Selecteer Toepassen om uw wijzigingen op te slaan.

Gebruikers toewijzen aan de toepassingsrollen

Als u gebruikers wilt toevoegen aan de approl die eerder is gedefinieerd, volgt u de richtlijnen hier: Gebruikers en groepen toewijzen aan rollen.

De app (java-servlet-webapp-roles) configureren om uw app-registratie te gebruiken

Gebruik de volgende stappen om de app te configureren:

1. Open het project in uw IDE.

2. Open het bestand authentication.properties.

3. Zoek de tekenreeks . Vervang de bestaande waarde door de tenant-id van Microsoft Entra ID.

4. Zoek de tekenreeks en vervang de bestaande waarde door de toepassings-id of van de toepassing die is gekopieerd uit Azure Portal.

5. Zoek de tekenreeks en vervang de bestaande waarde door de waarde die u hebt opgeslagen tijdens het maken van de app in de Azure-portal.

6. Zoek de eigenschap en zorg ervoor dat de waarde is ingesteld op , of vervang de namen door die van uw specifieke rollen.

Compileer het voorbeeld

Als u het voorbeeld wilt bouwen met behulp van Maven, gaat u naar de map met het pom.xml-bestand voor het voorbeeld en voert u de volgende opdracht uit:

mvn clean package

Met deze opdracht wordt een WAR-bestand gegenereerd dat u op verschillende toepassingsservers kunt uitvoeren.

De voorbeeldtoepassing uitvoeren

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

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

mvn package azure-webapp:deploy

Het voorbeeld verkennen

Gebruik de volgende stappen om het voorbeeld te verkennen:

1. Merk op dat de aanmeldings- of afmeldstatus in het midden van het scherm wordt weergegeven.
2. Selecteer de contextgevoelige knop in de hoek. Op deze knop staat Sign In wanneer u de app voor het eerst opent.
3. Volg op de volgende pagina de instructies en meld u aan met een account in de Microsoft Entra ID-tenant.
4. Let op de machtigingen die op het toestemmingsscherm worden gevraagd.
5. Merk op dat de contextgevoelige knop nu Afmelden zegt en uw gebruikersnaam weergeeft.
6. Selecteer Details van id-token om enkele van de gedecodeerde claims van het id-token weer te geven.
7. Selecteer Admins Only om de pagina te bekijken. Alleen gebruikers met een app-rol PrivilegedAdmin kunnen deze pagina bekijken. Anders wordt een autorisatiefoutbericht weergegeven.
8. Selecteer Reguliere gebruikers om de -pagina weer te geven. Alleen gebruikers met app-rol of kunnen deze pagina bekijken. Anders wordt een autorisatiefoutbericht weergegeven.
9. Gebruik de knop in de hoek om u af te melden.

Over de code

In dit voorbeeld wordt MSAL voor Java (MSAL4J) gebruikt om een gebruiker aan te melden en een id-token te verkrijgen dat de rolclaim kan bevatten. Op basis van de aanwezige rollenclaim kan de aangemelde gebruiker toegang krijgen tot geen, één of beide beveiligde pagina's, en .

Als u het gedrag van dit voorbeeld wilt repliceren, kunt u het pom.xml-bestand en de inhoud van de helpers en authservlets-mappen kopiëren in de map src/main/java/com/microsoft/azuresamples/msal4j . U hebt ook het bestand authentication.properties nodig. Deze klassen en bestanden bevatten algemene code die u kunt gebruiken in een breed scala aan toepassingen. U kunt ook de rest van het voorbeeld kopiëren, maar de andere klassen en bestanden zijn specifiek ontworpen om aan het doel van dit voorbeeld te voldoen.

Inhoud

In de volgende tabel ziet u de inhoud van de voorbeeldprojectmap:

Een rollenclaim verwerken in het id-token

De rollenclaim van het token bevat de namen van de rollen waaraan de aangemelde gebruiker is toegewezen, zoals wordt weergegeven in het volgende voorbeeld:

{
  ...
  "roles": [
    "Role1",
    "Role2",]
  ...
}

ConfidentialClientApplication

Er wordt een exemplaar van gemaakt in het bestand AuthHelper.java, zoals in het volgende voorbeeld wordt weergegeven. Dit object helpt bij het maken van de Autorisatie-URL van Microsoft Entra en helpt ook bij het uitwisselen van het verificatietoken voor een toegangstoken.

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

De volgende parameters worden gebruikt voor instantiëring:

• De client-id van de app.
• Het clientgeheim, dat vereist is voor Vertrouwelijke clienttoepassingen.
• De Microsoft Entra-id-autoriteit, die uw Microsoft Entra-tenant-id bevat.

In dit voorbeeld worden deze waarden gelezen uit het bestand authentication.properties met behulp van een eigenschappenlezer in het bestand Config.java .

Stapsgewijze handleiding

De volgende stappen bieden een overzicht van de functionaliteit van de app:

1. De eerste stap van het aanmeldproces is het verzenden van een aanvraag naar het -eindpunt voor uw Microsoft Entra ID-tenant. Het MSAL4J-exemplaar wordt gebruikt om een URL voor een autorisatieaanvraag op te bouwen. De app leidt de browser om naar deze URL, waar de gebruiker zich aanmeldt.

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

   In de volgende lijst worden de functies van deze code beschreven:

   • : Parameters die moeten worden ingesteld om een AuthorizationRequestUrl op te bouwen.
   • : Waar Microsoft Entra ID de browser naartoe omleidt, samen met de autorisatiecode, nadat gebruikersreferenties zijn verzameld. Deze moet overeenkomen met de omleidings-URI in de app-registratie voor Microsoft Entra ID in de Azure-portal.
   • : Scopes zijn machtigingen die door de applicatie worden aangevraagd.
     • Normaal gesproken volstaan de drie scopes voor het ontvangen van een ID-tokenreactie.
     • De volledige lijst met door de app aangevraagde machtigingen is te vinden in het bestand authentication.properties. U kunt meer machtigingen toevoegen, zoals .

2. De gebruiker krijgt een aanmeldingsprompt van Microsoft Entra ID. Als de aanmeldingspoging is geslaagd, wordt de browser van de gebruiker omgeleid naar het omleidingseindpunt van de app. Een geldig verzoek aan dit eindpunt bevat een autorisatiecode.

3. Het -exemplaar wisselt deze autorisatiecode vervolgens uit voor een ID-token en toegangstoken van 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();
   

   In de volgende lijst worden de functies van deze code beschreven:

   • : Parameters die moeten worden ingesteld om de autorisatiecode voor een ID-token en/of toegangstoken uit te wisselen.
   • : De autorisatiecode die is ontvangen bij het omleidingseindpunt.
   • : De redirect-URI die in de vorige stap is gebruikt, moet opnieuw worden meegegeven.
   • : De scopes die in de vorige stap zijn gebruikt, moeten opnieuw worden doorgegeven.

4. Als slaagt, worden de tokenclaims geëxtraheerd. Als de nonce-controle slaagt, worden de resultaten in geplaatst — een exemplaar van — en in de sessie opgeslagen. De toepassing kan vervolgens de uit de sessie instantiëren via een exemplaar van wanneer zij er toegang toe nodig heeft, zoals in de volgende code wordt weergegeven:

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

De routes beveiligen

Zie AuthenticationFilter.java voor informatie over hoe de voorbeeld-app de toegang tot routes filtert. In het bestand authentication.properties bevat de -eigenschap de door komma's gescheiden routes waartoe alleen geverifieerde gebruikers toegang hebben, zoals in het volgende voorbeeld wordt weergegeven:

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

Alle routes die worden vermeld in de door komma's gescheiden regelsets onder zijn ook niet toegankelijk voor niet-geverifieerde gebruikers, zoals in het volgende voorbeeld wordt weergegeven. Deze routes bevatten echter ook een door spaties gescheiden lijst met app-rollidmaatschappen: alleen gebruikers met ten minste één van de bijbehorende rollen hebben toegang tot deze routes na verificatie.

# local short names for app roles - for example, sets admin to mean PrivilegedAdmin (useful for long rule sets defined in the next key, app.protect.roles)
app.roles=admin PrivilegedAdmin, user RegularUser

# A route and its corresponding <space-separated> role(s) that can access it; the start of the next route & its role(s) is delimited by a <comma-and-space-separator>
# this says: /admins_only can be accessed by PrivilegedAdmin, /regular_user can be accessed by PrivilegedAdmin role and the RegularUser role
app.protect.roles=/admin_only admin, /regular_user admin user

Scopes

Scopes geven Microsoft Entra ID aan welk toegangsniveau de applicatie aanvraagt.

Op basis van de aangevraagde machtigingen toont Microsoft Entra ID de gebruiker een toestemmingsvenster wanneer deze zich aanmeldt. Als de gebruiker instemt met een of meer scopes en een token verkrijgt, worden de scopes waarvoor toestemming is gegeven gecodeerd in de resulterende .

Zie authentication.properties voor de machtigingen die door de toepassing zijn aangevraagd. Deze drie machtigingen worden standaard aangevraagd door MSAL en verleend door Microsoft Entra ID.

Meer informatie

• Microsoft Authentication Library (MSAL) voor Java
• Microsoft-identiteitsplatform
• Snelstart: een toepassing registreren bij het Microsoft identity platform
• Inzicht in toestemmingservaringen voor toepassingen in Microsoft Entra ID
• Begrijp de toestemming van gebruikers en beheerders
• MSAL-codevoorbeelden
• Procedure: Toepassingsrollen toevoegen aan uw toepassing en ze in het token ontvangen
• Gebruikerstoewijzing voor een app beheren in Microsoft Entra ID