使用 Microsoft 驗證連結庫取得和快取權杖（MSAL）

發行項
02/28/2024

存取令牌可讓用戶端安全地呼叫受 Azure 保護的 Web API。使用 Microsoft 驗證連結庫（MSAL）取得令牌的方法有很多種。有些則需要透過網頁瀏覽器進行用戶互動，有些則不需要用戶互動。通常，用來取得令牌的方法取決於應用程式是公用用戶端應用程式（桌面或行動裝置），還是機密用戶端應用程式（Web 應用程式、Web API 或精靈應用程式）。

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

您也可以從快取中移除帳戶，以清除令牌快取。不過，這不會移除瀏覽器中的會話 Cookie。

取得令牌時的範圍

範圍是 Web API 公開的用戶端應用程式可以要求存取的許可權。用戶端應用程式在提出驗證要求以取得令牌以存取 Web API 時，要求使用者同意這些範圍。 MSAL 可讓您取得令牌來存取 Microsoft 身分識別平台 API。 v2.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://11111111-1111-1111-1111-111111111111/api.read

範圍值的格式會根據接收存取令牌的資源和它接受的 aud 宣告值而有所不同。

僅針對 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）和範圍名稱，例如：

11111111-1111-1111-1111-111111111111/api.read

提示

如果下游資源不在您的控制之下，如果您在將存取令牌傳遞至資源時收到 401 或其他錯誤，您可能需要嘗試不同的範圍值格式（例如含/不含配置和主機）。

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

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

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

MSAL 會維護令牌快取（或兩個機密用戶端應用程式的快取），並在取得令牌之後快取令牌。在許多情況下，嘗試以無訊息方式取得令牌時，會根據快取中的令牌取得具有更多範圍的另一個令牌。當令牌接近到期時，它也能夠重新整理令牌（因為令牌快取也包含重新整理令牌）。

公用用戶端應用程式的建議呼叫模式

應用程式原始碼應該先嘗試從快取以無訊息方式取得令牌。如果方法呼叫傳回「需要 UI」錯誤或例外狀況，請嘗試以其他方式取得令牌。

有兩個流程 不應該 嘗試以無訊息方式取得令牌：

客戶端認證流程，不會使用使用者令牌快取，而是使用應用程式令牌快取。此方法會先確認應用程式令牌快取，再將要求傳送至安全性令牌服務（STS）。
Web 應用程式中的授權碼流程，因為它會兌換應用程式透過登入使用者取得的程式代碼，並讓他們同意更多範圍。由於程式代碼而非帳戶會當做參數傳遞，因此方法在兌換程序代碼之前無法查看快取，這會叫用對服務的呼叫。

使用授權碼流程的 Web 應用程式中建議的呼叫模式

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

使用自定義串行化來具現化令牌快取的機密用戶端應用程式。
使用授權碼流程取得令牌

取得權杖

取得令牌的方法取決於其為公用用戶端或機密用戶端應用程式。

公用用戶端應用程式

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

讓使用者透過UI或彈出視窗登入，以互動方式取得令牌。
如果桌面應用程式在已加入網域或 Azure 的 Windows 電腦上執行，請使用整合式 Windows 驗證（IWA/Kerberos）以無訊息方式取得登入使用者的令牌。
在 .NET Framework 傳統型用戶端應用程式中取得具有使用者名稱和密碼的令牌（不建議使用）。請勿在機密用戶端應用程式中使用使用者名稱/密碼。
在沒有網頁瀏覽器的裝置上執行的應用程式中，透過裝置程式代碼流程取得令牌。使用者會提供 URL 和程式碼，然後前往另一部裝置上的網頁瀏覽器並輸入程式碼並登入。然後，Microsoft Entra ID 會將令牌傳回至無瀏覽器裝置。

機密用戶端應用程式

針對機密用戶端應用程式（Web 應用程式、Web API 或 Windows 服務之類的精靈應用程式），您可以;

使用客戶端認證流程，取得應用程式本身的令牌，而不是針對使用者取得令牌。這項技術可用於同步處理工具，或一般處理使用者的工具，而不是特定使用者。
使用代表者（OBO）流程，讓 Web API 代表使用者呼叫 API。應用程式會使用客戶端認證來識別，以便根據使用者判斷提示取得令牌（例如 SAML 或 JWT 令牌）。需要存取服務對服務呼叫中特定用戶資源的應用程式會使用此流程。令牌應該以會話為基礎快取，而不是以用戶為基礎。
在使用者透過授權要求 URL 登入之後，在 Web 應用程式中使用授權碼流程取得令牌。 OpenID 連線應用程式通常會使用此機制，讓使用者使用 OpenID 連線登入，然後代表使用者存取 Web API。令牌可以在使用者或會話的基礎上快取。如果以用戶為基礎快取令牌，建議您限制會話存留期，讓 Microsoft Entra ID 可以經常檢查條件式存取原則的狀態。

驗證結果

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

Web API 存取資源的存取令牌。此字串通常是Base64編碼的JWT，但客戶端不應該在存取令牌內查看。格式不保證會保持穩定，而且可以加密資源。人員根據用戶端上的存取令牌內容撰寫程序代碼，是最常見的錯誤來源之一和客戶端邏輯中斷。
用戶的標識碼令牌（JWT）。
權杖到期日，說明權杖到期的日期/時間。
租用戶識別碼包含在其中找到使用者的租用戶。對於來賓使用者（Microsoft Entra B2B 案例），租使用者標識碼是來賓租使用者，而不是唯一租使用者。當令牌以使用者名稱傳遞時，驗證結果也會包含此使用者的相關信息。對於要求令牌且沒有使用者（針對應用程式）的機密用戶端流程，此使用者資訊為 Null。
核發權杖的範圍。
使用者的唯一識別碼。

（進階）在背景應用程式和服務中存取使用者的快取令牌

您可以使用 MSAL 的令牌快取實作，允許背景應用程式、API 和服務使用存取令牌快取繼續代表使用者不在時採取行動。如果背景應用程式和服務在用戶結束前端 Web 應用程式之後，必須繼續代表使用者工作，則這樣做特別有用。

現今，大部分的背景進程在需要與用戶的數據搭配使用時，會使用應用程式許可權，而不需要他們存在即可進行驗證或重新驗證。因為應用程式許可權通常需要系統管理員同意，這需要提高許可權，因此開發人員不想取得使用者原本同意其應用程式的許可權，因此遇到不必要的摩擦。

GitHub 上的此程式碼範例示範如何透過從背景應用程式存取 MSAL 的令牌快取來避免這種不必要的摩擦：

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

另請參閱

MSAL 支援的數個平臺在該平台連結庫的檔中有其他令牌快取相關信息。例如：

使用 Microsoft 驗證連結庫取得和快取權杖 （MSAL）