使用角色和角色宣告保護 Java WebLogic 應用程式

發行項
06/13/2024

本文示範使用 OpenID Connect 登入使用者的 Java WebLogic 應用程式，並 Microsoft Entra ID 應用程式角色（應用程式角色）進行授權。

此應用程式會使用Microsoft Entra ID 的應用程式角色和角色宣告功能，實作角色型訪問控制（RBAC）。另一種方法是使用Microsoft Entra ID 群組和群組宣告。 Microsoft Entra 標識符群組和應用程式角色並非互斥。您可以使用它們來提供更細緻的訪問控制。

您也可以使用 RBAC 搭配應用程式角色和角色宣告，安全地強制執行授權原則。

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

如需此案例和其他案例中通訊協議運作方式的詳細資訊，請參閱驗證與授權。

此應用程式會使用 MSAL for Java （MSAL4J）來登入使用者，並從 Microsoft Entra ID 取得標識元令牌。

此範例會先使用 MSAL for Java （MSAL4J）來登入使用者。在首頁上，它會顯示使用者在其標識元令牌中檢視宣告的選項。此應用程式也可讓用戶檢視特殊許可權系統管理員頁面或一般用戶頁面，視他們獲指派的應用程式角色而定。其概念是提供一個範例，說明應用程式內特定功能或頁面的存取權受限於用戶子集，視使用者所屬的角色而定。

這種授權是使用 RBAC 實作。使用 RBAC 時，系統管理員會將許可權授與角色，而不是授與個別使用者或群組的許可權。系統管理員接著可以將角色指派給不同的使用者和群組，以控制誰可以存取特定內容和功能。

這個範例應用程式會定義下列兩 個應用程式角色：

PrivilegedAdmin：已獲授權存取 [僅限 系統管理員] 和 [ 一般使用者] 頁面。
RegularUser：已獲授權存取 [ 一般使用者] 頁面。

這些應用程式角色定義於應用程式註冊指令清單中的 Azure 入口網站。當使用者登入應用程式時，Microsoft Entra ID 會針對以角色成員資格形式個別授與給使用者的每個角色發出角色宣告。

您可以透過 Azure 入口網站將使用者和群組指派給角色。

注意

如果端點用來作為登入使用者的授權單位， https://login.microsoftonline.com/common/ 則租使用者中的來賓使用者不會有角色宣告。您必須將使用者登入租使用者端點，例如 https://login.microsoftonline.com/tenantid。

必要條件

JDK 第 8 版或更高版本
Maven 3
Microsoft Entra ID 租用戶。如需詳細資訊，請參閱如何取得Microsoft Entra ID 租使用者。
如果您想要只使用組織目錄中的帳戶，則您自己Microsoft Entra ID 租使用者的用戶帳戶，也就是單一租使用者模式。如果您尚未在租使用者中建立用戶帳戶，您應該先這麼做，再繼續進行。如需詳細資訊，請參閱如何建立、邀請和刪除使用者。

建議

一些熟悉 Java/Jakarta Servlets。
一些熟悉 Linux/OSX 終端機。
jwt.ms 檢查令牌。
Fiddler 用於監視您的網路活動和疑難解答。
請遵循Microsoft Entra ID 部落格，隨時掌握最新的發展。

設定範例

下列各節說明如何設定範例應用程式。

複製或下載範例存放庫

若要複製範例，請開啟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 入口網站註冊應用程式。

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

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

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

註冊應用程式（java-servlet-webapp-roles）

首先，依照快速入門：向 Microsoft 身分識別平台註冊應用程式中的指示，在 Azure 入口網站中註冊新的應用程式。

然後，使用下列步驟來完成註冊：

流覽至適用於開發人員的 Microsoft 身分識別平台應用程式註冊頁面。
選取新增註冊。
在出現的 [ 註冊應用程式] 頁面中 ，輸入下列應用程式註冊資訊：
- 在 [ 名稱] 區段中，輸入有意義的應用程式名稱，以顯示給應用程式的使用者，例如 java-servlet-webapp-roles。
- 在 [支持的帳戶類型] 底下，選取下列其中一個選項：
  - 只有在您要建置應用程式以供租使用者中的使用者使用時，才選取此組織目錄中的 [帳戶]，也就是單一租用戶應用程式。
- 在 [ 重新導向 URI] 區段中，選取 下拉式方塊中的 [Web ]，然後輸入下列重新導向 URI： http://localhost:8080/msal4j-servlet-roles/auth/redirect。
選取 [暫存器] 以建立應用程式。
在應用程式的註冊頁面上，尋找並複製 應用程式（用戶端）識別碼 值，以供稍後使用。您會在應用程式的組態檔或檔案中使用此值。
選取儲存以儲存變更。
在應用程式的註冊頁面上，選取 瀏覽窗格中的 [憑證和秘密 ]，以開啟您可以產生秘密並上傳憑證的頁面。
在用戶端密碼區段底下，選取新增用戶端密碼。
輸入描述 - 例如， 應用程式秘密。
選取其中一個可用的持續時間： 在1年、 2年內或 永不過期。
選取 [新增]。產生的值隨即顯示。
複製並儲存產生的值，以供後續步驟使用。您需要此值才能用於程式代碼的組態檔。此值不會再次顯示，而且您無法透過任何其他方式加以擷取。因此，請務必先從 Azure 入口網站儲存它，再流覽至任何其他畫面或窗格。

定義應用程式角色

若要定義應用程式角色，請使用下列步驟：

仍在相同的應用程式註冊上，選取 瀏覽窗格中的 [應用程式角色 ]。
選取 [ 建立應用程式角色]，然後輸入下列值：
- 針對 [ 顯示名稱]，輸入適當的名稱，例如 PrivilegedAdmin。
- 針對 [ 允許的成員類型]，選擇 [ 使用者]。
- 針對 [ 值]，輸入 PrivilegedAdmin。
- 針對 [描述]，輸入 PrivilegedAdmins 誰可以檢視管理頁面。
選取 [ 建立應用程式角色]，然後輸入下列值：
- 針對 [ 顯示名稱]，輸入適當的名稱，例如 RegularUser。
- 針對 [ 允許的成員類型]，選擇 [ 使用者]。
- 針對 [ 值]，輸入 RegularUser。
- 針對 [ 描述]，輸入 可檢視用戶頁面的 RegularUsers。
選取 [套用] 以儲存變更。

將使用者指派給應用程式角色

若要將使用者新增至稍早定義的應用程式角色，請遵循此處的指導方針：將使用者和群組指派給角色。

設定應用程式（java-servlet-webapp-roles）以使用您的應用程式註冊

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

注意

在下列步驟中，ClientID與或 AppId相同Application ID。

在 IDE 中開啟專案。
開啟 authentication.properties 檔案。
尋找字串 {enter-your-tenant-id-here}。以您的 Microsoft Entra ID 租使用者識別碼取代現有的值。
尋找字串{enter-your-client-id-here}，並將現有的值取代為從 Azure 入口網站複製的應用程式識別碼或clientIdjava-servlet-webapp-call-graph應用程式。
尋找字串{enter-your-client-secret-here}，並將現有的值取代為您在建立java-servlet-webapp-roles應用程式期間儲存的值，Azure 入口網站。
app.roles尋找屬性，並確定值設定為 app.roles=admin PrivilegedAdmin, user RegularUser，或取代特定角色的名稱。

建置範例

若要使用 Maven 建置範例，請流覽至包含 範例pom.xml 檔案的目錄，然後執行下列命令：

mvn clean package

此命令會產生 您可以在各種應用程式伺服器上執行的 .war 檔案。

部署範例

這些指示假設您已安裝 WebLogic 並設定某些伺服器網域。

在部署至 WebLogic 之前，請使用下列步驟在範例本身進行一些組態變更，然後建置或重建套件：

在範例中，尋找 您設定用戶端標識符、租使用者、重新導向 URL 等的 application.properties 或 authentication.properties 檔案。
在此檔案中，變更 WebLogic 執行之 URL 和埠的參考localhost:8080localhost:8443，其預設應該是 localhost:7001。
您也需要在 Azure 應用程式註冊中進行相同的變更，您可以在 Azure 入口網站中將它設定為 [驗證] 索引標籤上的 [重新導向 URI] 值。

使用下列步驟，透過 Web 控制台將範例部署至 WebLogic：

使用 DOMAIN_NAME\bin\startWebLogic.cmd 啟動 WebLogic 伺服器。
在瀏覽器中 http://localhost:7001/console流覽至 WebLogic Web 控制台。
移至 [網域結構>部署]，選取 [安裝]，選取 [上傳您的檔案]，然後尋找您使用 Maven 建置的 .war 檔案。
選取 [安裝此部署為應用程式]，選取 [下一步]，選取 [完成]，然後選取 [ 儲存]。
大部分的預設設定都應該沒問題，不同之處在於您應該將應用程式命名為符合您在範例組態或 Azure 應用程式註冊中設定的重新導向 URI。也就是說，如果重新導向 URI 是 http://localhost:7001/msal4j-servlet-auth，則您應該將應用程式 msal4j-servlet-auth命名為。
返回網域結構>部署，然後啟動您的應用程式。
應用程式啟動之後，流覽至 http://localhost:7001/<application-name>/，您應該能夠存取應用程式。

探索範例

使用下列步驟來探索範例：

請注意畫面中央顯示的已登入或註銷狀態。
選取角落中的上下文相關按鈕。當您第一次執行應用程式時，此按鈕會 讀取 [登入 ]。
在下一個頁面上，遵循指示，並使用 Microsoft Entra ID 租使用者中的帳戶登入。
在同意畫面上，請注意所要求的範圍。
請注意，上下文相關按鈕現在會顯示 [註銷 ] 並顯示您的用戶名稱。
選取 [ 標識符令牌詳細數據 ]，以查看一些標識符令牌已譯碼的宣告。
選取 [ 僅限系統管理員] 以檢視 /admin_only 頁面。只有具有應用程式角色 PrivilegedAdmin 的使用者才能檢視此頁面。否則，會顯示授權失敗訊息。
選取 [ 一般使用者 ] 以檢視 /regular_user 頁面。只有具有應用程式角色 RegularUser 或 PrivilegedAdmin 可檢視此頁面的使用者。否則，會顯示授權失敗訊息。
使用角落中的按鈕註銷。

關於程式碼

此範例會使用 MSAL for Java （MSAL4J）來登入使用者，並取得可能包含角色宣告的標識符令牌。根據存在的角色宣告，登入的使用者可以存取所有、一個或兩個受保護頁面和 Admins Only Regular Users。

如果您想要復寫此範例的行為，您可以在 src/main/java/com/microsoft/azuresamples/msal4j 資料夾中複製pom.xml檔案和協助程式和 authservlet 資料夾的內容。 您也需要 authentication.properties 檔案。這些類別和檔案包含一般程式代碼，您可以在各種應用程式中使用。您也可以複製範例的其餘部分，但會特別建置其他類別和檔案，以解決此範例的目標。

檔案/資料夾	描述
src/main/java/com/microsoft/azuresamples/msal4j/roles/	此目錄包含定義應用程式後端商業規則的類別。
src/main/java/com/microsoft/azuresamples/msal4j/authservlets/	此目錄包含用於登入和註銷端點的類別。
____Servlet.java	所有可用的端點都定義於以____Servlet.java結尾的類別.java類別中。
src/main/java/com/microsoft/azuresamples/msal4j/helpers/	驗證的協助程序類別。
AuthenticationFilter.java	將未經驗證的要求重新導向至受保護的端點至 401 頁面。
src/main/resources/authentication.properties	Microsoft Entra 識別碼和程序設定。
src/main/webapp/	此目錄包含 UI - JSP 範本
CHANGELOG.md	範例的變更清單。
CONTRIBUTING.md	參與範例的指導方針。
許可證	範例的授權。

在標識元令牌中處理角色宣告

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

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

ConfidentialClientApplication

ConfidentialClientApplication實例會在 AuthHelper.java 檔案中建立，如下列範例所示。此對象有助於製作Microsoft Entra 授權 URL，也有助於交換存取令牌的驗證令牌。

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

下列參數用於具現化：

應用程式的用戶端識別碼。
客戶端密碼，這是機密用戶端應用程式的需求。
Microsoft Entra 識別符授權單位，其中包含您的Microsoft Entra 租使用者標識符。

在此範例中，這些值會使用 Config.java 檔案中的屬性讀取器，從 authentication.properties 檔案讀取。

逐步解說

下列步驟提供應用程式的功能的逐步解說：

登入程式的第一個步驟是將要求傳送至 /authorize 您Microsoft Entra ID 租使用者的端點。 MSAL4J ConfidentialClientApplication 實例可用來建構授權要求 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);
```
下列清單描述此程式碼的功能：
- AuthorizationRequestUrlParameters：必須設定的參數，才能建置 AuthorizationRequestUrl。
- REDIRECT_URI：其中Microsoft Entra ID 會在收集使用者認證之後重新導向瀏覽器，以及驗證碼。它必須符合 Azure 入口網站中Microsoft Entra ID 應用程式註冊中的重新導向 URI。
- SCOPES：範圍是應用程式要求的許可權。
  - 一般而言，三個範圍 openid profile offline_access 足以接收標識符令牌回應。
  - 您可以在 authentication.properties 檔案中找到應用程式所要求的完整範圍清單。您可以新增更多範圍，例如 User.Read。
使用者會看到 Microsoft Entra ID 發出的登入提示。如果登入嘗試成功，則會將使用者的瀏覽器重新導向至應用程式的重新導向端點。對這個端點的有效要求包含授權碼。

然後，實例 ConfidentialClientApplication 會針對標識符令牌交換此授權碼，並從 entra ID Microsoft存取令牌。

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

下列清單描述此程式碼的功能：

AuthorizationCodeParameters：必須設定的參數，才能交換標識符和/或存取令牌的授權碼。
authCode：在重新導向端點收到的授權碼。
REDIRECT_URI：必須再次傳遞上一個步驟中使用的重新導向 URI。
SCOPES：必須再次傳遞上一個步驟中使用的範圍。

如果 acquireToken 成功，則會擷取權杖宣告。如果 nonce 檢查通過，結果會放在 context - 實例 IdentityContextData 中，並儲存至會話。然後，應用程式可以透過 IdentityContextAdapterServlet 實例從會話具現化IdentityContextData，只要需要存取它，如下列程式代碼所示：

// 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 檔案中app.protect.authenticated，屬性包含只有已驗證使用者可以存取的逗號分隔路由，如下列範例所示：

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

底下 app.protect.roles 逗號分隔規則集中所列的任何路由，也會對未驗證的已驗證用戶進行限制，如下列範例所示。不過，這些路由也包含以空格分隔的應用程式角色成員資格清單：只有至少有一個對應角色的使用者可以在驗證之後存取這些路由。

# 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標識符應用程式所要求的存取層級。

根據要求的範圍，Microsoft Entra ID 會在登入時向用戶顯示同意對話。如果使用者同意一或多個範圍並取得令牌，則 scopes-consented-to 會編碼為產生的 access_token。

如需應用程式要求的範圍，請參閱 authentication.properties。 MSAL 會要求這三個範圍，且預設會由 Microsoft Entra ID 提供。

其他相關資訊

後續步驟

將 Java WebLogic 應用程式部署至 Azure 上的 WebLogic 虛擬機器

共用方式為

使用角色和角色宣告保護 Java WebLogic 應用程式

必要條件

建議

設定範例

複製或下載範例存放庫

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

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

註冊應用程式（java-servlet-webapp-roles）

定義應用程式角色

將使用者指派給應用程式角色

設定應用程式（java-servlet-webapp-roles）以使用您的應用程式註冊

建置範例

部署範例

探索範例

關於程式碼

目錄

在標識元令牌中處理角色宣告

ConfidentialClientApplication

逐步解說

保護路由

範圍

其他相關資訊

後續步驟

意見反應

其他資源

共用方式為

使用角色和角色宣告保護 Java WebLogic 應用程式

必要條件

建議

設定範例

複製或下載範例存放庫

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

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

註冊應用程式 （java-servlet-webapp-roles）

定義應用程式角色

將使用者指派給應用程式角色

設定應用程式 （java-servlet-webapp-roles） 以使用您的應用程式註冊

建置範例

部署範例

探索範例

關於程式碼

目錄

在標識元令牌中處理角色宣告

ConfidentialClientApplication

逐步解說

保護路由

範圍

其他相關資訊

後續步驟

意見反應

其他資源

註冊應用程式（java-servlet-webapp-roles）

設定應用程式（java-servlet-webapp-roles）以使用您的應用程式註冊