Entwicklerleitfaden für Spring Boot Starter für Microsoft Entra

Artikel
08/13/2024

Dieser Artikel bezieht sich auf: ✔️ Version 4.19.0 ✔️ Version 5.18.0

In diesem Artikel werden die Funktionen und Kernszenarien von Spring Boot Starter für Microsoft Entra ID beschrieben. Darüber hinaus enthält dieser Artikel Anleitungen bei allgemeinen Problemen sowie Problemumgehungen und Diagnoseschritte.

Die Identitäts- und Zugriffsverwaltung ist ein grundlegender Bestandteil der Erstellung einer Webanwendung. Azure verfügt über einen cloudbasierten Identitätsdienst, der tief in das restliche Azure-Ökosystem integriert ist.

Mit Spring Security ist es zwar einfach, Ihre Spring-basierten Anwendungen zu schützen, aber es ist keine Ausrichtung auf einen bestimmten Identitätsanbieter vorhanden. Mit dem Spring Boot Starter für Microsoft Entra ID können Sie Ihre Webanwendung mit einem Microsoft Entra-Mandanten verbinden und Ihren Ressourcenserver mit Microsoft Entra ID schützen. Hierbei wird das OAuth 2.0-Protokoll verwendet, um Webanwendungen und Ressourcenserver zu schützen.

Über die folgenden Links können Sie auf das Starter-Paket, die Dokumentation und Beispiele zugreifen:

Voraussetzungen

Um die Anleitung in diesem Leitfaden befolgen zu können, müssen die folgenden Voraussetzungen erfüllt sein:

Ein Azure-Abonnement – wenn Sie noch kein Azure-Abonnement besitzen, können Sie Ihre MSDN-Abonnentenvorteile anwenden oder sich für ein Kostenloses Azure-Konto registrieren
Sie benötigen ein unterstütztes Java Development Kit (JDK) der Version 8 oder höher. Weitere Informationen finden Sie im Artikel zur Java-Unterstützung in Azure und Azure Stack.
Apache Maven Version 3.0 oder höher.
Eine Anwendung, die bei Microsoft Entra ID registriert ist. Weitere Informationen finden Sie unter Schnellstart: Eine Anwendung bei der Microsoft Identity Platform registrieren.

Wichtig

Für die Schritte in diesem Artikel wird mindestens die Spring Boot-Version 2.5 benötigt.

Schlüsselszenarien

In dieser Anleitung wird beschrieben, wie Sie Microsoft Entra Starter in den folgenden Szenarien verwenden:

Zugreifen auf eine Webanwendung
Zugreifen auf Ressourcenserver aus einer Webanwendung
Schützen eines Ressourcenservers oder einer API
Zugreifen auf andere Ressourcenserver von einem Ressourcenserver
Webanwendung und Ressourcenserver innerhalb einer Anwendung

Bei einer Webanwendung handelt es sich um eine webbasierte Anwendung, mit der sich ein Benutzer anmelden kann. Von einem Ressourcenserver wird der Zugriff entweder akzeptiert oder verweigert, nachdem ein Zugriffstoken überprüft wurde.

Zugreifen auf eine Webanwendung

In diesem Szenario wird der Flow OAuth 2.0-Autorisierungscodeberechtigung verwendet, um einem Benutzer das Anmelden mit einem Microsoft-Konto zu ermöglichen.

Führen Sie die folgenden Schritte aus, um den Microsoft Entra Starter in diesem Szenario zu verwenden:

Legen Sie den Umleitungs-URI auf <application-base-uri>/login/oauth2/code/ fest. Beispiel: http://localhost:8080/login/oauth2/code/ Achten Sie darauf, dass Sie den nachgestellten Schrägstrich (/) hinzufügen. Weitere Informationen zum Umleitungs-URI finden Sie unter Schnellstart: Registrieren einer Anwendung bei der Microsoft Identity Platform im Abschnitt Hinzufügen eines Umleitungs-URI.

Screenshot Azure-Portal mit der Seite „Web-App-Authentifizierung“ mit hervorgehobener Umleitungs-URI.

Fügen Sie der Datei pom.xml die folgenden Abhängigkeiten hinzu:

<dependency>
   <groupId>com.azure.spring</groupId>
   <artifactId>spring-cloud-azure-starter-active-directory</artifactId>
</dependency>
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>

Hinweis

Weitere Informationen zum Verwalten von Spring Cloud Azure-Bibliotheksversionen mithilfe einer Stückliste (BoM) finden Sie im Abschnitt Erste Schritte des Azure-Entwicklerhandbuchs für Spring Cloud.

Fügen Sie der Datei application.yml die folgenden Eigenschaften hinzu: Sie können die Werte für diese Eigenschaften aus der App-Registrierung abrufen, die Sie im Azure-Portal erstellt haben. Dies ist im Abschnitt mit den Voraussetzungen beschrieben.

spring:
 cloud:
   azure:
     active-directory:
       enabled: true
       profile:
         tenant-id: <tenant>
       credential:
         client-id: <your-client-ID>
         client-secret: <your-client-secret>

Hinweis

Die zulässigen Werte für tenant-id sind: common, organizations, consumers, oder die Mandanten-ID. Weitere Informationen zu diesen Werten finden Sie im Abschnitt Verwendung des falschen Endpunkts (persönliche und Organisationskonten) des Fehlers AADSTS50020 – Benutzerkonto des Identitätsanbieters ist nicht im Mandanten vorhanden. Informationen zum Konvertieren Ihrer Einzelmandanten-App finden Sie unter Konvertieren einer Einzelmandanten-App in eine mehrinstanzfähige Microsoft Entra ID.

Verwenden Sie die Standardsicherheitskonfiguration, oder geben Sie eine eigene Konfiguration an.

Spring Cloud Azure 4.x
Spring Cloud Azure 5.x

Option 1: Verwenden Sie die Standardkonfiguration.

Mit dieser Option müssen Sie nichts weiter tun. Die DefaultAadWebSecurityConfigurerAdapter-Klasse wird automatisch konfiguriert.

Option 2: Stellen Sie eine selbstdefinierte Konfiguration bereit.

Erweitern Sie zum Angeben einer Konfiguration die Klasse AadWebSecurityConfigurerAdapter, und rufen Sie super.configure(http) in der Funktion configure(HttpSecurity http) auf. Dies ist im folgenden Beispiel dargestellt:

@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class AadOAuth2LoginSecurityConfig extends AadWebSecurityConfigurerAdapter {

   /**
    * Add configuration logic as needed.
   */
   @Override
   protected void configure(HttpSecurity http) throws Exception {
       super.configure(http);
       http.authorizeRequests()
           .anyRequest().authenticated();
       // Do some custom configuration.
   }
}

Option 1: Verwenden Sie die Standardkonfiguration.

Mit dieser Option müssen Sie nichts weiter tun. Die DefaultAadWebSecurityConfiguration-Klasse wird automatisch konfiguriert.

Option 2: Stellen Sie eine selbstdefinierte Konfiguration bereit.

Um eine Konfiguration bereitzustellen, wenden Sie die Methode AadWebApplicationHttpSecurityConfigurer#aadWebApplication für das HttpSecurity folgende Beispiel an:

@Configuration(proxyBeanMethods = false)
@EnableWebSecurity
@EnableMethodSecurity
public class AadOAuth2LoginSecurityConfig {

   /**
    * Add configuration logic as needed.
    */
   @Bean
   SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
       http.apply(AadWebApplicationHttpSecurityConfigurer.aadWebApplication())
               .and()
           .authorizeHttpRequests()
               .anyRequest().authenticated();
           // Do some custom configuration.
       return http.build();
   }
}

Zugreifen auf Ressourcenserver aus einer Webanwendung

Führen Sie die folgenden Schritte aus, um den Microsoft Entra Starter in diesem Szenario zu verwenden:

Legen Sie den Umleitungs-URI wie oben beschrieben fest.

Fügen Sie der Datei pom.xml die folgenden Abhängigkeiten hinzu:

<dependency>
   <groupId>com.azure.spring</groupId>
   <artifactId>spring-cloud-azure-starter-active-directory</artifactId>
</dependency>
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>

Hinweis

Fügen Sie der Datei application.yml wie oben beschrieben die folgenden Eigenschaften hinzu:

spring:
 cloud:
   azure:
     active-directory:
       enabled: true
       profile:
         tenant-id: <tenant>
       credential:
         client-id: <your-client-ID>
         client-secret: <your-client-secret>
       authorization-clients:
         graph:
           scopes: https://graph.microsoft.com/Analytics.Read, email

Hinweis

Hier ist graph der Name Ihres OAuth2AuthorizedClient, und scopes steht für die Bereiche, die beim Anmelden für die Einwilligung benötigt werden.

Fügen Sie Ihrer Anwendung Code hinzu, der in etwa wie im folgenden Beispiel aussieht:

@GetMapping("/graph")
@ResponseBody
public String graph(
   @RegisteredOAuth2AuthorizedClient("graph") OAuth2AuthorizedClient graphClient
) {
   // toJsonString() is just a demo.
   // oAuth2AuthorizedClient contains access_token. We can use this access_token to access the resource server.
   return toJsonString(graphClient);
}

Hier steht graph für die Client-ID, die im vorherigen Schritt konfiguriert wurde. OAuth2AuthorizedClient enthält das Zugriffstoken, das für den Zugriff auf den Ressourcenserver verwendet wird.

Ein vollständiges Beispiel für dieses Szenario finden Sie unter spring-cloud-azure-starter-active-directory sample: aad-web-application.

Schützen eines Ressourcenservers oder einer API

In diesem Szenario wird die Anmeldung nicht unterstützt. Der Server ist aber geschützt, weil das Zugriffstoken überprüft wird. Wenn das Zugriffstoken gültig ist, wird die Anforderung vom Server bereitgestellt.

Führen Sie die folgenden Schritte aus, um den Microsoft Entra Starter in diesem Szenario zu verwenden:

Fügen Sie der Datei pom.xml die folgenden Abhängigkeiten hinzu:

<dependency>
   <groupId>com.azure.spring</groupId>
   <artifactId>spring-cloud-azure-starter-active-directory</artifactId>
</dependency>
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>

Hinweis

Fügen Sie der Datei application.yml wie oben beschrieben die folgenden Eigenschaften hinzu:

spring:
 cloud:
   azure:
     active-directory:
       enabled: true
       credential:
         client-id: <your-client-ID>
       app-id-uri: <your-app-ID-URI>

Sie können die Werte von <your-client-ID> und <your-app-ID-URI> verwenden, um das Zugriffstoken zu überprüfen. Sie können den Wert für <your-app-ID-URI> über das Azure-Portal abrufen. Dies ist in den folgenden Abbildungen dargestellt:

Screenshot des Azure-Portals mit der Web-App Verfügbar machen einer API-Seite, auf der der Anwendungs-ID-URI hervorgehoben ist.

Verwenden Sie die Standardsicherheitskonfiguration, oder geben Sie eine eigene Konfiguration an.

Spring Cloud Azure 4.x
Spring Cloud Azure 5.x

Option 1: Verwenden Sie die Standardkonfiguration.

Mit dieser Option müssen Sie nichts weiter tun. Die DefaultAadResourceServerWebSecurityConfigurerAdapter-Klasse wird automatisch konfiguriert.

Option 2: Stellen Sie eine selbstdefinierte Konfiguration bereit.

Erweitern Sie zum Angeben einer Konfiguration die Klasse AadResourceServerWebSecurityConfigurerAdapter, und rufen Sie super.configure(http) in der Funktion configure(HttpSecurity http) auf. Dies ist im folgenden Beispiel dargestellt:

@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class AadOAuth2ResourceServerSecurityConfig extends AadResourceServerWebSecurityConfigurerAdapter {

   /**
    * Add configuration logic as needed.
    */
   @Override
   protected void configure(HttpSecurity http) throws Exception {
       super.configure(http);
       http.authorizeRequests((requests) -> requests.anyRequest().authenticated());
   }
}

Option 1: Verwenden Sie die Standardkonfiguration.

Mit dieser Option müssen Sie nichts weiter tun. Die DefaultAadResourceServerConfiguration-Klasse wird automatisch konfiguriert.

Option 2: Stellen Sie eine selbstdefinierte Konfiguration bereit.

Um eine Konfiguration bereitzustellen, wenden Sie die Methode AadResourceServerHttpSecurityConfigurer#aadResourceServer für das HttpSecurity folgende Beispiel an:

@Configuration(proxyBeanMethods = false)
@EnableWebSecurity
@EnableMethodSecurity
public class AadOAuth2ResourceServerSecurityConfig {

   /**
    * Add configuration logic as needed.
    */
   @Bean
   public SecurityFilterChain apiFilterChain(HttpSecurity http) throws Exception {
       http.apply(AadResourceServerHttpSecurityConfigurer.aadResourceServer())
               .and()
           .authorizeHttpRequests()
               .anyRequest().authenticated();
       return http.build();
   }
}

Ein vollständiges Beispiel für dieses Szenario finden Sie unter spring-cloud-azure-starter-active-directory sample: aad-resource-server.

Zugreifen auf andere Ressourcenserver von einem Ressourcenserver

Bei diesem Szenario wird der Zugriff von einem Ressourcenserver auf andere Ressourcenserver unterstützt.

Führen Sie die folgenden Schritte aus, um den Microsoft Entra Starter in diesem Szenario zu verwenden:

Fügen Sie der Datei pom.xml die folgenden Abhängigkeiten hinzu:

<dependency>
   <groupId>com.azure.spring</groupId>
   <artifactId>spring-cloud-azure-starter-active-directory</artifactId>
</dependency>
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>

Hinweis

Fügen Sie der Datei application.yml die folgenden Eigenschaften hinzu:

spring:
 cloud:
   azure:
     active-directory:
       enabled: true
       profile:
         tenant-id: <tenant>
       credential:
         client-id: <web-API-A-client-ID>
         client-secret: <web-API-A-client-secret>
       app-id-uri: <web-API-A-app-ID-URI>
       authorization-clients:
         graph:
           scopes:
              - https://graph.microsoft.com/User.Read

Hinweis

Verwenden Sie das Attribut @RegisteredOAuth2AuthorizedClient in Ihrem Code, um auf den zugehörigen Ressourcenserver zuzugreifen. Dies ist im folgenden Beispiel dargestellt:

@PreAuthorize("hasAuthority('SCOPE_Obo.Graph.Read')")
@GetMapping("call-graph")
public String callGraph(@RegisteredOAuth2AuthorizedClient("graph") OAuth2AuthorizedClient graph) {
   return callMicrosoftGraphMeEndpoint(graph);
}

Ein vollständiges Beispiel für dieses Szenario finden Sie unter spring-cloud-azure-starter-active-directory sample: aad-resource-server-obo.

Webanwendung und Ressourcenserver innerhalb einer Anwendung

Bei diesem Szenario werden das Zugreifen auf eine Webanwendung und das Schützen eines Ressourcenservers oder einer API innerhalb einer Anwendung unterstützt.

Gehen Sie wie folgt vor, um aad-starter in diesem Szenario zu implementieren:

Fügen Sie der Datei pom.xml die folgenden Abhängigkeiten hinzu:

<dependency>
   <groupId>com.azure.spring</groupId>
   <artifactId>spring-cloud-azure-starter-active-directory</artifactId>
</dependency>
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>

Hinweis

Aktualisieren Sie Ihre Datei application.yml. Legen Sie die Eigenschaft spring.cloud.azure.active-directory.application-type auf web_application_and_resource_server fest, und geben Sie den Autorisierungstyp für die einzelnen Autorisierungsclients an, wie dies im folgenden Beispiel dargestellt ist.

spring:
 cloud:
   azure:
     active-directory:
       enabled: true
       profile:
         tenant-id: <tenant>
       credential:
         client-id: <Web-API-C-client-id>
         client-secret: <Web-API-C-client-secret>
       app-id-uri: <Web-API-C-app-id-url>
       application-type: web_application_and_resource_server  # This is required.
       authorization-clients:
         graph:
           authorizationGrantType: authorization_code  # This is required.
           scopes:
             - https://graph.microsoft.com/User.Read
             - https://graph.microsoft.com/Directory.Read.All

Hinweis

Schreiben Sie Java-Code, um mehrere Instanzen von HttpSecurity zu konfigurieren.

Spring Cloud Azure 4.x
Spring Cloud Azure 5.x

Im folgenden Beispielcode enthält AadWebApplicationAndResourceServerConfig zwei Sicherheitskonfigurationen: eine für einen Ressourcenserver und eine für eine Webanwendung. Die Priorität, den Sicherheitsadapter des Ressourcenservers zu konfigurieren, ist für die Klasse ApiWebSecurityConfigurationAdapter hoch. Für die Klasse HtmlWebSecurityConfigurerAdapter ist die Priorität, den Sicherheitsadapter der Webanwendung zu konfigurieren, niedrig.

@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class AadWebApplicationAndResourceServerConfig {

   @Order(1)
   @Configuration
   public static class ApiWebSecurityConfigurationAdapter extends AadResourceServerWebSecurityConfigurerAdapter {
       protected void configure(HttpSecurity http) throws Exception {
           super.configure(http);
           // All the paths that match `/api/**`(configurable) work as the esource server. Other paths work as  the web application.
           http.antMatcher("/api/**")
               .authorizeRequests().anyRequest().authenticated();
       }
   }

   @Configuration
   public static class HtmlWebSecurityConfigurerAdapter extends AadWebSecurityConfigurerAdapter {

       @Override
       protected void configure(HttpSecurity http) throws Exception {
           super.configure(http);
           // @formatter:off
           http.authorizeRequests()
                   .antMatchers("/login").permitAll()
                   .anyRequest().authenticated();
           // @formatter:on
       }
   }
}

Im folgenden Beispielcode enthält AadWebApplicationAndResourceServerConfig zwei Sicherheitsfilter-Kettenbeans: eine für einen Ressourcenserver und eine für eine Webanwendung. Die Priorität, den Sicherheitsbuilder des Ressourcenservers zu konfigurieren, ist für das Bean apiFilterChain hoch. Für das Bean htmlFilterChain ist die Priorität, den Sicherheitsbuilder der Webanwendung zu konfigurieren, niedrig.

@Configuration(proxyBeanMethods = false)
@EnableWebSecurity
@EnableMethodSecurity
public class AadWebApplicationAndResourceServerConfig {

    @Bean
    @Order(1)
    public SecurityFilterChain apiFilterChain(HttpSecurity http) throws Exception {
        http.apply(AadResourceServerHttpSecurityConfigurer.aadResourceServer())
                .and()
            // All the paths that match `/api/**`(configurable) work as the resource server. Other paths work as the web application.
            .securityMatcher("/api/**")
            .authorizeHttpRequests()
                .anyRequest().authenticated();
        return http.build();
    }

    @Bean
    public SecurityFilterChain htmlFilterChain(HttpSecurity http) throws Exception {
        // @formatter:off
        http.apply(AadWebApplicationHttpSecurityConfigurer.aadWebApplication())
                .and()
            .authorizeHttpRequests()
                .requestMatchers("/login").permitAll()
                .anyRequest().authenticated();
        // @formatter:on
        return http.build();
    }
}

Anwendungstyp

Die Eigenschaft spring.cloud.azure.active-directory.application-type ist optional, da ihr Wert von Abhängigkeiten abgeleitet werden kann. Sie müssen die Eigenschaft nur dann manuell festlegen, wenn Sie den Wert web_application_and_resource_server verwenden.

Weist eine Abhängigkeit auf: spring-security-oauth2-client	Weist eine Abhängigkeit auf: spring-security-oauth2-resource-server	Gültige Werte für den Anwendungstyp	Standardwert
Ja	Nr.	`web_application`	`web_application`
Nein	Ja	`resource_server`	`resource_server`
Ja	Ja	`web_application`,`resource_server`, `resource_server_with_obo`, `web_application_and_resource_server`	`resource_server_with_obo`

Konfigurierbare Eigenschaften

Spring Boot Starter für Microsoft Entra ID verfügt über die folgenden Eigenschaften:

Eigenschaften	Beschreibung
spring.cloud.azure.active-directory.app-id-uri	Wird vom Ressourcenserver verwendet, um die Zielgruppe im Zugriffstoken zu überprüfen. Das Zugriffstoken ist nur gültig, wenn die Zielgruppe den zuvor beschriebenen Werten für <your-client-ID> oder <your-app-ID-URI> entspricht.
spring.cloud.azure.active-directory.authorization-clients	Eine Zuordnung für die Konfiguration der Ressourcen-APIs, auf die von der Anwendung zugegriffen werden soll. Jedes Element steht für eine Ressourcen-API, auf die von der Anwendung zugegriffen wird. In Ihrem Spring-Code entspricht jedes Element einem `OAuth2AuthorizedClient`-Objekt.
spring.cloud.azure.active-directory.authorization-clients.<your-client-name>.scopes	Die API-Berechtigungen eines Ressourcenservers, die von der Anwendung abgerufen werden.
spring.cloud.azure.active-directory.authorization-clients.<your-client-name>.authorization-grant-type	Der Typ des Autorisierungsclients. Die unterstützten Typen sind authorization_code (Standardtyp für „webapp“), on_behalf_of (Standardtyp für „resource-server“) und client_credentials.
spring.cloud.azure.active-directory.application-type	Weitere Informationen finden Sie unter Anwendungstyp.
spring.cloud.azure.active-directory.profile.environment.active-directory-endpoint	Der Basis-URI für den Autorisierungsserver. Der Standardwert ist `https://login.microsoftonline.com/`.
spring.cloud.azure.active-directory.credential.client-id	Die registrierte Anwendungs-ID in Microsoft Entra ID
spring.cloud.azure.active-directory.credential.client-secret	Der geheime Clientschlüssel der registrierten Anwendung.
spring.cloud.azure.active-directory.user-group.use-transitive-members	Verwenden Sie `v1.0/me/transitiveMemberOf`, um Gruppen abzurufen, wenn sie auf true festgelegt sind. Verwenden Sie andernfalls `/v1.0/me/memberOf`.
spring.cloud.azure.active-directory.post-logout-redirect-uri	Der Umleitungs-URI für das Posten der Abmeldung.
spring.cloud.azure.active-directory.profile.tenant-id	Azure-Mandanten-ID Die zulässigen Werte für `tenant-id` sind: `common`, `organizations`, `consumers`, oder die Mandanten-ID.
spring.cloud.azure.active-directory.user-group.allowed-group-names	Die erwarteten Benutzergruppen, denen eine Autorität gewährt wird, wenn sie in der Antwort des `MemberOf`-Aufrufs der Graph-API enthalten sind.
spring.cloud.azure.active-directory.user-name-attribute	Gibt an, welcher Anspruch dem Namen des Prinzipals entspricht.

In den folgenden Beispielen wird veranschaulicht, wie Sie diese Eigenschaften verwenden:

Eigenschaftsbeispiel 1: Führen Sie den folgenden Schritt aus, um Azure China 21Vianet anstelle von Azure Global zu verwenden.

Fügen Sie der Datei application.yml die folgenden Eigenschaften hinzu:

spring:
   cloud:
     azure:
       active-directory:
         enabled: true
         profile:
           environment:
             active-directory-endpoint: https://login.partner.microsoftonline.cn

Mit dieser Methode können Sie anstelle der öffentlichen Azure-Cloud eine unabhängige oder nationale Azure-Cloud verwenden.

Eigenschaftsbeispiel 2: Führen Sie die folgenden Schritte aus, um einen Gruppennamen zum Schützen einer Methode in einer Webanwendung zu verwenden:

Fügen Sie der Datei application.yml die folgende Eigenschaft hinzu:

spring:
 cloud:
   azure:
     active-directory:
       enabled: true
       user-group:
         allowed-groups: group1, group2

Verwenden Sie die Standardsicherheitskonfiguration, oder geben Sie eine eigene Konfiguration an.

Spring Cloud Azure 4.x
Spring Cloud Azure 5.x

Option 1: Verwenden Sie die Standardkonfiguration. Mit dieser Option müssen Sie nichts weiter tun. Die DefaultAadWebSecurityConfigurerAdapter-Klasse wird automatisch konfiguriert.

Option 2: Stellen Sie eine selbstdefinierte Konfiguration bereit. Erweitern Sie zum Angeben einer Konfiguration die Klasse AadWebSecurityConfigurerAdapter, und rufen Sie super.configure(http) in der Funktion configure(HttpSecurity http) auf. Dies ist im folgenden Beispiel dargestellt:

@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class AadOAuth2LoginSecurityConfig extends AadWebSecurityConfigurerAdapter {

   /**
    * Add configuration logic as needed.
    */
   @Override
   protected void configure(HttpSecurity http) throws Exception {
       super.configure(http);
       http.authorizeRequests()
           .anyRequest().authenticated();
       // Do some custom configuration.
   }
}

Option 1: Verwenden Sie die Standardkonfiguration. Mit dieser Option müssen Sie nichts weiter tun. Die DefaultAadWebSecurityConfiguration-Klasse wird automatisch konfiguriert.

Option 2: Stellen Sie eine selbstdefinierte Konfiguration bereit. Um eine Konfiguration bereitzustellen, wenden Sie die Methode AadWebApplicationHttpSecurityConfigurer#aadWebApplication für das HttpSecurity folgende Beispiel an:

@Configuration(proxyBeanMethods = false)
@EnableWebSecurity
@EnableMethodSecurity
public class AadOAuth2LoginSecurityConfig {

   /**
    * Add configuration logic as needed.
    */
   @Bean
   public SecurityFilterChain htmlFilterChain(HttpSecurity http) throws Exception {
       // @formatter:off
       http.apply(AadWebApplicationHttpSecurityConfigurer.aadWebApplication())
               .and()
           .authorizeHttpRequests()
               .anyRequest().authenticated();
       // @formatter:on
       // Do some custom configuration.
       return http.build();
   }
}

Nutzen Sie die Anmerkung @PreAuthorize, um die Methode zu schützen. Dies ist im folgenden Beispiel dargestellt:

@Controller
public class RoleController {
   @GetMapping("group1")
   @ResponseBody
   @PreAuthorize("hasRole('ROLE_group1')")
   public String group1() {
       return "group1 message";
   }

   @GetMapping("group2")
   @ResponseBody
   @PreAuthorize("hasRole('ROLE_group2')")
   public String group2() {
       return "group2 message";
   }

   @GetMapping("group1Id")
   @ResponseBody
   @PreAuthorize("hasRole('ROLE_<group1-id>')")
   public String group1Id() {
       return "group1Id message";
   }

   @GetMapping("group2Id")
   @ResponseBody
   @PreAuthorize("hasRole('ROLE_<group2-id>')")
   public String group2Id() {
       return "group2Id message";
   }
}

Eigenschaftsbeispiel 3: Führen Sie die folgenden Schritte aus, um den Flow der Clientanmeldeinformationen auf einem Ressourcenserver zu aktivieren, der auf andere Ressourcenserver zugreift:

Fügen Sie der Datei application.yml die folgende Eigenschaft hinzu:

spring:
 cloud:
   azure:
     active-directory:
       enabled: true
       authorization-clients:
         webapiC:   # When authorization-grant-type is null, on behalf of flow is used by default
           authorization-grant-type: client_credentials
           scopes:
             - <Web-API-C-app-id-url>/.default

Fügen Sie Ihrer Anwendung Code hinzu, der in etwa wie im folgenden Beispiel aussieht:

@PreAuthorize("hasAuthority('SCOPE_Obo.WebApiA.ExampleScope')")
@GetMapping("webapiA/webapiC")
public String callClientCredential() {
   String body = webClient
       .get()
       .uri(CUSTOM_LOCAL_READ_ENDPOINT)
       .attributes(clientRegistrationId("webapiC"))
       .retrieve()
       .bodyToMono(String.class)
       .block();
   LOGGER.info("Response from Client Credential: {}", body);
   return "client Credential response " + (null != body ? "success." : "failed.");
}

Erweiterte Funktionen

Unterstützung der Zugriffssteuerung per ID-Token in einer Webanwendung

Starter unterstützt die Erstellung von GrantedAuthority über den Anspruch roles des ID-Tokens, um die Verwendung des ID-Tokens für die Autorisierung in einer Webanwendung zuzulassen. Sie können das Feature appRoles von Microsoft Entra ID verwenden, um einen roles-Anspruch zu erstellen und die Zugriffssteuerung zu implementieren.

Hinweis

Der Anspruch roles, der per appRoles generiert wurde, verfügt über das Präfix APPROLE_.

Bei der Verwendung von appRoles als roles-Anspruch sollten Sie es vermeiden, gleichzeitig ein Gruppenattribut als roles zu konfigurieren. Andernfalls überschreibt das Gruppenattribut den Anspruch, der dann nicht mehr appRoles enthält, sondern Gruppeninformationen. Sie sollten es vermeiden, in Ihrem Manifest die folgende Konfiguration zu verwenden:

"optionalClaims": {
    "idtoken": [{
        "name": "groups",
        "additionalProperties": ["emit_as_roles"]
    }]
}

Führen Sie die folgenden Schritte aus, um die Zugriffssteuerung per ID-Token in einer Webanwendung zu unterstützen:

Fügen Sie App-Rollen in Ihrer Anwendung hinzu, und weisen Sie sie Benutzern oder Gruppen zu. Weitere Informationen finden Sie unter Gewusst wie: Hinzufügen von App-Rollen zu Ihrer Anwendung und Empfangen der Rollen im Token.

Fügen Sie dem Manifest Ihrer Anwendung die folgende Konfiguration für appRoles hinzu:

 "appRoles": [
   {
     "allowedMemberTypes": [
       "User"
     ],
     "displayName": "Admin",
     "id": "2fa848d0-8054-4e11-8c73-7af5f1171001",
     "isEnabled": true,
     "description": "Full admin access",
     "value": "Admin"
    }
 ]

Fügen Sie Ihrer Anwendung Code hinzu, der in etwa wie im folgenden Beispiel aussieht:

@GetMapping("Admin")
@ResponseBody
@PreAuthorize("hasAuthority('APPROLE_Admin')")
public String Admin() {
   return "Admin message";
}

Problembehandlung

Aktivieren der Clientprotokollierung

Die Azure SDKs für Java bieten eine konsistente Protokollierungsstory, um die Problembehandlung und Behebung von Anwendungsfehlern zu unterstützen. In den erstellten Protokollen wird der Flow einer Anwendung erfasst, bevor sie den Endzustand erreicht. Dies trägt zur Ermittlung der Grundursache bei. Eine Anleitung zum Aktivieren der Protokollierung finden Sie im Wiki-Artikel zur Protokollierung.

Aktivieren der Spring-Protokollierung

Mit Spring können für alle unterstützten Protokollierungssysteme in der Spring-Umgebung (z. B. in application.properties) Protokollierungsebenen festgelegt werden, indem logging.level.<logger-name>=<level> genutzt wird. Hierbei steht „level“ für „TRACE“, „DEBUG“, „INFO“, „WARN“, „ERROR“, „FATAL“ oder „OFF“. Sie können die Stammprotokollierung mit logging.level.root konfigurieren.

Im folgenden Beispiel sind potenzielle Protokollierungseinstellungen in der Datei application.properties dargestellt:

logging.level.root=WARN
logging.level.org.springframework.web=DEBUG
logging.level.org.hibernate=ERROR

Weitere Informationen zur Protokollierungskonfiguration in Spring finden Sie in der Spring-Dokumentation unter Protokollierung.

Nächste Schritte

Weitere Informationen zu Spring und Azure finden Sie im Dokumentationscenter zu Spring in Azure.

Spring Framework in Azure

Teilen über

Entwicklerleitfaden für Spring Boot Starter für Microsoft Entra

Voraussetzungen

Schlüsselszenarien

Zugreifen auf eine Webanwendung

Zugreifen auf Ressourcenserver aus einer Webanwendung

Schützen eines Ressourcenservers oder einer API

Zugreifen auf andere Ressourcenserver von einem Ressourcenserver

Webanwendung und Ressourcenserver innerhalb einer Anwendung

Anwendungstyp

Konfigurierbare Eigenschaften

Erweiterte Funktionen

Unterstützung der Zugriffssteuerung per ID-Token in einer Webanwendung

Problembehandlung

Aktivieren der Clientprotokollierung

Aktivieren der Spring-Protokollierung

Nächste Schritte

Feedback

Zusätzliche Ressourcen