Microsoft Entra 개발자용 Spring Boot Starter 가이드

이 문서는✅ 버전 4.19.0 ✅ 버전 5.19.0에 적용됩니다.

이 문서에서는 Microsoft Entra ID용 Spring Boot Starter의 기능 및 핵심 시나리오에 대해 설명합니다. 이 문서에는 일반적인 문제, 해결 방법 및 진단 단계에 대한 지침도 포함되어 있습니다.

웹 애플리케이션을 빌드할 때 ID 및 액세스 관리는 기본 요소입니다. Azure는 나머지 Azure 에코시스템과 긴밀하게 통합된 클라우드 기반 ID 서비스를 제공합니다.

Spring Security를 사용하면 Spring 기반 애플리케이션을 쉽게 보호할 수 있지만 특정 ID 공급자에 맞게 조정되지는 않습니다. Microsoft Entra용 Spring Boot Starter ID를 사용하면 웹 애플리케이션을 Microsoft Entra 테넌트에 연결하고 Microsoft Entra ID로 리소스 서버를 보호할 수 있습니다. Oauth 2.0 프로토콜을 사용하여 웹 애플리케이션 및 리소스 서버를 보호합니다.

다음 링크는 시작 패키지, 설명서 및 샘플에 대한 액세스를 제공합니다.

• "Spring-cloud-azure-starter-active-directory" 패키지 (Maven)
• 빠른 시작
• 샘플

필수 구성 요소

이 가이드의 지침을 따르려면 다음 필수 구성 요소가 있어야 합니다.

• Azure 구독; Azure 구독이 아직 없는 경우 MSDN 구독자 혜택을 활성화하거나무료 Azure 계정등록할 수 있습니다.
• 지원되는 JDK(Java Development Kit), 버전 8 이상. 자세한 내용은 Azure 및 Azure Stack에서 Java 지원을 참조하세요.
• Apache Maven버전 3.0 이상.
• Microsoft Entra ID에 등록된 애플리케이션입니다. 자세한 내용은 빠른 시작: Microsoft ID 플랫폼애플리케이션 등록을 참조하세요.

핵심 시나리오

이 가이드에서는 다음 시나리오에서 Microsoft Entra Starter를 사용하는 방법을 설명합니다.

• 웹 애플리케이션에 액세스하다
• 웹 애플리케이션에서 리소스 서버에 액세스
• 리소스 서버/API 보호
• 리소스 서버에서 다른 리소스 서버에 액세스
• 웹 애플리케이션 및 리소스 서버를 한 애플리케이션으로

웹 애플리케이션 사용자가 로그인할 수 있도록 하는 모든 웹 기반 애플리케이션입니다. 리소스 서버 액세스 토큰의 유효성을 검사한 후 액세스를 수락하거나 거부합니다.

웹 애플리케이션에 액세스

이 시나리오에서는 OAuth 2.0 권한 부여 코드 부여 흐름을 사용하여 사용자가 Microsoft 계정으로 로그인할 수 있도록 합니다.

이 시나리오에서 Microsoft Entra Starter를 사용하려면 다음 단계를 사용합니다.

리디렉션 URI를 <application-base-uri>/login/oauth2/code/로 설정합니다. 예: http://localhost:8080/login/oauth2/code/. 반드시 후행 /을 포함해야 합니다. 리디렉션 URI에 대한 자세한 내용은 빠른 시작에서 리디렉션 URI 추가: Microsoft ID 플랫폼애플리케이션 등록을 참조하세요.

pom.xml 파일에 다음 종속성을 추가합니다.

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

application.yml 파일에 다음 속성을 추가합니다. 필수 구성 요소에 설명된 대로 Azure Portal에서 만든 앱 등록에서 이러한 속성의 값을 가져올 수 있습니다.

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

기본 보안 구성을 사용하거나 사용자 고유의 구성을 제공합니다.

@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();
   }
}

@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.
   }
}

웹 애플리케이션에서 리소스 서버에 액세스

이 시나리오에서 Microsoft Entra Starter를 사용하려면 다음 단계를 사용합니다.

앞에서 설명한 대로 리디렉션 URI를 설정합니다.

pom.xml 파일에 다음 종속성을 추가합니다.

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

앞에서 설명한 대로 application.yml 파일에 다음 속성을 추가합니다.

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

여기서 graph은 OAuth2AuthorizedClient의 이름이고, scopes는 로그인할 때 필요한 동의 범위입니다.

다음 예제와 유사한 코드를 애플리케이션에 추가합니다.

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

여기서 graph 이전 단계에서 구성한 클라이언트 ID입니다. OAuth2AuthorizedClient 리소스 서버에 액세스하는 데 사용되는 액세스 토큰을 포함합니다.

이 시나리오를 보여주는 전체 샘플은 spring-cloud-azure-starter-active-directory 샘플: aad-web-application참고하세요.

리소스 서버/API 보호

이 시나리오는 로그인을 지원하지 않지만 액세스 토큰의 유효성을 검사하여 서버를 보호합니다. 액세스 토큰이 유효한 경우 서버는 요청을 제공합니다.

이 시나리오에서 Microsoft Entra Starter를 사용하려면 다음 단계를 사용합니다.

pom.xml 파일에 다음 종속성을 추가합니다.

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

앞에서 설명한 대로 application.yml 파일에 다음 속성을 추가합니다.

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

클라이언트 ID <> 및 앱-ID-URI <> 값을 사용하여 액세스 토큰을 확인할 수 있습니다. 다음 이미지와 같이 Azure 포털에서 <your-app-ID-URI> 값을 가져올 수 있습니다.

기본 보안 구성을 사용하거나 사용자 고유의 구성을 제공합니다.

@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();
   }
}

@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());
   }
}

이 상황을 보여주는 완전한 샘플을 보려면 spring-cloud-azure-starter-active-directory 샘플: aad-resource-server를 참조하세요.

리소스 서버에서 다른 리소스 서버에 액세스

이 시나리오는 다른 리소스 서버를 방문하는 리소스 서버를 지원합니다.

이 시나리오에서 Microsoft Entra Starter를 사용하려면 다음 단계를 사용합니다.

pom.xml 파일에 다음 종속성을 추가합니다.

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

application.yml 파일에 다음 속성을 추가합니다.

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

다음 예제와 같이 코드의 @RegisteredOAuth2AuthorizedClient 특성을 사용하여 관련 리소스 서버에 액세스합니다.

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

이 시나리오를 보여주는 전체 샘플에 대해서는 spring-cloud-azure-starter-active-directory 샘플: aad-resource-server-obo를 참고하십시오.

한 애플리케이션의 웹 애플리케이션 및 리소스 서버

이 시나리오는 한 애플리케이션에서 웹 애플리케이션에 액세스하고 리소스 서버/API를 보호하는 것을 지원합니다.

이 시나리오에서 aad-starter 사용하려면 다음 단계를 수행합니다.

pom.xml 파일에 다음 종속성을 추가합니다.

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

application.yml 파일을 업데이트합니다. 다음 예제와 같이 속성 spring.cloud.azure.active-directory.application-typeweb_application_and_resource_server설정하고 각 권한 부여 클라이언트에 대한 권한 부여 유형을 지정합니다.

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

Java 코드를 작성하여 여러 HttpSecurity 인스턴스를 구성합니다.

@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();
    }
}

@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 resource 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
       }
   }
}

애플리케이션 유형

spring.cloud.azure.active-directory.application-type 속성은 해당 값을 종속성으로 유추할 수 있으므로 선택 사항입니다. web_application_and_resource_server 값을 사용하는 경우에만 속성을 수동으로 설정해야 합니다.

구성 가능한 속성

Microsoft Entra ID용 Spring Boot Starter는 다음 속성을 제공합니다.

다음 예제에서는 이러한 속성을 사용하는 방법을 보여 줍니다.

속성 예제 1: Azure Global 대신 Azure China 21Vianet 사용하려면 다음 단계를 사용합니다.

• application.yml 파일에 다음 속성을 추가합니다.

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

이 방법을 사용하면 Azure 퍼블릭 클라우드 대신 Azure 소버린 또는 국가별 클라우드 사용할 수 있습니다.

속성 예제 2: 그룹 이름을 사용하여 웹 애플리케이션에서 일부 메서드를 보호하려면 다음 단계를 사용합니다.

application.yml 파일에 다음 속성을 추가합니다.

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

기본 보안 구성을 사용하거나 사용자 고유의 구성을 제공합니다.

@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();
   }
}

@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.
   }
}

다음 예제와 같이 @PreAuthorize 주석을 사용하여 메서드를 보호합니다.

@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";
   }
}

속성 예제 3: 리소스 서버를 방문하는 리소스 서버에서 클라이언트 자격 증명 흐름을 사용하도록 설정하려면 다음 단계를 사용합니다.

application.yml 파일에 다음 속성을 추가합니다.

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

다음 예제와 유사한 코드를 애플리케이션에 추가합니다.

@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.");
}

고급 기능

웹 애플리케이션에서 ID 토큰별 액세스 제어 지원

시작기는 ID 토큰의 roles 클레임에서 GrantedAuthority을 생성하여 웹 애플리케이션에서 인증에 ID 토큰을 사용할 수 있도록 지원합니다. Microsoft Entra ID의 appRoles 기능을 사용하여 roles 클레임을 만들고 액세스 제어를 구현할 수 있습니다.

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

웹 애플리케이션에서 ID 토큰으로 액세스 제어를 지원하려면 다음 단계를 사용합니다.

애플리케이션에 앱 역할을 추가하고 사용자 또는 그룹에 할당합니다. 자세한 내용은 애플리케이션에 앱 역할을 추가하고 토큰을 수신하는 방법을 참조하세요.

애플리케이션의 매니페스트에 다음 appRoles 구성을 추가합니다.

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

다음 예제와 유사한 코드를 애플리케이션에 추가합니다.

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

문제 해결

클라이언트 로깅 활성화

Java용 Azure SDK는 애플리케이션 오류를 해결하고 해결하는 데 도움이 되는 일관된 로깅 스토리를 제공합니다. 생성된 로그는 터미널에 도달하기 전에 애플리케이션의 흐름을 캡처하여 근본 문제를 찾는 데 도움이 됩니다. 로깅을 사용하도록 설정하는 방법에 대한 지침은 로깅 wiki를 참조하세요.

Spring 로깅 가능 설정

Spring을 사용하면 모든 지원되는 로깅 시스템이 Spring 환경(예: application.properties)에서 logging.level.<logger-name>=<level>를 사용하여 TRACE, DEBUG, INFO, WARN, ERROR, FATAL, 또는 OFF 중 하나로 로거 수준을 설정할 수 있습니다. logging.level.root사용하여 루트 로거를 구성할 수 있습니다.

다음 예제에서는 application.properties 파일의 잠재적인 로깅 설정을 보여 줍니다.

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

Spring의 로깅 구성에 대한 자세한 내용은 Spring 설명서의 로깅 참조하세요.

다음 단계

Spring 및 Azure에 대해 자세히 알아보려면 Spring on Azure 설명서 센터를 계속 진행하세요.