Delen via

Java Tomcat-apps beveiligen met behulp van groepen en groepsclaims

  • Artikel

In dit artikel leest u hoe u een Java Tomcat-app maakt waarmee gebruikers worden aangemeld met Microsoft Authentication Library (MSAL) voor Java. De app beperkt ook de toegang tot pagina's op basis van het lidmaatschap van de beveiligingsgroep Microsoft Entra ID.

In het volgende diagram ziet u de topologie van de app:

Diagram met de topologie van de app.

De client-app gebruikt MSAL voor Java (MSAL4J) om gebruikers aan te melden bij een Microsoft Entra ID-tenant en een id-token te verkrijgen van Microsoft Entra ID. Het id-token bewijst dat een gebruiker is geverifieerd met deze tenant. De app beveiligt de routes op basis van de verificatiestatus en het groepslidmaatschap van de gebruiker.

Zie Autorisatie implementeren in uw toepassingen met behulp van app-rollen, beveiligingsgroepen, bereiken en directoryrollen voor een video waarin dit scenario wordt behandeld.

Vereisten

Aanbevelingen

  • Enige bekendheid met de Java / Jakarta Servlets.
  • Enige bekendheid met Linux/OSX-terminal.
  • jwt.ms voor het controleren van uw tokens.
  • Fiddler voor het bewaken van uw netwerkactiviteit en het oplossen van problemen.
  • Volg de Microsoft Entra ID-blog om op de hoogte te blijven van 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/groups

U kunt ook naar de opslagplaats ms-identity-msal-java-samples navigeren, het downloaden als een .zip-bestand en het extraheren naar uw harde schijf.

Belangrijk

Om beperkingen voor bestandspadlengten in Windows te voorkomen, kloont of extraheert u de opslagplaats in een map in de buurt van de hoofdmap van uw harde schijf.

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 het Azure-portaal.

  2. Als uw account aanwezig is in meer dan één Microsoft Entra ID-tenant, selecteert u uw profiel in de hoek van Azure Portal en selecteert u vervolgens Schakelen tussen mappen om uw sessie te wijzigen in de gewenste Microsoft Entra ID-tenant.

De app registreren (java-servlet-webapp-groups)

Registreer eerst een nieuwe app in Azure Portal door de instructies in quickstart te volgen: Een toepassing registreren bij het Microsoft Identity Platform.

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 beschrijvende toepassingsnaam in om weer te geven aan gebruikers van de app, java-servlet-webapp-groupsbijvoorbeeld.
    • Onder Ondersteunde accounttypen selecteert u Enkel accounts in deze organisatieadreslijst.
    • Selecteer in de sectie Omleidings-URI het web in de keuzelijst met invoervak en voer de volgende omleidings-URI in: http://localhost:8080/msal4j-servlet-groups/auth/redirect.

  4. Selecteer Registreren om de toepassing te maken.

  5. Zoek en kopieer op de registratiepagina van de app de waarde van de toepassings-id (client) 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 van de beschikbare duur: in 1 jaar, in 2 jaar of nooit verloopt.

  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.

  13. Selecteer op de registratiepagina van de app API-machtigingen in het navigatiedeelvenster om de pagina te openen om toegang te krijgen tot de API's die uw toepassing nodig heeft.

  14. Selecteer Een machtiging toevoegen.

  15. Zorg ervoor dat het tabblad Microsoft-API's is geselecteerd.

  16. Selecteer in de sectie Veelgebruikte Microsoft-API's de optie Microsoft Graph.

  17. Selecteer in de sectie Gedelegeerde machtigingen User.Read en GroupMember.Read.All in de lijst. Gebruik het zoekvak indien nodig.

  18. Selecteer Machtigingen toevoegen.

  19. GroupMember.Read.All vereist beheerderstoestemming, dus selecteer Beheerderstoestemming verlenen/intrekken voor {tenant}, en selecteer vervolgens Ja wanneer u wordt gevraagd of u toestemming wilt verlenen voor de aangevraagde machtigingen voor alle accounts in de tenant. U moet een tenantbeheerder van Microsoft Entra ID zijn om deze actie uit te voeren.

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

Gebruik de volgende stappen om de app te configureren:

Notitie

In de volgende stappen ClientID is dit hetzelfde als Application ID of AppId.

  1. Open het project in uw IDE.

  2. Open het bestand ./src/main/resources/authentication.properties .

  3. Zoek de tekenreeks {enter-your-tenant-id-here}. Vervang de bestaande waarde door uw Microsoft Entra-tenant-id als u uw app hebt geregistreerd met de accounts in deze organisatiemap.

  4. Zoek de tekenreeks {enter-your-client-id-here} en vervang de bestaande waarde door de toepassings-id of clientId de java-servlet-webapp-groups toepassing die is gekopieerd uit Azure Portal.

  5. Zoek de tekenreeks {enter-your-client-secret-here} en vervang de bestaande waarde door de waarde die u hebt opgeslagen tijdens het maken van de java-servlet-webapp-groups app in Azure Portal.

Beveiligingsgroepen configureren

U hebt de volgende opties beschikbaar voor het verder configureren van uw toepassingen voor het ontvangen van de groepsclaim:

Notitie

Als u de on-premises groep samAccountName of On Premises Group Security Identifier in plaats van de groeps-id wilt ophalen, raadpleegt u de sectie Vereisten voor het gebruik van groepskenmerken die zijn gesynchroniseerd vanuit Active Directory in Groepsclaims configureren voor toepassingen met behulp van Microsoft Entra-id.

Configureer uw toepassing om alle groepen te ontvangen waaraan de aangemelde gebruiker is toegewezen, inclusief geneste groepen

Voer de volgende stappen uit om uw toepassing te configureren:

  1. Selecteer op de registratiepagina van de app tokenconfiguratie in het navigatiedeelvenster om de pagina te openen waar u de claims kunt configureren die aan uw toepassing zijn uitgegeven.

  2. Selecteer Groepenclaim toevoegen om het scherm Groepen claim bewerken te openen.

  3. Selecteer Beveiligingsgroepen OF de optie Alle groepen (inclusief distributielijsten, maar niet groepen die zijn toegewezen aan de toepassing). Als u beide opties kiest, wordt het effect van de optie Beveiligingsgroepen genegeerd.

  4. Selecteer in de sectie Id de optie Groeps-id. Deze selectie zorgt ervoor dat Microsoft Entra-id de object-id verzendt van de groepen waaraan de gebruiker is toegewezen in de groepsclaim van het id-token dat uw app ontvangt na het aanmelden van een gebruiker.

Configureer uw toepassing voor het ontvangen van de claimwaarden van groepen uit een gefilterde set groepen waaraan een gebruiker mogelijk is toegewezen

Deze optie is handig als de volgende gevallen waar zijn:

  • Uw toepassing is geïnteresseerd in een geselecteerde set groepen waaraan een aanmeldingsgebruiker kan worden toegewezen.
  • Uw toepassing is niet geïnteresseerd in elke beveiligingsgroep waaraan deze gebruiker is toegewezen in de tenant.

Deze optie helpt uw toepassing het overschrijdingsprobleem te voorkomen.

Notitie

Deze functie is niet beschikbaar in de gratis versie van Microsoft Entra ID.

Geneste groepstoewijzingen zijn niet beschikbaar wanneer u deze optie gebruikt.

Gebruik de volgende stappen om deze optie in te schakelen in uw app:

  1. Selecteer op de registratiepagina van de app tokenconfiguratie in het navigatiedeelvenster om de pagina te openen waar u de claims kunt configureren die aan uw toepassing zijn uitgegeven.

  2. Selecteer Groepenclaim toevoegen om het scherm Groepen claim bewerken te openen.

  3. Selecteer Groepen die zijn toegewezen aan de toepassing.

    Als u andere opties kiest, zoals beveiligingsgroepen of alle groepen (inclusief distributielijsten, maar geen groepen die zijn toegewezen aan de toepassing), worden de voordelen die uw app heeft afgeleid van het kiezen van deze optie wegneemt.

  4. Selecteer in de sectie Id de optie Groeps-id. Deze selectie resulteert in Microsoft Entra-id die de object-id verzendt van de groepen waaraan de gebruiker is toegewezen in de groepsclaim van het id-token.

  5. Als u een web-API beschikbaar maakt met behulp van de optie Een API beschikbaar maken, kunt u ook de optie Groeps-id kiezen onder de sectie Access . Deze optie resulteert in Microsoft Entra ID die de object-id verzendt van de groepen waaraan de gebruiker is toegewezen in de groepsclaim van het toegangstoken.

  6. Selecteer Op de registratiepagina van de app Overzicht in het navigatiedeelvenster om het overzichtsscherm van de toepassing te openen.

  7. Selecteer de hyperlink met de naam van uw toepassing in beheerde toepassing in de lokale map. Deze veldtitel kan bijvoorbeeld worden afgekapt Managed application in .... Wanneer u deze koppeling selecteert, gaat u naar de pagina Overzicht van bedrijfstoepassingen die is gekoppeld aan de service-principal voor uw toepassing in de tenant waar u deze hebt gemaakt. U kunt teruggaan naar de pagina voor app-registratie met behulp van de knop Vorige van uw browser.

  8. Selecteer Gebruikers en groepen in het navigatiedeelvenster om de pagina te openen waar u gebruikers en groepen aan uw toepassing kunt toewijzen.

  9. Selecteer Gebruiker toevoegen.

  10. Selecteer Gebruiker en Groepen in het resulterende scherm.

  11. Kies de groepen die u aan deze toepassing wilt toewijzen.

  12. Selecteer Selecteren om de groepen te selecteren.

  13. Selecteer Toewijzen om het groepstoewijzingsproces te voltooien.

    Uw toepassing ontvangt nu deze geselecteerde groepen in de groepenclaim wanneer een gebruiker die zich aanmeldt bij uw app lid is van een of meer van deze toegewezen groepen.

  14. Selecteer Eigenschappen in het navigatiedeelvenster om de pagina te openen met de basiseigenschappen van uw toepassing. Stel de vereiste gebruikerstoewijzing in op Ja.

Belangrijk

Wanneer u gebruikerstoewijzing hebt ingesteld ? op Ja, controleert Microsoft Entra ID of alleen gebruikers die zijn toegewezen aan uw toepassing in het deelvenster Gebruikers en groepen zich kunnen aanmelden bij uw app. U kunt gebruikers rechtstreeks toewijzen of door beveiligingsgroepen toe te wijzen waartoe ze behoren.

De app (java-servlet-webapp-groups) configureren om groeps-id's te herkennen

Gebruik de volgende stappen om de app te configureren:

Belangrijk

Als u op de pagina Tokenconfiguratie een andere optie dan groupID hebt gekozen, zoals DNSDomain\sAMAccountName , moet u de groepsnaam invoeren in de volgende stappen, contoso.com\Test Group bijvoorbeeld - in plaats van de object-id:

  1. Open het bestand ./src/main/resources/authentication.properties .

  2. Zoek de tekenreeks {enter-your-admins-group-id-here} en vervang de bestaande waarde door de object-id van de GroupAdmin groep die u hebt gekopieerd uit Azure Portal. Verwijder ook de accolades uit de tijdelijke aanduidingswaarde.

  3. Zoek de tekenreeks {enter-your-users-group-id-here} en vervang de bestaande waarde door de object-id van de GroupMember groep die u hebt gekopieerd uit Azure Portal. Verwijder ook de accolades uit de tijdelijke aanduidingswaarde.

Bouw het sample

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

In de volgende secties ziet u hoe u het voorbeeld implementeert in Azure-app Service.

Vereisten

De Maven-invoegtoepassing configureren

Wanneer u implementeert in Azure-app Service, gebruikt de implementatie automatisch uw Azure-referenties van de Azure CLI. Als de Azure CLI niet lokaal is geïnstalleerd, verifieert de Maven-invoegtoepassing zich met OAuth of apparaataanmelding. Zie verificatie met Maven-invoegtoepassingen voor meer informatie.

Gebruik de volgende stappen om de invoegtoepassing te configureren:

  1. Voer de volgende opdracht uit om de implementatie te configureren. Met deze opdracht kunt u het besturingssysteem Azure-app Service, de Java-versie en de Tomcat-versie instellen.

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

  2. Als u een nieuwe uitvoeringsconfiguratie wilt maken, drukt u op Y en vervolgens op Enter.

  3. Voor De waarde Definiëren voor het besturingssysteem drukt u op 1 voor Windows of 2 voor Linux en drukt u vervolgens op Enter.

  4. Druk voor De waarde definiëren voor javaVersion op 2 voor Java 11 en druk vervolgens op Enter.

  5. Druk voor De waarde definiëren voor webContainer op 4 voor Tomcat 9.0 en druk vervolgens op Enter.

  6. Voor Waarde definiëren voor pricingTier drukt u op Enter om de standaard P1v2-laag te selecteren.

  7. Voor Bevestigen drukt u op Y en drukt u vervolgens op Enter.

In het volgende voorbeeld ziet u de uitvoer van het implementatieproces:

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

Nadat u uw keuzes hebt bevestigd, voegt de invoegtoepassing het vereiste invoegtoepassingselement en de vereiste instellingen toe aan het pom.xml-bestand van uw project om uw app te configureren voor uitvoering in Azure-app Service.

Het relevante gedeelte van het pom.xml-bestand moet er ongeveer uitzien als in het volgende voorbeeld:

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

U kunt de configuraties voor App Service rechtstreeks in uw pom.xml wijzigen. Enkele algemene configuraties worden vermeld in de volgende tabel:

Eigenschappen Vereist Beschrijving
subscriptionId false De abonnements-id.
resourceGroup true De Azure-resourcegroep voor uw app.
appName true De naam van uw app.
region false De regio waarin u uw app wilt hosten. De standaardwaarde is centralus. Zie Ondersteunde regio's voor geldige regio's.
pricingTier false De prijscategorie voor uw app. De standaardwaarde is P1v2 voor een productieworkload. De aanbevolen minimumwaarde voor Java-ontwikkeling en -tests is B2. Zie App Service-prijzen voor meer informatie.
runtime false De configuratie van de runtime-omgeving. Zie Configuratiedetails voor meer informatie.
deployment false De implementatieconfiguratie. Zie Configuratiedetails voor meer informatie.

Zie de referentiedocumentatie van de invoegtoepassing voor de volledige lijst met configuraties. Alle Azure Maven-invoegtoepassingen delen een algemene set configuraties. Zie Common Configurations voor deze configuraties. Zie de Azure-app: Configuratiedetails voor configuraties die specifiek zijn voor Azure-app Service.

Zorg ervoor dat u de appName waarden en resourceGroup waarden opslaat voor later gebruik.

De app voorbereiden voor implementatie

Wanneer u uw toepassing implementeert in App Service, verandert uw omleidings-URL in de omleidings-URL van uw geïmplementeerde app-exemplaar. Gebruik de volgende stappen om deze instellingen in het eigenschappenbestand te wijzigen:

  1. Navigeer naar het bestand authentication.properties van uw app en wijzig de waarde van de domeinnaam van app.homePage uw geïmplementeerde app, zoals wordt weergegeven in het volgende voorbeeld. Als u bijvoorbeeld in de vorige stap voor uw app-naam hebt gekozen example-domain , moet u deze nu gebruiken https://example-domain.azurewebsites.net voor de app.homePage waarde. Zorg ervoor dat u ook het protocol hebt gewijzigd van http in 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. Nadat u dit bestand hebt opgeslagen, gebruikt u de volgende opdracht om uw app opnieuw te bouwen:

    mvn clean package

Belangrijk

In hetzelfde bestand authentication.properties hebt u een instelling voor uw aad.secret. Het is geen goede gewoonte om deze waarde in App Service te implementeren. Het is ook geen goed idee om deze waarde in uw code te laten staan en deze mogelijk naar uw Git-opslagplaats te pushen. Voor het verwijderen van deze geheime waarde uit uw code vindt u gedetailleerdere richtlijnen in de sectie Implementeren in App Service - Geheim verwijderen. Met deze richtlijnen worden extra stappen toegevoegd voor het pushen van de geheime waarde naar Key Vault en het gebruik van Key Vault-verwijzingen.

De registratie van uw Microsoft Entra ID-app bijwerken

Omdat de omleidings-URI wordt gewijzigd in uw geïmplementeerde app in Azure-app Service, moet u ook de omleidings-URI wijzigen in de registratie van uw Microsoft Entra ID-app. Gebruik de volgende stappen om deze wijziging aan te brengen:

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

  2. Gebruik het zoekvak om te zoeken naar uw app-registratie, java-servlet-webapp-authenticationbijvoorbeeld.

  3. Open uw app-registratie door de naam te selecteren.

  4. Selecteer in het menu de optie Verificatie.

  5. Selecteer URI toevoegen in de sectie Webomleidings-URI's - .

  6. Vul de URI van uw app in, bijvoorbeeld /auth/redirect https://<your-app-name>.azurewebsites.net/auth/redirect.

  7. Selecteer Opslaan.

De app implementeren

U bent nu klaar om uw app te implementeren in Azure-app Service. Gebruik de volgende opdracht om ervoor te zorgen dat u bent aangemeld bij uw Azure-omgeving om de implementatie uit te voeren:

az login

Nu alle configuraties klaar zijn in uw pom.xml-bestand , kunt u nu de volgende opdracht gebruiken om uw Java-app in Azure te implementeren:

mvn package azure-webapp:deploy

Nadat de implementatie is voltooid, is uw toepassing gereed op http://<your-app-name>.azurewebsites.net/. Open de URL met uw lokale webbrowser, waar u de startpagina van de msal4j-servlet-auth toepassing zou moeten zien.

Het voorbeeld verkennen

Gebruik de volgende stappen om het voorbeeld te verkennen:

  1. U ziet dat de status van de aangemelde of afgemelde status wordt weergegeven in het midden van het scherm.
  2. Selecteer de contextgevoelige knop in de hoek. Met deze knop wordt Aanmelden gelezen wanneer u de app voor het eerst uitvoert.
  3. Volg op de volgende pagina de instructies en meld u aan met een account in de Microsoft Entra ID-tenant.
  4. In het toestemmingsscherm ziet u de bereiken die worden aangevraagd.
  5. U ziet dat de contextgevoelige knop nu afmeldt 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 Groepen om informatie over lidmaatschap van beveiligingsgroepen voor de aangemelde gebruiker weer te geven.
  8. Selecteer Alleen beheerder of gewone gebruiker om toegang te krijgen tot de met groepen beveiligde eindpunten.
    • Als uw aangemelde gebruiker zich in de GroupAdmin groep bevindt, kan de gebruiker beide pagina's invoeren.
    • Als uw aangemelde gebruiker zich in de GroupMember groep bevindt, kan de gebruiker alleen de pagina Gewone gebruiker invoeren.
    • Als uw aangemelde gebruiker zich in geen van beide groepen bevindt, heeft de gebruiker geen toegang tot een van de twee pagina's.
  9. Gebruik de knop in de hoek om u af te melden.
  10. Nadat u zich hebt afgemelding, selecteert u Id-tokendetails om te zien dat de app een 401: unauthorized fout weergeeft in plaats van de id-tokenclaims wanneer de gebruiker niet is geautoriseerd.

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 groepsclaim kan bevatten. Als er te veel groepen zijn voor emissie in het id-token, gebruikt het voorbeeld Microsoft Graph SDK voor Java om de groepslidmaatschapsgegevens van Microsoft Graph te verkrijgen. Op basis van de groepen waartoe de gebruiker behoort, heeft de aangemelde gebruiker toegang tot geen, één of beide beveiligde pagina's Admins Only en Regular Users.

Als u het gedrag van dit voorbeeld wilt repliceren, moet u MSAL4J en Microsoft Graph SDK toevoegen aan uw projecten met behulp van Maven. U kunt 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 gebouwd om het doel van dit voorbeeld te verhelpen.

Inhoud

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

Bestand/map Beschrijving
src/main/java/com/microsoft/azuresamples/msal4j/groupswebapp/ Deze map bevat de klassen die de bedrijfslogica van de back-end van de app definiëren.
src/main/java/com/microsoft/azuresamples/msal4j/authservlets/ Deze map bevat de klassen die worden gebruikt voor aanmeldings- en afmeldingseindpunten.
____Servlet.java Alle beschikbare eindpunten worden gedefinieerd in .java klassen die eindigen op ____Servlet.java.
src/main/java/com/microsoft/azuresamples/msal4j/helpers/ Helperklassen voor verificatie.
AuthenticationFilter.java Leidt niet-geverifieerde aanvragen om naar beveiligde eindpunten naar een 401-pagina.
src/main/resources/authentication.properties Configuratie van Microsoft Entra-id en -programma.
src/main/webapp/ Deze map bevat de gebruikersinterface - JSP-sjablonen
CHANGELOG.md Lijst met wijzigingen in het voorbeeld.
CONTRIBUTING.md Richtlijnen voor bijdragen aan het voorbeeld.
LICENTIE De licentie voor het voorbeeld.

Een groepsclaim verwerken in tokens, inclusief het verwerken van overschrijding

In de volgende secties wordt beschreven hoe de app een groepsclaim verwerkt.

De groepsclaim

De object-id van de beveiligingsgroepen waarvan de aangemelde gebruiker lid is, wordt geretourneerd in de groepsclaim van het token, zoals wordt weergegeven in het volgende voorbeeld:

{
  ...
  "groups": [
    "0bbe91cc-b69e-414d-85a6-a043d6752215",
    "48931dac-3736-45e7-83e8-015e6dfd6f7c",]
  ...
}

De overschrijdingsclaim voor groepen

Om ervoor te zorgen dat de grootte van het token niet groter is dan de limieten voor HTTP-headers, beperkt het Microsoft Identity Platform het aantal object-id's dat het bevat in de groepsclaim.

De overschrijdingslimiet is 150 voor SAML-tokens, 200 voor JWT-tokens en 6 voor toepassingen met één pagina. Als een gebruiker lid is van meer groepen dan de overschrijdingslimiet, verzendt het Microsoft Identity Platform de groeps-id's niet in de groepsclaim in het token. In plaats daarvan bevat het een overschrijdingsclaim in het token dat aangeeft aan de toepassing om een query uit te voeren op de Microsoft Graph API om het groepslidmaatschap van de gebruiker op te halen, zoals wordt weergegeven in het volgende voorbeeld:

{
  ...
  "_claim_names": {
    "groups": "src1"
    },
    {
   "_claim_sources": {
    "src1": {
        "endpoint":"[Graph Url to get this user's group membership from]"
        }
    }
  ...
}

Het overschrijdingsscenario in dit voorbeeld maken voor testen

Als u het overschrijdingsscenario wilt maken, kunt u de volgende stappen uitvoeren:

  1. U kunt het bestand BulkCreateGroups.ps1 in de map AppCreationScripts gebruiken om een groot aantal groepen te maken en gebruikers aan hen toe te wijzen. Dit bestand helpt bij het testen van overschrijdingsscenario's tijdens de ontwikkeling. Vergeet niet om de gebruiker te wijzigen die objectId is opgegeven in het script BulkCreateGroups.ps1 .

  2. Wanneer u dit voorbeeld uitvoert en er een overschrijding plaatsvindt, ziet u de _claim_names startpagina nadat de gebruiker zich heeft aangemeld.

  3. We raden u ten zeere aan de groepsfilterfunctie, indien mogelijk, te gebruiken om te voorkomen dat er groepsoverschrijdingen worden uitgevoerd. Zie de sectie Uw toepassing configureren voor het ontvangen van de claimwaarden van groepen uit een gefilterde set groepen waaraan een gebruiker mogelijk is toegewezen voor meer informatie.

  4. Als u niet kunt voorkomen dat er groepsoverschrijding optreedt, raden we u aan de volgende stappen te gebruiken om de groepsclaim in uw token te verwerken:

    1. Controleer op de claim _claim_names met een van de waarden die worden gegroepeerd. Deze claim geeft overschrijding aan.
    2. Indien gevonden, roept u het eindpunt aan dat is _claim_sources opgegeven om gebruikersgroepen op te halen.
    3. Als er geen gevonden is, kijkt u naar de groepsclaim voor gebruikersgroepen.

Notitie

Voor het afhandelen van overschrijding is een aanroep naar Microsoft Graph vereist om de groepslidmaatschappen van de aangemelde gebruiker te lezen, zodat uw app de machtiging GroupMember.Read.All moet hebben om de functie getMemberObjects te kunnen uitvoeren.

Zie de video Een inleiding tot Microsoft Graph voor ontwikkelaars voor meer informatie over programmeren voor Microsoft Graph.

ConfidentialClientApplication

Er ConfidentialClientApplication wordt een exemplaar gemaakt in het AuthHelper.java-bestand , zoals wordt weergegeven in het volgende voorbeeld. 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-instantie, 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 procedure

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

  1. De eerste stap van het aanmeldingsproces is het verzenden van een aanvraag naar het /authorize eindpunt voor uw Microsoft Entra ID-tenant. Het MSAL4J-exemplaar ConfidentialClientApplication wordt gebruikt om een AUTORISATIEaanvraag-URL samen te stellen. 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:

    • AuthorizationRequestUrlParameters: Parameters die moeten worden ingesteld om een AuthorizationRequestUrl te bouwen.
    • REDIRECT_URI: Waar Microsoft Entra de browser omleidt, samen met de verificatiecode, na het verzamelen van gebruikersreferenties. Deze moet overeenkomen met de omleidings-URI in de registratie van de Microsoft Entra ID-app in Azure Portal.
    • SCOPES: Bereiken zijn machtigingen die door de toepassing worden aangevraagd.
      • Normaal gesproken volstaan openid profile offline_access de drie bereiken voor het ontvangen van een id-tokenantwoord.
      • De volledige lijst met bereiken die door de app zijn aangevraagd, vindt u in het bestand authentication.properties . U kunt meer bereiken toevoegen, zoals User.Read.

  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 geldige aanvraag voor dit eindpunt bevat een autorisatiecode.

  3. Het ConfidentialClientApplication 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:

    • AuthorizationCodeParameters: Parameters die moeten worden ingesteld om de autorisatiecode voor een id en/of toegangstoken uit te wisselen.
    • authCode: De autorisatiecode die is ontvangen op het omleidingseindpunt.
    • REDIRECT_URI: De omleidings-URI die in de vorige stap is gebruikt, moet opnieuw worden doorgegeven.
    • SCOPES: De bereiken die in de vorige stap worden gebruikt, moeten opnieuw worden doorgegeven.

  4. Als acquireToken dit lukt, worden de tokenclaims geëxtraheerd. Als de nonce-controle is geslaagd, worden de resultaten geplaatst in context - een exemplaar van IdentityContextData - en opgeslagen in de sessie. De toepassing kan de sessie vervolgens instantiëren IdentityContextData via een exemplaar van IdentityContextAdapterServlet wanneer deze toegang nodig heeft, zoals wordt weergegeven in de volgende code:

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

// handle groups overage if it has occurred.
handleGroupsOverage(contextAdapter);

  5. Na de vorige stap kunt u groepslidmaatschappen extraheren met context.getGroups() behulp van een exemplaar van IdentityContextData.

  6. Als de gebruiker lid is van te veel groepen - meer dan 200 - kan een aanroep context.getGroups() leeg zijn als dat niet het gevolg is van het gesprek.handleGroupsOverage() Retourneert ondertussen context.getGroupsOverage() truehet signaal dat er een overschrijding is opgetreden en dat het ophalen van de volledige lijst met groepen een aanroep naar Microsoft Graph vereist. Zie de handleGroupsOverage() methode in AuthHelper.java om te zien hoe deze toepassing wordt gebruikt context.setGroups() wanneer er sprake is van een overschrijding.

De routes beveiligen

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

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

Alle routes die worden vermeld in de door komma's gescheiden regelsets onder de app.protect.groups regels, zijn ook niet-geverifieerde geverifieerde gebruikers, zoals wordt weergegeven in het volgende voorbeeld. Deze routes bevatten echter ook een door spaties gescheiden lijst met groepslidmaatschappen. Alleen gebruikers die tot ten minste één van de bijbehorende groepen behoren, hebben na verificatie toegang tot deze routes.

# define short names for group IDs here for the app. This is useful in the next property (app.protect.groups).
# EXCLUDE the curly braces, they are in this file only as delimiters.
# example:
# app.groups=groupA abcdef-qrstuvw-xyz groupB abcdef-qrstuv-wxyz
app.groups=admin {enter-your-admins-group-id-here}, user {enter-your-users-group-id-here}

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

Bereiken

Bereiken vertellen Microsoft Entra ID het toegangsniveau dat de toepassing aanvraagt.

Op basis van de aangevraagde bereiken geeft Microsoft Entra ID een toestemmingsdialoog aan de gebruiker bij het aanmelden. Als de gebruiker toestemming verleent voor een of meer bereiken en een token verkrijgt, worden de bereiken waarvoor toestemming is gegeven, gecodeerd in het resulterende access_tokenbereik.

Zie authentication.properties voor de bereiken die door de toepassing zijn aangevraagd. Standaard stelt de toepassing de waarde voor bereiken in op GroupMember.Read.All. Dit specifieke Microsoft Graph API-bereik is vereist voor het geval de toepassing Graph moet aanroepen om de groepslidmaatschappen van de gebruiker op te halen.

Meer informatie