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

이 문서에서는 사용자가 로그인할 때 OpenID Connect를 사용하고 권한 부여에 Microsoft Entra ID 애플리케이션 역할(앱 역할)을 사용하는 Java WebSphere 앱을 보여 줍니다.

이 애플리케이션은 Microsoft Entra ID의 애플리케이션 역할 및 역할 클레임 기능을 사용하여 RBAC(역할 기반 액세스 제어)를 구현합니다. 또 다른 방법은 Microsoft Entra ID 그룹 및 그룹 클레임을 사용하는 것입니다. Microsoft Entra ID 그룹 및 애플리케이션 역할은 상호 배타적이지 않습니다. 둘 다 사용하여 세분화된 액세스 제어를 제공할 수 있습니다.

애플리케이션 역할 및 역할 클레임과 함께 RBAC를 사용하여 권한 부여 정책을 안전하게 적용할 수도 있습니다.

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

이 시나리오와 다른 시나리오에서 프로토콜이 어떻게 작동하는지에 대한 자세한 내용은 인증과 권한 부여를 참조하세요.

이 애플리케이션은 사용자가 로그인하고 Microsoft Entra ID에서 ID 토큰을 가져오도록 Java용 MSAL(MSAL4J)을 사용합니다.

이 샘플에서는 먼저 MSAL4J(Java용 MSAL)를 사용하여 사용자를 로그인합니다. 홈페이지에는 사용자가 ID 토큰에서 클레임을 볼 수 있는 옵션이 표시됩니다. 또한 이 애플리케이션을 통해 사용자는 할당된 앱 역할에 따라 권한 있는 관리자 페이지 또는 일반 사용자 페이지를 볼 수 있습니다. 이 아이디어는 애플리케이션 내에서 특정 기능 또는 페이지에 대한 액세스가 속한 역할에 따라 사용자의 하위 집합으로 제한되는 방법의 예를 제공하는 것입니다.

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

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

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

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

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

참고

테넌트의 게스트 사용자에게는 엔드포인트를 사용자의 로그인 권한 엔드포인트로 사용하는 경우 역할 클레임이 포함되지 않습니다. 와 같은 테넌트 엔드포인트에 사용자를 로그인해야 합니다.

필수 조건

JDK 버전 8 이상
Maven 3
Microsoft Entra ID 테넌트. 자세한 내용은 Microsoft Entra ID 테넌트를 가져오는 방법을 참조하세요.
조직 디렉터리의 계정만 대상으로 작업하려는 경우, 즉 단일 테넌트 모드인 경우 자신의 Microsoft Entra ID 테넌트에 있는 사용자 계정 테넌트에서 사용자 계정을 아직 만들지 않은 경우 계속하기 전에 만들어야 합니다. 자세한 내용은 사용자를 만들고, 초대하고, 삭제하는 방법을 참조하세요.

WebSphere
Visual Studio Code
Visual Studio Code용 Azure 도구

권장 사항

Java / Jakarta Servlets에 대한 기본적인 이해.
Linux/OSX 터미널에 대해 잘 알고 있습니다.
토큰을 검사하기 위한 jwt.ms
네트워크 활동을 모니터링하고 문제를 해결하기 위한 Fiddler
최신 개발 소식을 확인하려면 Microsoft Entra 블로그를 팔로우하세요.

샘플 설정

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

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

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

git clone https://github.com/Azure-Samples/ms-identity-msal-java-samples.git
cd 3-java-servlet-web-app/3-Authorization-II/roles

또는 ms-identity-msal-java-samples 리포지토리로 이동한 다음, 이를 .zip 파일로 다운로드하여 하드 드라이브에 압축을 풉니다.

중요

Windows에서 파일 경로 길이 제한을 방지하려면 리포지토리를 하드 드라이브 루트 근처의 디렉터리에 복제하거나 추출합니다.

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

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

애플리케이션을 만들려는 Microsoft Entra ID 테넌트를 선택합니다.

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

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

앱 등록(java-servlet-webapp-roles)

먼저 빠른 시작: Microsoft ID 플랫폼에 애플리케이션 등록의 지침에 따라 Azure 포털에서 새 앱을 등록합니다.

그런 다음, 다음 단계를 사용하여 등록을 완료합니다.

개발자용 Microsoft ID 플랫폼 앱 등록 페이지로 이동합니다.
새 등록을 선택합니다.
표시되는 애플리케이션 등록 페이지에서 다음 앱 등록 정보를 입력합니다.
- Name 섹션에서 앱 사용자에게 표시될 의미 있는 애플리케이션 이름(예: )을 입력합니다.
- 지원되는 계정 유형에서 다음 옵션 중 하나를 선택합니다.
  - 테넌트의 사용자(즉, 단일 테넌트 애플리케이션)에서만 사용할 애플리케이션을 빌드하는 경우에만 이 조직 디렉터리에서 계정을 선택합니다.
- 리디렉션 URI 섹션의 콤보 상자에서 Web을 선택하고 다음 리디렉션 URI를 입력합니다: .
등록을 선택하여 애플리케이션을 만듭니다.
앱의 등록 페이지에서 나중에 사용할 애플리케이션(클라이언트) ID 값을 찾아 복사합니다. 앱의 구성 파일 또는 파일에서 이 값을 사용합니다.
저장을 선택하여 변경 내용을 저장합니다.
앱의 등록 페이지에서 탐색 창에서 인증서 및 비밀을 선택하여 비밀을 생성하고 인증서를 업로드할 수 있는 페이지를 엽니다.
클라이언트 비밀 섹션에서 새 클라이언트 비밀을 선택합니다.
설명(예: 앱 비밀)을 입력합니다.
암호에 대해 만료를 선택하거나 사용자 지정 수명을 지정합니다. 클라이언트 비밀은 최대 수명 24개월로 제한되며, Microsoft 12개월 미만의 만료를 권장합니다. 프로덕션 앱의 경우 클라이언트 암호보다 인증서 또는 페더레이션 ID 자격 증명을 선호합니다.
추가를 선택합니다. 생성된 값이 표시됩니다.
이후 단계에서 사용할 생성된 값을 복사하고 저장합니다. 코드의 구성 파일에 이 값이 필요합니다. 이 값은 다시 표시되지 않으며 다른 어떤 수단으로도 검색할 수 없습니다. 따라서 다른 화면 또는 창으로 이동하기 전에 Azure Portal에서 저장해야 합니다.

애플리케이션 역할 정의

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

같은 앱 등록에서 계속하여 탐색 창에서 App roles를 선택합니다.
앱 역할 만들기를 선택한 다음, 다음 값을 입력합니다.
- 표시 이름에 적합한 이름(예: PrivilegedAdmin)을 입력합니다.
- 허용되는 멤버 형식의 경우 사용자를 선택합니다.
- Value의 경우 PrivilegedAdmin을 입력하세요.
- Description에는 Admin Page를 볼 수 있는 PrivilegedAdmins를 입력합니다.
앱 역할 만들기를 선택한 다음, 다음 값을 입력합니다.
- 표시 이름에 적합한 이름(예: RegularUser)을 입력합니다.
- 허용되는 멤버 형식의 경우 사용자를 선택합니다.
- Value에 RegularUser를 입력합니다.
- Description에는 사용자 페이지를 볼 수 있는 RegularUsers를 입력합니다.
적용을 선택하여 변경 내용을 저장합니다.

애플리케이션 역할에 사용자 할당

앞에서 정의한 앱 역할에 사용자를 추가하려면 여기에 있는 지침을 따르세요: 역할에 사용자 및 그룹 할당

앱(java-servlet-webapp-roles)이 앱 등록을 사용하도록 설정합니다.

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

참고

다음 단계에서 는 또는 와 같습니다.

IDE에서 프로젝트를 엽니다.
authentication.properties 파일을 엽니다.
문자열 을 찾으세요. 기존 값을 Microsoft Entra ID 테넌트 ID로 바꿉니다.
문자열 을(를) 찾아 기존 값을 Azure Portal에서 복사한 애플리케이션의 애플리케이션 ID 또는 값으로 바꿉니다.
문자열 을(를) 찾아 Azure Portal에서 앱을 만들 때 저장한 값으로 기존 값을 바꾸세요.
속성을 찾아 값이 로 설정되어 있는지 확인하거나, 해당 이름을 사용자의 특정 역할 이름으로 바꾸세요.

샘플 빌드

Maven을 사용하여 샘플을 빌드하려면 샘플에 대한 pom.xml 파일이 포함된 디렉터리로 이동한 다음 다음 명령을 실행합니다.

mvn clean package

이 명령은 다양한 애플리케이션 서버에서 실행할 수 있는 .war 파일을 생성합니다.

샘플 실행

이러한 지침에서는 WebSphere를 설치하고 서버를 설정했다고 가정합니다. 기본 서버 설정의 경우 Azure Virtual Machines에서 WebSphere Application Server(기존) 클러스터 배포의 지침을 참조할 수 있습니다.

WebSphere에 배포하기 전에 다음 단계를 사용하여 샘플 자체에서 몇 가지 구성을 변경한 다음 패키지를 빌드하거나 다시 빌드합니다.

다음 예와 같이 앱의 authentication.properties 파일로 이동한 다음, 의 값을 사용하려는 서버 URL과 포트 번호로 변경합니다.

# app.homePage is by default set to dev server address and app context path on the server
# for apps deployed to azure, use https://your-sub-domain.azurewebsites.net
app.homePage=https://<server-url>:<port-number>/msal4j-servlet-auth/

이 파일을 저장한 후 다음 명령을 사용하여 앱을 다시 빌드합니다.
```
mvn clean package
```
코드 빌드가 완료되면 .war 파일을 대상 서버의 파일 시스템에 복사합니다.

또한 Azure 앱 등록에서도 동일한 변경 사항을 적용해야 하며, 이 값은 Azure 포털의 Authentication 탭에서 Redirect URI 값으로 설정합니다.

개발자용 Microsoft ID 플랫폼 앱 등록 페이지로 이동합니다.
검색 상자를 사용하여 앱 등록을 검색하세요. 예를 들어, 입니다.
이름을 선택하여 앱 등록을 엽니다.
메뉴에서 인증을 선택합니다.
Web리디렉션 URI 섹션에서 URI 추가를 선택합니다.
앱의 URI를 입력하고 /auth/redirect를 뒤에 붙이세요. 예:
저장을 선택합니다.

다음 단계를 사용하여 WebSphere의 통합 솔루션 콘솔을 사용하여 샘플을 배포합니다.

애플리케이션 탭에서 새 애플리케이션, 새 엔터프라이즈 애플리케이션을 선택합니다.
빌드한 .war 파일을 선택한 다음 웹 모듈 설치 단계의 맵 컨텍스트 루트에 도착할 때까지 다음을 선택합니다. 다른 기본 설정은 괜찮을 것입니다.
컨텍스트 루트의 경우 샘플 구성/Azure 앱 등록에서 설정한 '리디렉션 URI'의 포트 번호 뒤와 동일한 값으로 설정합니다. 즉, 리디렉션 URI가 이면 컨텍스트 루트는 여야 합니다.
마침을 선택합니다.
애플리케이션 설치가 완료되면 애플리케이션 탭의 WebSphere 엔터프라이즈 애플리케이션 섹션으로 이동합니다.
애플리케이션 목록에서 설치한 .war 파일을 선택한 다음 배포 시작을 선택합니다.
배포가 완료되면 로 이동하면 애플리케이션을 확인할 수 있습니다.

샘플 탐색

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

화면 중앙에 로그인 또는 로그아웃 상태가 표시됩니다.
모서리에서 상황에 맞는 단추를 선택합니다. 이 버튼은 앱을 처음 실행하면 로그인이라고 표시됩니다.
다음 페이지에서 지침을 따르고 Microsoft Entra ID 테넌트에 있는 계정으로 로그인합니다.
동의 화면에서 요청되는 범위를 확인합니다.
이제 상황별 버튼에 로그아웃이라고 표시되고 사용자 이름도 표시되는 것을 확인하세요.
ID 토큰 세부 정보를 선택하여 ID 토큰의 디코딩된 클레임 중 일부를 확인합니다.
Admins Only을 선택하여 페이지를 보려면. 앱 역할이 인 사용자만 이 페이지를 볼 수 있습니다. 그렇지 않으면 권한 부여 실패 메시지가 표시됩니다.
Regular Users를 선택하여 페이지를 확인합니다. 앱 역할이 또는 인 사용자만 이 페이지를 볼 수 있습니다. 그렇지 않으면 권한 부여 실패 메시지가 표시됩니다.
모서리의 단추를 사용하여 로그아웃합니다.

코드 정보

이 샘플에서는 MSAL4J(Java용 MSAL)를 사용하여 사용자를 로그인하고 역할 클레임을 포함할 수 있는 ID 토큰을 가져옵니다. 현재 포함된 역할 클레임에 따라 로그인한 사용자는 보호된 페이지인 및 에 액세스하지 못할 수도 있고, 둘 중 하나에만 액세스할 수도 있으며, 둘 다에 액세스할 수도 있습니다.

이 샘플의 동작을 복제하려면 src/main/java/com/microsoft/azuresamples/msal4j 폴더에서 pom.xml 파일과 도우미 및 authservlets 폴더의 내용을 복사할 수 있습니다. authentication.properties 파일도 필요합니다. 이러한 클래스 및 파일에는 다양한 애플리케이션에서 사용할 수 있는 제네릭 코드가 포함되어 있습니다. 샘플의 나머지 부분도 복사할 수 있지만 다른 클래스와 파일은 이 샘플의 목표를 해결하기 위해 특별히 빌드됩니다.

파일/폴더	설명
src/main/java/com/microsoft/azuresamples/msal4j/roles/	이 디렉터리에는 앱의 백 엔드 비즈니스 논리를 정의하는 클래스가 포함되어 있습니다.
src/main/java/com/microsoft/azuresamples/msal4j/authservlets/	이 디렉터리에는 로그인 및 로그아웃 엔드포인트에 사용되는 클래스가 포함되어 있습니다.
*Servlet.java	사용 가능한 모든 엔드포인트는 이름이 `Servlet`끝나는 Java 클래스에 정의됩니다.
src/main/java/com/microsoft/azuresamples/msal4j/helpers/	인증을 위한 도우미 클래스입니다.
AuthenticationFilter.java	인증되지 않은 요청을 보호된 엔드포인트로 401 페이지로 리디렉션합니다.
src/main/resources/authentication.properties	Microsoft Entra ID 및 프로그램 구성.
src/main/webapp/	이 디렉터리에는 UI - JSP 템플릿이 포함되어 있습니다.
CHANGELOG.md	샘플의 변경 내용 목록입니다.
CONTRIBUTING.md	샘플에 기여하기 위한 지침입니다.
라이선스	샘플에 대한 라이선스입니다.

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

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

{
  ...
  "roles": [
    "Role1",
    "Role2",]
  ...
}

ConfidentialClientApplication

다음 예제와 같이 AuthHelper.java 파일에서 인스턴스가 생성됩니다. 이 개체는 Microsoft Entra 권한 부여 URL을 만드는 데 도움이 되며 액세스 토큰에 대한 인증 토큰을 교환하는 데도 도움이 됩니다.

// getConfidentialClientInstance method
IClientSecret secret = ClientCredentialFactory.createFromSecret(SECRET);
confClientInstance = ConfidentialClientApplication
                     .builder(CLIENT_ID, secret)
                     .authority(AUTHORITY)
                     .build();

인스턴스화에는 다음 매개 변수가 사용됩니다.

앱의 클라이언트 ID입니다.
기밀 클라이언트 애플리케이션에 대한 요구 사항인 클라이언트 암호입니다.
Microsoft Entra 테넌트 ID를 포함하는 Microsoft Entra ID 기관입니다.

이 샘플에서는 Config.java 파일의 속성 리더를 사용하여 authentication.properties 파일에서 이러한 값들을 읽습니다.

단계별 안내

다음 단계에서는 앱의 기능을 단계별로 안내합니다:

로그인 프로세스의 첫 번째 단계는 Microsoft Entra ID 테넌트의 엔드포인트로 요청을 보내는 것입니다. MSAL4J 인스턴스는 권한 부여 요청 URL을 생성하는 데 사용됩니다. 앱은 사용자가 로그인하는 이 URL로 브라우저를 리디렉션합니다.
```
final ConfidentialClientApplication client = getConfidentialClientInstance();
AuthorizationRequestUrlParameters parameters = AuthorizationRequestUrlParameters.builder(Config.REDIRECT_URI, Collections.singleton(Config.SCOPES))
        .responseMode(ResponseMode.QUERY).prompt(Prompt.SELECT_ACCOUNT).state(state).nonce(nonce).build();

final String authorizeUrl = client.getAuthorizationRequestUrl(parameters).toString();
contextAdapter.redirectUser(authorizeUrl);
```
다음 목록에서는 이 코드의 기능을 설명합니다.
- : AuthorizationRequestUrl을 생성하기 위해 반드시 설정해야 하는 매개변수입니다.
- : Microsoft Entra ID가 사용자 자격 증명을 수집한 후 인가 코드와 함께 브라우저를 리디렉션하는 위치입니다. Azure portal의 Microsoft Entra ID 앱 등록에 있는 리디렉션 URI와 일치해야 합니다.
- : Scopes는 애플리케이션이 요청하는 권한입니다.
  - 일반적으로 세 가지 스코프 만으로도 ID 토큰 응답을 받는 데 충분합니다.
  - 앱에서 요청한 전체 범위 목록은 authentication.properties 파일에서 찾을 수 있습니다. 와 같은 더 많은 범위를 추가할 수 있습니다.
사용자에게 Microsoft Entra ID의 로그인 프롬프트가 표시됩니다. 로그인 시도가 성공하면 사용자의 브라우저가 앱의 리디렉션 엔드포인트로 리디렉션됩니다. 이 엔드포인트에 대한 유효한 요청에는 권한 부여 코드가 포함됩니다.
그런 다음 인스턴스는 이 권한 부여 코드를 Microsoft Entra ID로부터 ID 토큰과 액세스 토큰을 받기 위해 교환합니다.
```
// First, validate the state, then parse any error codes in response, then extract the authCode. Then:
// build the auth code params:
final AuthorizationCodeParameters authParams = AuthorizationCodeParameters
        .builder(authCode, new URI(Config.REDIRECT_URI)).scopes(Collections.singleton(Config.SCOPES)).build();

// Get a client instance and leverage it to acquire the token:
final ConfidentialClientApplication client = AuthHelper.getConfidentialClientInstance();
final IAuthenticationResult result = client.acquireToken(authParams).get();
```
다음 목록에서는 이 코드의 기능을 설명합니다.
- : ID 토큰 및/또는 액세스 토큰을 받기 위해 Authorization Code와 교환할 때 반드시 설정해야 하는 매개변수입니다.
- : 리디렉션 엔드포인트에서 수신된 권한 부여 코드입니다.
- : 이전 단계에서 사용한 리디렉션 URI가 다시 전달되어야 합니다.
- : 이전 단계에서 사용한 스코프를 다시 전달해야 합니다.

이(가) 성공하면 토큰 클레임이 추출됩니다. nonce 검사를 통과하면 결과는 의 인스턴스인 에 저장된 후 세션에 저장됩니다. 그런 다음 애플리케이션은 아래 코드와 같이, 이에 액세스해야 할 때마다 의 인스턴스를 통해 세션에서 를 인스턴스화할 수 있습니다.

// parse IdToken claims from the IAuthenticationResult:
// (the next step - validateNonce - requires parsed claims)
context.setIdTokenClaims(result.idToken());

// if nonce is invalid, stop immediately! this could be a token replay!
// if validation fails, throws exception and cancels auth:
validateNonce(context);

// set user to authenticated:
context.setAuthResult(result, client.tokenCache().serialize());

경로 보호

샘플 앱이 경로에 대한 액세스를 필터링하는 방법에 대한 자세한 내용은 AuthenticationFilter.java 참조하세요. authentication.properties 파일에서 속성에는 다음 예와 같이 인증된 사용자만 액세스할 수 있는 쉼표로 구분된 경로가 포함되어 있습니다.

# for example, /token_details requires any user to be signed in and does not require special roles claim(s)
app.protect.authenticated=/token_details

다음 예와 같이 아래의 쉼표로 구분된 규칙 집합에 나열된 모든 경로는 인증되지 않은 사용자가 접근할 수 없습니다. 그러나 이러한 경로에는 공백으로 구분된 앱 역할 멤버 자격 목록이 포함되어 있습니다. 해당 역할 중 하나 이상을 가진 사용자만 인증 후 이러한 경로에 액세스할 수 있습니다.

# local short names for app roles - for example, sets admin to mean PrivilegedAdmin (useful for long rule sets defined in the next key, app.protect.roles)
app.roles=admin PrivilegedAdmin, user RegularUser

# A route and its corresponding <space-separated> role(s) that can access it; the start of the next route & its role(s) is delimited by a <comma-and-space-separator>
# this says: /admins_only can be accessed by PrivilegedAdmin, /regular_user can be accessed by PrivilegedAdmin role and the RegularUser role
app.protect.roles=/admin_only admin, /regular_user admin user

범위

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

요청된 범위에 따라 Microsoft Entra ID는 로그인 시 사용자에게 동의 대화 상자를 제공합니다. 사용자가 하나 이상의 스코프에 동의하고 토큰을 얻으면, 동의한 스코프가 결과 에 인코딩됩니다.

애플리케이션에서 요청한 범위는 authentication.properties를 참조하세요. 이러한 세 가지 범위는 MSAL에서 요청되며 기본적으로 Microsoft Entra ID에 의해 제공됩니다.

자세한 정보

Java용 Microsoft 인증 라이브러리(MSAL)
Microsoft ID 플랫폼
빠른 시작: Microsoft ID 플랫폼에 애플리케이션 등록
Microsoft Entra ID 애플리케이션 동의 환경 이해
사용자 및 관리자 동의 이해
MSAL 코드 예제
방법: 애플리케이션에 앱 역할을 추가하고 토큰에서 이를 받는 방법
Microsoft Entra ID에서 앱에 대한 사용자 할당 관리

다음 단계

Azure Virtual Machines의 Traditional WebSphere에 Java WebSphere 애플리케이션 배포

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-09-17