快速入門：設定應用程式以公開 Web API

  • 發行項

在本快速入門中，您將向 Microsoft 身分識別平台 註冊 Web API，並藉由新增範圍向用戶端應用程式公開。 藉由註冊您的 Web API 並透過範圍公開它、指派擁有者和應用程式角色，您可以將許可權型存取權提供給存取您 API 的授權使用者和用戶端應用程式。

必要條件

註冊 Web API

存取 API 需要設定存取範圍和角色。 如果您想要將資源應用程式 Web API 公開給用戶端應用程式，請設定 API 的存取範圍和角色。 如果您想要讓用戶端應用程式存取 Web API，請設定許可權以存取應用程式註冊中的 API。

若要提供 Web API 中資源的限定範圍存取權，您必須先向 Microsoft 身分識別平台 註冊 API。

執行快速入門：向 Microsoft 身分識別平台 註冊應用程式一節中的步驟。

略過 [ 重新導向 URI （選擇性）] 區段。 因為沒有任何使用者以互動方式登入，所以您不需要設定 Web API 的重新導向 URI。

指派應用程式擁有者

  1. 在您的應用程式註冊中，於 [管理] 底下選取 [擁有者]，然後選取 [新增擁有者]。
  2. 在新視窗中，尋找並選取您要指派給應用程式的擁有者。 選取的擁有者會出現在右側面板中。 完成後，請確認 [ 選取]。 應用程式擁有者現在會出現在擁有者的清單中。

注意

請確定您想要同時將許可權新增至兩者都有擁有者，否則要求 API 許可權時不會列出 API。

指派應用程式角色

  1. 在應用程式註冊的 [管理] 底下，選取 [應用程式角色]，然後選取 [建立應用程式角色]。

  2. 接下來，在 [ 建立應用程式角色] 窗格中指定應用程式角色 的屬性。 在此逐步解說中，您可以使用範例值或自行指定值。

    欄位 描述 範例
    顯示名稱 應用程式角色的名稱 員工記錄
    允許的成員類型 指定是否可以將應用程式角色指派給使用者/群組和/或應用程式 應用程式
    值 令牌的「角色」宣告中顯示的值 Employee.Records
    說明 應用程式角色的更詳細描述 應用程式可以存取員工記錄

  3. 選取複選框以啟用應用程式角色。

註冊 Web API 並獲指派應用程式角色和擁有者後，您可以將範圍新增至 API 的程式代碼，以便為取用者提供更細微的許可權。

新增範圍

提示

本文中的步驟可能會根據您從開始的入口網站稍有不同。

用戶端應用程式中的程式碼會要求權限，以執行 Web API 所定義的作業，方法是將存取權杖連同其要求傳遞至受保護的資源 (Web API)。 您的 Web API 接著只有在收到的存取令牌包含作業所需的範圍時，才會執行要求的作業。

首先，請遵循下列步驟來建立名為 的 Employees.Read.All範例範圍：

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

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

  3. 流覽至 [身分>識別應用程式> 應用程式註冊]，然後選取 API 的應用程式註冊。

  4. 選取 [ 公開 API]

  5. 如果您尚未設定應用程式識別碼 URI，請選取 [新增]。

    您可以使用預設值 api://<application-client-id> 或其他 支援的應用程式識別碼 URI 模式。 應用程式識別碼 URI 會作為您將在 API 程式碼中參考範圍的前置詞，而且必須是全域唯一的值。

  6. 選取 [ 新增範圍]：

    An app registration's Expose an API pane in the Azure portal

  7. 接下來，在 [新增範圍] 窗格中指定範圍的屬性。 在此逐步解說中，您可以使用範例值或自行指定值。

    欄位 描述 範例
    範圍名稱 您的範圍名稱。 常見的範圍命名慣例是 resource.operation.constraint。 Employees.Read.All
    神秘 可以同意 使用者是否可以同意此範圍，或是否需要管理員同意。 僅針對較高許可權選取 [管理員]。 管理員和使用者
    管理員 同意顯示名稱 只有管理員才會看到範圍用途的簡短說明。 Read-only access to Employee records
    管理員 同意描述 只有管理員才會看到範圍所授與之權限的更詳細描述。 Allow the application to have read-only access to all Employee data.
    使用者同意顯示名稱 範圍用途的簡短描述。 只有在您設定 神秘 同意管理員 和使用者時，才會向用戶顯示。 Read-only access to your Employee records
    使用者同意描述 範圍所授與之權限的更詳細描述。 只有在您設定 神秘 同意管理員 和使用者時，才會向用戶顯示。 Allow the application to have read-only access to your Employee data.

  8. 將 [狀態]設定為 [啟用]，然後選取 [新增範圍]。

  9. (選用) 若要隱藏提示您的應用程式使用者同意您已定義的範圍，可以預先授權用戶端應用程式存取您的 Web API。 系統只會預先授權您信任的用戶端應用程式，因為您的使用者不會有機會拒絕同意。

    1. 在 [授權的用戶端應用程式] 下，選取 [新增用戶端應用程式]
    2. 輸入您要預先授權的用戶端應用程式的應用程式 (用戶端) 識別碼。 例如，您先前註冊的 Web 應用程式的識別碼。
    3. 在 [授權範圍] 底下，選取您想要隱藏同意提示的範圍，然後選取 [新增應用程式]。

    如果您遵循這個選擇性步驟，用戶端應用程式現在是預先授權的用戶端應用程式（PCA），使用者不會在登入時提示使用者同意。

接下來，新增另一個名為 的範例範圍 Employees.Write.All ，只有系統管理員可以同意。 需要管理員同意的範圍通常用於提供較高許可權作業的存取權，而且通常是由以後端服務或精靈身分執行且不會以互動方式登入使用者的用戶端應用程式使用。

若要新增範例範圍，請遵循 [新增Employees.Write.All範圍] 區段中的步驟，並在 [新增範圍] 窗格中指定這些值：

欄位 範例值
範圍名稱 Employees.Write.All
神秘 同意 僅限 管理員
管理員 同意顯示名稱 Write access to Employee records
管理員 同意描述 Allow the application to have write access to all Employee data.
使用者同意顯示名稱 沒有 （保留空白）
使用者同意描述 沒有 （保留空白）

將 [狀態]設定為 [啟用]，然後選取 [新增範圍]。

驗證公開的範圍

如果您已成功新增上一節所述的這兩個範例範圍，它們會出現在 Web API 應用程式註冊的 [公開 API ] 窗格中，如下圖所示：

Screenshot of the Expose an API pane showing two exposed scopes.

如圖片中所示，範圍的完整字串是您的 Web API 的應用程式識別碼 URI 和範圍的範圍名稱的串連。

例如，如果您的 Web API 應用程式識別碼 URI 是 https://contoso.com/api ，且範圍名稱為 Employees.Read.All，則完整範圍為：

https://contoso.com/api/Employees.Read.All

使用公開的範圍

在本系列中的下一篇文章中，您會依照本文中的步驟，設定用戶端應用程式的註冊，以存取您的 Web API 和您定義的範圍。

一旦授與用戶端應用程式註冊存取 Web API 的許可權，用戶端就可以由身分識別平台發出 OAuth 2.0 存取令牌。 當用戶端呼叫 Web API 時，它會顯示存取令牌，其範圍 （scp） 宣告會設定為您在用戶端應用程式註冊中指定的許可權。

稍後您可以視需要公開其他範圍。 假設您的 Web API 可以公開多個與數個作業相關聯的範圍。 您的資源可以在運行時間控制 Web API 的存取，方法是評估其收到的 OAuth 2.0 存取令牌中的範圍 （scp） 宣告。

下一步

既然您已藉由設定 Web API 範圍來公開 Web API，請設定用戶端應用程式的註冊，並具有存取範圍的許可權。

設定 Web API 存取的應用程式註冊