Java Spring Boot-apps inschakelen om gebruikers aan te melden en toegang te krijgen tot Microsoft Graph

In dit artikel wordt een Java Spring Boot-web-app gedemonstreerd waarmee gebruikers zich aanmelden en een toegangstoken wordt verkregen voor het aanroepen van Microsoft Graph. Het maakt gebruik van de Microsoft Entra ID Spring Boot Starter client library for Java voor authenticatie, autorisatie en tokenverwerving. Het gebruikt Microsoft Graph SDK for Java om gegevens uit Graph op te halen.

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

Diagram dat de topologie van de app toont.

De app gebruikt de Microsoft Entra ID Spring Boot Starter-clientbibliotheek voor Java om een toegangstoken voor Microsoft Graph te verkrijgen van Microsoft Entra ID. Het toegangstoken bewijst dat de gebruiker gemachtigd is om toegang te krijgen tot het Microsoft Graph API-eindpunt, zoals gedefinieerd in het bereik.

Vereisten

• JDK versie 15. Dit voorbeeld is ontwikkeld op een systeem met Java 15, maar is mogelijk compatibel met andere versies.
• Maven 3
• Java Extension Pack for Visual Studio Code wordt aanbevolen om dit voorbeeld uit te voeren in Visual Studio Code.
• Een Microsoft Entra ID-tenant. Zie Een Microsoft Entra ID-tenant verkrijgen voor meer informatie.
• Een gebruikersaccount in uw Microsoft Entra ID-tenant. Dit voorbeeld werkt niet met een persoonlijk Microsoft-account. Als u zich met een persoonlijk account hebt aangemeld bij Azure Portal en u geen gebruikersaccount in uw directory hebt, moet u er nu een maken.
• Visual Studio Code
• Azure Tools voor Visual Studio Code

Aanbevelingen

• Enige vertrouwdheid met het Spring Framework.
• 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 4-spring-web-app/2-Authorization-I/call-graph

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 voorbeeldtoepassingen 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-spring-webapp-call-graph)

Voer de volgende stappen uit om de app te registreren:

1. Ga naar het Azure-portal en selecteer Microsoft Entra ID.

2. Selecteer App-registraties in het navigatiedeelvenster en selecteer vervolgens Nieuwe registratie.

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

   • Voer in de sectie Naam een duidelijke toepassingsnaam in die aan gebruikers van de app wordt weergegeven, bijvoorbeeld .
   • Onder Ondersteunde accounttypen selecteert u Enkel accounts in deze organisatieadreslijst.
   • Selecteer in de sectie Redirect-URI (optioneel) Web in de keuzelijst en voer de volgende redirect-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 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.

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

8. Typ een beschrijving, bijvoorbeeld app-geheim.

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

10. Selecteer Toevoegen. De gegenereerde waarde wordt weergegeven.

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

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

13. Selecteer Machtigingen toevoegen en zorg ervoor dat het tabblad Microsoft-API's is geselecteerd.

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

15. Selecteer in de sectie Gedelegeerde machtigingen User.Read in de lijst. Gebruik het zoekvak indien nodig.

16. Selecteer Machtigingen toevoegen.

De app (java-spring-webapp-call-graph) 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 src\main\resources\application.yml .

3. Zoek de plaatsaanduiding en vervang de bestaande waarde door uw Microsoft Entra-tenant-id.

4. Zoek de placeholder en vervang de bestaande waarde door de toepassings-id of van de -app, gekopieerd uit de Azure-portal.

5. Zoek de placeholder en vervang de bestaande waarde door de waarde die u hebt opgeslagen tijdens het maken van en die u vanuit de Azure-portal hebt gekopieerd.

De voorbeeldtoepassing uitvoeren

az login

az upgrade

az extension add --name containerapp --upgrade

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

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

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

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

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

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

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

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. U kunt ook de tokendetails of de aanroepgrafiek selecteren. Omdat deze pagina is beveiligd en verificatie vereist, wordt u automatisch omgeleid naar de aanmeldingspagina.
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. Wanneer de aanmeldingsstroom is voltooid, wordt u omgeleid naar de startpagina, waarin de aanmeldingsstatus wordt weergegeven, of een van de andere pagina's, afhankelijk van de knop die uw aanmeldingsstroom heeft geactiveerd.
6. Merk op dat de contextgevoelige knop nu Afmelden zegt en uw gebruikersnaam weergeeft.
7. Als u zich op de startpagina bevindt, selecteert u Details van id-token om enkele van de gedecodeerde claims van het ID-token weer te geven.
8. Selecteer Call Graph om een aanroep te doen naar het /me-eindpunt van Microsoft Graph en een selectie van de opgehaalde gebruikersgegevens te bekijken.
9. Gebruik de knop in de hoek om u af te melden. De statuspagina geeft de nieuwe status weer.

Over de code

In dit voorbeeld ziet u hoe u de Microsoft Entra ID Spring Boot Starter-clientbibliotheek voor Java gebruikt om gebruikers aan te melden bij uw Microsoft Entra ID-tenant en een toegangstoken te verkrijgen voor het aanroepen van Microsoft Graph. Het voorbeeld maakt ook gebruik van de Spring Oauth2-client en Spring Web Boot Starters.

Inhoud

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

Id-tokenclaims

Om tokendetails te extraheren, maakt de app gebruik van de Spring Security-objecten en in een requestmapping, zoals in het volgende voorbeeld. Zie de Sample Controller voor volledige informatie over hoe deze app gebruikmaakt van ID-tokenclaims.

import org.springframework.security.oauth2.core.oidc.user.OidcUser;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
//...
@GetMapping(path = "/some_path")
public String tokenDetails(@AuthenticationPrincipal OidcUser principal) {
    Map<String, Object> claims = principal.getIdToken().getClaims();
}

Aanmeld- en afmeldkoppelingen

Voor aanmelding doet de app een aanvraag naar het microsoft Entra ID-aanmeldingseindpunt dat automatisch is geconfigureerd door de Microsoft Entra ID Spring Boot Starter-clientbibliotheek voor Java, zoals wordt weergegeven in het volgende voorbeeld:

<a class="btn btn-success" href="/oauth2/authorization/azure">Sign In</a>

Voor het afmelden verstuurt de app een POST-aanvraag naar het -eindpunt, zoals in het volgende voorbeeld wordt weergegeven:

<form action="#" th:action="@{/logout}" method="post">
  <input class="btn btn-warning" type="submit" value="Sign Out" />
</form>

Verificatieafhankelijke UI-elementen

De app heeft een aantal eenvoudige logica op de pagina's van de gebruikersinterfacesjabloon voor het bepalen van de inhoud die moet worden weergegeven op basis van of de gebruiker is geverifieerd, zoals wordt weergegeven in het volgende voorbeeld met spring Security Thymeleaf-tags:

<div sec:authorize="isAuthenticated()">
  this content only shows to authenticated users
</div>
<div sec:authorize="isAnonymous()">
  this content only shows to not-authenticated users
</div>

Routes beveiligen met AADWebSecurityConfigurerAdapter

Standaard beveiligt de app de id-tokendetails en oproepgrafiekpagina's , zodat alleen aangemelde gebruikers er toegang toe hebben. De app configureert deze routes op basis van de eigenschap uit het bestand application.yml. Als u de specifieke vereisten van uw app wilt configureren, kunt u uitbreiden in een van uw klassen. Zie voor een voorbeeld de klasse SecurityConfig van deze app, zoals weergegeven in de volgende code:

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

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

Oproepgrafiek

Wanneer de gebruiker naar navigeert, maakt de toepassing een exemplaar van de met behulp van een of die door de Microsoft Entra ID boot starter is voorbereid. De app vraagt om het -endpoint aan te roepen en geeft details weer van de momenteel aangemelde gebruiker. komt uit de Microsoft Graph SDK voor Java, v3.

De moet met de juiste scopes zijn geconfigureerd. Zie het application.yml-bestand en de volgende Scopes-sectie. Het wordt gebruikt om het toegangstoken beschikbaar te maken en het in de -header van -aanvragen te plaatsen, zoals in het volgende voorbeeld wordt getoond:

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

Het volgende voorbeeld uit het bestand application.yml toont de aangevraagde scopes:

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

Scopes

Machtigingen geven Microsoft Entra ID aan welk toegangsniveau de toepassing aanvraagt. Zie application.yml voor de Microsoft Graph-scopes die door deze toepassing zijn aangevraagd.

Standaard stelt de toepassing de waarde van scopes in op . Het bereik is bedoeld voor het openen van de gegevens van de momenteel aangemelde gebruiker via het /me-eindpunt. Geldige aanvragen voor het /me-eindpunt moeten het -bereik bevatten.

Wanneer een gebruiker zich aanmeldt, toont Microsoft Entra ID aan de gebruiker een dialoogvenster voor toestemming op basis van de machtigingsbereiken die door de applicatie worden aangevraagd. Als de gebruiker toestemming verleent voor een of meer scopes en een token verkrijgt, worden de scopes waarvoor toestemming is verleend opgenomen in het resulterende toegangstoken.

In deze app toont het toegangstoken dat bewijst met welke machtigingen de gebruiker heeft ingestemd. De app gebruikt dit token om een instantie van te maken die Graph-aanvragen afhandelt.

Met behulp van wordt een verzoek opgebouwd en verzonden naar . Het toegangstoken wordt in de -header van het verzoek geplaatst.

Meer informatie

• Documentatie over het Microsoft-identiteitsplatform
• Overzicht van Microsoft Authentication Library (MSAL)
• Snelstart: een toepassing registreren bij het Microsoft identity platform
• Snelstart: Een clienttoepassing configureren voor toegang tot web-API's
• Inzicht in toestemmingservaringen voor toepassingen in Microsoft Entra ID
• Begrijp de toestemming van gebruikers en beheerders
• Overzicht van toepassings- en service-principalobjecten in Microsoft Entra ID
• Nationale cloudomgevingen
• MSAL-codevoorbeelden
• Azure Active Directory Spring Boot Starter-clientbibliotheek voor Java
• Microsoft Authentication Library voor Java (MSAL4J)
• MSAL4J Wiki
• ID-tokens
• Toegangstokens in het Microsoft identity platform

Zie Authenticatiescenario's voor Microsoft Entra ID voor meer informatie over hoe OAuth 2.0-protocollen werken in dit scenario en andere scenario's.