使用 Microsoft 驗證程式庫 (MSAL) 取得和快取權杖

  • 發行項

存取權杖可讓用戶端安全地呼叫受 Azure 保護的 Web API。 有數種方法可使用 Microsoft 驗證程式庫 (MSAL) 取得權杖。 有些方法需要使用者透過網頁瀏覽器進行互動，而其他方法則不需要使用者互動。 通常用來取得權杖的方法取決於應用程式是公用用戶端應用程式 (桌面或行動裝置)，還是保密用戶端應用程式 (Web 應用程式、Web API 或精靈應用程式)。

MSAL 會在取得權杖之後建立其快取。 您的應用程式程式碼應該先嘗試從快取以無訊息方式取得權杖，然後再嘗試以其他方式取得權杖。

您也可以清除權杖快取，方法是將此帳戶從快取中移除。 不過，這不會移除瀏覽器中的工作階段 cookie。

取得權杖時的範圍

範圍是 Web API 所公開，讓用戶端應用程式可要求其存取權的權限。 用戶端應用程式在提出驗證要求以取得 Web API 的存取權杖時，會要求使用者同意這些範圍。 MSAL 可讓您取得權杖，以存取 Microsoft 身分識別平台 API。 2.0 版通訊協定會使用範圍而非要求中的資源。 根據其所接受的 Web API 權杖版本組態，v2.0 端點會對 MSAL 傳回存取權杖。

有幾種 MSAL 的權杖取得方法需要 scopes 參數。 scopes 參數是字串清單，其宣告所需權限和要求的資源。 知名的範圍是 Microsoft Graph 權限。

Web API 的要求範圍

當應用程式必須對資源 API 要求具有特定權限的存取權杖時，您必須使用格式 <app ID URI>/<scope> 傳遞包含 API 應用程式識別碼 URI 的範圍。

不同資源的一些範例範圍值：

  • Microsoft Graph API：https://graph.microsoft.com/User.Read
  • 自訂 Web API：api://00001111-aaaa-2222-bbbb-3333cccc4444/api.read

範圍值格式會根據接收存取權杖及其接受的 aud 宣告值的資源 (API) 而有所不同。

僅限 Microsoft Graph，user.read 範圍會對應至 https://graph.microsoft.com/User.Read，而且這兩種範圍格式可交替使用。

某些 Web API，例如 Azure Resource Manager API (https://management.core.windows.net/) 預期存取權杖的對象宣告 (aud) 中要有正斜線 (/)。 在此情況下，請將範圍傳遞為 https://management.core.windows.net//user_impersonation，包括兩個正斜線 (//)。

其他 API 可能會要求範圍值中不包含任何配置或主機，而且只預期應用程式識別碼 (GUID) 和範圍名稱，例如：

00001111-aaaa-2222-bbbb-3333cccc4444/api.read

提示

如果下游資源不在您的控制下，且在傳遞存取權杖至資源時收到 401 或其他錯誤，則您可能需要嘗試不同的範圍值格式 (例如，有/沒有配置和主機)。

當您的應用程式所提供的功能或其需求變更時，您可以視需要使用 scope 參數來要求其他權限。 這類動態範圍可讓您的使用者對範圍提供累加式同意。

例如，您可能會登入使用者，但一開始拒絕讓他們存取任何資源。 稍後，您可以在取得權杖方法中要求行事曆範圍，並取得使用者的同意，讓他們能夠查看其行事曆。 例如，藉由要求 https://graph.microsoft.com/User.Read 和 https://graph.microsoft.com/Calendar.Read 範圍。

以無訊息方式從快取中取得權杖

MSAL 會保有一個權杖快取 (若為機密用戶端應用程式，則有兩個快取)，並在取得權杖之後建立其快取。 在許多情況下，嘗試以無訊息方式取得權杖將會取得另一個具有多個範圍的權杖 (根據快取中的權杖而定)。 快取也可以在即將到期時重新整理權杖 (因為權杖快取也會包含重新整理權杖)。

應用程式原始程式碼應該會先試著以無訊息方式從快取中取得權杖。 如果方法呼叫傳回「需要 UI」錯誤或例外狀況，則會嘗試透過其他方式取得權杖。

不過，請勿在下列兩個流程中嘗試以無訊息方式取得權杖：

  • 用戶端認證流程，這不會使用使用者的權杖快取，而會使用應用程式的權杖快取。 這個方法會先負責確認此應用程式的權杖快取，再對 Security Token Service (STS) 傳送要求。
  • Web Apps 中的授權碼流程，因為此流程會兌換應用程式藉由將使用者登入、再讓其同意更多範圍而獲得的授權碼。 因為授權碼會以參數 (而非帳戶) 形式傳遞，該方法無法在兌換授權碼之前先查看快取，因為這麼做需要叫用服務呼叫。

對於使用 OpenID Connect 授權碼流程的 Web 應用程式，控制器中的建議模式是：

  • 使用自訂序列化以權杖快取具現化機密用戶端應用程式。
  • 使用授權碼流程取得權杖

取得權杖

取得權杖的方法取決於其為公用用戶端應用程式還是保密用戶端應用程式。

公用用戶端應用程式

在公用用戶端應用程式中 (桌面和行動裝置)，您可以：

  • 讓使用者透過 UI 或快顯視窗登入，以互動方式取得權杖。
  • 使用整合式 Windows 驗證 (IWA/Kerberos) 來為已登入的使用者以無訊息方式取得權杖 (如果傳統型應用程式是在加入網域或 Azure 的 Windows 電腦上執行)。
  • 在 .NET Framework 桌面用戶端應用程式中以使用者名稱和密碼取得權杖 (不建議)。 請勿在機密用戶端應用程式中使用使用者名稱/密碼。
  • 在執行於裝置上且沒有網頁瀏覽器的應用程式中，透過裝置代碼流程取得權杖。 使用者會獲得 URL 和代碼，接著便能前往其他裝置上的網頁瀏覽器，然後輸入代碼並登入。 Microsoft Entra ID 接著會將權杖傳回給無瀏覽器的裝置。

機密用戶端應用程式

若為保密用戶端應用程式 (Web 應用程式、Web API 或精靈應用程式，如 Windows 服務)，則您可以；

  • 可以使用用戶端認證流程取得應用程式本身而非使用者的權杖。 此技術可用於同步工具，或用於會處理整體使用者而非特定使用者的工具。
  • 使用代理者 (OBO) 流程，讓 Web API 代表使用者呼叫 API。 應用程式會使用用戶端認證來識別，以根據使用者判斷提示來取得權杖 (例如 SAML，或 JWT 權杖)。 需要在服務對服務的呼叫中存取特定使用者資源的應用程式會使用此流程。 應以工作階段為基礎 (而不是以使用者為基礎) 對權杖進行快取。
  • 可以在使用者透過授權要求 URL 來登入後，於 Web 應用程式中使用授權碼流程來取得權杖。 OpenID Connect 應用程式一般會使用這個機制，這可以讓使用者使用 OpenID Connect 登入，然後代表使用者存取 Web API。 能夠以使用者或工作階段的基礎對權杖進行快取。 如果以使用者為基礎快取權杖，建議您限制工作階段存留期，以便 Microsoft Entra ID 可以經常檢查條件式存取原則的狀態。

驗證結果

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

  • Web API 用來存取資源的存取權杖。 這個字串通常是以 Base64 編碼的 JWT，但用戶端永遠不該查看存取權杖內部。 此格式不保證會維持穩定，並可針對資源將其加密。 根據用戶端上的存取權杖內容來撰寫程式碼的人員，是發生錯誤和用戶端邏輯破碎的最常見來源之一。
  • 使用者的識別碼權杖 (JWT)。
  • 權杖到期日，說明權杖到期的日期/時間。
  • 租用戶識別碼包含在其中找到使用者的租用戶。 針對來賓使用者 (Microsoft Entra B2B 案例)，租用戶識別碼是來賓租用戶，而非唯一租用戶。 當權杖透過使用者名稱傳遞時，驗證結果也會包含此使用者的相關資訊。 對於不會向使用者要求權杖的機密用戶端流程 (針對應用程式)，此使用者資訊是 Null。
  • 核發權杖的範圍。
  • 使用者的唯一識別碼。

(進階) 在背景應用程式和服務中存取使用者的快取權杖

您可以使用 MSAL 的權杖快取執行，讓背景應用程式、API 和服務可以使用存取權杖快取，以繼續代表使用者執行動作。 如果背景應用程式和服務需要在使用者結束前端 Web 應用程式之後，以使用者身分繼續工作，這項功能就特別有用。

目前，大部分的背景程序在需要用到使用者資料時都會使用應用程式權限，而不需要提供驗證或重新驗證。 因為應用程式權限通常需要管理員同意 (需要提高權限)，所以開發人員不想取得使用者原本同意其應用程式的權限時，就會發生不必要的分歧。

此 GitHub 程式碼範例顯示如何從背景應用程式存取 MSAL 的權杖快取，以避免這種不必要的摩擦：

從背景應用程式、API 和服務存取已登入使用者的權杖快取

另請參閱

MSAL 支援的數個平台在該平台程式庫的文件中有額外的權杖快取相關資訊。 例如：