使用群組和群組宣告保護 Java Spring Boot 應用程式

本文示範 Java Spring Boot Web 應用程式，其使用 適用於 Java 的 Microsoft Entra ID Spring Boot Starter 用戶端連結庫進行驗證、授權和令牌取得。 應用程式會使用 OpenID Connect 通訊協定來登入使用者，並根據Microsoft Entra ID 安全組成員資格來限制頁面的存取權。

下圖顯示應用程式的拓撲：

用戶端應用程式會使用適用於 Java 的 Microsoft Entra ID Spring Boot Starter 用戶端連結庫，在 Microsoft Entra ID 租使用者中登入使用者，並從 Microsoft Entra ID 取得 標識符令牌 。

標識元令牌包含群組宣告。 應用程式會將宣告載入至已登入使用者的 Spring GrantedAuthorities 清單。 這些值會決定用戶獲授權存取的頁面。

如需涵蓋此案例的影片，請參閱 使用應用程式角色、安全組、範圍和目錄角色在應用程式中實作授權。

必要條件

• JDK 第 15 版。 此範例是在 Java 15 的系統上開發，但可能與其他版本相容。
• Maven 3
• 建議使用適用於Visual Studio Code的 Java 擴充套件，在Visual Studio Code 中執行此範例。
• Microsoft Entra ID 租用戶。 如需詳細資訊，請參閱快速入門：設定租用戶。
• 您Microsoft Entra ID 租使用者中的用戶帳戶。 此範例不適用於個人Microsoft帳戶。 因此，如果您使用個人帳戶登入 Azure 入口網站，而且目錄中沒有用戶帳戶，您現在必須建立一個帳戶。
• 兩個名為 AdminGroup 和 UserGroup的安全組，包含您想要簽署並測試此範例的用戶或使用者。 或者，您可以將使用者新增至租使用者中的兩個現有安全組。 如果您選擇使用現有的群組，請務必修改範例組態，以使用您現有的安全組名稱和對象識別碼。
• 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/groups

或者，流覽至 ms-identity-msal-java-samples 存放庫，然後將它下載為 .zip 檔案，並將其解壓縮至您的硬碟。

向Microsoft Entra ID 租用戶註冊範例應用程式

此範例中有一個專案。 下列各節說明如何使用 Azure 入口網站 註冊應用程式。

選擇要在其中建立應用程式的Microsoft Entra ID 租使用者

若要選擇您的租使用者，請使用下列步驟：

1. 登入 Azure 入口網站。

2. 如果您的帳戶存在於多個Microsoft Entra ID 租使用者中，請在 Azure 入口網站 的角落選取您的配置檔，然後選取 [切換目錄]，將會話變更為所需的Microsoft Entra ID 租使用者。

註冊應用程式 （java-spring-webapp-groups）

若要註冊應用程式，請使用下列步驟：

1. 流覽至 Azure 入口網站，然後選取 [Microsoft Entra ID]。

2. 在瀏覽窗格中選取 [應用程式註冊 ]，然後選取 [ 新增註冊]。

3. 在出現的 [ 註冊應用程式] 頁面中 ，輸入下列應用程式註冊資訊：

   • 在 [ 名稱] 區段中，輸入有意義的應用程式名稱，以顯示給應用程式的使用者 ，例如 java-spring-webapp-groups。
   • 在 [支援的帳戶類型] 底下，選取 [僅在此組織目錄中的帳戶]。
   • 在 [ 重新導向 URI （選擇性）] 區段中，選取 下拉式方塊中的 [Web ]，然後輸入下列重新導向 URI： http://localhost:8080/login/oauth2/code/。

4. 選取 [暫存器] 以建立應用程式。

5. 在應用程式的註冊頁面上，尋找並複製 應用程式 （用戶端） 識別碼 值，以供稍後使用。 您會在應用程式的組態檔或檔案中使用此值。

6. 在應用程式的註冊頁面上，選取 瀏覽窗格中的 [憑證和秘密 ]，以開啟您可以產生秘密並上傳憑證的頁面。

7. 在用戶端密碼區段底下，選取新增用戶端密碼。

8. 輸入描述 - 例如， 應用程式秘密。

9. 選取其中一個可用的持續時間： 6 個月、 12 個月或 [自定義]。

10. 選取 [新增]。 產生的值隨即顯示。

11. 複製並儲存產生的值，以供後續步驟使用。 您需要此值才能用於程式代碼的組態檔。 此值不會再次顯示，而且您無法透過任何其他方式加以擷取。 因此，請務必先從 Azure 入口網站 儲存它，再流覽至任何其他畫面或窗格。

12. 在應用程式的註冊頁面上，選取 瀏覽窗格中的 [API 許可權 ] 以開啟頁面，您可以在其中新增應用程式所需的 API 存取權。

13. 選取新增權限。

14. 確認已選取 [Microsoft API] 索引標籤。

15. 在 [常用的 Microsoft API] 區段中，選取 [Microsoft Graph]。

16. 在 [ 委派的許可權] 區段中，從清單中選取 [GroupMember.Read.All ]。 如有需要請使用搜尋方塊。 如果發生超額案例，則需要此許可權才能透過 Graph 取得群組成員資格。

17. 選取按鈕以授與管理員同意。GroupMember.Read.All

18. 選取 [新增權限]。

建立安全性群組

若要建立安全組，請使用下列步驟：

1. 流覽至 Azure 入口網站，然後選取 [Microsoft Entra ID]。

2. 選取 瀏覽窗格上的 [群組 ]。

3. 在 [群組] 窗格中，選取 [新增群組]，然後提供下列資訊：

   • 針對 [ 群組類型]，選取 [ 安全性]。
   • 針對 [組名]，輸入 AdminGroup。
   • 針對 [群組描述]，輸入 系統管理安全組。
   • 新增您想要在此範例中使用和測試的群組擁有者和群組成員。
   • 選取 建立。

4. 在 [群組] 窗格中，選取 [新增群組]，然後提供下列資訊：

   • 針對 [ 群組類型]，選取 [ 安全性]。
   • 針對 [組名]，輸入 UserGroup。
   • 針對 [群組描述]，輸入 使用者安全組。
   • 新增您想要在此範例中使用和測試的群組擁有者和群組成員。
   • 選取 建立。

如需詳細資訊，請參閱管理 Microsoft Entra 群組和群組成員資格。

設定安全性群組

您有下列選項說明如何進一步設定應用程式以接收群組宣告：

• 在包含巢狀群組的 Microsoft Entra ID 租使用者中，接收已登入使用者指派給的所有群組。 如需詳細資訊，請參閱設定您的應用程式以接收已登入使用者指派給的所有群組，包括巢狀群組一節。

• 從已篩選的一組群組接收群組宣告值，您的應用程式會用來處理這些群組。 如需詳細資訊，請參閱設定應用程式以從使用者可能指派的已篩選群組集合接收群組宣告值一節。 此選項不適用於 Microsoft Entra ID Free Edition。

設定您的應用程式以接收已登入使用者指派的所有群組，包括巢狀群組

若要設定應用程式，請使用下列步驟：

1. 在應用程式的註冊頁面上，選取 瀏覽窗格中的 [令牌 組態]，以開啟頁面，您可以在其中設定向應用程式發出的宣告提供的令牌。

2. 選取 [新增群組宣告 ] 以開啟 [ 編輯群組宣告 ] 畫面。

3. 選取 [安全組] 或 [所有群組] （包括通訊組清單，但不包含指派給應用程式的群組）。 選擇這兩者會否定 [安全組] 選項的效果。

4. 在 [ 標識符] 區段底下，選取 [ 群組標識符]。 此選取專案會導致Microsoft Entra ID ，將使用者指派給的群組對象 標識碼傳送至應用程式登入用戶之後所接收標識元 令牌 的群組宣告中。

將您的應用程式設定為從使用者可能指派給的已篩選群組集合接收群組宣告值

當下列情況成立時，此選項很有用：

• 您的應用程式對登入使用者可能指派的一組選取群組感興趣。
• 您的應用程式對租使用者中指派給的每個安全組並不感興趣。

這個選項可協助您的應用程式避免 超額 問題。

若要在應用程式中啟用此選項，請使用下列步驟：

1. 在應用程式的註冊頁面上，選取 瀏覽窗格中的 [令牌 組態]，以開啟頁面，您可以在其中設定向應用程式發出的宣告提供的令牌。

2. 選取 [新增群組宣告 ] 以開啟 [ 編輯群組宣告 ] 畫面。

3. 選取 指派給應用程式的 [群組]，但不選取任何其他選項。 如果您選擇更多選項，例如安全組或所有群組（包括指派給應用程式的通訊組清單，但不包括指派給應用程式的群組），這些選項會否定指派給應用程式選項的群組效果。

4. 在 [ 標識符] 區段底下，選取 [ 群組標識符]。 此選取專案會導致Microsoft Entra ID ，將使用者指派給的群組對象 標識碼傳送至應用程式登入用戶之後所接收標識元 令牌 的群組宣告中。

5. 如果您使用 [公開 API] 選項來公開 Web API，則您也可以選擇 [存取] 區段底下的 [群組標識符] 選項。 此選取專案會導致Microsoft Entra ID 將使用者指派給群組的物件識別碼傳送至您 API 用戶端應用程式之存取令牌的群組宣告中。

6. 在應用程式的註冊頁面上，選取瀏覽窗格中的 [概觀] 以開啟 [應用程式概觀] 畫面。

7. 選取具有本機目錄中受控應用程式中應用程式名稱的超連結。 此欄位標題可能會遭到截斷 ─ 例如... 中的 Managed 應用程式。當您選取此連結時，您會流覽至 與您建立應用程式租使用者中應用程式服務主體相關聯的 [企業應用程式概觀 ] 頁面。 您可以使用瀏覽器的 [上一頁] 按鈕，巡覽回應用程式註冊頁面。

8. 選取 瀏覽窗格上的 [使用者和群組 ]，以開啟頁面，您可以在其中將使用者和群組指派給應用程式。

9. 選取 [新增使用者]。

10. 從結果畫面選取 [使用者和群組 ]。

11. 選擇您要指派給此應用程式的群組。

12. 選取 [ 選取 ] 以完成選取群組。

13. 選取 [ 指派 ] 以完成群組指派程式。

    當使用者登入您的應用程式是一或多個指派群組的成員時，您的應用程式現在會在群組宣告中接收這些選取的群組。

14. 選取 瀏覽窗格上的 [屬性 ]，以開啟列出應用程式基本屬性的頁面。 將 [ 需要使用者指派？] 旗標設定為 [ 是]。

設定程式代碼範例以使用您的應用程式註冊和安全組 （java-spring-webapp-groups）

使用下列步驟來設定應用程式：

1. 在 IDE 中開啟專案。

2. 開啟 src\main\resources\application.yml 檔案。

3. 尋找佔位元元 Enter_Your_Tenant_ID_Here ，並以您的 Microsoft Entra 租使用者標識碼取代現有的值。

4. 尋找佔位元元Enter_Your_Client_ID_Here，並將現有的值取代為從 Azure 入口網站 複製的應用程式識別碼或clientIdjava-spring-webapp-groups應用程式。

5. 尋找佔位元Enter_Your_Client_Secret_Here，並將現有值取代為您在建立java-spring-webapp-groups從 Azure 入口網站 複製期間儲存的值。

6. 尋找佔位元Enter_Your_Admin_Group_ID_Here元，並以AdminGroup的值取代現有的值objectId。

7. 尋找佔位元Enter_Your_User_Group_ID_Here元，並以UserGroup的值取代現有的值objectId。

8. 開啟 src/main/java/com/microsoft/azuresamples/msal4j/msidentityspringbootwebapp/SampleController.java 檔案。

9. 尋找佔位元Enter_Your_Admin_Group_ID_Here元，並以AdminGroup的值取代現有的值objectId。

10. 尋找佔位元Enter_Your_User_Group_ID_Here元，並以UserGroup的值取代現有的值objectId。

執行範例

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. 如果您是在首頁上，請選取 [標識符令牌詳細數據 ]，以查看部分標識元令牌已譯碼的宣告，包括群組。
8. 選取 [ 僅限 系統管理員] 以檢視 /admin_only。 只有屬於 AdminGroup 安全組的使用者才能檢視此頁面。 否則，會顯示授權失敗訊息。
9. 選取 [ 一般使用者 ] 以檢視 /regular_user 頁面。 只有屬於 UserGroup 安全組的使用者才能檢視此頁面。 否則，會顯示授權失敗訊息。
10. 使用角落中的按鈕註銷。狀態頁面會反映新狀態。

關於程式碼

此範例示範如何使用 適用於 Java 的 Microsoft Entra ID Spring Boot Starter 用戶端連結庫，將使用者登入您的 Microsoft Entra ID 租使用者。 此範例也會使用 Spring Oauth2 用戶端和 Spring Web 開機入門。 此範例會使用從 Microsoft Entra ID 取得的標識碼令牌宣告來顯示登入使用者的詳細數據，以及使用群組宣告進行授權來限制對某些頁面的存取。

目錄

下表顯示範例項目資料夾的內容：

標識元令牌宣告

為了擷取令牌詳細數據，應用程式會在要求對應中使用 Spring Security 的 AuthenticationPrincipal 和 OidcUser 物件，如下列範例所示。 如需此應用程式如何使用標識元令牌宣告的完整詳細數據，請參閱範例控制器。

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

在標識元令牌中處理群組宣告

令牌的群組宣告包含已登入使用者指派給的群組名稱，如下列範例所示：

{
  ...
  "groups": [
    "xyz-id-xyz",
    "xyz-id-xyz",]
  ...
}

存取組名的常見方式記載於 標識元令牌宣告一 節中。

Microsoft Entra ID Boot Starter v3.5 和更新版本會自動剖析群組宣告，並將每個群組新增至登入使用者的 Authorities。 此組態可讓開發人員使用 方法搭配 Spring PrePost 條件批註使用 hasAuthority 群組。 例如，您可以在SampleController.java中找到下列@PreAuthorize示範的條件：

@GetMapping(path = "/admin_only")
@PreAuthorize("hasAuthority('enter-admin-group-id-here')")
public String adminOnly(Model model) {
    // restrict to users who belong to AdminGroup
}
@GetMapping(path = "/regular_user")
@PreAuthorize("hasAnyAuthority('enter-user-group-id-here','enter-admin-group-id-here')")
public String regularUser(Model model) {
    // restrict to users who belong to any of UserGroup or AdminGroup
}

下列程式代碼會取得指定使用者的完整授權清單：

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

登入和註銷連結

針對登入，應用程式會向 Microsoft Entra ID Spring Boot Starter 用戶端連結庫 for Java 自動設定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 元素

應用程式在UI範本頁面中有一些簡單的邏輯，可用來根據使用者是否已驗證來判斷要顯示的內容，如下列使用 Spring Security Thymeleaf 標籤的範例所示：

<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 保護路由

根據預設，應用程式會保護標識元 令牌詳細數據、 僅限系統管理員和 一般用戶 頁面，以便只有登入的使用者才能存取它們。 應用程式會使用app.protect.authenticated來自 application.yml 檔案的 屬性來設定這些路由。 若要設定應用程式的特定需求，您可以在其中一個類別中擴充 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.
    }
}

群組超額宣告

為了確保令牌大小不會超過 HTTP 標頭大小限制，Microsoft 身分識別平台 限制其包含在群組宣告中的物件標識碼數目。

SAML 令牌的超額限制為150，JWT令牌為200，單頁應用程式為6。 如果使用者是超過超額限制的群組成員，則 Microsoft 身分識別平台 不會在令牌中的群組宣告中發出群組標識符。 相反地，它會在令牌中包含超額宣告，指示應用程式查詢 Microsoft Graph API 以擷取使用者的群組成員資格。

Microsoft Entra ID Boot Starter v3.5 和更新版本會自動剖析群組宣告，並將每個群組新增至登入使用者的 Authorities。 入門程式會自動處理群組超額案例。

建立超額案例以進行測試

您可以使用 AppCreationScripts 資料夾中提供的 BulkCreateGroups.ps1 檔案來建立大量群組，並將使用者指派給他們。 此檔案有助於在開發期間測試超額案例。 請記得變更 BulkCreateGroups.ps1 腳本中所提供的使用者objectId。

處理超額需要呼叫 Microsoft Graph 才能讀取已登入使用者的群組成員資格，因此您的應用程式必須具有 getMemberGroups 函式的 User.Read 和 GroupMember.Read.All 許可權才能順利執行。

更新 Microsoft Entra ID 應用程式註冊 （java-spring-webapp-groups）

若要更新應用程式註冊，請使用下列步驟：

1. 流覽回 Azure 入口網站。

2. 在瀏覽窗格中，選取 [Azure Active Directory]，然後選取 [應用程式註冊 [預覽]。

3. 在產生的畫面中 java-spring-webapp-groups ，選取應用程式。

4. 在應用程式的註冊頁面上，從功能表中選取 [ 驗證 ]。

5. 在 [ 重新導向 URI] 區段中，更新回復 URL 以符合 Azure 部署的網站 URL， https://java-spring-webapp-groups.azurewebsites.net/login/oauth2/code/例如 。

其他相關資訊

• Microsoft 身分識別平台文件
• Microsoft驗證連結庫概觀 （MSAL）
• 快速入門：使用 Microsoft 身分識別平台來註冊應用程式
• 快速入門：設定用戶端應用程式以存取 Web API
• 瞭解Microsoft Entra ID 應用程式同意體驗
• 瞭解使用者和系統管理員同意
• Azure Active Directory 中的應用程式和服務主體物件
• 國家雲端
• MSAL 程式代碼範例

如需 OAuth 2.0 通訊協定在此案例和其他案例中運作方式的詳細資訊，請參閱 Microsoft Entra ID 的驗證案例。