受 Microsoft 身分識別同意架構保護的 API 範例

本文可協助您身為開發人員，設計 應用程式許可權策略 以提供 最低許可權。 在繼續之前，請參閱 API 保護 一文，以瞭解註冊、許可權和存取的最佳做法。

讓我們看看受 Microsoft 身分識別平台 保護的 API 如何使用 Microsoft 身分識別同意架構。 我們使用 Microsoft Graph API 作為範例，因為它會使用最廣泛的 Microsoft 身分識別平台 同意架構。

許可權名稱的命名慣例

Microsoft Graph 小組為許可權名稱建立了命名慣例，讓您更輕鬆地將許可權連線到許可權所啟用的資源存取權。 Microsoft Graph 許可權名稱 會遵循簡單的 resource.operation.constraint 模式。 這兩個主要作業是 Read 和 ReadWrite （包括更新和刪除）。

條件 約束 元素會影響應用程式在目錄內的存取程度。 Microsoft Graph 支援下列條件約束：

• 所有 都會授與應用程式的許可權，以在目錄中指定類型的所有資源上執行作業。
• 共用會 授與應用程式的許可權，以對其他使用者與登入使用者共用的資源執行作業。
• AppFolder 會授與應用程式讀取和寫入 OneDrive 中專用資料夾中檔案的許可權。 此條件約束只會在 Files 許可權物件上公開，而且僅適用於 Microsoft 帳戶。
• 如果您指定 [無條件約束]，則應用程式只能對登入使用者所擁有的資源執行作業。

針對特定資源存取和作業

讓我們看看 Microsoft Graph 中用戶物件的一些許可權或範圍，以瞭解 Microsoft API 設計工具如何針對特定資源啟用特定存取和作業：

權限	顯示字串	描述
User.Read	登入和讀取使用者配置檔	允許使用者登入應用程式，並允許應用程式讀取登入使用者的配置檔。 它也允許應用程式讀取登入使用者的基本公司資訊。
User.ReadWrite	使用者配置檔的讀取和寫入存取權	允許應用程式讀取登入使用者的完整配置檔。 它也可讓應用程式代表他們更新登入使用者的配置檔資訊。

User.Read和 User.ReadWrite 存在（與不存在這樣的User.Access單一許可權相反），讓應用程式可以遵循最低許可權的 零信任 原則。 如果開發者沒有更新使用者設定檔的需求和程式碼，則應用程式不會要求 User.ReadWrite。 因此，攻擊者無法入侵應用程式，並用它來變更數據。

請注意， User.Read 不只是為應用程式提供用戶物件的存取權。 每個許可權都代表特定範圍的作業。 開發人員和系統管理員必須閱讀許可權描述，才能確切查看任何特定許可權啟用的內容。 User.Read除了啟用讀取目前使用者的完整配置檔之外，還可讓應用程式查看 Microsoft Graph 中 Organizations 物件的基本資訊。

讓我們看看另一個許可權：

權限	顯示字串	描述
User.ReadBasic.All	讀取所有使用者的基本配置檔	允許應用程式代表登入的使用者讀取組織中其他使用者的基本配置檔屬性集。 包括顯示名稱、名字和系列名稱、電子郵件地址、開啟延伸模組和相片。 允許應用程式讀取已登入使用者的完整配置檔。

作業範圍， User.ReadBasic.All 以執行的所有項目 User.Read 開始。 此外，您可以存取顯示名稱、名字和系列名稱、電子郵件位址、相片，以及為其他組織用戶開啟延伸模組。 特定作業範圍可讓應用程式擁有不錯的人員選擇器 UI，而且是 API 設計工具使用許可權來啟用特定作業範圍的範例。

讓我們看看 Microsoft Graph 使用者物件的更多許可權：

權限	顯示字串	描述
User.Read.All	讀取所有使用者的完整設定檔	允許應用程式代表登入的使用者讀取組織中其他使用者的完整配置檔屬性、報告和管理員。
User.ReadWrite.All	讀取和寫入所有使用者的完整配置檔	允許應用程式代表登入的使用者讀取和寫入組織中其他使用者的完整配置檔屬性、報告和管理員。 也允許應用程式建立和刪除使用者，並代表登入的使用者重設用戶密碼。

與 和 User.ReadUser.ReadWrite一樣，User.Read.All和 User.ReadWrite.All 是不同的許可權，可讓應用程式遵循最低許可權 零信任 原則。

User.Read.All 很有趣，因為組織中的每個使用者都有這項功能（例如，開啟 Outlook、上下報表鏈結）。 身為個人，您可以看到組織中所有其他使用者的完整使用者配置檔。 不過，Microsoft Graph API 設計工具決定只有系統管理員才允許應用程式執行相同的作業，因為 User.Read.All 包含租使用者的組織階層。 如果不良動作專案存取這項資訊，他們可以掛接目標式網路釣魚攻擊，其中網路釣魚電子郵件來自個人的經理或其經理。

User.ReadWrite.All 是強大的作業範圍。 授與此許可權的應用程式可以更新或甚至刪除租使用者中的每個使用者。 作為委派的許可權，當使用者在應用程式前面時，應用程式只能執行目前使用者可以執行的動作。 無論應用程式的許可權為何，一般使用者都無法更新或刪除其他使用者。 不過，當租用戶系統管理員使用應用程式時，他們可以執行這些作業。 決定授與或拒絕此許可權時，您應該考慮使用租用戶系統管理員用戶來評估您的應用程式。

需要管理員同意的許可權

根據 和User.ReadWrite.All的功能User.Read.All，Microsoft Graph API 設計工具會將這些許可權指定為需要系統管理員同意。 讓我們新增 管理員 嗎？權限資料表的數據行，以指出許可權何時需要管理員同意：

權限	顯示字串	描述	管理員？
User.Read	登入和讀取使用者配置檔	允許使用者登入應用程式，並允許應用程式讀取登入使用者的配置檔。 它也允許應用程式讀取登入使用者的基本公司資訊。	否
User.ReadWrite	使用者配置檔的讀取和寫入存取權	允許應用程式讀取登入使用者的完整配置檔。 它也可讓應用程式代表他們更新登入使用者的配置檔資訊。	否
User.ReadBasic.All	讀取所有使用者的基本配置檔	允許應用程式代表登入的使用者讀取組織中其他使用者的基本配置檔屬性集。 包括顯示名稱、名字和系列名稱、電子郵件地址、開啟延伸模組和相片。 允許應用程式讀取已登入使用者的完整配置檔。	否
User.Read.All	讀取所有使用者的完整設定檔	允許應用程式代表登入的使用者讀取組織中其他使用者的完整配置檔屬性、報告和管理員。	是
User.ReadWrite.All	讀取和寫入所有使用者的完整配置檔	允許應用程式代表登入的使用者讀取和寫入組織中其他使用者的完整配置檔屬性、報告和管理員。 也允許應用程式建立和刪除使用者，並代表登入的使用者重設用戶密碼。	是

如要求需要系統管理同意的許可權一文所示，租用戶系統管理員可以覆寫需求，並指定其租使用者中的任何或所有應用程式許可權，以要求系統管理員同意。 當您未從要求收到令牌時，您明智地設計應用程式以正常處理。 缺乏同意是您的應用程式可能不會收到令牌的許多原因之一。

下一步

• 從另一個 API 呼叫 API 可協助您確保有一個 API 需要呼叫另一個 API，並在應用程式代表使用者運作時安全地開發應用程式時，零信任。
• 取得存取資源的授權可協助您瞭解如何在取得應用程式的資源訪問許可權時，最好確保 零信任。
• 自定義令牌 描述您可以在 Microsoft Entra 令牌中接收的資訊。 它說明如何自定義令牌，以改善彈性和控制，同時提高應用程式零信任安全性與最低許可權。
• 在令牌 中設定群組宣告和應用程式角色會示範如何使用應用程式角色定義來設定應用程式，並將安全組指派給應用程式角色。 這些方法有助於改善彈性和控制，同時以最低許可權增加應用程式零信任安全性。
• 要求需要系統管理同意 的許可權描述應用程式許可權需要系統管理同意時的許可權和同意體驗。
• 在本快速入門中：使用 Microsoft 身分識別平台 保護 Web API，下載並執行程式碼範例，示範如何保護 ASP.NET Web API。
• 在本教學課程 - 在 Azure API 管理 中轉換和保護 API，瞭解如何設定通用原則以隱藏 API HTTP 回應本文中的技術堆疊資訊和原始 URL。
• 授權最佳做法 可協助您為應用程式實作最佳的授權、許可權和同意模型。