啟用 Java Spring Boot 應用程式以登入使用者並存取 Microsoft Graph

本文示範 Java Spring Boot Web 應用程式，可登入使用者並取得呼叫 Microsoft Graph 的存取令牌。 它會使用適用於 Java 的 Microsoft Entra ID Spring Boot Starter 用戶端連結庫進行驗證、授權和令牌取得。 它會使用 適用於 Java 的 Microsoft Graph SDK，從 Graph 取得數據。

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

應用程式會使用適用於 Java 的 Microsoft Entra ID Spring Boot Starter 用戶端連結庫，從 Microsoft Entra ID 取得 Microsoft Graph 的存取令牌。 存取令牌證明用戶有權存取範圍中所定義的 Microsoft Graph API 端點。

必要條件

• JDK 第 15 版。 此範例是在 Java 15 的系統上開發，但可能與其他版本相容。
• Maven 3
• 建議使用適用於Visual Studio Code的 Java 擴充套件，在Visual Studio Code 中執行此範例。
• Microsoft Entra ID 租用戶。 如需詳細資訊，請參閱 如何取得Microsoft Entra ID 租使用者。
• 您Microsoft Entra ID 租使用者中的用戶帳戶。 此範例不適用於個人Microsoft帳戶。 因此，如果您使用個人帳戶登入 Azure 入口網站，而且目錄中沒有用戶帳戶，您現在必須建立一個帳戶。
• 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/2-Authorization-I/call-graph

或者，流覽至 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-call-graph）

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

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

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

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

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

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

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

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

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

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

9. 選取其中一個可用的持續時間： 在1年、 2年內或 永不過期。

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

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

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

13. 選取 [ 新增許可權]，然後確定 已選取 [Microsoft API] 索引 標籤。

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

15. 在 [ 委派的許可權] 區段中，從清單中選取 [User.Read ]。 如有需要請使用搜尋方塊。

16. 選取新增權限。

設定應用程式 （java-spring-webapp-call-graph） 以使用您的應用程式註冊

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

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-call-graph應用程式。

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

執行範例

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. 選取 [呼叫 Graph ] 來呼叫 Microsoft Graph 的 /me 端點 ，並查看取得的使用者詳細數據。
9. 使用角落中的按鈕註銷。狀態頁面會反映新狀態。

關於程式碼

此範例示範如何使用 適用於 Java 的 Microsoft Entra ID Spring Boot Starter 用戶端連結庫，將使用者登入您的 Microsoft Entra ID 租使用者，並取得呼叫 Microsoft Graph 的存取令牌。 此範例也會使用 Spring Oauth2 用戶端和 Spring Web 開機入門。

目錄

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

標識元令牌宣告

為了擷取令牌詳細數據，應用程式會在要求對應中使用 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();
}

登入和註銷連結

針對登入，應用程式會向 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 保護路由

根據預設，應用程式會保護標識元令牌詳細數據和呼叫圖形頁面，以便只有登入的使用者才能存取它們。 應用程式會從 application.yml 檔案中的 app.protect.authenticated 屬性設定這些路由。 若要設定應用程式的特定需求，您可以在其中一個類別中擴充 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, /call_graph)
      .antMatchers("/**").permitAll();                  // allow all other routes.
    }
}

呼叫圖表

當使用者流覽至 /call_graph時，應用程式會使用 Oauth2AuthorizedClient 建立的實例，或是graphAuthorizedClientMicrosoft Entra ID 開機啟動器已備妥的 實例GraphServiceClient。 應用程式會要求 GraphServiceClient 呼叫端點， /me 並顯示目前登入使用者的詳細數據。 GraphServiceClient 來自 適用於 Java 的 Microsoft Graph SDK v3。

Oauth2AuthorizedClient必須備妥正確的範圍。 請參閱application.yml檔案和下列範圍一節。 Oauth2AuthorizedClient用來呈現存取令牌，並將其放在要求的標頭GraphServiceClient中Authorization，如下列範例所示：

//see SampleController.java
@GetMapping(path = "/call_graph")
public String callGraph(@RegisteredOAuth2AuthorizedClient("graph") OAuth2AuthorizedClient graphAuthorizedClient) {
  // See the Utilities.graphUserProperties() method for the full example of the following operation:
  GraphServiceClient graphServiceClient = Utilities.getGraphServiceClient(graphAuthorizedClient);
  User user = graphServiceClient.me().buildRequest().get();
  return user.displayName;
}

下列來自 application.yml 檔案的 範例會顯示所要求的範圍：

# see application.yml file
authorization-clients:
  graph:
    # Specifies the Microsoft Graph scopes that your app needs access to:
    scopes: https://graph.microsoft.com/User.Read

範圍

範圍會告訴Microsoft Entra標識符應用程式所要求的存取層級。 如需此應用程式所要求的Microsoft Graph 範圍，請參閱 application.yml。

根據預設，應用程式會將範圍值設定為 https://graph.microsoft.com/User.Read。 範圍User.Read是從 /me 端點存取目前登入用戶的資訊。 對 /me 端點的有效要求必須包含User.Read範圍。

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

在此應用程式中，會顯示 graphAuthorizedClient 可證明使用者同意的範圍的存取令牌。 應用程式會使用此令牌來建立的實例 GraphServiceClient ，以處理 Graph 要求。

使用 GraphServiceClient.me().buildRequest().get()時，會建置並對 提出 https://graph.microsoft.com/v1.0/me要求。 存取令牌會放在 Authorization 要求的標頭中。

其他相關資訊

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

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