共用方式為

為什麼要更新至Microsoft身分識別平臺 （v2.0）？

  • 發行項

開發新的應用程式時，請務必瞭解Microsoft身分識別平臺 （v2.0） 與 Azure Active Directory （v1.0） 端點之間的差異。 本文涵蓋端點與Microsoft身分識別平臺的一些現有限制之間的主要差異。

誰可以登入

誰可以使用 v1.0 和 v2.0 端點登入

  • v1.0 端點只允許公司與學校帳戶登入您的應用程式 （Azure AD）
  • Microsoft 身分識別平臺端點，允許來自 Microsoft Entra ID 的工作和學校帳戶，以及個人 Microsoft 帳戶（即 MSA），如 hotmail.com、outlook.com 和 msn.com，進行登入。
  • 這兩個端點也接受 來賓使用者的登入， 設定為 單一租使用者 的應用程式Microsoft Entra 目錄，或針對設定為指向租使用者特定端點的應用程式 多租使用者 應用程式登入（https://login.microsoftonline.com/{TenantId_or_Name}）。

Microsoft身分識別平臺端點可讓您撰寫應用程式，以接受來自個人Microsoft帳戶和公司與學校帳戶的登入。 這可讓您撰寫完全與帳戶無關的應用程式。 例如，如果您的 app 呼叫 Microsoft Graph，某些額外的功能和數據將可用於工作帳戶，例如其 SharePoint 網站或目錄數據。 但對於許多動作，例如 讀取使用者的郵件，相同的程式代碼可以存取個人和工作和學校帳戶的電子郵件。

針對 Microsoft 身分識別平台端點，您可以使用 Microsoft 驗證圖書館（MSAL）來存取消費者、教育及企業領域。 Azure AD v1.0 端點只接受來自公司與學校帳戶的登入。

需要使用 Azure AD v1.0 端點的應用程式，才能事先指定其所需的 OAuth 2.0 許可權，例如：

顯示許可權註冊 UI 的範例

直接在應用程式註冊上設定的許可權是 固定的。 雖然在 Azure 入口網站中定義應用程式的靜態使用權限，可讓程式碼保持簡潔，但它可能為開發人員帶來一些問題：

  • 應用程式必須在使用者第一次登入時要求可能會需要的所有權限。 這會導致一長串的權限，讓使用者不願意在初始登入時核准應用程式的存取。

  • 應用程式必須事先知道可能會存取的所有資源。 很難建立可存取任意數目資源的應用程式。

透過Microsoft身分識別平臺端點，您可以忽略 Azure 入口網站中應用程式註冊資訊中定義的靜態許可權，並改為以累加方式要求許可權，這表示在客戶使用其他應用程式功能時，要求一組最少的許可權，並隨著時間增加而增加。 若要這樣做，您可以在要求存取令牌時，在 scope 參數中包含新的範圍，而不需要在應用程式註冊資訊中預先定義這些範圍，即可隨時指定應用程式所需的範圍。 如果使用者尚未同意新增至要求的新範圍，系統會提示他們只同意新的許可權。 若要深入瞭解，請參閱 許可權、同意和範圍。

允許應用程式透過 scope 參數動態要求許可權，可讓開發人員完全掌控用戶體驗。 您也可以預先載入同意體驗，並在一個初始授權要求中要求所有許可權。 如果您的應用程式需要大量的許可權，您可以累加收集使用者的許可權，因為他們嘗試在一段時間內使用應用程式的某些功能。

代表組織完成的管理員同意仍然需要為應用程式註冊的靜態許可權，因此如果您需要系統管理員代表整個組織同意，您應該在應用程式註冊入口網站中為應用程式設定這些許可權。 這可減少組織管理員設定應用程式所需的週期。

範圍，而非資源

對於使用 v1.0 端點的應用程式，應用程式可以做為 資源或令牌收件者。 資源可以定義一些 範圍， 或 oAuth2Permissions 它瞭解，讓用戶端應用程式向該資源要求特定範圍的令牌。 請將 Microsoft Graph API 視為資源的範例：

  • 資源標識碼或 AppID URI：https://graph.microsoft.com/
  • 範圍，或 oAuth2Permissions：Directory.Read、Directory.Write等。

這適用於Microsoft身分識別平臺端點。 應用程式仍可做為資源、定義範圍，並由 URI 識別。 用戶端應用程式仍然可以要求存取這些範圍。 不過，用戶端要求這些許可權的方式已變更。

針對 v1.0 端點，對 Azure AD 的 OAuth 2.0 授權要求可能看起來如下：

GET https://login.microsoftonline.com/common/oauth2/authorize?
client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&resource=https://graph.microsoft.com/
...

在這裡，資源 參數指出用戶端應用程式要求授權的資源。 Azure AD 會根據 Azure 入口網站中的靜態組態計算應用程式所需的許可權，並據以發行令牌。

對於使用 Microsoft 身分識別平臺端點的應用程式，相同的 OAuth 2.0 授權要求看起來如下：

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&scope=https://graph.microsoft.com/directory.read%20https://graph.microsoft.com/directory.write
...

在這裡，範圍 參數會指出應用程式要求授權的資源和許可權。 所需的資源仍存在於要求中， 它包含在範圍參數的每個值中。 以這種方式使用 scope 參數可讓Microsoft身分識別平臺端點更符合 OAuth 2.0 規格，並更貼近常見的產業做法。 它也可讓應用程式執行 累加式同意 -- 只有在應用程式需要許可權時，才要求許可權，而不是預先要求許可權。

已知的範圍

離線存取

使用 Microsoft 身分識別平臺端點的應用程式可能需要使用一項新的常用許可權範圍 - offline_access。 如果使用者需要代表使用者存取資源一段時間，即使使用者可能未主動使用應用程式，所有應用程式都需要要求此許可權。 offline_access 範圍會在同意對話框中顯示為 隨時存取您的資料，使用者必須同意。 要求 offline_access 許可權可讓 Web 應用程式從Microsoft身分識別平臺端點接收 OAuth 2.0 refresh_tokens。 重新整理權杖具有長時間效力，並可用來交換新的 OAuth 2.0 存取權杖以延長存取時間。

如果您的應用程式未要求 offline_access 範圍，則不會收到刷新令牌。 這表示當您在 OAuth 2.0 授權碼流程中兌換授權碼時，您只會從 /token 端點接收存取令牌。 該存取令牌在短時間內仍然有效（通常是一小時），但最終會過期。 屆時，您的應用程式必須將使用者重新導向回 /authorize 端點，以擷取新的授權碼。 在此重新導向期間，使用者可能或可能不需要再次輸入其認證或重新登入許可權，視應用程式類型而定。

若要深入瞭解 OAuth 2.0、refresh_tokens和 access_tokens，請參閱 Microsoft 身分識別平臺通訊協議參考。

OpenID、個人資料和電子郵件

在過去，使用 Microsoft 身分平台的最基本 OpenID Connect 登入流程，會在產生的 id_token中提供大量的使用者信息。 id_token中的宣告可以包含使用者的名稱、慣用的使用者名稱、電子郵件地址、物件識別碼等等。

openid 範圍提供您應用程式存取權的信息現在受到限制。 openid 範圍只會允許您的應用程式登入使用者，並接收使用者的應用程式特定標識碼。 如果您想要取得應用程式中使用者的相關個人資料，您的應用程式必須向使用者要求其他許可權。 兩個新的範圍，email 和 profile，可讓您要求額外的許可權。

  • email 範圍可讓您的應用程式透過id_token中的 email 宣告存取使用者的主要電子郵件位址，假設使用者具有可尋址的電子郵件位址。
  • profile scope 可讓您的應用程式存取使用者的所有基本資訊，例如姓名、慣用使用者名稱、對象ID等，這些資訊位於id_token中。

這些範圍可讓您以最少披露的方式撰寫應用程式程式代碼，因此您只能要求使用者提供應用程式執行其工作所需的資訊集。 如需這些範圍的詳細資訊，請參閱 Microsoft 身分識別平臺範圍參考。

令牌宣告

預設情況下，Microsoft 身分識別平台端點會在其令牌中發出較少的宣告，以減少負載。 如果您的應用程式和服務依賴於 v1.0 令牌中的特定宣告，而該宣告在 Microsoft 身分識別平台的令牌中不再預設提供，請考慮使用 選擇性宣告功能 來包含該宣告。

這很重要

v1.0 和 v2.0 令牌可由 v1.0 和 v2.0 端點發出！ id_tokens 一律 符合其所要求的端點，且存取令牌 一律 符合用戶端使用該令牌呼叫的 Web API 預期格式。 因此，如果您的應用程式使用 v2.0 端點來取得令牌來呼叫 Microsoft Graph，其需要 v1.0 格式存取令牌，則您的應用程式會收到 v1.0 格式的令牌。

局限性

使用Microsoft身分識別平臺時，有一些需要注意的限制。

當您建置與Microsoft身分識別平臺整合的應用程式時，您必須決定Microsoft身分識別平臺端點和驗證通訊協定是否符合您的需求。 v1.0 端點和平臺仍受到完整支援，在某些方面，功能比Microsoft身分識別平臺更豐富。 不過，Microsoft身分識別平臺 為開發人員帶來顯著 優勢。

以下是適用於開發人員的簡化建議：

  • 如果您想要或需要支援應用程式中的個人Microsoft帳戶，或撰寫新的應用程式，請使用Microsoft身分識別平臺。 但在進行之前，請確定您已瞭解本文所討論的限制。
  • 如果您要移轉或更新依賴 SAML 的應用程式，則無法使用Microsoft身分識別平臺。 請改為參閱 Azure AD v1.0 指南，。

Microsoft身分識別平臺端點會演進以消除此處所列的限制，因此您只需要使用Microsoft身分識別平臺端點。 同時，使用本文來判斷Microsoft身分識別平臺端點是否適合您。 我們會繼續更新本文，以反映Microsoft身分識別平臺端點的目前狀態。 請回頭查看，以針對Microsoft身分識別平臺功能重新評估您的需求。

應用程式註冊的限制

在 Azure 入口網站中，您可以在新的 應用程式註冊體驗 中，為您想要與 Microsoft 身分識別平臺端點整合的每個應用程式建立應用程式註冊。 現有的 Microsoft 帳戶應用程式與入口網站不相容，但所有 Microsoft Entra 應用程式都相容，無論其註冊的時間或地點。

支援公司與學校帳戶和個人帳戶的應用程式註冊有下列注意事項：

  • 每個應用程式識別碼只允許兩個應用程式秘密。
  • 未在租用戶中註冊的應用程式只能由註冊它的帳戶管理。 無法與其他開發人員共用。 在應用程式註冊入口網站中使用個人Microsoft帳戶註冊的大部分應用程式都是如此。 如果您想要與多個開發人員共用應用程式註冊，請使用 Azure 入口網站中新的 應用程式註冊 區段，在租用戶中註冊應用程式。
  • 允許重新導向 URL 的格式有數個限制。 如需重新導向 URL 的詳細資訊，請參閱下一節。

重新導向URL的限制

如需最新的 up-to有關註冊 Microsoft 身分識別平台應用程式的重新導向 URL 限制的資訊，請參閱 Microsoft 身分識別平台文檔中的 重新導向 URI/回覆 URL 限制和 限制。

若要瞭解如何註冊應用程式以搭配Microsoft身分識別平臺使用，請參閱 使用新的應用程式註冊體驗註冊應用程式。

函式庫和 SDK 的限制

目前，對於Microsoft身份驗證平台端點的程式庫支援仍然有限。 如果您想要在生產應用程式中使用Microsoft身分識別平台端點，您有下列選項：

  • 如果您要建置 Web 應用程式，則可以安全地使用一般可用的伺服器端中間件來執行登入和令牌驗證。 其中包括適用於 ASP.NET 和 Node.js Passport 外掛程式的 OWIN OpenID Connect 中間件。 如需使用 Microsoft 中間件的程式代碼範例，請參閱 Microsoft 身分識別平台入門 一節。
  • 如果您要建置桌面或行動應用程式，您可以使用其中一個 Microsoft 驗證程式庫（MSAL）。 這些連結庫已正式推出，或在生產環境支援的預覽版中，因此在生產應用程式中使用連結庫是安全的。 您可以在 驗證連結庫參考中深入瞭解預覽條款和可用的連結庫。
  • 針對Microsoft連結庫未涵蓋的平臺，您可以直接在應用程式程式代碼中傳送和接收通訊協定訊息，與Microsoft身分識別平臺端點整合。 OpenID Connect 和 OAuth 通訊協定 會明確記載，以協助您進行這類整合。
  • 最後，您可以使用開放原始碼 OpenID Connect 和 OAuth 連結庫來與Microsoft身分識別平臺端點整合。 Microsoft身分識別平臺端點應該與許多開放原始碼通訊協定連結庫相容，而不需要變更。 這類連結庫的可用性會因語言和平台而異。 OpenID Connect 和 OAuth 2.0 網站會維護熱門實作的清單。 如需詳細資訊，請參閱 Microsoft身分識別平臺和驗證連結庫，以及已使用 Microsoft 身分識別平臺端點測試的開放原始碼用戶端連結庫和範例清單。
  • 供參考，Microsoft 身分識別平台的通用端點 .well-known 的端點是 https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration。 將 common 替換為您的租戶 ID，以取得您租戶特定的數據。

通訊協定變更

Microsoft身分識別平臺端點不支援 SAML 或 WS-Federation;它只支援 OpenID Connect 和 OAuth 2.0。 V1.0 端點中 OAuth 2.0 通訊協議的顯著變更如下：

  • 如果配置了選擇性宣告 或在要求中指定了 scope=email，則會傳回 email 宣告。
  • 現在支援 scope 參數取代 resource 參數。
  • 許多響應已經過修改，使其更符合 OAuth 2.0 規格的規範，例如，正確地將 expires_in 傳回為 int，而不是字串。

若要進一步瞭解Microsoft身分識別平臺端點中支援的通訊協定功能範圍，請參閱 OpenID Connect 和 OAuth 2.0 通訊協議參考。

SAML 使用量

如果您在 Windows 應用程式中使用過 Active Directory 驗證庫 (ADAL)，可能曾利用 Windows 整合式驗證，這種驗證方式使用了安全性聲明標記語言 (SAML) 的聲明授權。 透過此授權，聯邦 Microsoft Entra 租戶的用戶可在不輸入認證的情況下，自動與內部部署 Active Directory 實例進行驗證。 雖然 SAML 仍然是支援與企業使用者搭配使用的通訊協定，但 v2.0 端點只適用於 OAuth 2.0 應用程式。

後續步驟

若要深入瞭解，請參閱 Microsoft 身分識別平台檔案。