使用 OpenID Connect 保護具有 Microsoft Entra ID 的安全 Quarkus 應用程式

發行項
10/14/2024

本文說明如何使用 OpenID Connect （OIDC）保護具有 Microsoft Entra ID 的 Red Hat Quarkus 應用程式。

在本文中，您將學會如何：

使用 Microsoft Entra ID 設定 OpenID Connect 提供者。
使用 OpenID Connect 保護 Quarkus 應用程式。
執行及測試 Quarkus 應用程式。

必要條件

Azure 訂用帳戶。如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。
至少具有雲端應用程式管理員Microsoft Entra 角色的 Azure 身分識別。如需詳細資訊，請參閱列出Microsoft Entra 角色指派和 Microsoft Entra 內建角色。
Microsoft Entra 租用戶。如果您沒有現有的租使用者，請參閱快速入門：設定租使用者。
已安裝類似 Unix 作業系統的本機電腦，例如 Ubuntu、macOS 或 Windows 子系統 Linux 版。
Git。
Java SE 實作版本 21 或更新版本 - 例如 OpenJDK 的Microsoft組建。
Maven 3.9.3 版或更新版本。

使用 Microsoft Entra ID 設定 OpenID Connect 提供者

在本節中，您會使用 Microsoft Entra ID 來設定 OpenID Connect 提供者，以搭配您的 Quarkus 應用程式使用。在稍後的章節中，您會使用 OpenID Connect 設定 Quarkus 應用程式，以驗證和授權您Microsoft Entra 租使用者中的使用者。

在 Microsoft Entra 租使用者中建立使用者

首先，遵循如何建立、邀請和刪除使用者中的步驟，在Microsoft Entra 租使用者中建立兩個使用者。您只需要建立新的使用者區段。當您流覽本文時，請使用下列指示，然後在您在 Microsoft Entra 租使用者中建立用戶之後返回本文。

若要建立使用者以作為應用程式中的「系統管理員」，請使用下列步驟：

當您在 [建立新的使用者] 區段中觸達 [基本] 索引卷標時，請使用下列步驟：
1. 針對 [ 用戶主體名稱]，輸入 admin。儲存值，以便稍後當您登入應用程式時使用它。
2. 針對 [郵件昵稱]，選取 [ 衍生自用戶主體名稱]
3. 針對 [ 顯示名稱]，輸入 [系統管理員]。
4. 針對 [ 密碼]，選取 [ 自動產生密碼]。當您登入應用程式時，請複製並儲存密碼值以供稍後使用。
5. 選取 [已啟用帳戶]。
6. 選取 [檢閱 + 建立]>[建立]。等候使用者建立。
7. 等候一分鐘左右，然後選取 [ 重新整理]。您應該會在清單中看到新的使用者。

若要建立使用者以作為應用程式中的「使用者」，請重複這些步驟，但使用下列值：

針對 [ 用戶主體名稱]，輸入 user。
針對 [ 顯示名稱]，輸入 [使用者]。

在 Microsoft Entra ID 中註冊應用程式

接下來，依照快速入門：向 Microsoft 身分識別平台註冊應用程式中的步驟來註冊應用程式。當您流覽本文時，請使用下列指示，然後在註冊並設定應用程式之後返回本文。

當您到達 [ 註冊應用程式 ] 區段時，請使用下列步驟：
1. 針對 [支持的帳戶類型]，選取 [僅限此組織目錄中的帳戶] （僅限默認目錄 - 單一租使用者）。
2. 註冊完成時，請 儲存應用程式（用戶端）識別碼 和 目錄（租使用者）識別碼 值，以供稍後在應用程式組態中使用。
當您到達 [ 新增重新導向 URI ] 區段時，請略過目前的步驟。您稍後會在本文本機執行及測試範例應用程式時新增重新導向 URI。
當您到達 [ 新增認證 ] 區段時，請選取 [ 新增客戶端密碼 ] 索引標籤。
當您新增客戶端密碼時，請記下 [客戶端密碼 ] 值，以便稍後在應用程式組態中使用。

將應用程式角色新增至您的應用程式

然後，依照將應用程式角色新增至您的應用程式中的步驟，在令牌中接收應用程式角色，以將應用程式角色新增至您的應用程式。您只需要宣告應用程式的角色，並將使用者和群組指派給Microsoft Entra 角色一節。當您流覽本文時，請使用下列指示，然後在宣告應用程式的角色之後返回本文。

當您觸達應用程式區段的宣告角色時，請使用 應用程式角色 UI 來建立系統管理員和一般使用者的角色。
1. 使用下列值建立系統管理員使用者角色：
  - 針對 [ 顯示名稱]，輸入 [系統管理員]。
  - 針對 [ 允許的成員類型]，選取 [ 使用者/群組]。
  - 針對 [值]，輸入 admin。
  - 針對 [ 描述]，輸入 系統管理員。
  - 選取 [您要啟用此應用程式角色嗎？]。
2. 選取套用。等候角色建立。
3. 使用相同的步驟建立一般使用者角色，但具有下列值：
  - 針對 [ 顯示名稱]，輸入 [使用者]。
  - 針對 [ 值]，輸入 使用者。
  - 針對 [ 描述]，輸入 [使用者]。
當您觸達 [ 將使用者和群組指派給 Microsoft Entra 角色] 區段時，請使用下列步驟：
1. 選取 [新增使用者/群組]。
2. 在 [新增指派] 窗格中，針對 [使用者]，選取 [使用者管理員]，然後選取 [選取角色管理員]。然後，選取 [指派]。等到應用程式指派成功為止。您可能需要側邊捲動數據表，才能查看 [角色指派 ] 數據行。
3. 重複上述步驟，將使用者角色指派給用戶使用者。
4. 選取 [ 重新整理 ]，您應該會在 [ 使用者和群組 ] 窗格中看到指派的使用者和角色。
  
  您可能需要調整數據行標頭的寬度，讓您的檢視看起來像影像。

請勿遵循將應用程式角色新增至您的應用程式中的任何 其他步驟，並在令牌中接收它們。

使用 OpenID Connect 保護 Quarkus 應用程式

在本節中，您會使用 OpenID Connect 保護 Quarkus 應用程式，以驗證並授權您 Microsoft Entra 租使用者中的使用者。您也會瞭解如何使用角色型存取控制（RBAC）讓使用者存取應用程式的某些部分。

本快速入門的範例 Quarkus 應用程式位於 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/user和 /profile/admin 鏈接都會指向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"));
    }

}

配置文件頁面資源會使用 @RolesAllowed 註釋來啟用 RBAC。批註的 @RolesAllowed 自變數指定只有具有 admin 角色的使用者可以存取 /profile/admin 路徑，且具有 user 或 admin 角色的使用者可以存取 /profile/user 路徑。

/profile/admin和 /profile/user 端點都會傳回配置檔頁面。配置文件頁面 UI 定義於 profile.qute.html，如下列範例所示。這個頁面會顯示用戶的名稱、角色和範圍。配置文件頁面也有位於的註銷連結 /logout，可將使用者重新導向至 OIDC 提供者以登出。配置文件頁面是使用Qute範本化引擎所撰寫。請注意頁面中表達式的使用 {} 方式。這些表達式會使用使用 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 提供者。

將重新導向 URI 新增至應用程式註冊

若要在本機成功執行及測試應用程式，您必須將重新導向 URI 新增至應用程式註冊。請遵循快速入門：使用 Microsoft 身分識別平台註冊應用程式，並使用下列值中的指示：新增重新導向 URI 一節：

針對 [ 設定平臺]，選取 [Web]。
針對 [重新導向 URI]，輸入 http://localhost:8080。

準備範例

使用下列步驟來準備範例 Quarkus 應用程式：

使用下列命令從 GitHub 複製範例 Quarkus 應用程式，並瀏覽至 entra-id-quarkus 目錄：
```
git clone https://github.com/Azure-Samples/quarkus-azure
cd quarkus-azure/entra-id-quarkus
git checkout 2024-09-26
```
如果您看到有關處於中斷連結的 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.properties屬性值為空白，Quarkus 會將屬性名稱轉換成環境變數，並從環境讀取值。如需命名轉換的詳細資訊，請參閱 MicroProfile Config 規格。

執行 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 會使用每個使用者的電子郵件地址作為使用者標識碼進行登入。使用下列步驟來取得系統管理員使用者和一般使用者的電子郵件地址：

以至少雲端應用程式系統管理員的身分登入 Microsoft Entra 系統管理中心。
如果您有多個租使用者的存取權，請使用 頂端功能表中的 [設定 ] 圖示（）切換至您想要從 [目錄 + 訂 用帳戶] 功能表註冊應用程式的租使用者。
流覽至 [身分>識別使用者>所有使用者]。
在清單中找出系統管理員使用者，然後加以選取。
找出 [ 用戶主體名稱] 欄位。
使用欄位值旁的複製圖示，將使用者的電子郵件地址儲存到剪貼簿。儲存值以供日後使用。
若要取得一般使用者的電子郵件位址，請遵循相同的步驟。

使用系統管理員用戶的密碼，以及您在建立使用者時所設定的一般使用者。

練習應用程式的功能

使用下列步驟來練習功能：

選取 [ 以使用者身分登入] 連結。使用您稍早建立的一般使用者登入。登入之後，Microsoft Entra ID 會將您重新導向至配置檔頁面，您可以在其中看到您的名稱、角色和範圍。
如果這是您第一次登入，系統會提示您更新密碼。請遵循指示來更新您的密碼。
如果您收到組織 提示，則需要額外的安全性資訊。依照提示下載並設定 Microsoft Authenticator 應用程式，您可以選取 [ 稍後詢問] 以繼續測試。
如果您收到要求的許可權提示，請檢閱應用程式所要求的許可權。選取 [ 接受 ] 以繼續測試。
選取 [註銷 ] 以註銷 Quarkus 應用程式。 Microsoft Entra ID 會執行註銷。註銷之後，Microsoft Entra ID 會將您重新導向至歡迎頁面。
選取 [ 以系統管理員身分登入] 連結。 Microsoft Entra ID 會將您重新導向至登入頁面。使用您稍早建立的系統管理員使用者登入。登入之後，Microsoft Entra ID 會將您重新導向至類似的配置檔頁面，並具有不同的角色 admin。
再次註銷，並嘗試使用您稍早建立的一般使用者以 系統管理員 身分登入。您應該會看到錯誤訊息，因為一般用戶沒有 admin 角色。

清除資源

本文不會引導您在 Azure 上部署應用程式。雖然有Microsoft Entra ID 資源，但是沒有 Azure 資源可清除應用程式。若要在 Azure 上部署應用程式，您可以遵循下一節中參考的指引。

當您完成此範例應用程式的資源時，請使用下列步驟來清除Microsoft Entra ID 資源。拿掉未使用Microsoft Entra ID 資源是重要的安全性最佳做法。

依照移除向 Microsoft 身分識別平台註冊的應用程式中的步驟，移除您建立的應用程式註冊。您只需要遵循移除組織所撰寫應用程式一節中的步驟。
拿掉應用程式註冊的動作也應該刪除企業應用程式。如需刪除企業應用程式的詳細資訊，請參閱刪除企業應用程式。
依照如何建立、邀請和刪除使用者中的步驟，刪除您所建立的使用者。

下一步

在本快速入門中，您會使用 OpenID Connect 使用 Microsoft Entra ID 保護 Quarkus 應用程式。若要深入瞭解，請探索下列資源：

共用方式為