使用 Microsoft 驗證程式庫授與 API 的存取權

5 分鐘

現在，您可以將公司的使用者登入 Web 應用程式。接下來，您想要在頁面上顯示員工設定檔中的資訊，例如其職稱、工作電子郵件等等。您會發現 Microsoft Graph API 提供了使用者相關資料的存取權。

在此單元中，您將了解 MSAL 如何協助您取得如 Microsoft Graph API 等 Microsoft 服務的授權存取權。

API 權限和範圍

受 Microsoft Entra ID 保護的 Web 服務會定義一組權限，提供對於該服務所公開的 API 功能和資料的存取。應用程式可向使用者和系統管理員要求這些權限，且必須在他們核准要求後，應用程式才可存取資料或代表使用者執行動作。例如，Microsoft Graph 已定義權限來執行下列工作，以及其他工作：

讀取使用者的行事曆
寫入使用者的行事曆
以使用者身分傳送電子郵件

使用者和系統管理員可以施加控制，並了解應用程式可存取的資料。在您的應用程式可存取由 Microsoft 保護的 API 之前，您必須提供執行該動作的應用程式權限。

Microsoft Entra ID 支援兩種類型的權限：委派權限和應用程式權限。

委派權限供已有登入使用者的應用程式使用。針對這些應用程式，使用者或系統管理員須同意應用程式所要求的權限。應用程式會獲得委派權限，讓其在呼叫目標 API 時以登入使用者的身分行事。某些高特殊權限需要系統管理員同意。
應用程式權限供不需使用者登入即可執行的應用程式使用；例如，當作背景服務或精靈來執行的應用程式。只有管理員可以同意應用程式權限。

您可以從 Azure 入口網站將這些 API 權限指派給您的應用程式註冊。

範圍

Microsoft Entra ID 會實作 OAuth 2.0 授權通訊協定，這是可讓應用程式代表使用者存取 Web 主控資源的通訊協定。

在 OAuth 2.0 中，這些類型的權限集合稱為「範圍」。向 Microsoft Entra ID 提出授權要求時，應用程式會在要求的 scope 查詢參數中指定權限，以要求其所需的權限。例如，範圍值 https://graph.microsoft.com/Calendars.Read 可用來要求在 Microsoft Graph 中讀取使用者行事曆的權限。

透過 MSAL 取得存取權杖

存取權杖可讓用戶端應用程式安全地呼叫受 Microsoft Entra ID 保護的 Web API。您可透過數種方式使用 Microsoft 驗證程式庫 (MSAL) 取得存取權杖。一般情況下，用來取得權杖的方法取決於應用程式是公用用戶端應用程式 (例如，桌面或行動應用程式)，還是機密用戶端應用程式 (如 Web 應用程式、Web API 或精靈應用程式)。

有幾個 MSAL 的權杖取得方法需要 scopes 參數，這是一份字串清單，用來宣告所需的權限和要求的資源。

適用於 Web 應用程式的建議呼叫模式

MSAL 會在取得權杖之後加以快取。對於使用 OpenID Connect 授權碼流程的 Web 應用程式，控制器中建議的模式為：

先嘗試以無訊息方式從快取取得權杖，再嘗試以其他方式取得權杖。下列程式碼是從 AuthHelper 類別中實作 acquireTokenSilently 方法的摘錄。

final SilentParameters parameters = SilentParameters
                                        .builder(Collections.singleton(Config.SCOPES), context.getAccount())
                                        .build();

final ConfidentialClientApplication client = getConfidentialClientInstance();

client.tokenCache().deserialize(context.getTokenCache());

final IAuthenticationResult result = client.acquireTokenSilently(parameters).get();

如果快取中沒有權杖，且無訊息權杖要求無法取得權杖，您可以使用授權碼流程來取得權杖：

final AuthorizationCodeParameters authParams = AuthorizationCodeParameters
                                                    .builder(authCode, new URI(Config.REDIRECT_URI)).scopes(Collections.singleton(Config.SCOPES))
                                                    .build();

final IAuthenticationResult result = app.acquireToken(authParams).get();

MSAL 也能夠在權杖即將到期時重新整理權杖，(因為權杖快取也包含重新整理權杖)。

驗證結果

當用戶端要求存取權杖時，Microsoft Entra ID 也會傳回驗證結果，其中包括關於存取權杖的中繼資料。此資料可讓您的應用程式執行存取權杖的智慧型快取，而無須剖析存取權杖本身。 MSAL 傳回的 AuthenticationResult 會公開：

Web API 的存取權杖。
使用者的識別碼權杖 (JWT)。
權杖到期日，說明權杖到期的日期/時間。
租用戶識別碼包含在其中找到使用者的租用戶。
核發權杖的範圍。
使用者的唯一識別碼。

Microsoft Graph 簡介

Microsoft Graph API 提供了單一端點 https://graph.microsoft.com，可讓您存取 Microsoft 雲端中豐富、以人為中心的資料和深入解析。您可以使用 REST API 或 SDK 來存取端點，並建置支援 Microsoft 365 案例的應用程式，範圍涵蓋生產力、共同作業、教育、人員和工作場所智慧等等。 Microsoft Graph 也包含一組功能強大的服務，可管理使用者和裝置身分識別。

例如，您可藉由存取 https://graph.microsoft.com/v1.0/me 端點來讀取登入使用者的屬性。