Java Spring Boot 앱이 사용자를 로그인하고 Microsoft Graph에 액세스할 수 있도록 설정

이 문서에서는 사용자를 로그인하고 Microsoft Graph를 호출하기 위한 액세스 토큰을 가져오는 Java Spring Boot 웹앱을 보여 줍니다. 인증, 권한 부여 및 토큰 획득을 위해 Java용 Microsoft Entra ID Spring Boot Starter 클라이언트 라이브러리를 사용합니다. Java용 Microsoft Graph SDK를 사용하여 Graph에서 데이터를 가져옵니다.

다음 다이어그램은 앱의 토폴로지입니다.

이 앱은 Java용 Microsoft Entra ID Spring Boot Starter 클라이언트 라이브러리를 사용하여 Microsoft Entra ID에서 Microsoft Graph에 대한 액세스 토큰을 가져옵니다. 액세스 토큰은 사용자가 범위에 정의된 대로 Microsoft Graph API 엔드포인트에 액세스할 권한이 있음을 증명합니다.

필수 조건

• JDK 버전 15. 이 샘플은 Java 15를 사용하는 시스템에서 개발되었지만 다른 버전과 호환될 수 있습니다.
• Maven 3
• Visual Studio Code용 Java 확장 팩은 Visual Studio Code 에서 이 샘플을 실행하는 데 권장됩니다.
• Microsoft Entra ID 테넌트. 자세한 내용은 Microsoft Entra ID 테넌트를 가져오는 방법을 참조 하세요.
• Microsoft Entra ID 테넌트에 있는 사용자 계정입니다. 이 샘플은 개인 Microsoft 계정에서 작동하지 않습니다. 따라서 개인 계정 사용하여 Azure Portal에 로그인하고 디렉터리에 사용자 계정이 없는 경우 지금 만들어야 합니다.
• Visual Studio Code
• Visual Studio Code용 Azure 도구

권장 사항

• Spring Framework에 대해 잘 알고 있습니다.
• Linux/OSX 터미널에 대해 잘 알고 있습니다.
• 토큰을 검사하기 위한 jwt.ms.
• 네트워크 활동 모니터링 및 문제 해결을 위한 Fiddler 입니다.
• Microsoft Entra ID 블로그에 따라 최신 개발을 최신 상태로 유지합니다.

샘플 설정

다음 섹션에서는 샘플 애플리케이션을 설정하는 방법을 보여줍니다.

샘플 리포지토리 복제 또는 다운로드

샘플을 복제하려면 Bash 창을 열고 다음 명령을 사용합니다.

git clone https://github.com/Azure-Samples/ms-identity-msal-java-samples.git
cd 4-spring-web-app/2-Authorization-I/call-graph

또는 ms-identity-msal-java-samples 리포지토리로 이동한 다음, .zip 파일로 다운로드하여 하드 드라이브에 추출합니다.

Microsoft Entra ID 테넌트에 샘플 애플리케이션 등록

이 샘플에는 하나의 프로젝트가 있습니다. 다음 섹션에서는 Azure Portal을 사용하여 앱을 등록하는 방법을 보여 줍니다.

애플리케이션을 만들 Microsoft Entra ID 테넌트 선택

테넌트 선택하려면 다음 단계를 사용합니다.

1. Azure Portal에 로그인합니다.

2. 계정이 둘 이상의 Microsoft Entra ID 테넌트에 있는 경우 Azure Portal 모서리에서 프로필을 선택한 다음 디렉터리 전환을 선택하여 세션을 원하는 Microsoft Entra ID 테넌트로 변경합니다.

앱 등록(java-spring-webapp-call-graph)

앱을 등록하려면 다음 단계를 사용합니다.

1. Azure Portal로 이동하여 Microsoft Entra ID를 선택합니다.

2. 탐색 창에서 앱 등록을 선택한 다음, 새 등록을 선택합니다.

3. 표시되는 애플리케이션 등록 페이지에서 다음 애플리케이션 등록 정보를 입력합니다.

   • 이름 섹션에서 앱 사용자에게 표시할 의미 있는 애플리케이션 이름(예java-spring-webapp-call-graph: .)을 입력합니다.
   • 지원되는 계정 유형 아래에서 이 조직 디렉터리의 계정만을 선택합니다.
   • 리디렉션 URI(선택 사항) 섹션에서 콤보 상자에서 웹을 선택하고 다음 리디렉션 URIhttp://localhost:8080/login/oauth2/code/를 입력합니다.

4. 등록을 선택하여 애플리케이션을 만듭니다.

5. 앱의 등록 페이지에서 나중에 사용할 애플리케이션(클라이언트) ID 값을 찾아 복사합니다. 앱의 구성 파일 또는 파일에서 이 값을 사용합니다.

6. 앱의 등록 페이지에서 탐색 창에서 인증서 및 비밀을 선택하여 비밀을 생성하고 인증서를 업로드할 수 있는 페이지를 엽니다.

7. 클라이언트 비밀 섹션에서 새 클라이언트 비밀을 선택합니다.

8. 설명(예: 앱 비밀)을 입력합니다.

9. 사용 가능한 기간 중 하나(1년, 2년 후 또는 만료 안 됨) 중 하나를 선택합니다.

10. 추가를 선택합니다. 생성된 값이 표시됩니다.

11. 이후 단계에서 사용할 생성된 값을 복사하고 저장합니다. 코드의 구성 파일에 이 값이 필요합니다. 이 값은 다시 표시되지 않으며 다른 어떤 수단으로도 검색할 수 없습니다. 따라서 다른 화면 또는 창으로 이동하기 전에 Azure Portal에서 저장해야 합니다.

12. 앱의 등록 페이지에서 탐색 창에서 API 권한 창을 선택하여 애플리케이션에 필요한 API에 액세스할 수 있는 페이지를 엽니다.

13. 권한 추가를 선택한 다음 Microsoft API 탭이 선택되어 있는지 확인합니다.

14. 일반적으로 사용되는 Microsoft API 섹션에서 Microsoft Graph를 선택합니다.

15. 위임된 권한 섹션의 목록에서 User.Read를 선택합니다. 필요한 경우 검색 상자를 사용합니다.

16. 권한 추가를 선택합니다.

앱 등록을 사용하도록 앱 구성(java-spring-webapp-call-graph)

다음 단계를 사용하여 앱을 구성합니다.

1. IDE에서 프로젝트를 엽니다.

2. src\main\resources\application.yml 파일을 엽니다.

3. 자리 표시자를 Enter_Your_Tenant_ID_Here 찾아 기존 값을 Microsoft Entra 테넌트 ID로 바꿉니다.

4. 자리 표시자를 Enter_Your_Client_ID_Here 찾아 기존 값을 Azure Portal에서 복사한 애플리케이션 ID 또는 clientId 앱으로 java-spring-webapp-call-graph 바꿉니다.

5. 자리 표시자를 Enter_Your_Client_Secret_Here 찾아 기존 값을 Azure Portal에서 복사를 만드는 java-spring-webapp-call-graph 동안 저장한 값으로 바꿉니다.

샘플 실행

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

샘플 탐색

다음 단계를 사용하여 샘플을 탐색합니다.

1. 화면 중앙에 로그인 또는 로그아웃 상태가 표시됩니다.
2. 모서리에서 상황에 맞는 단추를 선택합니다. 이 단추는 앱을 처음 실행할 때 로그인을 읽습니다. 또는 토큰 세부 정보를 선택하거나 그래프를 호출합니다. 이 페이지는 보호되고 인증이 필요하므로 로그인 페이지로 자동으로 리디렉션됩니다.
3. 다음 페이지에서 지침을 따르고 Microsoft Entra ID 테넌트에 있는 계정으로 로그인합니다.
4. 동의 화면에서 요청되는 범위를 확인합니다.
5. 로그인 흐름이 성공적으로 완료되면 로그인 흐름을 트리거한 단추에 따라 로그인 상태를 표시하는 홈 페이지 또는 다른 페이지 중 하나로 리디렉션되어야 합니다.
6. 이제 상황에 맞는 단추에 로그아웃이 표시되고 사용자 이름이 표시됩니다.
7. 홈페이지에 있는 경우 ID 토큰 세부 정보를 선택하여 ID 토큰의 디코딩된 클레임 중 일부를 확인합니다.
8. Graph 호출을 선택하여 Microsoft Graph의 /me 엔드포인트를 호출하고 가져온 사용자 세부 정보를 확인합니다.
9. 모서리의 단추를 사용하여 로그아웃합니다. 상태 페이지에 새 상태가 반영됩니다.

코드 정보

이 샘플에서는 Java용 Microsoft Entra ID Spring Boot Starter 클라이언트 라이브러리를 사용하여 사용자를 Microsoft Entra ID 테넌트에 로그인하고 Microsoft Graph를 호출하기 위한 액세스 토큰을 가져오는 방법을 보여 줍니다. 또한 샘플에서는 Spring Oauth2 클라이언트 및 Spring Web 부팅 스타터를 사용합니다.

콘텐츠

다음 표에서는 샘플 프로젝트 폴더의 내용을 보여 줍니다.

ID 토큰 클레임

토큰 세부 정보를 추출하기 위해 앱은 다음 예제와 같이 요청 매핑에서 Spring Security AuthenticationPrincipal 및 OidcUser 개체를 사용합니다. 이 앱이 ID 토큰 클레임을 사용하는 방법에 대한 자세한 내용은 샘플 컨트롤러 를 참조하세요.

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

로그인 및 로그아웃 링크

로그인의 경우 앱은 다음 예제와 같이 Java용 Microsoft Entra ID Spring Boot Starter 클라이언트 라이브러리에 의해 자동으로 구성된 Microsoft Entra ID 로그인 엔드포인트에 대한 요청을 수행합니다.

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

로그아웃의 경우 앱은 다음 예제와 같이 엔드포인트에 logout POST 요청을 수행합니다.

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

인증 종속 UI 요소

앱에는 Spring Security Thymeleaf 태그를 사용하는 다음 예제와 같이 사용자가 인증되었는지 여부에 따라 표시할 콘텐츠를 결정하기 위한 몇 가지 간단한 논리가 UI 템플릿 페이지에 있습니다.

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

AADWebSecurityConfigurerAdapter를 사용하여 경로 보호

기본적으로 앱은 로그인한 사용자만 액세스할 수 있도록 ID 토큰 세부 정보 및 통화 그래프 페이지를 보호합니다. 앱은 application.yml 파일의 app.protect.authenticated 속성에서 이러한 경로를 구성합니다. 앱의 특정 요구 사항을 구성하려면 클래스 중 하나에서 확장 AADWebSecurityConfigurationAdapter 할 수 있습니다. 예를 들어 다음 코드에 표시된 이 앱의 SecurityConfig 클래스를 참조하세요.

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

호출 그래프

사용자가 탐색할 /call_graph때 애플리케이션은 Microsoft Entra ID 부팅 시작이 준비한 Oauth2AuthorizedClient 사용 인스턴스 GraphServiceClient 를 graphAuthorizedClient 만듭니다. 앱은 엔드포인트를 호출 /me 하도록 요청하고 GraphServiceClient 현재 로그인한 사용자에 대한 세부 정보를 표시합니다. GraphServiceClient은 Java용 Microsoft Graph SDK, v3에서 가져옵니다.

Oauth2AuthorizedClient 올바른 범위로 준비해야 합니다. application.yml 파일 및 다음 범위 섹션을 참조하세요. 다음 Oauth2AuthorizedClient 예제와 같이 액세스 토큰을 표시하고 요청 헤더 GraphServiceClient 에 배치 Authorization 하는 데 사용됩니다.

//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;
}

application.yml 파일의 다음 예제에서는 요청된 범위를 보여 줍니다.

# 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

범위

범위는 Microsoft Entra ID에 애플리케이션이 요청하는 액세스 수준을 알려줍니다. 이 애플리케이션에서 요청한 Microsoft Graph 범위는 application.yml 참조하세요.

기본적으로 애플리케이션은 범위 값을 .로 https://graph.microsoft.com/User.Read설정합니다. 범위는 User.Read /me 엔드포인트에서 현재 로그인한 사용자의 정보에 액세스하기 위한 것입니다. /me 엔드포인트에 대한 유효한 요청에는 범위가 User.Read 포함되어야 합니다.

사용자가 로그인하면 Microsoft Entra ID는 애플리케이션에서 요청한 범위에 따라 사용자에게 동의 대화 상자를 표시합니다. 사용자가 하나 이상의 범위에 동의하고 토큰을 가져오는 경우 범위 동의는 결과 액세스 토큰으로 인코딩됩니다.

이 앱 graphAuthorizedClient 에서는 사용자가 동의한 범위를 증명하는 액세스 토큰을 표시합니다. 앱은 이 토큰을 사용하여 그래프 요청을 처리하는 인스턴스 GraphServiceClient 를 만듭니다.

를 사용하여 GraphServiceClient.me().buildRequest().get()요청이 빌드되고 .에 대해 https://graph.microsoft.com/v1.0/me만들어집니다. 액세스 토큰은 요청의 헤더에 Authorization 배치됩니다.

자세한 정보

• Microsoft ID 플랫폼 설명서
• MSAL(Microsoft 인증 라이브러리) 개요
• 빠른 시작: Microsoft ID 플랫폼에 애플리케이션 등록
• 빠른 시작: 웹 API에 액세스하도록 클라이언트 애플리케이션 구성
• Microsoft Entra ID 애플리케이션 동의 환경 이해
• 사용자 및 관리자 동의 이해
• Microsoft Entra ID의 애플리케이션 및 서비스 주체 개체
• 국가별 클라우드
• MSAL 코드 샘플
• Java용 Azure Active Directory Spring Boot Starter 클라이언트 라이브러리
• Java용 Microsoft 인증 라이브러리(MSAL4J)
• MSAL4J Wiki
• ID 토큰
• Microsoft ID 플랫폼의 액세스 토큰

이 시나리오 및 기타 시나리오에서 OAuth 2.0 프로토콜이 작동하는 방식에 대한 자세한 내용은 Microsoft Entra ID에 대한 인증 시나리오를 참조하세요.