OpenID Connect를 사용하여 Microsoft Entra ID로 Quarkus 애플리케이션 보호

아티클
08/01/2024

이 문서에서는 OIDC(OpenID Connect)를 사용하여 Microsoft Entra ID로 Red Hat Quarkus 애플리케이션을 보호하는 방법을 보여 줍니다.

이 문서에서는 다음 방법을 설명합니다.

Microsoft Entra ID를 사용하여 OpenID Connect 공급자를 설정합니다.
OpenID Connect를 사용하여 Quarkus 앱을 보호합니다.
Quarkus 앱을 실행하고 테스트합니다.

필수 구성 요소

Azure 구독 Azure 구독이 아직 없는 경우 시작하기 전에 체험 계정을 만듭니다.
적어도 클라우드 애플리케이션 관리자 역할이 있는 Azure ID입니다. 자세한 내용은 Microsoft Entra 역할 할당 및 Microsoft Entra 기본 제공 역할 목록을 참조하세요.
Microsoft Entra 테넌트. 기존 테넌트가 없는 경우 빠른 시작: 테넌트 설정을 참조하세요.
Unix와 유사한 운영 체제가 설치된 로컬 컴퓨터(예: Ubuntu, macOS 또는 Linux용 Windows 하위 시스템).
Git
Java SE 구현 버전 21 이상(예: OpenJDK의 Microsoft 빌드).
Maven, 버전 3.9.3 이상.

Microsoft Entra ID를 사용하여 OpenID Connect 공급자 설정

이 섹션에서는 Quarkus 앱에 사용할 Microsoft Entra ID를 사용하여 OpenID Connect 공급자를 설정합니다. 이후 섹션에서는 OpenID Connect를 사용하여 Microsoft Entra 테넌트에서 사용자를 인증하고 권한을 부여하여 Quarkus 앱을 구성합니다.

Microsoft Entra 테넌트에서 사용자 만들기

먼저 사용자를 만들고 초대하고 삭제하는 방법의 단계에 따라 Microsoft Entra 테넌트에서 두 명의 사용자를 만듭니다. 새 사용자 만들기 섹션만 있으면 됩니다. 문서를 진행할 때 다음 지침을 사용한 다음, Microsoft Entra 테넌트에서 사용자를 만든 후 이 문서로 돌아갑니다.

앱에서 "관리자"로 사용할 사용자를 만들려면 다음 단계를 사용합니다.

새 사용자 만들기 섹션의 기본 사항 탭에 도달하면 다음 단계를 사용합니다.
1. 사용자 계정 이름으로 관리자를 입력합니다. 나중에 Quarkus 앱에 로그인할 때 사용할 수 있도록 값을 저장합니다.
2. 메일 애칭의 경우 사용자 계정 이름에서 파생을 선택합니다.
3. 표시 이름에 관리자를 입력합니다.
4. 암호의 경우 암호 자동 생성을 선택합니다. 나중에 Quarkus 앱에 로그인할 때 사용할 암호 값을 복사하고 저장합니다.
5. 사용하도록 설정된 계정을 선택합니다.
6. 검토 + 만들기>만들기를 차례로 선택합니다. 사용자가 생성될 때까지 기다립니다.
7. 1분 정도 기다렸다가 새로 고침을 선택합니다. 목록에 새 사용자가 표시됩니다.

앱에서 "사용자"로 사용할 사용자를 만들려면 다음 단계를 반복하지만 다음 값을 사용합니다.

사용자 계정 이름으로 사용자를 입력합니다.
표시 이름에 대해 사용자를 입력합니다.

Microsoft Entra ID에 애플리케이션 등록

다음으로, 빠른 시작의 단계에 따라 애플리케이션을 등록합니다. Microsoft ID 플랫폼 애플리케이션을 등록합니다. 문서를 진행할 때 다음 지침을 사용한 다음, 애플리케이션을 등록하고 구성한 후 이 문서로 돌아갑니다.

애플리케이션 등록 섹션에 도달하면 다음 단계를 사용합니다.
1. 지원되는 계정 유형의 경우 이 조직 디렉터리에서만 계정을 선택합니다(기본 디렉터리만 - 단일 테넌트).
2. 등록이 완료되면 나중에 Quarkus 앱 구성에서 사용할 애플리케이션(클라이언트) ID 및 디렉터리(테넌트) ID 값을 저장합니다.
리디렉션 URI 추가 섹션에 도달하면 다음 단계를 사용합니다.
1. 플랫폼 구성의 경우 웹을 선택합니다.
2. 리디렉션 URI에 http://localhost:8080를 입력합니다.
자격 증명 추가 섹션에 도달하면 클라이언트 비밀 추가 탭을 선택합니다.
클라이언트 암호를 추가할 때 나중에 Quarkus 앱 구성에서 사용할 클라이언트 비밀 값을 적어 씁니다.

애플리케이션에 앱 역할 추가

그런 다음 애플리케이션에 앱 역할 추가의 단계에 따라 애플리케이션에 앱 역할을 추가하고 토큰에서 받습니다. 애플리케이션에 대한 역할 선언 및 Microsoft Entra 역할에 사용자 및 그룹 할당 섹션만 있으면 됩니다. 문서를 진행할 때 다음 지침을 사용한 다음, 애플리케이션에 대한 역할을 선언한 후 이 문서로 돌아갑니다.

애플리케이션에 대한 역할 선언 섹션에 도달하면 앱 역할 UI를 사용하여 관리자와 일반 사용자에 대한 역할을 만듭니다.
1. 다음 값을 사용하여 관리자 사용자 역할을 만듭니다.
  - 표시 이름에 관리자를 입력합니다.
  - 허용되는 멤버 유형에 대해 사용자/그룹을 선택합니다.
  - 값에 admin을 입력합니다.
  - 설명을 보려면 관리자를 입력합니다.
  - 이 앱 역할을 사용하도록 설정하시겠습니까?를 선택합니다.
2. 적용을 선택합니다. 역할이 생성될 때까지 기다립니다.
3. 동일한 단계를 사용하지만 다음 값을 사용하여 일반 사용자 역할을 만듭니다.
  - 표시 이름에 대해 사용자를 입력합니다.
  - 값의 경우 사용자를 입력합니다.
  - 설명을 위해 사용자를 입력합니다.
Microsoft Entra 역할에 사용자 및 그룹 할당에 도달하면 다음 단계를 사용합니다.
1. 사용자/그룹 추가를 선택합니다.
2. 할당 추가 창에서 사용자에 대해 사용자 관리자를 선택하고 역할을 선택하려면 역할 관리자를 선택합니다. 그런 다음 할당을 선택합니다. 애플리케이션 할당이 성공할 때까지 기다립니다. 역할 할당 열을 보려면 테이블을 옆으로 스크롤해야 할 수 있습니다.
3. 이전 단계를 반복하여 사용자 사용자에게 사용자 역할을 할당합니다.
4. 새로 고침을 선택하면 사용자 및 그룹 창에 할당된 사용자 및 역할이 표시됩니다.
  
  보기가 이미지처럼 보이도록 열 머리글의 너비를 조정해야 할 수 있습니다.

애플리케이션에 앱 역할 추가의 다른 단계를 수행하고 토큰에서 수신하지 마세요.

OpenID Connect를 사용하여 Quarkus 앱 보호

이 섹션에서는 OpenID Connect를 사용하여 Microsoft Entra 테넌트에서 사용자를 인증하고 권한을 부여하는 Quarkus 앱을 보호합니다. 또한 RBAC(역할 기반 액세스 제어)를 사용하여 사용자에게 앱의 특정 부분에 대한 액세스 권한을 부여하는 방법을 알아봅니다.

이 빠른 시작에 대한 샘플 Quarkus 앱은 쿼쿠스-azure 리포지토리의 GitHub에 있으며 entra-id-quarkus 디렉터리에 있습니다.

인증 및 권한 부여를 사용하여 앱 보호

앱에는 다음 예제 코드에 표시된 WelcomePage.java 정의된 시작 페이지 리소스가 있습니다. 이 페이지는 인증되지 않은 사용자가 액세스할 수 있습니다. 시작 페이지의 루트 경로는 .에 있습니다 /.

@Path("/")
public class WelcomePage {

    private final Template welcome;

    public WelcomePage(Template welcome) {
        this.welcome = requireNonNull(welcome, "welcome page is required");
    }

    @GET
    @Produces(MediaType.TEXT_HTML)
    public TemplateInstance get() {
        return welcome.instance();
    }

}

시작 페이지에서 사용자는 앱에 로그인하여 프로필 페이지에 액세스할 수 있습니다. 시작 페이지에는 사용자 또는 관리자로 로그인할 수 있는 링크가 있습니다. 링크는 각각에 /profile/user 있습니다 /profile/admin. 시작 페이지 UI는 welcome.qute.html 정의되며 다음 예제에 나와 있습니다.

<html>
    <head>
        <meta charset="UTF-8">
        <title>Greeting</title>
    </head>
    <body>
        <h1>Hello, welcome to Quarkus and Microsoft Entra ID integration!</h1>
        <h1>
            <a href="/profile/user">Sign in as user</a>
        </h1>
        <h1>
            <a href="/profile/admin">Sign in as admin</a>
        </h1>
    </body>
</html>

링크와 /profile/admin 링크는 /profile/user 다음 예제 코드와 같이 ProfilePage.java 정의된 프로필 페이지 리소스를 가리킵니다. 이 페이지는 패키지의 @RolesAllowed("**") jakarta.annotation.security.RolesAllowed 주석을 사용하여 인증된 사용자만 액세스할 수 있습니다. 주석은 @RolesAllowed("**") 인증된 사용자만 경로에 /profile 액세스할 수 있도록 지정합니다.

@Path("/profile")
@RolesAllowed("**")
public class ProfilePage {

    private final Template profile;

    @Inject
    SecurityIdentity identity;

    @Inject
    JsonWebToken accessToken;

    public ProfilePage(Template profile) {
        this.profile = requireNonNull(profile, "profile page is required");
    }

    @Path("/admin")
    @GET
    @Produces(MediaType.TEXT_HTML)
    @RolesAllowed("admin")
    public TemplateInstance getAdmin() {
        return getProfile();
    }

    @Path("/user")
    @GET
    @Produces(MediaType.TEXT_HTML)
    @RolesAllowed({"user","admin"})
    public TemplateInstance getUser() {
        return getProfile();
    }

    private TemplateInstance getProfile() {
        return profile
                .data("name", identity.getPrincipal().getName())
                .data("roles", identity.getRoles())
                .data("scopes", accessToken.getClaim("scp"));
    }

}

프로필 페이지 리소스를 사용하면 주석을 사용하여 RBAC를 @RolesAllowed 사용할 수 있습니다. 주석에 대한 @RolesAllowed 인수는 역할이 있는 사용자만 경로에 /profile/admin admin 액세스할 수 있도록 지정하고, 또는 admin 역할이 있는 사용자는 경로에 user /profile/user 액세스할 수 있습니다.

/profile/admin 엔드포인트와 /profile/user 엔드포인트 모두 프로필 페이지를 반환합니다. 프로필 페이지 UI는 다음 예제와 같이 profile.qute.html 정의됩니다. 이 페이지에는 사용자의 이름, 역할 및 범위가 표시됩니다. 프로필 페이지에는 사용자를 OIDC 공급자로 리디렉션하여 로그아웃하는 로그아웃 링크 /logout도 있습니다. 프로필 페이지는 Qute 템플릿 엔진을 사용하여 작성됩니다. 페이지에서 식을 {} 사용합니다. 이러한 식은 using data() 메서드에 TemplateInstance 전달된 값을 사용합니다. Qute에 대한 자세한 내용은 Qute 템플릿 엔진을 참조하세요.

<html>
    <head>
        <meta charset="UTF-8">
        <title>Profile</title>
    </head>
    <body>
        <h1>Hello, {name}</h1>
        <h2>Roles</h2>
        <ul>
            {#if roles}
                {#for role in roles}
                    <li>{role}</li>
                {/for}
            {#else}
                <li>No roles found!</li>
            {/if}
        </ul>
        <h2>Scopes</h2>
        <p>
            {scopes}
        </p>
        <h1>
            <b><a href="/logout">Sign out</a></b>
        </h1>
    </body>
</html>

로그아웃한 후 사용자는 시작 페이지로 리디렉션되고 다시 로그인할 수 있습니다.

Quarkus 앱 실행 및 테스트

이 섹션에서는 Quarkus 앱을 실행하고 테스트하여 Microsoft Entra ID를 OpenID Connect 공급자로 사용하는 방법을 확인합니다.

샘플 준비

다음 단계를 사용하여 샘플 Quarkus 앱을 준비합니다.

다음 명령을 사용하여 GitHub에서 샘플 Quarkus 앱을 복제하고 디렉터리로 entra-id-quarkus 이동합니다.
```
git clone https://github.com/Azure-Samples/quarkus-azure
cd quarkus-azure/entra-id-quarkus
git checkout 2024-07-17
```
분리된 HEAD 상태에 있다는 메시지가 표시되면 이 메시지는 무시해도 안전합니다. 이 문서에는 커밋이 필요하지 않으므로 분리된 HEAD 상태가 적절합니다.
다음 명령을 사용하여 앞에서 기록한 값으로 다음 환경 변수를 정의합니다.
```
export QUARKUS_OIDC_CLIENT_ID=<application/client-ID>
export QUARKUS_OIDC_CREDENTIALS_SECRET=<client-secret>
export QUARKUS_OIDC_AUTH_SERVER_URL=https://login.microsoftonline.com/<directory/tenant-ID>/v2.0
```
이러한 환경 변수는 Quarkus에서 OpenID Connect를 기본적으로 지원하는 값을 제공합니다. 해당 속성 application.properties 은 다음 예제에 나와 있습니다.
```
quarkus.oidc.client-id=
quarkus.oidc.credentials.secret=
quarkus.oidc.auth-server-url=
```
속성 값이 비어 있으면 application.propertiesQuarkus는 속성 이름을 환경 변수로 변환하고 환경에서 값을 읽습니다. 명명 변환에 대한 자세한 내용은 MicroProfile 구성 사양을 참조 하세요.

Quarkus 앱 실행

다른 모드에서 Quarkus 앱을 실행할 수 있습니다. Quarkus 앱을 실행하려면 다음 방법 중 하나를 선택합니다. Quarkus가 Microsoft Entra ID에 연결할 수 있도록 하려면 이전 섹션에 표시된 환경 변수를 정의한 셸에서 명령을 실행해야 합니다.

개발 모드에서 Quarkus 앱을 실행합니다.
```
mvn quarkus:dev
```

JVM 모드에서 Quarkus 앱을 실행합니다.

mvn install
java -jar target/quarkus-app/quarkus-run.jar

기본 모드에서 Quarkus 앱을 실행합니다.

mvn install -Dnative -Dquarkus.native.container-build
./target/quarkus-ad-1.0.0-SNAPSHOT-runner

다른 모드를 시도하려면 Ctrl+C를 사용하여 Quarkus 앱을 중지한 다음, 다른 모드에서 Quarkus 앱을 실행합니다.

Quarkus 앱 테스트

Quarkus 앱이 실행되면 프라이빗 탭 http://localhost:8080이 있는 웹 브라우저를 열고 . 사용자 또는 관리자로 로그인할 수 있는 링크가 있는 시작 페이지가 표시됩니다. 프라이빗 탭을 사용하면 일반 브라우저에 있을 수 있는 기존 Microsoft Entra ID 활동이 오염되는 것을 방지할 수 있습니다.

두 사용자의 자격 증명 수집

이 문서에서 Microsoft Entra ID는 각 사용자의 이메일 주소를 로그인을 위한 사용자 ID로 사용합니다. 다음 단계를 사용하여 관리자 및 일반 사용자의 전자 메일 주소를 가져옵니다.

최소한 클라우드 애플리케이션 관리자로 Microsoft Entra 관리 센터에 로그인합니다.
여러 테넌트에 액세스할 수 있는 경우 위쪽 메뉴의 설정 아이콘( )을 사용하여 디렉터리 + 구독 메뉴에서 애플리케이션 을 등록하려는 테넌트로 전환합니다 .
ID > 사용자 모든 사용자를 > 찾습니다.
목록에서 관리자 사용자를 찾아 선택합니다.
사용자 계정 이름 필드를 찾습니다.
필드 값 옆에 있는 복사 아이콘을 사용하여 사용자의 전자 메일 주소를 클립보드에 저장합니다. 나중에 사용할 수 있는 값을 저장합니다.
일반 사용자의 전자 메일 주소를 얻으려면 동일한 단계를 수행합니다.

사용자를 만들 때 설정한 관리자 사용자 및 일반 사용자에 대한 암호를 사용합니다.

앱의 기능 연습

다음 단계를 사용하여 기능을 연습합니다.

사용자로 로그인 링크를 선택합니다. 이전에 만든 일반 사용자로 로그인합니다. 로그인한 후 Microsoft Entra ID는 사용자 이름, 역할 및 범위를 볼 수 있는 프로필 페이지로 리디렉션됩니다.
처음 로그인하는 경우 암호를 업데이트하라는 메시지가 표시됩니다. 지침에 따라 암호를 업데이트합니다.
조직에 메시지가 표시되면 추가 보안 정보가 필요합니다. 프롬프트에 따라 Microsoft Authenticator 앱을 다운로드하고 설정합니다. 나중에 요청을 선택하여 테스트를 계속할 수 있습니다.
권한 요청 메시지가 표시되면 앱에서 요청한 사용 권한을 검토합니다. [수락]을 선택하여 테스트를 계속합니다.
Quarkus 앱에서 로그아웃하려면 로그아웃을 선택합니다. Microsoft Entra ID는 로그아웃을 수행합니다. 로그아웃하면 Microsoft Entra ID가 시작 페이지로 리디렉션됩니다.
관리자 권한으로 로그인 링크를 선택합니다. Microsoft Entra ID는 사용자를 로그인 페이지로 리디렉션합니다. 이전에 만든 관리자 사용자로 로그인합니다. 로그인한 후 Microsoft Entra ID는 다른 역할 admin로 유사한 프로필 페이지로 리디렉션됩니다.
다시 로그아웃하고 이전에 만든 일반 사용자로 관리자로 로그인합니다. 일반 사용자에게 역할이 없 admin 으므로 오류 메시지가 표시됩니다.

리소스 정리

이 문서에서는 Azure에 Quarkus 앱을 배포하도록 지시하지 않습니다. Quarkus 앱에 대해 정리할 리소스가 없습니다. Azure에 Quarkus 앱을 배포하려면 다음 섹션에서 참조하는 지침을 따를 수 있습니다.

이 샘플 앱에 대한 리소스를 완료하면 다음 단계를 사용하여 Microsoft Entra ID 리소스를 정리합니다. 사용되지 않는 Microsoft Entra ID 리소스를 제거하는 것이 중요한 보안 모범 사례입니다.

Microsoft ID 플랫폼 등록된 애플리케이션 제거의 단계에 따라 만든 앱 등록을 제거합니다. 조직에서 작성한 애플리케이션 제거 섹션의 단계만 수행하면 됩니다.
앱 등록을 제거하는 작업도 엔터프라이즈 애플리케이션을 삭제해야 합니다. 엔터프라이즈 애플리케이션 삭제에 대한 자세한 내용은 엔터프라이즈 애플리케이션 삭제를 참조하세요.
사용자를 만들고 초대하고 삭제하는 방법의 단계에 따라 만든 사용자를 삭제합니다.

다음 단계

이 빠른 시작에서는 OpenID Connect를 사용하여 Microsoft Entra ID로 Quarkus 애플리케이션을 보호합니다. 자세히 알아보려면 다음 리소스를 살펴보세요.

다음을 통해 공유