역할 및 역할 클레임을 사용하여 Java Spring Boot 앱 보호

이 문서에서는 인증, 권한 부여 및 토큰 획득을 위해 Java용 Microsoft Entra ID Spring Boot Starter 클라이언트 라이브러리를 사용하는 Java Spring Boot 웹앱을 보여 줍니다. 앱은 OpenID Connect 프로토콜을 사용하여 사용자를 로그인하고 권한 부여를 위해 Microsoft Entra ID 애플리케이션 역할(앱 역할)을 사용하여 일부 경로에 대한 액세스를 제한합니다.

앱 역할은 보안 그룹과 함께 권한 부여를 구현하는 인기 있는 수단입니다. 애플리케이션 역할 및 역할 클레임과 함께 RBAC(역할 기반 액세스 제어)를 사용하면 최소한의 노력으로 권한 부여 정책을 안전하게 적용할 수 있습니다. 또 다른 방법은 Microsoft Entra ID 그룹 및 그룹 클레임을 사용하는 것입니다. Microsoft Entra ID 그룹 및 애플리케이션 역할은 상호 배타적이지 않습니다. 둘 다 사용하여 세분화된 액세스 제어를 제공할 수 있습니다.

유사한 시나리오를 다루는 비디오는 앱 역할, 보안 그룹, 범위 및 디렉터리 역할을 사용하여 애플리케이션에서 권한 부여 구현을 참조하세요.

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

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

앱은 Java용 Microsoft Entra ID Spring Boot Starter 클라이언트 라이브러리를 사용하여 사용자를 로그인하고 Microsoft Entra ID에서 ID 토큰을 가져옵니다. ID 토큰에는 역할 클레임이 포함됩니다. 애플리케이션은 이 클레임의 값을 검사하여 사용자에게 액세스 권한이 부여된 페이지를 결정합니다.

이러한 종류의 권한 부여는 RBAC를 사용하여 구현됩니다. RBAC를 사용하면 관리자는 개별 사용자 또는 그룹이 아닌 역할에 대한 권한을 부여합니다. 그런 다음 관리자는 다른 사용자 및 그룹에 역할을 할당하여 특정 콘텐츠 및 기능에 대한 액세스 권한이 있는 사용자를 제어할 수 있습니다.

이 샘플 애플리케이션은 다음 두 애플리케이션 역할을 정의합니다.

• PrivilegedAdmin: 관리자 전용 및 일반 사용자 페이지에 액세스할 수 있는 권한이 부여되었습니다.
• RegularUser: 일반 사용자 페이지에 액세스할 수 있는 권한이 부여되었습니다.

이러한 애플리케이션 역할은 애플리케이션의 등록 매니페스트의 Azure Portal에서 정의됩니다. 사용자가 애플리케이션에 로그인하면 Microsoft Entra ID는 역할 멤버 자격의 형태로 사용자에게 개별적으로 부여된 각 역할에 대한 역할 클레임을 내보낸다.

Azure Portal을 통해 역할에 사용자 및 그룹을 할당할 수 있습니다.

필수 조건

• 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/3-Authorization-II/roles

또는 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-roles)

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

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

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

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

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

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

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

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

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

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

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

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

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

앱 역할 정의

앱 역할을 정의하려면 다음 단계를 사용합니다.

1. 동일한 앱 등록에서 탐색 창에서 앱 역할을 선택합니다.

2. 앱 역할 만들기를 선택한 다음, 다음 값을 입력합니다.

   • 표시 이름에 적합한 이름(예: PrivilegedAdmin)을 입력합니다.
   • 허용되는 멤버 형식의 경우 사용자를 선택합니다.
   • 값에 대해 PrivilegedAdmin을 입력합니다.
   • 설명을 보려면 관리자 페이지를 볼 수 있는 PrivilegedAdmins를 입력합니다.

3. 앱 역할 만들기를 선택한 다음, 다음 값을 입력합니다.

   • 표시 이름에 적합한 이름(예: RegularUser)을 입력합니다.
   • 허용되는 멤버 형식의 경우 사용자를 선택합니다.
   • 값에 RegularUser를 입력합니다.
   • 설명을 보려면 사용자 페이지를 볼 수 있는 RegularUsers를 입력합니다.

4. 적용을 선택하여 변경 내용을 저장합니다.

앱 역할에 사용자 할당

앞에서 정의한 앱 역할에 사용자를 추가하려면 다음 지침을 따릅니다. 역할에 사용자 및 그룹 할당.

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

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

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-roles 바꿉니다.

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

6. src/main/java/com/microsoft/azuresamples/msal4j/msidentityspringbootapplication/Sample.Controller.java 파일을 엽니다.

7. 이 파일에서 앱 역할에 대한 참조 PrivilegedAdmin RegularUser 를 찾습니다. 필요한 경우 이전 단계에서 선택한 앱 역할 이름을 반영하도록 변경합니다.

샘플 실행

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. 관리자만 선택하여 을 봅니다/admin_only. 앱 역할이 PrivilegedAdmin 있는 사용자만 이 페이지를 볼 수 있습니다. 그렇지 않으면 권한 부여 실패 메시지가 표시됩니다.
9. 일반 사용자를 선택하여 페이지를 봅니다/regular_user. 앱 역할을 RegularUser 가진 사용자만 또는 PrivilegedAdmin 이 페이지를 볼 수 있습니다. 그렇지 않으면 권한 부여 실패 메시지가 표시됩니다.
10. 모서리의 단추를 사용하여 로그아웃합니다. 상태 페이지에 새 상태가 반영됩니다.

코드 정보

이 샘플에서는 Java용 Microsoft Entra ID Spring Boot Starter 클라이언트 라이브러리를 사용하여 사용자를 Microsoft Entra ID 테넌트에 로그인하는 방법을 보여 줍니다. 또한 샘플에서는 Spring Oauth2 클라이언트 및 Spring Web 부팅 스타터를 사용합니다. 샘플에서는 Microsoft Entra ID에서 가져온 ID 토큰의 클레임을 사용하여 로그인한 사용자의 세부 정보를 표시하고 권한 부여를 위해 역할 클레임을 사용하여 일부 페이지에 대한 액세스를 제한합니다.

콘텐츠

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

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

ID 토큰에서 역할 클레임 처리

토큰의 역할 클레임에는 다음 예제와 같이 로그인한 사용자가 할당한 역할의 이름이 포함됩니다.

{
  ...
  "roles": [
    "PrivilegedAdmin",
    "RegularUser",]
  ...
}

역할 이름에 액세스하는 일반적인 방법은 ID 토큰 클레임 섹션에 설명되어 있습니다.

또한 Microsoft Entra ID Boot Starter v3.3 이상에서는 역할 클레임을 자동으로 구문 분석하고 로그인한 사용자의 Authorities역할에 각 역할을 추가하여 각각 문자열 APPROLE_을 접두사로 추가합니다. 이 구성을 통해 개발자는 이 메서드를 사용하여 hasAuthority Spring PrePost 조건 주석으로 앱 역할을 사용할 수 있습니다. 예를 들어 SampleController.java 다음과 같은 @PreAuthorize 조건을 확인할 수 있습니다.

@GetMapping(path = "/admin_only")
@PreAuthorize("hasAuthority('APPROLE_PrivilegedAdmin')")
public String adminOnly(Model model) {
    // restrict to users who have PrivilegedAdmin app role only
}
@GetMapping(path = "/regular_user")
@PreAuthorize("hasAnyAuthority('APPROLE_PrivilegedAdmin','APPROLE_RegularUser')")
public String regularUser(Model model) {
    // restrict to users who have any of RegularUser or PrivilegedAdmin app roles
}

다음 코드는 지정된 사용자에 대한 권한의 전체 목록을 가져옵니다.

@GetMapping(path = "/some_path")
public String tokenDetails(@AuthenticationPrincipal OidcUser principal) {
   Collection<? extends GrantedAuthority> authorities = principal.getAuthorities();
}

로그인 및 로그아웃 링크

로그인의 경우 앱은 다음 예제와 같이 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, /admin_only, /regular_user)
      .antMatchers("/**").permitAll();                  // allow all other routes.
    }
}

자세한 정보

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

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