共用方式為

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

  • 發行項

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

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

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

取得令牌時的範圍

範圍是 Web API 公開的用戶端應用程式可以要求存取的許可權。 用戶端應用程式在提出驗證要求以取得令牌以存取 Web API 時，要求使用者同意這些範圍。 MSAL 可讓您取得令牌，以存取適用於開發人員的 Azure AD（v1.0）和 Microsoft 身分識別平台 API。 v2.0 通訊協定會使用範圍，而不是要求中的資源。 根據 Web API 所接受之令牌版本的組態，v2.0 端點會將存取令牌傳回 MSAL。

MSAL 的數個 scopes 令牌擷取方法需要參數。 參數 scopes 是一份字串清單，可宣告所需的許可權和所要求的資源。 已知的範圍是 Microsoft Graph 許可權。

MSAL 也可以存取 v1.0 資源。 如需詳細資訊，請參閱 v1.0 應用程式的範圍。

要求 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 應用程式中的授權碼流程，因為它會兌換應用程式透過登入使用者取得的程式代碼，並讓他們同意更多範圍。 由於程式代碼而非帳戶會當做參數傳遞，因此方法在兌換程序代碼之前無法查看快取，這會叫用對服務的呼叫。

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

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

取得權杖

一般而言，取得令牌的方法取決於它是公用用戶端還是機密用戶端應用程式。

公用用戶端應用程式

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

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

機密用戶端應用程式

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

  • 使用客戶端認證流程，取得應用程式本身的令牌，而不是針對使用者取得令牌。 這項技術可用於同步處理工具，或一般處理使用者的工具，而不是特定使用者。
  • 使用代表者 （OBO） 流程，讓 Web API 代表使用者呼叫 API。 應用程式會使用客戶端認證來識別，以便根據使用者判斷提示取得令牌（例如 SAML 或 JWT 令牌）。 需要存取服務對服務呼叫中特定用戶資源的應用程式會使用此流程。
  • 在使用者透過授權要求 URL 登入之後，在 Web 應用程式中使用授權碼流程取得令牌。 OpenID 連線 應用程式通常會使用此機制，讓使用者使用 Open ID connect 登入，然後代表使用者存取 Web API。

驗證結果

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

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