Delen via

Java Spring Boot-apps beveiligen met behulp van Microsoft Entra-id

  • Artikel

In dit artikel wordt een Java Spring Boot-web-app gedemonstreert die gebruikers aanmeldt bij uw Microsoft Entra ID-tenant met behulp van de Microsoft Entra ID Spring Boot Starter-clientbibliotheek voor Java. Het maakt gebruik van het OpenID Connect-protocol.

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

Diagram met de topologie van de app.

De client-app maakt gebruik van de Microsoft Entra ID Spring Boot Starter-clientbibliotheek voor Java om een gebruiker aan te melden en een id-token op te halen van Microsoft Entra ID. Het id-token bewijst dat de gebruiker is geverifieerd met Microsoft Entra-id en dat de gebruiker toegang heeft tot beveiligde routes.

Vereisten

Aanbevelingen

  • Enige bekendheid met het Spring Framework.
  • 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 4-spring-web-app/1-Authentication/sign-in

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 padlengtebeperkingen voor Windows te voorkomen, raden we u aan om te klonen in een map in de buurt van de hoofdmap van uw station.

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 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-spring-webapp-auth)

Voer de volgende stappen uit om de app te registreren:

  1. Navigeer naar 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 toepassingsregistratiegegevens in:

    • Voer in de sectie Naam een beschrijvende toepassingsnaam in om weer te geven aan gebruikers van de app, java-spring-webapp-authbijvoorbeeld.
    • Onder Ondersteunde accounttypen selecteert u Enkel accounts in deze organisatieadreslijst.
    • Selecteer in de sectie Omleidings-URI (optioneel) web in de keuzelijst met invoervak en voer de volgende omleidings-URI in: http://localhost:8080/login/oauth2/code/.

  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 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 van de beschikbare duur: in 1 jaar, in 2 jaar of nooit verloopt.

  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.

De app (java-spring-webapp-auth) 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\application.yml .

  3. Zoek de tijdelijke aanduiding Enter_Your_Tenant_ID_Here en vervang de bestaande waarde door uw Microsoft Entra-tenant-id.

  4. Zoek de tijdelijke aanduiding Enter_Your_Client_ID_Here en vervang de bestaande waarde door de toepassings-id of clientId de java-spring-webapp-auth app die is gekopieerd uit Azure Portal.

  5. Zoek de tijdelijke aanduiding Enter_Your_Client_Secret_Here en vervang de bestaande waarde door de waarde die u hebt opgeslagen tijdens het maken van java-spring-webapp-auth de kopie uit Azure Portal.

De voorbeeldtoepassing uitvoeren

In de volgende secties ziet u hoe u het voorbeeld implementeert in Azure Container Apps.

Vereisten

Het Spring-project voorbereiden

Gebruik de volgende stappen om het project voor te bereiden:

  1. Gebruik de volgende Maven-opdracht om het project te bouwen:

    mvn clean verify

  2. Voer het voorbeeldproject lokaal uit met behulp van de volgende opdracht:

    mvn spring-boot:run

Instellingen

Als u zich wilt aanmelden bij Azure vanuit de CLI, voert u de volgende opdracht uit en volgt u de aanwijzingen om het verificatieproces te voltooien.

az login

Voer de upgradeopdracht uit om ervoor te zorgen dat u de nieuwste versie van de CLI uitvoert.

az upgrade

Installeer of werk vervolgens de Azure Container Apps-extensie voor de CLI bij.

Als u fouten ontvangt over ontbrekende parameters wanneer u opdrachten uitvoert az containerapp in Azure CLI, moet u ervoor zorgen dat de nieuwste versie van de Azure Container Apps-extensie is geïnstalleerd.

az extension add --name containerapp --upgrade

Notitie

Vanaf mei 2024 schakelen Azure CLI-extensies standaard geen preview-functies meer in. Als u toegang wilt krijgen tot de preview-functies van Container Apps, installeert u de Container Apps-extensie met --allow-preview true.

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

Nu de huidige extensie of module is geïnstalleerd, registreert u de Microsoft.App en Microsoft.OperationalInsights naamruimten.

Notitie

Azure Container Apps-resources zijn gemigreerd van de Microsoft.Web naamruimte naar de Microsoft.App naamruimte. Raadpleeg de naamruimtemigratie van Microsoft.Web naar Microsoft.App in maart 2022 voor meer informatie.

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

De Azure Container Apps-omgeving maken

Nu uw Azure CLI-installatie is voltooid, kunt u de omgevingsvariabelen definiëren die in dit artikel worden gebruikt.

Definieer de volgende variabelen in uw bash-shell.

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"

Maak een resourcegroep.

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

Maak een omgeving met een automatisch gegenereerde Log Analytics-werkruimte.

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

Het standaarddomein van de container-app-omgeving weergeven. Noteer dit domein voor gebruik in latere secties.

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

De app voorbereiden voor implementatie

Wanneer u uw toepassing implementeert in Azure Container Apps, verandert uw omleidings-URL in de omleidings-URL van uw geïmplementeerde app-exemplaar in Azure Container Apps. Gebruik de volgende stappen om deze instellingen in uw application.yml-bestand te wijzigen:

  1. Navigeer naar het bestand src\main\resources\application.yml van uw app en wijzig de waarde van de domeinnaam van post-logout-redirect-uri uw geïmplementeerde app, zoals wordt weergegeven in het volgende voorbeeld. Zorg ervoor dat u de werkelijke waarden vervangt <API_NAME> en <default-domain-of-container-app-environment> vervangt. Met het standaarddomein voor uw Azure Container App-omgeving uit de vorige stap en ms-identity-api voor de naam van uw app gebruikt u https://ms-identity-api.<default-domain> bijvoorbeeld voor de post-logout-redirect-uri waarde.

    post-logout-redirect-uri: https://<API_NAME>.<default-domain-of-container-app-environment>

  2. Nadat u dit bestand hebt opgeslagen, gebruikt u de volgende opdracht om uw app opnieuw te bouwen:

    mvn clean package

Belangrijk

Het application.yml-bestand van de toepassing bevat momenteel de waarde van uw clientgeheim in de client-secret parameter. Het is niet raadzaam om deze waarde in dit bestand te bewaren. Mogelijk neemt u ook een risico als u het bestand doorvoert in een Git-opslagplaats. Zie Geheimen beheren in Azure Container Apps voor de aanbevolen aanpak.

De registratie van uw Microsoft Entra ID-app bijwerken

Omdat de omleidings-URI wordt gewijzigd in uw geïmplementeerde app in Azure Container Apps, 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 /login/oauth2/code/ https://<containerapp-name>.<default domain of container app environment>/login/oauth2/code/.

  7. Selecteer Opslaan.

De app implementeren

Implementeer het JAR-pakket in Azure Container Apps.

Notitie

Indien nodig kunt u de JDK-versie opgeven in de omgevingsvariabelen van de Java-build. Zie Omgevingsvariabelen bouwen voor Java in Azure Container Apps voor meer informatie.

U kunt nu uw WAR-bestand implementeren met de az containerapp up CLI-opdracht.

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

Notitie

De standaardversie van JDK is 17. Als u de JDK-versie wilt wijzigen voor compatibiliteit met uw toepassing, kunt u het --build-env-vars BP_JVM_VERSION=<YOUR_JDK_VERSION> argument gebruiken om het versienummer aan te passen.

Zie Omgevingsvariabelen bouwen voor Java in Azure Container Apps voor meer omgevingsvariabelen.

De app valideren

In dit voorbeeld bevat de containerapp up opdracht het --query properties.configuration.ingress.fqdn argument, dat de FQDN (Fully Qualified Domain Name) retourneert, ook wel de URL van de app genoemd. Gebruik de volgende stappen om de logboeken van de app te controleren om een implementatieprobleem te onderzoeken:

  1. Open de URL van de uitvoertoepassing op de pagina Uitvoer van de sectie Implementatie .

  2. Selecteer in het navigatiedeelvenster van de overzichtspagina van het Azure Container Apps-exemplaar logboeken om de logboeken van de app te controleren.

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. U kunt ook tokendetails 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. In het toestemmingsscherm ziet u de bereiken die worden aangevraagd.
  5. Wanneer de aanmeldingsstroom is voltooid, wordt u omgeleid naar de startpagina, waarin de aanmeldingsstatus wordt weergegeven, of de pagina met tokengegevens , afhankelijk van de knop die uw aanmeldingsstroom heeft geactiveerd.
  6. U ziet dat de contextgevoelige knop nu afmeldt 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. 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. Het voorbeeld maakt ook gebruik van de Spring Oauth2-client en Spring Web Boot Starters. In het voorbeeld worden claims gebruikt van het id-token dat is verkregen van Microsoft Entra ID om de details van de aangemelde gebruiker weer te geven.

Inhoud

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

Bestand/map Beschrijving
pom.xml Toepassingsafhankelijkheden.
src/main/resources/templates/ Thymeleaf-sjablonen voor de gebruikersinterface.
src/main/resources/application.yml Configuratie van de microsoft-entra-id Boot Starter-bibliotheek.
src/main/java/com/microsoft/azuresamples/msal4j/msidentityspringbootwebapp/ Deze map bevat het ingangspunt, de controller en de configuratieklassen van de hoofdtoepassing.
.../MsIdentitySpringBootWebappApplication.java Hoofdklasse.
.../SampleController.java Controller met eindpunttoewijzingen.
.../SecurityConfig.java Beveiligingsconfiguratie: voor welke routes bijvoorbeeld verificatie is vereist.
.../Utilities.java Hulpprogrammaklasse: bijvoorbeeld filter-id-tokenclaims.
CHANGELOG.md Lijst met wijzigingen in het voorbeeld.
CONTRIBUTING.md Richtlijnen voor bijdragen aan het voorbeeld.
LICENTIE De licentie voor het voorbeeld.

Id-tokenclaims

Voor het extraheren van tokendetails maakt de app gebruik van Spring Security AuthenticationPrincipal en OidcUser het object in een aanvraagtoewijzing, zoals wordt weergegeven in het volgende voorbeeld. Zie de voorbeeldcontroller voor de volledige details van 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();
}

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 afmelden doet de app een POST-aanvraag naar het logout eindpunt, zoals wordt weergegeven in het volgende voorbeeld:

<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

De app beveiligt standaard de pagina Details van het id-token , zodat alleen aangemelde gebruikers er toegang toe hebben. De app configureert deze routes met behulp van de app.protect.authenticated eigenschap uit het application.yml-bestand . Als u de specifieke vereisten van uw app wilt configureren, past u de AadWebApplicationHttpSecurityConfigurer#aadWebApplication methode toe op het HttpSecurity exemplaar. Zie voor een voorbeeld de SecurityConfig-klasse van deze app, weergegeven in de volgende code:

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig  {
    
    @Value("${app.protect.authenticated}")
    private String[] allowedOrigins;
    
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        // @formatter:off
        http.apply(AadWebApplicationHttpSecurityConfigurer.aadWebApplication())
            .and()
            .authorizeHttpRequests(auth -> auth
                .requestMatchers(allowedOrigins).authenticated()
                .anyRequest().permitAll()
                );
        // @formatter:on
        return http.build();
    }

    @Bean
    @RequestScope
    public ServletUriComponentsBuilder urlBuilder() {
        return ServletUriComponentsBuilder.fromCurrentRequest();
    }    
}

Meer informatie

Zie Verificatiescenario's voor Microsoft Entra-id voor meer informatie over de werking van OAuth 2.0-protocollen in dit scenario en andere scenario's.