共用方式為


快速入門:設定用戶端應用程式以存取 Web API

在本快速入門中,您會提供向 Microsoft 身分識別平台註冊的用戶端應用程式,並具備範圍限定的權限,可存取您自己的 Web API。 您也會提供 Microsoft Graph 的用戶端應用程式存取權。

藉由在用戶端應用程式的註冊中指定 Web API 的範圍,用戶端應用程式可以從 Microsoft 身分識別平台取得包含這些範圍的存取權杖。 接著 Web API 可以在程式碼中根據存取權杖中找到的範圍,提供其資源的權限存取權。

必要條件

新增用來存取 Web API 的權限

提示

根據您開始使用的入口網站,本文中的步驟可能略有不同。

存取 API 需要設定存取範圍和角色。 若要將資源應用程式 Web API 公開給用戶端應用程式,即可設定 API 的存取範圍和角色。 若要讓用戶端應用程式存取 Web API,即可在應用程式註冊中設定可存取 API 的權限。

若要將您自己的 Web API 的存取權授與用戶端應用程式,您需要有兩個應用程式註冊:

此圖顯示兩個應用程式註冊彼此的關聯性,其中用戶端應用程式具有不同的權限類型,而且 Web API 具有用戶端應用程式可存取的不同範圍。 在本節中,您會將權裉新增至用戶端應用程式的註冊。

折線圖:顯示右側具有已公開範圍的 Web API,以及左側選取這些範圍作為權限的用戶端應用程式

一旦您註冊了用戶端應用程式和 Web API,並藉由建立範圍來公開 API,您可以遵循下列步驟來設定用戶端對 API 的權限:

  1. 以至少 雲端應用程式系統管理員 的身分登入 Microsoft Entra 系統管理中心

  2. 如果您可存取多個租用戶,請使用頂端功能表中的 [設定] 圖示 ,以從 [目錄 + 訂用帳戶] 功能表,切換至包含應用程式註冊之租用戶。

  3. 瀏覽至 [身分識別] > [應用程式] > [應用程式註冊],然後選取用戶端應用程式 (「非」您的 Web API)。

  4. 選取 [API 權限],然後選取 [新增權限],然後在資訊看板中選取 [我的 API]

  5. 選取您已在必要條件過程註冊的 Web API,然後選取 [委派權限]

    • 「委派權限」適用於以已登入使用者身分存取 Web API 的用戶端應用程式,而且其存取權應該限制為您在下一個步驟中所選取的權限。 為此範例選取 [委派的權限]

    • 應用程式權限適用於需要自行存取 Web API 的服務或精靈類型應用程式,而無需使用者介入來進行登入或同意。 除非您已定義 Web API 的應用程式角色,否則會停用此選項。

  6. 選取權限下,展開您為 Web API 定義之範圍的資源,然後選取用戶端應用程式應該代表登入使用者的權限。

    • 如果您已使用先前快速入門中所指定的範例範圍名稱,則應該會看到 Employees.Read.AllEmployees.Write.All
  7. 選取您已在完成必要條件時建立的權限,例如,Employees.Read.All

  8. 選取 [新增權限] 來完成程序。

將權限新增至您的 API 後,您應該會在設定的權限之下看到選取的權限。 下圖顯示範例 Employees.Read.All 委派的權限已新增至用戶端應用程式的註冊。

Azure 入口網站中顯示新增權限的 [已設定權限] 窗格

您也可能會注意到 Microsoft Graph API 的 User.Read 權限。 當您在 Azure 入口網站中註冊應用程式時,系統會自動新增此權限。

新增用來存取 Microsoft Graph 的權限

除了會代表登入的使用者存取您自己的 Web API,您的應用程式可能也需要存取或修改儲存在 Microsoft Graph 中的使用者 (或其他) 資料。 或者,您可能會需要以本身身分存取 Microsoft Graph 的服務或精靈應用程式,並在不需要任何使用者互動的情況下執行作業。

Microsoft Graph 的委派權限

設定 Microsoft Graph 的委派權限,讓您的用戶端應用程式能夠代表登入的使用者執行作業,例如讀取其電子郵件或修改其設定檔。 根據預設,當使用者登入時,系統會詢問用戶端應用程式的使用者同意您已為其設定的委派權限。

  1. 從用戶端應用程式的 [概觀] 頁面中,選取 [API 權限] > [新增權限] > [Microsoft Graph]

  2. 選取委派的權限。 Microsoft Graph 會公開許多權限,其中最常顯示在清單頂端。

  3. 選取權限底下,選取下列權限:

    權限 描述
    email 檢視使用者的電子郵件地址
    offline_access 維護您授與其存取權的資料存取權
    openid 將使用者登入
    profile 檢視使用者的基本個人檔案
  4. 選取 [新增權限] 來完成程序。

每當設定權限時,系統會在您的應用程式使用者登入時要求他們同意,以允許您的應用程式代表他們存取資源 API。

身為管理員,您也可以代表「所有」使用者授與同意,如此系統就不會提示使用者執行此動作。 本文章的詳細說明 API 權限和管理員同意一節會討論管理員同意。

Microsoft Graph 的應用程式權限

設定應用程式的應用程式權限,以在不需要使用者互動或同意的情況下,自行進行驗證。 應用程式權限通常是由背景服務或以「無周邊」方式存取 API 的精靈,以及存取另一個 (下游) API 的 Web API 所使用。

在下列步驟中,您會將權限授與 Microsoft Graph 的 Files.Read.All 權限作為範例。

  1. 以至少 雲端應用程式系統管理員 的身分登入 Microsoft Entra 系統管理中心
  2. 如果您可存取多個租用戶,請使用頂端功能表中的 [設定] 圖示 ,以從 [目錄 + 訂用帳戶] 功能表,切換至包含應用程式註冊之租用戶。
  3. 瀏覽至 [身分識別] > [應用程式] > [應用程式註冊],然後選取用戶端應用程式。
  4. 選取 [API 權限]>[新增權限]>[Microsoft Graph]>[應用程式權限]
  5. Microsoft Graph 所公開的所有權限都會顯示在選取權限之下。
  6. 選取您想要授與應用程式的權限。 例如,您可能有一個可掃描組織中檔案的精靈應用程式,會針對特定檔案類型或名稱發出警示。 在 [選取權限] 下方,展開 [檔案],然後選取 Files.Read.All 權限。
  7. 選取新增權限
  8. 某些權限 (例如 Microsoft Graph 的 Files.Read.All 權限) 需要管理員同意。 若要授與管理員同意,請選取 [授與管理員同意] 按鈕,稍後我們會在 管理員同意按鈕一節中討論。

設定用戶端認證

使用應用程式權限的應用程式會使用自己的認證以自己的身分進行驗證,而不需要任何使用者互動。 您必須先設定用戶端應用程式的認證,您的應用程式 (或 API) 才能使用應用程式權限來存取 Microsoft Graph、您自己的 Web API 或其他 API。

如需設定應用程式認證的詳細資訊,請參閱快速入門:向 Microsoft 身分識別平台註冊應用程式新增認證一節。

應用程式註冊的 [API 權限] 窗格包含 [已設定權限] 資料表和系統管理員同意按鈕,如下列各節所述。

已設定權限

[API 權限] 窗格上的 [已設定權限] 資料表會顯示您的應用程式進行基本作業所需的權限清單 - 「需要的資源存取 (RRA)」清單。 使用者或其管理員必須先同意這些權限,才能使用您的應用程式。 您可在稍後於執行階段要求其他選用的權限 (使用動態同意)。

這是使用者同意您應用程式所需的最低權限清單。 您可能會有更多權限,但這些是一定必要的。 為確保安全性,並協助使用者和管理員更熟悉您的應用程式,請不要詢問任何您不需要的資訊。

您可以使用上述步驟來新增或移除此資料表中所顯示的權限。 身為管理員,您可以授與管理員同意資料表中所顯示的完整 API 權限集合,並撤銷個別權限的同意。

授與 {your tenant} 管理員同意按鈕可讓系統管理員對於應用程式上設定的權限授與系統管理員同意。 選取該按鈕時,會顯示一個對話方塊要求您確認同意動作。

Azure 入口網站的 [已設定權限] 窗格中已反白顯示 [授與系統管理員同意] 按鈕

授與同意之後,需要管理員同意的權限就會顯示為同意授權:

Azure 入口網站中顯示針對 Files.Read.All 權限所授與系統管理員同意的 [設定權限] 資料表

如果您不是系統管理員,或未針對應用程式設定權限,則會「停用」授與管理員同意按鈕。 如果您有已授與但未設定的權限,系統管理員同意按鈕會提示您處理這些權限。 您可以將其新增至已設定權限,或將其移除。

移除應用程式權限

不給應用程式過多權限十分重要。 撤銷管理員對您應用程式中權限的同意;

  1. 瀏覽至您的應用程式並選取 [API 權限]
  2. 在 [已設定權限] 下,選取要移除之權限旁邊的三個點,然後選取 [移除權限]
  3. 在出現的快顯項目中,選取 [是,移除] 以撤銷管理員對權限的同意。

前進到系列中的下一個快速入門,以了解如何設定哪些帳戶類型可以存取您的應用程式。 例如,您可以限制只有組織中的使用者 (單一租用戶) 才能存取,或是允許其他 Microsoft Entra 租用戶 (多租用戶) 中的使用者和具有個人 Microsoft 帳戶 (MSA) 的使用者進行存取。